Connect a Zigbee USB coordinator (e.g., a CC2652-based stick) and identify its serial port; install Zigbee2MQTT following the official guide and configure configuration.yaml with the correct serial port path and your MQTT broker address
Set homeassistant: true in configuration.yaml to enable Home Assistant MQTT discovery; Zigbee2MQTT will automatically publish MQTT discovery messages so entities appear in Home Assistant without manual configuration
Enable device joining by publishing {"value":true} to zigbee2mqtt/bridge/request/permit_join or using the Zigbee2MQTT frontend; put the device in pairing mode according to the device's instructions (typically a button sequence)
Once paired, the device appears in the Zigbee2MQTT devices list and its state is published to zigbee2mqtt/<friendly_name>; send control commands by publishing JSON to zigbee2mqtt/<friendly_name>/set (e.g., {"state":"ON","brightness":150})
Disable permit_join after pairing to secure the network; rename devices using zigbee2mqtt/bridge/request/device/rename with {"from":"<ieee_addr>","to":"<friendly_name>"} for readable topic names
Monitor the zigbee2mqtt/bridge/state and zigbee2mqtt/bridge/event topics for coordinator health, device join/leave events, and interview completion; check the log topic for errors
Known gotchas
Only one Zigbee coordinator can be connected to a single Zigbee2MQTT instance; if a device was previously paired with another coordinator or app (e.g., SmartThings, the vendor app) it must be factory-reset before it will join a new network
Devices must be close to the coordinator or a router device during initial pairing; moving them to their final location after pairing is fine, but pairing from far away causes intermittent failures and incomplete device interviews
Zigbee2MQTT stores the network database in a JSON file (devices.yaml/database.db); if this file is lost, all device bindings and names are gone and devices must be re-paired — back up this file regularly
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp