Integrate Zigbee devices with Home Assistant via Zigbee2MQTT and a USB coordinator

domain: zigbee2mqtt.io · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. 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
  2. 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
  3. 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)
  4. 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})
  5. 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
  6. 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

Related routes

Create and manage a Zigbee2MQTT group to control multiple devices as one
iot · 5 steps · unrated
Integrate a custom device into Home Assistant using MQTT discovery so it appears automatically without manual YAML configuration
home-assistant.io · 6 steps · unrated
Add support for an unsupported Zigbee device to Zigbee2MQTT by writing an external converter
zigbee2mqtt.io · 6 steps · unrated

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans