search

rmoesbergen / openwrt-ha-device-tracker

OpenWRT device tracker for Home Assistant that actually works
107 stars 18 forks source link
homeassistant openwrt presence-detection

readme

OpenWRT Home Assistant device tracker

Table of contents

What is this?

This script is a Wi-Fi device tracker that runs on OpenWRT devices. It is an alternative for the built-in OpenWRT luci or OpenWRT ubus integrations that uses a 'push' model instead of 'polling' for updates. It watches ubus join/leave events of Wi-Fi clients in realtime and updates their status in Home Assistant by calling the Home Assistant REST API (device_tracker.see endpoint). This causes Wi-Fi events to be noticed by Home Assistant instantly, making your home automation a lot more responsive. It can handle network failures or Home Assistant being offline, and will recover once Home Assistant is back online. It does this by adding all events to a queue and making sure every event is accepted by Home Assistant before removing it from the queue.

Installation

Steps to perform on your OpenWRT device

Steps to perform in Home Assistant

The version entity

To verify that the communication between Home Assistant and the presence detector is OK and at the latest version, the presence detector registers a 'presence_detector_version' entity with the current version number of the script in Home Assistant. You can view it as follows:

OpenWRT device configuration

The settings file on your OpenWRT device looks like this:

{
  "hass_url": "http://hassio.local:8123",
  "hass_token": "<Home Assistant REST API Bearer Token>",
  "interfaces": ["hostapd.wlan0", "hostapd.wlan1"],
  "filter_is_denylist": true,
  "filter": ["01:23:45:67:89:ab"],
  "params": {
    "00:00:00:00:00:00": {
      "host_name": "Dave",
      "dev_id": "phonedave"
    }
  },
  "ap_name": "",
  "location": "home",
  "away": "not_home",
  "fallback_sync_interval": 0,
  "debug": false
}

These settings will need a bit of explaining:

(Optional) Home Assistant Configuration

This section goes into a bit more detail about where the entity information discovered by OpenWRT is stored in HA, and how you can tune the appearance of the Wi-Fi device entities. This is all optional and not needed to get a functioning automation going.

As mentioned, this script calls the device_tracker.see service in HA. This will create an entry in the known_devices.yaml file in the HA configuration directory. Entries in this file create entities inside HA which you can use for automations. Using the example params shown above the known_devices.yaml entry will be:

dave:
  name: Dave
  mac: 00:00:00:00:00:00
  icon:
  picture:
  track: true

Note that these entries will be created automatically the first time a device is 'seen' by your OpenWRT router. After an entry has been created, you can update the configuration to enhance the appearance of the device in HA. You can select the icon this entity will use by entering an MDI code for the icon, ie icon: mdi:cellphone-basic. Updating the icon or other settings manually requires a restart of HA.

Adding this icon will create an entity that looks like: Entity

Testing indicates that HA only cares about the device MAC address for updating the entity state. This means you can omit the params in presence-detector.settings.json entirely and freely edit known_devices.yaml to give the entity any name you like as long as you keep the MAC address the same. This also means you can add new devices to known_devices.yaml directly without them being present on your network if you know the MAC address.

The entities created from entries in known_devices.yaml will be read only in the HA web UI. The reason for this is explained here. If you want to edit an entity, change the entry in known_devices.yaml and restart Home Assistant. If you want to delete an entity then remove it from known_devices.yaml and the entity will disappear from the HA UI shortly.

NB These entities will persist over reboots even if deleted, I'm assuming there's a background task that cleans them up during normal operation.

An example automation

Here's how to create an example automation that uses the OpenWRT device state:

Now you can test the automation by turning the device's Wi-Fi radio on/off or clicking "disconnect" in the OpenWRT webGUI.

Linking multiple devices to one "Person"

If you have multiple devices that can indicate if a "Person" is home or not, you can use the "Person" integration. Instead of tracking one device and basing automations on that, you can trigger automations on the Person being "Home" or "Away". Only if all devices assigned to the Person are "Away", will the Person be marked as "Away".

You can configure this as follows:

Troubleshooting

The program will run as a 'service' in the background and will log interesting events to syslog. You can read these events by running 'logread' on your OpenWRT device, or using your favorite web-ui.

In case something doesn't work, here are a some things you can do to check your setup: