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 format
• action_id: 0, message: Match successful
• action_id: 1, message: Match failed
• action_id: 2, message: Timeout
• action_id: 3, message: Low quality
• action_id: 4, message: Insufficient area
• action_id: 5, message: Skin is too dry
• action_id: 5, message: Skin is too wet

action: door

• action_id: 0, message: Door is open
• action_id: 1, message: Door is closed
• action_id: 2, message: Timeout is not closed
• action_id: 3, message: Knock on the door
• action_id: 4, message: Breaking the door
• action_id: 5, message: Door is stuck

action: lock

• key_id - Key ID in short decimal format
• action_id: 0, message: Unlock outside the door
• action_id: 1, message: Lock
• action_id: 2, message: Turn on anti-lock
• action_id: 3, message: Turn off anti-lock
• action_id: 4, message: Unlock inside the door
• action_id: 5, message: Lock inside the door
• action_id: 6, message: Turn on child lock
• action_id: 7, message: Turn off child lock
• method_id: 0, method: bluetooth
• method_id: 1, method: password
• method_id: 2, method: biological
• method_id: 3, method: key
• method_id: 4, method: turntable
• method_id: 5, method: nfc
• method_id: 6, method: one-time password
• method_id: 7, method: two-step verification
• method_id: 8, method: coercion
• method_id: 10, method: manual
• method_id: 11, method: automatic
• key_id: 0xc0de0000, error: Frequent unlocking with incorrect password
• key_id: 0xc0de0001, error: Frequent unlocking with wrong fingerprints
• key_id: 0xc0de0002, error: Operation timeout (password input timeout)
• key_id: 0xc0de0003, error: Lock picking
• key_id: 0xc0de0004, error: Reset button is pressed
• key_id: 0xc0de0005, error: The wrong key is frequently unlocked
• key_id: 0xc0de0006, error: Foreign body in the keyhole
• key_id: 0xc0de0007, error: The key has not been taken out
• key_id: 0xc0de0008, error: Error NFC frequently unlocks
• key_id: 0xc0de0009, error: Timeout is not locked as required
• key_id: 0xc0de000a, error: Failure to unlock frequently in multiple ways
• key_id: 0xc0de000b, error: Unlocking the face frequently fails
• key_id: 0xc0de000c, error: Failure to unlock the vein frequently
• key_id: 0xc0de000d, error: Hijacking alarm
• key_id: 0xc0de000e, error: Unlock inside the door after arming
• key_id: 0xc0de000f, error: Palmprints frequently fail to unlock
• key_id: 0xc0de0010, error: The safe was moved
• key_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 abnormal
• key_id: 0xc0de1003, error: The accessory battery is low
• key_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