Xiaomi Gateway 3 integration for Home Assistant

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.

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)

Supported Zigbee Devices

Tested Devices:

• Aqara Bulb (ZNLDP12LM)
• Aqara Button (WXKG11LM)
• Aqara Cube (MFKZQ01LM)
• Aqara Door Sensor (MCCGQ11LM)
• Aqara Double Wall Button (WXKG02LM)
• Aqara Motion Sensor (RTCGQ11LM)
• Aqara Opple Six Button (WXCJKG13LM)
• Aqara Relay (LLKZMK11LM)
• 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.

Supported BLE Devices

Demo video:

Tested Devices:

• Xiaomi Door Sensor 2 (MCCGQ02HL)
• Xiaomi Flower Monitor (HHCCJCY01)
• 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.

Install

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.

Config

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.

Advanced config

Support custom occupancy timeout for motion sensor. Default 90 seconds.

xiaomi_gateway3:
  devices:
    '0x158d00044c5dff':
      occupancy_timeout: 90  # (optional) default 90 seconds

Handle BLE Locks

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

Email 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'] }}

How it works

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.

Debug mode

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