Xiaomi Gateway 3 for Home Assistant

Home Assistant custom component for control Xiaomi Multimode Gateway (aka Gateway 3), Xiaomi Multimode Gateway 2, Aqara Hub E1 on default firmwares over LAN.

| Gateway | Model | Supported | |---------------------------------|-----------------------|-------------------| | Xiaomi Multimode Gateway (CN) | ZNDMWG03LM | yes | | Xiaomi Multimode Gateway (EU) | ZNDMWG02LM, YTC4044GL | yes | | Xiaomi Multimode Gateway 2 (CN) | DMWG03LM | yes | | Xiaomi Multimode Gateway 2 (EU) | ZNDMWG04LM, BHR6765GL | yes | | Aqara Hub E1 (CN) | ZHWG16LM | yes | | Xiaomi Gateway 2 (CN) | DGNWG02LM | no, goto | | Xiaomi Gateway (EU) | DGNWG05LM | no, goto |

Other. Aqara Hub E1 (EU), Aqara G2H (CN), Aqara H1 (CN), Aqara M1S (CN), Aqara M2 (CN), Aqara P3 (CN) | HE1-G01, ZNSXJ12LM, QBCZWG11LM, ZHWG15LM, ZHWG12LM, KTBL12LM - no, goto

Thanks to @Serrj for instruction how to enable Telnet on old firmwares. And thanks to an unknown researcher for instruction how to open telnet on new firmwares.

---

• Supported Firmwares
• Supported Devices
  • Add new device
• Installation
• Configuration
• Network configuration
• Regional Restrictions
• Statistics table
• Gateway controls
• Advanced config
  • Integration config
  • Devices config
  • Entities customize
• Zigbee Home Automation Mode
• Zigbee2MQTT Mode
• Zigbee custom firmware
• Handle Button Actions
• Handle BLE Locks
• Obtain Mi Home device token
• Multiple Hass
• Disable Buzzer
• How it works
• Troubleshooting
• Debug mode
• FAQ
• Useful links

Supported Firmwares

| Gateway | Firmwares | Required | |------------------------------------|---------------|---------------| | Xiaomi Multimode Gateway (CN/EU) | 1.5.0 - 1.5.4 | only Token | | Xiaomi Multimode Gateway 2 (CN/EU) | 1.0.3 - 1.0.6 | only Token | | Aqara Hub E1 (CN) | 4.0.1 | only Token | | Xiaomi Multimode Gateway (CN/EU) | 1.5.5 - 1.5.6 | Token and Key | | Xiaomi Multimode Gateway 2 (CN/EU) | 1.0.7 | Token and Key |

PS. Firmwares from 1.4.6 to 1.4.7 for Xiaomi Multimode Gateway may work but UNSUPPORTED. Please don't create issues if something doesn't work on them.

PS. For "only Token" firmwares integration will get Key automatically and save it to integration settings and to /config/.storage/xiaomi_gateway3/keys.json. Please save it safely somewhere else.

Recommended firmwares:

• Xiaomi Multimode Gateway (CN/EU) - 1.5.4 - 1.5.6
• Xiaomi Multimode Gateway 2 (CN/EU) - 1.0.6 - 1.0.7
• Aqara Hub E1 (CN) - 4.0.1

HOWTO get token read here

HOWTO get key

| Gateway | Situation | Solution | |-----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|----------------------------------------------------------------------| | Xiaomi Multimode Gateway (CN/EU) | firmware 1.5.4 and lower | setup integration and use only Token | | Xiaomi Multimode Gateway 2 (CN/EU) | firmware 1.0.6 and lower | setup integration and use only Token | | Aqara Hub E1 (CN) | firmware 4.0.1 and lower | setup integration and use only Token | | Xiaomi Multimode Gateway (CN/EU) | firmware 1.5.5 and more, but shipped from the factory with firmware 1.4.6 and lower | use button click method | | Xiaomi Multimode Gateway (CN/EU), Xiaomi Multimode Gateway 2 (CN/EU), Aqara Hub E1 (CN) | worked previously in the Hass, but you updated it to latest firmware | use button click method | | Xiaomi Multimode Gateway (CN/EU) | firmware 1.5.5 and more, never worked in the Hass | use UART | | Xiaomi Multimode Gateway 2 (CN/EU) | firmware 1.0.7 and more, never worked in the Hass | use UART | | Aqara Hub E1 (CN) | firmware 4.0.4 and more, never worked in the Hass | no solution |

• Read more https://github.com/AlexxIT/Blog/issues/13

For Xiaomi Multimode Gateway you also can:

• optional update firmware via Telnet
• optional install custom firmware

Please, not ask me why you need it.

Supported Devices

Gateway Zigbee chip can work in three modes:

1. Mi Home (default)

• Support Xiaomi/Aqara Zigbee devices simultaneously in Mi Home and Hass
• Support some Zigbee devices from other brands only in Hass

2. Zigbee Home Automation (ZHA)

• Support for Zigbee devices of hundreds of brands only in Hass (read more)

3. Zigbee2mqtt

• Support for Zigbee devices of hundreds of brands in MQTT (read more)

Zigbee devices in ZHA or z2m modes doesn't controlled by this integration!

Xiaomi BLE and Mesh devices works simultaneously in Mi Home and Hass. No matter which zigbee mode is used.

Matter devices supported only for Xiaomi Multimode Gateway 2 (EU) with fw 1.0.7_0019 and higher.

Some BLE devices may or may not have battery data depending on the device firmware.

Gateway entity shows connection state to gateway. It has many useful information in attributes.

Zigbee, BLE, Mesh and Matter devices has optional zigbee, ble, mesh, matter that shows last_report time in state and may useful intormation in attributes.

Add new device

You can change the operation of an existing device or add support for any Xiaomi Zigbee, Xiaomi BLE, Xiaomi Mesh or any other brand Zigbee device by writing an external converter.

It is welcomed if you return a working converter to integration. You can create an issue or make a pull request.

Installation

HACS > Integrations > Plus > XiaomiGateway3 > Install

Or manually copy xiaomi_gateway3 folder from latest release to /config/custom_components folder.

Configuration

Settings > Integrations > Add Integration > Xiaomi Gateway3

If the integration is not in the list, you need to clear the browser cache.

You need to add integration two times:

1. Cloud version. It used ONLY to load tokens and names for your devices from cloud.
2. Gateway. It adds your gateway and all connected Zigbee, BLE and Mesh devices.

You may skip 1st step if you know token for you Gateway. If you have multiple Gateways - repeat step 2 for each of them.

You need gateway key only for Xiaomi Multimode Gateway on fw 1.5.5, read more.

ATTENTION: If you using two Hass with one gateway - you should use same integration version on both of them!

Network configuration

All settings are important or you may have an unstable operation of the gateway.

• Shared LAN between Gateway and Hass server. You may use VPN, but both IP-address should be in same network subnet!
• Open ping (accept ICMP) from Gateway to Router
• Fixed IP-address for Gateway on your Router
• Wi-Fi Router settings:
  • Fixed channel from 1 to 11
  • Channel width: 20MHz (don't use 4