Control Zigbee devices from Home Assistant with Xiaomi Gateway 3 (ZNDMWG03LM) on original firmware.
Gateway support Zigbee 3, Bluetooth Mesh and HomeKit.
This method does not change the device firmware. Gateway continues to work with Mi Home and HomeKit.
Real user config with 3 Gateways
Thanks to @Serrj for instruction how to enable Telnet on this device.
Important: This component does not work with:
- Xiaomi Gateway 2 (DGNWG02LM, lumi.gateway.v3) - use this component
- Xiaomi Gateway EU (DGNWG05LM, lumi.gateway.mieu01)
Attention: component works with the ZNDMWG03LM model and firmwares v1.4.6_0012 and v1.4.6_0030. When new firmwares appear - do not update until someone tell you that it is safe!
- Supported Zigbee Devices
- Supported BLE Devices
- Install
- Config
- Advanced config
- Add and remove Zigbee devices
- Add third-party Zigbee devices
- Zigbee Home Automation Mode
- Handle Button Actions
- Handle BLE Locks
- How it works
- Debug mode
Tested Devices:
- Aqara Bulb (ZNLDP12LM)
- Aqara Button (WXKG11LM)
- Aqara Cube (MFKZQ01LM)
- Aqara Curtain (ZNCLDJ11LM)
- Aqara Door Sensor (MCCGQ11LM)
- Aqara Double Wall Button (WXKG02LM)
- Aqara Motion Sensor (RTCGQ11LM)
- Aqara Opple Six Button (WXCJKG13LM)
- Aqara Relay (LLKZMK11LM)
- Aqara Roller Shade (ZNGZDJ11LM)
- Aqara Socket (QBCZ11LM)
- Aqara Vibration Sensor (DJT11LM)
- Aqara Wall Double Switch (QBKG03LM)
- Aqara Water Leak Sensor (SJCGQ11LM)
- IKEA Bulb E14
- Xiaomi Button (WXKG01LM)
- Xiaomi Door Sensor (MCCGQ01LM)
- Xiaomi Light Sensor (GZCGQ01LM)
- Xiaomi Motion Sensor (RTCGQ01LM)
- Xiaomi Plug (ZNCZ02LM)
- Xiaomi Plug EU (ZNCZ04LM)
- Xiaomi TH Sensor (WSDCGQ01LM)
Currently supported, but not tested other Xiaomi and Aqara Zibee devices officially supported by the Gateway. Check list here.
Plans to support for Zigbee devices from other manufacturers. May be support for ZHA.
Demo video:
Tested Devices:
- Aqara N100 Smart Door Lock
- Xiaomi Door Sensor 2 (MCCGQ02HL)
- Xiaomi Flower Monitor (HHCCJCY01)
- Xiaomi Loock Smart Lock
- Xiaomi Rubik's Cube (XMMF01JQD) - don't sends edge info, only direction!
- Xiaomi TH Sensor (LYWSD03MMC)
- Xiaomi TH Sensor (LYWSDCGQ/01ZM)
- Xiaomi TH Watch (LYWSD02MMC)
Currently supported, but not tested, other Xiaomi BLE devices officially supported by the Gateway with these attributes:
temperature, humidity, motion, illuminance, moisture, conductivity, formaldehyde, mosquitto, battery
BLE devices and their attributes do not appear immediately! And don't save their data across HA reboots! Their data is updated only when the device itself sends them. Temperature, humidity and battery may refresh at different times.
HOWTO video:
You can install component with HACS custom repo (example): AlexxIT/XiaomiGateway3
.
Or manually copy xiaomi_gateway3
folder from latest release to custom_components
folder in your config folder.
With GUI. Configuration > Integration > Xiaomi Gateway 3. And enter Gateway IP address and Mi Home token.
You need obtain Mi Home token. I am using the method with Mi Home v5.4.54 for non-rooted Android. If you don't have an Android - you can install the emulator on Windows.
Attention: The component is under active development. Breaking changes may appear.
Support custom occupancy timeout for motion sensor. Default 90 seconds.
xiaomi_gateway3:
devices:
'0x158d00044c5dff':
occupancy_timeout: 90 # (optional) default 90 seconds
To enter the pairing mode, turn on the switch Xiaomi Gateway 3 Pair. Pairing lasts 60 seconds.
After successfully adding the device, the Gateway will sound two long beeps.
If the addition was unsuccessful, for example, an unsupported device, the Gateway will sound three short beeps.
To delete a device from Hass and from Gateway - you need to rename device to delete. Just the device, not its objects!
Video Demo
Attention 1: Only devices similar to Xiaomi devices will work!
Attention 2: After the first pairing, Mi Home remembers the selected device model. And with the next pairings, it will show old interface, even if you change the model. Hass will take the new device model on the next pairings.
To add a custom device, you need to call the service remote.send_command
with params:
entity_id: remote.0x680ae2fffe123456_pair # change to your Gateway remote
command: pair
device: ikea.light.led1623g12 # change to your device model
You need to choose the most similar Xiaomi model for your device from this file.
For example, for a lamp or dimmer - choose an IKEA lamp ikea.light.led1623g12
.
Sometimes it doesn't work the first time and you need to try pairing again.
The devices added in this way will work even after the Gateway is restarted. They will continue to work without Hass. And they can be used in Mi Home automations.
You can discuss the feature here.
Video Demo
Zigbee Home Automation (ZHA) is a standard Home Assistant component for managing Zigbee devices. It works with various radio modules such as CC2531, Conbee II, Tasmoted Sonoff ZBBridge and others.
Important: ZHA component is in early development stage. Don't expect it to work well with all devices.
Attention: ZHA mode cannot work simultaneously with Mi Home!
When you turn on ZHA mode - zigbee devices in Mi Home will stop working. Bluetooth devices will continue to work.
To switch the mode - delete the old integration and configure the new one in a different mode. Zigbee devices will not migrate from Mi Home to ZHA. You will need to pair them again with ZHA.
You can change the operating mode at any time. Just remove the old integration and set up the new one. Your gateway firmware does not change! Just reboot the gateway and it is back in stock.
When switching from ZHA to Mi Home mode - restart the gateway. When switching from Mi Home to ZHA - no reboot required.
Thanks to @zvldz for help with socat.
Buttons, vibration sensor, cube, locks and other - create an action entity. The entity changes its state for a split second and returns to an empty state. The attributes contain useful data, they are not cleared after the event is triggered.
automation:
- alias: Turn off all lights
trigger:
- platform: state
entity_id: sensor.0x158d0002fa99fd_action
to: button_1_single
action:
- service: light.turn_off
entity_id: all
mode: single
BLE locks have an action entity, just like buttons.
The state changes to door
, lock
, fingerprint
, armed
when an event occurs. Details of the event are in the entity attributes.
action
: fingerprint
key_id
- Key ID in full hex formataction_id
: 0,message
: Match successfulaction_id
: 1,message
: Match failedaction_id
: 2,message
: Timeoutaction_id
: 3,message
: Low qualityaction_id
: 4,message
: Insufficient areaaction_id
: 5,message
: Skin is too dryaction_id
: 5,message
: Skin is too wet
action
: door
action_id
: 0,message
: Door is openaction_id
: 1,message
: Door is closedaction_id
: 2,message
: Timeout is not closedaction_id
: 3,message
: Knock on the dooraction_id
: 4,message
: Breaking the dooraction_id
: 5,message
: Door is stuck
action
: lock
key_id
- Key ID in short decimal formataction_id
: 0,message
: Unlock outside the dooraction_id
: 1,message
: Lockaction_id
: 2,message
: Turn on anti-lockaction_id
: 3,message
: Turn off anti-lockaction_id
: 4,message
: Unlock inside the dooraction_id
: 5,message
: Lock inside the dooraction_id
: 6,message
: Turn on child lockaction_id
: 7,message
: Turn off child lockmethod_id
: 0,method
: bluetoothmethod_id
: 1,method
: passwordmethod_id
: 2,method
: biologicalmethod_id
: 3,method
: keymethod_id
: 4,method
: turntablemethod_id
: 5,method
: nfcmethod_id
: 6,method
: one-time passwordmethod_id
: 7,method
: two-step verificationmethod_id
: 8,method
: coercionmethod_id
: 10,method
: manualmethod_id
: 11,method
: automatickey_id
: 0xc0de0000,error
: Frequent unlocking with incorrect passwordkey_id
: 0xc0de0001,error
: Frequent unlocking with wrong fingerprintskey_id
: 0xc0de0002,error
: Operation timeout (password input timeout)key_id
: 0xc0de0003,error
: Lock pickingkey_id
: 0xc0de0004,error
: Reset button is pressedkey_id
: 0xc0de0005,error
: The wrong key is frequently unlockedkey_id
: 0xc0de0006,error
: Foreign body in the keyholekey_id
: 0xc0de0007,error
: The key has not been taken outkey_id
: 0xc0de0008,error
: Error NFC frequently unlockskey_id
: 0xc0de0009,error
: Timeout is not locked as requiredkey_id
: 0xc0de000a,error
: Failure to unlock frequently in multiple wayskey_id
: 0xc0de000b,error
: Unlocking the face frequently failskey_id
: 0xc0de000c,error
: Failure to unlock the vein frequentlykey_id
: 0xc0de000d,error
: Hijacking alarmkey_id
: 0xc0de000e,error
: Unlock inside the door after armingkey_id
: 0xc0de000f,error
: Palmprints frequently fail to unlockkey_id
: 0xc0de0010,error
: The safe was movedkey_id
: 0xc0de1000,error
: The battery level is less than 10%key_id
: 0xc0de1001,error
: The battery is less than 5%key_id
: 0xc0de1002,error
: The fingerprint sensor is abnormalkey_id
: 0xc0de1003,error
: The accessory battery is lowkey_id
: 0xc0de1004,error
: Mechanical failure
Write me if the values are wrong somewhere. I translated from Chinese documentation.
Example of several automations:
automation:
- alias: Doorbell
trigger:
platform: state
entity_id: sensor.ble_1010274797_action
to: door
condition:
condition: template
value_template: "{{ trigger.to_state.attributes['action_id'] == 3 }}"
action:
service: persistent_notification.create
data_template:
title: Doorbell
message: The doorbell is ringing
- alias: Lock Error
trigger:
platform: state
entity_id: sensor.ble_1010274797_action
to: lock
condition:
condition: template
value_template: "{{ trigger.to_state.attributes['error'] }}"
action:
service: persistent_notification.create
data_template:
title: Lock ERROR
message: "{{ trigger.to_state.attributes['error'] }}"
- alias: Open lock
trigger:
platform: state
entity_id: sensor.ble_1010274797_action
to: lock
condition:
condition: template
value_template: "{{ trigger.to_state.attributes['action_id'] == 0 }}"
action:
service: persistent_notification.create
data_template:
title: Lock is open
message: |
Opening method: {{ trigger.to_state.attributes['method'] }}
User ID: {{ trigger.to_state.attributes['key_id'] }}
The component enables Telnet on Gateway via Miio protocol. Only this Gateway supports this command. Do not try to execute it on other Xiaomi/Aqara Gateways.
The component starts the MQTT Server on the public port of the Gateway. All the logic in the Gateway runs on top of the built-in MQTT Server. By default, access to it is closed from the outside.
ATTENTION: Telnet and MQTT work without a password! Do not use this method on public networks.
After rebooting the device, all changes will be reset. The component will launch Telnet and public MQTT every time it detects that they are disabled.
Component support debug mode. Shows only component logs. The link to the logs is always random.
Demo video of my other component, but the idea is the same:
With debug: bluetooth
or debug debug: mqtt
option you will get advanced log for raw BLE and MQTT data.
With debug: true
option you will get usual component logs.
xiaomi_gateway3:
debug: true # you will get HA notification with a link to the logs page
You can filter data in the logs and enable auto refresh (in seconds).
http://192.168.1.123:8123/c4e99cfc-0c83-4a39-b7f0-278b0e719bd1?q=ble_event&r=2