What it exposes
| Feature | Property | Values | Control |
|---|---|---|---|
| Battery | battery | % · 0…100 | read only |
| Voltage | voltage | mV | read only |
| Presence | presence | — | read only |
| Illuminance | illuminance | lx | read only |
| Humidity | humidity | % | read only |
| Temperature | temperature | °C | read only |
| Presence sensitivity | presence_sensitivity | low, medium, high | settable |
| Absence delay timer | absence_delay_timer | sec · 10…300 | settable |
| Spatial learning | spatial_learning | Start Learning | settable |
| Restart device | restart_device | Restart Device | settable |
| Ai interference source selfidentification | ai_interference_source_selfidentification | — | settable |
| Ai sensitivity adaptive | ai_sensitivity_adaptive | — | settable |
| Temp and humidity sampling | temp_and_humidity_sampling | off, low, medium, high, custom | settable |
| Temp and humidity sampling period | temp_and_humidity_sampling_period | sec · 0.5…3600 | settable |
| Temp reporting interval | temp_reporting_interval | sec · 600…3600 | settable |
| Temp reporting threshold | temp_reporting_threshold | °C · 0.2…3 | settable |
| Temp reporting mode | temp_reporting_mode | threshold, reporting interval, threshold and interval | settable |
| Humidity reporting interval | humidity_reporting_interval | sec · 600…3600 | settable |
| Humidity reporting threshold | humidity_reporting_threshold | % · 2…15 | settable |
| Humidity report mode | humidity_report_mode | threshold, reporting interval, threshold and interval | settable |
| Light sampling | light_sampling | off, low, medium, high, custom | settable |
| Light sampling period | light_sampling_period | sec · 0.5…3600 | settable |
| Light reporting interval | light_reporting_interval | sec · 20…3600 | settable |
| Light reporting threshold | light_reporting_threshold | % · 3…20 | settable |
| Light report mode | light_report_mode | threshold, reporting interval, threshold and interval | settable |
| Track target distance | track_target_distance | start_tracking_distance | settable |
| Target distance | target_distance | m | read only |
| Detection range | detection_range | m · 0…6 | settable |
| Led disabled night | led_disabled_night | — | settable |
| Identify | identify | identify | settable |
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:
{
"battery": 87,
"voltage": 2950,
"presence": false,
"illuminance": 120,
"humidity": 46.2,
"temperature": 21.6,
"presence_sensitivity": "low",
"absence_delay_timer": 155,
"spatial_learning": "Start Learning",
"restart_device": "Restart Device",
"ai_interference_source_selfidentification": false,
"ai_sensitivity_adaptive": false,
"temp_and_humidity_sampling": "off",
"temp_and_humidity_sampling_period": 1800,
"linkquality": 120
}
Send commands to zigbee2mqtt/my_device/set:
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"presence_sensitivity":"medium"}'
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"ai_interference_source_selfidentification":true}'
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"ai_sensitivity_adaptive":true}'
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"temp_and_humidity_sampling":"low"}'
mosquitto_pub -t zigbee2mqtt/my_device/set -m '{"temp_reporting_mode":"reporting interval"}'
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.