unifi2mqtt

Ubiquiti UniFi network controller to MQTT: client presence, devices, WLANs

Connects to a UniFi Network controller — a UniFi OS console (Dream Machine, Dream Router, Cloud Key Gen2, Cloud Gateway) or a self-hosted legacy controller — and bridges it to an MQTT broker, following the mqtt-smarthome architecture. Every wireless and wired client gets a retained presence topic, connect/disconnect events arrive instantly over the controller's event websocket, WLANs and device LEDs can be switched, and everything is announced to Home Assistant via MQTT discovery (one device_tracker per client).

Status: 2.0.0 is a complete rewrite that has not yet been verified against a real controller. It follows the documented UniFi OS and legacy APIs and is tested against fixture responses; see Controller compatibility and please report what works and what does not. 1.x users: see Upgrading from 1.x.

Install

npm install -g unifi2mqtt

Requires Node.js ^20.19, ^22.12 or >= 24. unifi2mqtt 2 is built on mqtt-interfaces-core (mqtt-smarthome spec 2.x) like the author's other adapters.

Create a local user on the controller for unifi2mqtt (UniFi OS: Settings → Admins & Users → Admin, "Restrict to local access only"; a read-only role is enough for status, the set topics need an admin). Cloud/SSO accounts and MFA do not work with the API.

Usage

unifi2mqtt --controller https://192.168.1.1 --username unifi2mqtt --password s3cret -k --mqtt-url mqtt://broker

| option | default | description | | ------------------------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------- | | -c, --controller | | controller url, required: https://<console> (UniFi OS) or https://<host>:8443 (legacy controller) | | --username, --password | | controller credentials, required: a local account without 2fa (not a Ubiquiti sso login) | | --site | default | site id (the part after /site/ in the controller url; not the display name) | | --mode | auto | api flavour: unifi-os (UDM, UDR, UCK G2, Cloud Gateway) or legacy (self-hosted controller); auto detects | | -k, --insecure | off | accept the controller's tls certificate without validation (consoles ship self-signed certificates) | | --events | on | subscribe to the controller's event websocket for instant client events; --no-events for polling only | | --poll-interval | 60 | seconds between polls of clients, devices and wlans (min 5) | | --presence-timeout | 0 | seconds a client may be gone before it is reported absent (0 = immediately) | | --clients | all | only publish these clients: mac addresses, names or hostnames, comma separated | | --client-key | name | how clients are named in topics: name (alias, else hostname, else mac), hostname or mac | | --ha-clients | on | announce a device_tracker per client to Home Assistant; --no-ha-clients for controller and devices only | | --publish-raw | off | additionally publish every websocket frame of the controller as <name>/raw | | -u, --mqtt-url | mqtt://localhost | broker URL, see MQTT.js | | --mqtt-username, --mqtt-password | | broker credentials | | --mqtt-tls-ca | | CA certificate file for mqtts:// | | -n, --name | unifi | instance name, used as topic prefix | | --json-payloads | on | status as {"val", "ts", "lc"} JSON; --no-json-payloads for plain values | | --ha-discovery | on | Home Assistant MQTT discovery (--no-ha-discovery disables and clears it) | | --ha-prefix | homeassistant | discovery prefix | | --maintenance | on | accept <name>/maintenance/set/{loglevel,restart}; --no-maintenance disables | | -v, --verbosity | info | error, warn, info, debug | | --install / --uninstall | | install/remove the systemd service unifi2mqtt@<name> | | --config-schema | | print the JSON Schema of all options and exit |

Every option can also be set via environment variable with the prefix UNIFI2MQTT_, e.g. UNIFI2MQTT_CONTROLLER=https://192.168.1.1 UNIFI2MQTT_PASSWORD=… unifi2mqtt; the broker settings fall back to the unprefixed MQTT_URL, MQTT_USERNAME, MQTT_PASSWORD.

Run as a systemd service

sudo unifi2mqtt --install --name unifi -c https://192.168.1.1 --username unifi2mqtt --password s3cret -k -u mqtt://192.168.1.2

--install creates a system user unifi2mqtt, writes the given options to /etc/unifi2mqtt/<name>.env (UNIFI2MQTT_* variables, 0640 root:unifi2mqtt — edit and systemctl restart unifi2mqtt@<name> to change), installs the template unit /etc/systemd/system/[email protected] and enables + starts unifi2mqtt@<name>. The instance name is the --name option, i.e. the MQTT topic prefix. Broker settings shared by all mqtt-interfaces adapters on the host can go to /etc/mqtt-interfaces/broker.env (MQTT_URL, MQTT_USERNAME, MQTT_PASSWORD). Logs: journalctl -u unifi2mqtt@<name> -f.

Several sites or controllers: run --install once per site with a different --name — each becomes its own instance with its own config and topic prefix, sharing one template unit and one system user:

sudo unifi2mqtt --install --name unifi        -c https://192.168.1.1 --site default …
sudo unifi2mqtt --install --name unifi-office -c https://192.168.1.1 --site office …
systemctl status 'unifi2mqtt@*'

sudo unifi2mqtt --uninstall --name unifi-office removes one instance (the template unit goes with the last one). she can install, configure and update instances from its Services page (config form from --config-schema, the password masked).

Docker

docker run -d --name unifi2mqtt --restart unless-stopped \
  -e UNIFI2MQTT_CONTROLLER=https://192.168.1.1 \
  -e UNIFI2MQTT_USERNAME=unifi2mqtt \
  -e UNIFI2MQTT_PASSWORD=s3cret \
  -e UNIFI2MQTT_INSECURE=true \
  -e UNIFI2MQTT_MQTT_URL=mqtt://broker \
  ghcr.io/hobbyquaker/unifi2mqtt

Topics

<name> defaults to unifi. Names of clients, devices and WLANs are used as topic levels after sanitising: whitespace, /, + and # become _ (Home WiFi → Home_WiFi); duplicate client names get a _<last 4 mac digits> suffix.

<name>/connected

Retained. 0 = not connected to the broker (set via last will), 1 = connected to the broker but not to the controller (login failed, controller unreachable, last poll failed), 2 = the controller answers.

<name>/info and <name>/maintenance/set/…

<name>/info (retained JSON) describes the running instance: package name and version, mqtt-smarthome spec version, node version, host, pid, start time, controller url, site, detected api flavour (mode), whether the event websocket is connected (events), poll interval. <name>/maintenance/set/loglevel (error|warn|info|debug) changes the log level at runtime, <name>/maintenance/set/restart exits cleanly so the service manager restarts the process; --no-maintenance turns both off.

<name>/status/<item>

Retained status reports (except events), published after every poll and instantly on websocket events — only when the value changed. Every status is {"val": <value>, "ts": <ms received>, "lc": <ms last changed>}; with --no-json-payloads the plain value (objects as JSON).

| item | type | notes | | -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | client/<key>/present | bool | true while the controller lists the client (or a connect event arrived), false after a disconnect or a poll without it (see below) | | client/<key>/details | object | {mac, name, hostname, ip, wired, ssid, band, channel, ap, network} — band is 2.4 GHz / 5 GHz / 6 GHz, ap the access point / switch name, null fields are unknown | | event/client | object | not retained: {type, client, mac, hostname, ssid, ap, wired, guest, time, msg}; type is connected, disconnected, roam, roam_radio | | client_count | int | clients present, all networks | | client_count/wireless | int | wireless clients present | | client_count/wired | int | wired clients present | | wifi/<ssid>/enabled | bool | WLAN enabled — settable | | wifi/<ssid>/client_count | int | clients on this SSID | | device/<key>/online | bool | access point / switch / gateway is connected to the controller | | device/<key>/led | string | on, off or default (site setting) — settable | | device/<key>/clients | int | clients on this device | | device/<key>/details | object | {mac, name, model, type, ip, version} |

<key> of a client is, with the default --client-key name, the alias set in the controller, else the hostname, else the mac address (--client-key hostname / mac to choose). A client that was seen once keeps its topics; when it is renamed the old topics are cleared and the new ones published. With --clients only the listed clients get topics (counts still cover everyone).

After a restart the adapter reads back what it retained on the broker in a previous run and, once the first poll is in, clears every client/…, device/… and wifi/… topic the controller no longer reports — a client that left while the adapter was down, a renamed client, a client now excluded by --clients. Nothing stays present: true from a previous life (#22); the log says how many items were cleared. Needs mqtt-interfaces-core 0.16; on an older core the readback is skipped.

Presence comes from two sources: the client list (stat/sta) polled every --poll-interval seconds, and the controller's event websocket (connect / disconnect / roam events, instant). A client disappears (present: false) when a disconnect event arrives or a poll no longer lists it — immediately with the default --presence-timeout 0, or after that many seconds without a sighting, which smooths phones that drop off the WLAN for a moment. Devices and WLANs are polled with the clients; device events (adopted, restarted, …) trigger an extra refresh.

<name>/set/<item>

Change requests. Payload is a plain value or mqtt-smarthome style JSON ({"val": true}).

| topic | payload | | ----------------------------------- | ----------------------------------------------------------------------------------------------------- | | <name>/set/wifi/<ssid>/enabled | true/false, 1/0, on/off | | <name>/set/device/<key>/led | on, off, default (booleans map to on/off) | | <name>/set/device/<key>/provision | any payload — force-provision the device (cmd/devmgr), for an AP that did not pick up a WLAN change |

mosquitto_pub -t unifi/set/wifi/Guests/enabled -m false
mosquitto_pub -t unifi/set/device/AP_Living_Room/led -m off

The status is re-read from the controller after the command; a rejected command is logged at warn.

<name>/raw

With --publish-raw every frame the controller sends on its event websocket is published as <name>/raw (not retained) — useful to see what your controller version emits (sta:sync, device:sync, alert, events, …) and to collect fixtures.

Home Assistant

MQTT discovery is on by default (HA ≥ 2024.11, device-based discovery). The controller/site appears as a device with client count sensors and one switch (enabled) + one sensor (clients) per WLAN. Every access point, switch and gateway is its own device (linked via the bridge) with a connectivity sensor, an LED select (on/off/default) and a client count. Every client is a device with a device_tracker entity (source_type: router, home/not_home) whose attributes are the client's details (mac, ip, ssid, ap, …); --no-ha-clients skips the clients, --clients limits them. Availability follows <name>/connected.

Device and entity ids are based on mac addresses (unifi2mqtt_<name>_client_<mac>), so renaming a client in the controller keeps its HA history. --no-ha-discovery disables discovery and removes the announcements on startup; --ha-prefix changes the discovery prefix.

Controller compatibility

unifi2mqtt talks to the controller directly (no node-unifi, no ubnt-unifi): POST /api/auth/login + /proxy/network/api/s/<site>/… on UniFi OS, POST /api/login + /api/s/<site>/… on legacy controllers, the session cookie and CSRF token as the ui uses them, the event websocket at …/wss/s/<site>/events. The account must be a local controller user without two-factor authentication — a Ubiquiti SSO login does not work with the local login endpoints, and a 2FA challenge cannot be answered non-interactively; the adapter says so in the log instead of retrying. --mode auto decides by GET /: a UniFi OS console answers 200, a legacy controller redirects to /manage. --mode unifi-os / legacy overrides.

| controller | status | | ------------------------------------------------------ | ----------------------------------------------------------------- | | UniFi OS consoles (UDM, UDM Pro/SE, UDR, UCK G2+, UCG) | implemented after the documented api, not yet verified | | legacy self-hosted Network application (:8443) | implemented after the 1.x adapter's api use, not yet verified |

A login the controller rate-limits (HTTP 429 — UniFi OS answers AUTHENTICATION_FAILED_LIMIT_REACHED after too many failed logins and locks the account for a while) is not retried every 10 s, because each attempt can extend the lockout: the adapter waits for Retry-After when the controller sends it, else 5 minutes, doubling up to 30, and says so at warn on every attempt (#23).

Run with --verbosity debug to see every request and websocket frame. The quickest way to help is a dump from your controller:

git clone https://github.com/hobbyquaker/unifi2mqtt && cd unifi2mqtt && npm ci
node scripts/dump.js -c https://192.168.1.1 --username unifi2mqtt --password … -k --seconds 120

It logs in, fetches stat/sta, stat/device, rest/wlanconf and a few more endpoints, listens to the event websocket for --seconds (connect or disconnect a wifi client meanwhile) and writes everything to ./dump/, redacted: macs keep their vendor part, public ips, names, SSIDs, serials and every secret are replaced consistently. Skim the files, then attach the directory to a GitHub issue together with the controller model and Network version. Nothing is written to the controller, no broker is needed.

Upgrading from 1.x

unifi2mqtt 2.0 is a rewrite on mqtt-interfaces-core; the topic layout changed:

| 1.x | 2.0 | | ----------------------------------------------------------- | ----------------------------------------------------------------------------- | | status/wifi/<ssid>/client/<hostname> {val, mac, ts} | status/client/<key>/present {val, ts, lc} + status/client/<key>/details | | status/wifi/<ssid>/event/connected {val: hostname, …} | status/event/client {val: {type: "connected", client, mac, ssid, ap, …}} | | status/wifi/<ssid>/event/disconnected | status/event/client with type: "disconnected" | | status/wifi/<ssid>/clientCount | status/wifi/<ssid>/client_count | | status/wifi/<ssid>/enabled, set/wifi/<ssid>/enabled | unchanged (SSID sanitised: Home WiFi → Home_WiFi) | | status/clientCount (wireless) | status/client_count (all), status/client_count/wireless, …/wired | | status/device/<name>/led, set/device/<name>/led | unchanged (name sanitised) + device/<name>/online, /clients, /details | | -a/--unifi-host, -p/--unifi-port | -c/--controller https://host[:port] | | -c/--unifi-user, -s/--unifi-password, -w/--unifi-site | --username, --password, --site | | -u/--url | -u/--mqtt-url (--url alias kept) | | env unifi-password=… | UNIFI2MQTT_PASSWORD=… (see --config-schema) | | pm2 | sudo unifi2mqtt --install --name unifi … or Docker |

Wired clients, UniFi OS consoles, <name>/info, maintenance topics, --presence-timeout, --clients, Home Assistant discovery and the systemd installer are new. See CHANGELOG.md.

License

MIT © Sebastian Raff