github.com/awilliams/wifi-presence
Presence detection on OpenWrt routers using connect/disconnect events of WiFi clients. Events are published to MQTT with Home Assistant integration.
wifi-presence connects to hostapd's control interface to receive client connect and disconnect events.Requirements:
Contents:
wifi-presence on an OpenWrt access point. See okpg or download./etc/config/wifi-presence configuration file. Update the mqttAddr to the desired MQTT broker's address.wifi-presence/config topic a list of MAC addresses to track. See configuration.If using Home Assistant with the same MQTT broker, it should automatically be updated with each configured WiFi client.
A home automation system that reacts to presence and absence events provides a more automated experience.
There are many ways to determine presence, e.g. motion sensors, network traffic monitoring, GPS & geo-fencing, etc. A person's phone typically travels with them in and out of a household. Most phones automatically connect and disconnect from home WiFi networks. Therefore a WiFi connection to one or more access points (APs) can be used as a proxy for physical presence.
There are similar projects that periodically ping client devices.
This method may be less reliable than using hostapd because phones may not respond to pings while in low power mode.
There is also a delay introduced by the ping frequency.
wifi-presence integrates with Home Assistant using the MQTT integration.
This can be enabled/disabled via the -hass.autodiscovery flag (true by default).
Although supported, Home Assistant isn't required. The messages published to MQTT can be consumed by any subscriber(s).
Configuration is done via command-line flags at startup, and via MQTT at runtime.
The MQTT configuration determines the WiFi devices/clients wifi-presence will monitor. For each configured device, wifi-presence will publish state information on connect and disconnect. See the note about iOS devices and MAC addresses.
Configuration is a JSON published to the config topic (<mqtt.prefix>/config).
Example configuration:
{
"devices": [
{
"name": "My Phone",
"mac": "AA:BB:CC:DD:EE:FF"
},
{
"name": "TV",
"mac": "00:11:22:33:44:55"
},
{
"name": "Other Phone",
"mac": "FF:EE:EE:DD:CC:BB"
}
]
}
Example using Mosquitto to the JSON configuration in wifi-presence.config.json:
$ mosquitto_pub \
-h 'my-mqtt-broker' \
-t 'wifi-presence/config' \
-r \
-f wifi-presence.config.json
The OpenWrt project is
OpenWrt is a highly extensible GNU/Linux distribution for embedded devices (typically wireless routers).
See the openwrt branch for package and build scripts.
Installation via OpenWrt's opkg package manager:
# Add public key
wget https://wifi-presence.s3.us-east-2.amazonaws.com/public.key
opkg-key add public.key
# Add package source as a custom feed
echo "src/gz wifi-presence http://wifi-presence.s3-website.us-east-2.amazonaws.com" >> /etc/opkg/customfeeds.conf
# Fetch/update list of packages
opkg update
# Install/upgrade wifi-presence
opkg install wifi-presence
# Update configuration
vim /etc/config/wifi-presence
# Enable and start wifi-presence
/etc/init.d/wifi-presence enable
The configuration file is: /etc/config/wifi-presence.
OpenWrt packages of wifi-presence are available for download.
When running wifi-presence using OpenWrt, use the provided /etc/config/wifi-presence file to configure.
As a standalone program, the following command-line flags are used:
wifi-presence [options]
Options:
-apName string
Access point name (default "my-router")
-debounce duration
Time to wait until considering a station disconnected. Examples: 5s, 1m (default 10s)
-hass.autodiscovery
Enable Home Assistant MQTT autodiscovery (default true)
-hass.prefix string
Home Assistant MQTT topic prefix (default "homeassistant")
-help
Print detailed help message
-hostapd.socks string
Hostapd control interface socket(s). Separate multiple paths by ':'
-mqtt.addr string
MQTT broker address, e.g "tcp://mqtt.broker:1883"
-mqtt.id string
MQTT client ID (default "wifi-presence.my-router")
-mqtt.password string
MQTT password (optional)
-mqtt.prefix string
MQTT topic prefix (default "wifi-presence")
-mqtt.username string
MQTT username (optional)
-sockDir string
Directory for local socket(s) (default "/var/folders/99/0z1nqy2d54x12xj2md6xz67w0000gn/T/")
-v Verbose logging (alias)
-verbose
Verbose logging
-version
Print version and exit
wifi-presence publishes and subscribes to an MQTT broker. The -mqtt.prefix flag can be used to change the topic prefix, along with -hass.prefix for Home Assistant's topic prefix.
The following topics are used:
<PREFIX>/<AP_NAME>/status
The status of wifi-presence (online / offline).
<PREFIX>/config
wifi-presence subscribes to this topic for configuration updates.
<HASS_PREFIX>/device_tracker/<AP_NAME>/<MAC>/config
If -hass.autodiscovery is enabled, then all configured devices will be published
to these topics (based on their MAC address). Home Assistant subscribes to these
topics and registers/unregisters entities accordingly based on messages received.
<PREFIX>/station/<AP_NAME>/<MAC>/state
The state of a device (home / not_home) is published to these topics.
<PREFIX>/station/<AP_NAME>/<MAC>/attrs
A JSON object with device attributes (SSID, BSSID, etc) is published to these topics.
wifi-presence requires hostapd running with control interface(s) enabled.
This is the default for OpenWrt.
The hostapd configuration option is ctrl_interface. More information:
https://w1.fi/cgit/hostap/plain/hostapd/hostapd.conf
The wifi-presence -hostapd.socks option should correspond to the socket locations defined by 'ctrl_interface'. Multiple sockets can be monitored (one socket per radio is created by hostapd).
OpenWrt includes a stripped down version of hostapd, which is the default. This stripped down version is compatible with wifi-presence, but prevents wifi-presence from getting a list of connected devices at startup. In this case, all devices will be considered "disconnected" until a (re)-connect is seen.
The full version of hostapd can be installed to improve wifi-presence. When using the full version, wifi-presence will query hostapd for a list of connected devices at startup/when receiving new configuration. Any connected stations will immediately be considered "connected", triggering a corresponding MQTT message for each.
The full version is included as part of various packages. For example, commands to install the full version using wpad:
opkg remove wpad-basic-wolfssl
opkg install wpad-wolfssl
iOS version 14 introduced "private Wi-Fi addresses" to improve privacy.
When enabled, an iOS client will connect to APs using different MAC addresses. Consider disabling this feature for APs that
you control and are running wifi-presence to help make presence detection configuration easier.
The OpenWrt Luci integration similar presence detection functionality.
Some differences between wifi-presence and the luci integration:
The luci integration communicates with the OpenWrt router using the OpenWrt admin HTTP(S) interface, while wifi-presence uses MQTT.
The MQTT HomeAssistant integration is then what bridges the two.
There's not necessarily an advantage to either approach, although if you don't have MQTT already integrated, then wifi-presence may not make as much sense.
Presence Detection:
luci integration uses polling, i.e. it periodically queries the OpenWrt interface for the list of connected clients, while wifi-presence is event-driven.
It connects with OpenWrt's hostapd (the system responsible for WiFi) and receives connect/disconnect events in real-time.luci integration effectively scrapes the ARP and DHCP tables on the OpenWrt router to get a list of connected clients.
While wifi-presence is integrated directly with hostapd and has direct access to the connected clients.FAQs
Unknown package
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.