Simple Magic Packet Service (for Home Assistant)

Overview

Simple Magic Packet Service is a C# web application that exposes two web api endpoints for Wake on LAN packet sending and ICMP Ping checks. It was developed for Home Assistant to keep Home Assistant itself off of sensitive networks but have the ability to use Wake on LAN for Computers, Televisions and other WoL compatible devices. I did not want cross-vlan/network multicast traffic as it complicates things too much in the home network, thus this service was developed.

This service takes basic networking and Home Assistant knowledge to successfully implement.

Git repository/learn more here.

Security Warning ⚠️

Simple Magic Packet Service does not have any built-in authentication for sending Wake on LAN or ICMP packets. It is meant to be used within a home network were sending Wake on LAN packets or ICMP pings to endpoints while being unauthenticated is not an issue or worry. Authentication is being planned in the form of X-API-Key header but is not the primary focus of this repository at this time.

With this being said, it was developed with absolutely no intentions of implementation in secure enterprise or corporate networks.

Compatibility ⚠️

Simple Magic Packet Service is only compatible Docker running Linux on the host OS. This is due to the requirement of bridging the host network adapters to the container for proper multicast support. By default, Docker containers are NATed and do not support multicast on the host’s network.

Installation 📦

To use Simple Magic Packet Service, follow these steps:

1. Follow the installation steps for installing Docker Engine on your platform of choice.

2. Clone the repository:

git clone https://git.graycatdevelopment.com/simple-magic-packet-service/simple-magic-packet-service.git

3. Build the Docker image for the container:

cd "simple-magic-packet-service/Simple Magic Packet Service"
docker build -t smps_server:latest .

4. Spin up a Docker container using the newly built image (see usage section).

Usage 📖

There are two options for spinning up a container:

Docker Compose (Recommended):

Create a docker-compose.yml file with the contents of:

services:
    smps_server:
        image: smps_server:latest
        container_name: smps_server
        network_mode: host
        restart: unless-stopped

Start the Docker container with docker compose up -d.

This will run the container in detached mode and will start with the Docker Engine unless explicitly stopped (example: on system reboot, if Docker is enabled to start on boot).

Docker Command Line:

Start the Docker container with docker run -d --restart unless-stopped --network host --name smps_server smps_server:latest

This will run the container in detached mode and will start with the Docker Engine unless explicitly stopped (example: on system reboot, if Docker is enabled to start on boot).

Continued Usage:

Once the Docker container has been spun up, it will listen on HTTP *:8080 via the host’s network connections.

The application exposes two HTTP API Endpoints:

1. Magic Packet

Method: POST /magicpacket

HTTP Request:

{
    "macAddress":"00:00:00:00:00:00"
}

HTTP Response (Success):

{
    "success": true,
    "errors": [],
    "messages": [
        "A magic packet for 00:00:00:00:00:00 was sent."
    ]
}

• Input MAC address will be validated, if validation fails, you will receive a non-successful response with an error message.

2. Ping

Method: POST /ping

HTTP Request:

{
    "ipAddress":"192.168.1.1"
}

HTTP Response (Host Online):

{
    "success": true,
    "errors": [],
    "messages": [
        "Host 192.168.1.1 is online with RTT latency of 0ms."
    ]
}

HTTP Response (Host Not Online/Other Network Issue):

{
    "success": false,
    "errors": [
        "Status: TimedOut"
    ],
    "messages": [
        "Ping for 192.168.1.1 did not complete successfully.",
        "Reference errors field for more information."
    ]
}

• Input IP address will be validated, if validation fails, you will receive a non-successful response with an error message.
• Error messages for the ping endpoint can return several different statuses, if you are encountering issues, it is advised to check the HTTP response.

Home Assistant Integration:

Home Assistant integration is very easy to implement and uses the REST/REST Commands integration alongside Binary Sensors to determine host status.

To implement a basic host status check button with Wake on LAN support:

1. Edit Home Assistant’s configuration.yaml and add:

rest_command:
  send_magic_packet:
    url: "http://{CHANGEME_DOCKER_HOST}:8080/magicpacket"
    method: POST
    headers:
        Content-Type: application/json
    payload: '{"macAddress": "{{  macaddress  }}"}'

binary_sensor:
  - platform: rest
    name: Living Room TV Online
    resource: "http://{CHANGEME_DOCKER_HOST}:8080/ping"
    method: POST
    headers:
      Content-Type: application/json
    payload: '{"ipAddress": "{CHANGEME_DEVICE_IPADDR}"}'
    value_template: "{{ value_json.success }}"
    scan_interval: 1

2. Add a button card to your dashboard’s configuration file:

type: button
name: Living Room TV (Wake on LAN)
tap_action:
  action: call-service
  service: rest_command.send_magic_packet
  service_data:
    macaddress: {CHANGEME_DEVICE_MACADDR}
hold_action:
  action: none
state_color: true
icon: mdi:power
entity: binary_sensor.living_room_tv_online

After adding the button, it will display the state of the binary sensor (binary_sensor.living_room_tv_online) via a color.

Clicking the button will result in Home Assistant sending a POST request to the Simple Magic Packet Service server and will send out a Wake on LAN packet to the device.

The button’s color will change depending on if the host is responding to ICMP pings.

The button does not support turning the device off, rather just waking it from an offline state.

🤚HEADS UP: Do not forget to change the following placeholders in the example implementation configuration:

• {CHANGEME_DOCKER_HOST}: The IP address of the Docker host running the Simple Magic Packet Service container.
• {CHANGEME_DEVICE_IPADDR}: The IP address of the device you want to check the online status of.
• {CHANGEME_DEVICE_MACADDR}: The IP address of the device you want to send magic packets to.
• Note: CHANGEME_DEVICE_IPADDR’s MAC address should resolve to {CHANGEME_DEVICE_MACADDR} for ideal functionality.

Here is a look at the final button programmed to my LG webOS TV on the dashboard (my Home Assistant instance is using a theme, yours may look different):