What it exposes
| Feature | Property | Values | Control |
|---|---|---|---|
| On / off | state | absence, presence, disabled | read only |
| Presence | presence | — | read only |
| Current status | current_status | approaching, departing, clear | read only |
| Illuminance | illuminance | lx | read only |
| Hold delay time | hold_delay_time | s · 0…300 | settable |
| Sensitivity | sensitivity | low, medium, high | settable |
| Trigger distance | trigger_distance | m · 0.5…4 | settable |
| Forbidden area | forbidden_area | m · 0…1.8 | settable |
| AI environment self-learning | ai_self_learning | AI self-learning | settable |
| Fast setting | fast_setting | small, medium, large | settable |
| LED indicator | indicator | — | settable |
| Sensor mode | sensor_mode | presence, motion | settable |
| Single mode | single_mode | — | settable |
| Absence circling report | absence_circling_report | — | settable |
| Absence circling interval | absence_circling_interval | min · 2…30 | settable |
| Find device | find_device | — | settable |
| Enable sensor | enable_sensor | — | settable |
| Factory reset | factory_reset | factory reset | settable |
| Lux mode | lux_mode | threshold, report | settable |
| Daylight threshold | daylight_threshold | lux · 1…3000 | settable |
| Lux report mode | lux_report_mode | timed, difference | settable |
| Lux timed interval | lux_timed_interval | s · 5…3600 | settable |
| Lux difference threshold | lux_difference_threshold | lux · 1…2000 | settable |
| Lux difference value | lux_difference_value | — | read only |
| Interference positions | interference_positions | — | read only |
| Home environment | home_environment | normal, slight, strong, severe | read only |
MQTT: state and commands
Zigbee2MQTT publishes the device state to zigbee2mqtt/my_device (my_device is the name you give the device). An example message:
{
"state": "absence",
"presence": false,
"current_status": "approaching",
"illuminance": 120,
"hold_delay_time": 150,
"sensitivity": "low",
"trigger_distance": 2,
"forbidden_area": 1,
"ai_self_learning": "AI self-learning",
"fast_setting": "small",
"indicator": false,
"sensor_mode": "presence",
"single_mode": false,
"absence_circling_report": false,
"linkquality": 120
}
Send commands to zigbee2mqtt/my_device/set:
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"sensitivity":"medium"}'
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"fast_setting":"medium"}'
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"indicator":true}'
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"sensor_mode":"motion"}'
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"single_mode":true}'
Watch the topics live from the browser: MQTT client.
Home Assistant automation example
Zigbee2MQTT creates Home Assistant entities from the device name. If it is called my_device, an automation in automations.yaml can look like this:
- alias: "Light on motion"
mode: single
triggers:
- trigger: state
entity_id: binary_sensor.my_device_presence
to: "on"
conditions:
- condition: sun
after: sunset
actions:
- action: light.turn_on
target:
entity_id: light.hallway
Check the YAML: YAML checker.
How to pair it
- In Zigbee2MQTT click Permit join.
- Put the device in pairing mode: usually a long press of the reset button (5–10 s) until the LED blinks; bulbs: switch the power off and on 5–6 times.
- Keep the device close to the coordinator or a router while pairing.
- Give it a clear name: MQTT topics and Home Assistant entities are built from it.
Exact procedure and model notes: the device page in the Zigbee2MQTT docs. No coordinator yet: coordinator picker.