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

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

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

• Read more AlexxIT/Blog#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.

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.

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.

HACS > Integrations > Plus > XiaomiGateway3 > Install

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

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!

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 40MHz)
  • Authentication: WPA2 (don't use WPA3)
• MikroTik Router settings:
  • Wireless > Security Profiles > Group Key Update: 01:00:00 (1 hour or more)
• Keenetic Router settings:
  • Disable "Airtime Fairness" for 2.4GHz
  • Disable "256-QAM" for 2.4GHz

With the following settings the operation of the gateway may be unstable: different subnets, closed ping to router, Wi-Fi channel 40MHz, WPA3.

Xiaomi Mijia Smart Multi-Mode Gateway has two models - ZNDMWG03LM (China) and ZNDMWG02LM/YTC4044GL (Euro). Both this models can be added to China or to Euro cloud servers.

PS. This is the ONLY Xiaomi/Aqara gateway that has the same internal model for the China and Euro versions - lumi.gateway.mgl03. So the Hass component and the Xiaomi cloud servers see no difference between the models.

Most older Xiaomi/Aqara Zigbee devices can also be added to China and to Euro cloud servers.

New Zigbee devices from E1 series can be added ONLY to China cloud servers. They supported in official Mi Home application.

New Zigbee devices from H1 and T1 series are not officially supported in Mi Home. But they can be added ONLY to China cloud servers. You can controll them from Hass (check supported list) but not from stock Mi Home application. Some of this model (mostly H1 switches and T1 relays) can be controlled from Mi Home by Vevs.

Some of Bluetooth BLE and Mesh can be added ONLY to China cloud. But with Mi Home by Vevs they can be added to any cloud.

PS. You can't add Zigbee devices E1/H1/T1 to Euro cloud even with Mi Home by Vevs.

If you control your devices from Home Assistant - it makes absolutely no difference which cloud they are added to. Devices are controlled locally and without delay in any case.

PS. Some Aqara devices are not supported at all in Mi Home in any version, e.g. Aqara Door Lock N100 Zigbee version.

Integration support multiple gateways in one MiHome account.

Zigbee devices can be attached (paired) to only one gateway. I recommend to split your Zigbee network into several gateways, so it will be more stable. I recommend not to mix battery and powered devices in the same network.

Bluetooth BLE and Mesh devices can work simultaneously with all gateways. In this technology, there is no binding to the gateway.

If a user has more than one Bluetooth Mesh Gateway on the network - only one will send Bluetooth device data to the cloud. But this integration can continue to collect Bluetooth data from all gateways simultaneously and locally.

Device info - displays device information in notification.

extra:
  cloud_fw: 2.1.1_0025               # device firmware from cloud integration
  cloud_name: Dev Presence Sensor 2  # device name from cloud integration
  did: '1005xxxxxx'                  # device ID from MiHome
  mac: 64:9e:31:xx:xx:xx
  market_brand: Linptech
  market_model: ES1ZB, linp.sensor_occupy.hb01
  market_name: Presence Sensor ES1
  rssi_54ef44xxxxxx: -69             # rssi for each gateway
  rssi_54ef55xxxxxx: -79
  seq: 185                           # message sequence number
  type: mesh                         # device type: gateway, zigbee, ble, mesh, group, matter
last_report:                         # last decoded report from device
  not_occupancy_duration: 11
last_report_gw:                      # the gateway that received the last report
  fw_ver: 1.0.7_0021
  host: 192.168.1.123
  mac: 54:ef:44:xx:xx:xx
  model: lumi.gateway.mcn001
  name: Gateway 2
last_report_ts: 48s                  # how long ago was the last message
last_seen:
  54ef44xxxxxx: 48s                  # how long ago each gateway seen device
  54ef55xxxxxx: 48s
listeners: 7                         # subscribers for device updates (internal logic)
model: 10441                         # device model (number for BLE and Mesh, string for Zigbee and Matter)
params:                              # all decoded params in one message
  action: away
  distance: 5.15
  illuminance: 237.0
  not_occupancy_duration: 11
  occupancy: false
  occupancy_duration: 0
ttl: 50m                             # time to live (TTL) - available timeout (maximum last_seen value)
uid: 649e31xxxxxx                    # hass UID - "12 hex mac" for BLE and Mesh, "0x + 16 hex IEEE" for Zigbee 

Device update - manual call for device params update. Don't work for many Zigbee battery devices. Don't work for all BLE devices. Don't work for offline Mesh devices.

Zigbee reconfig - start the initial setup process for 3rd party Zigbee devices

Delete device - manual call leave command for Zigbee devices. Important! Hass device will be automatically removed only when device leave network. You need to wake up the battery device so it can receive leave command.

1. To enable stats sensors go to:

   • Settings > Integrations > Xiaomi Gateway 3 > Options > Add statistic sensors

2. Install Flex Table from HACS

3. Add new Lovelace tab with Panel Mode

4. Add new Lovelace card:

   • example 1
   • example 2

Gateway binary sensor

• sensor shows connection to gateway, so you can check the stability of your Wi-Fi
• radio_tx_power - zigbee chip power
• radio_channel - zigbee chip channel
• free_mem - gateway free memory in bytes
• load_avg - gateway CPU /proc/loadavg
• rssi - gateway Wi-Fi signal strength
• uptime - gateway uptime after reboot

Read more about additional attributes from openmiio.

Available commands:

• Gateway run FTP - enable FTP on gateway
• Gateway reboot - reboot gateway
• Gateway disable/enable - just for test, so you can check gateway offline logic
• OpenmiIO reload - restart openmiio app on gateway
• Zigbee pairing - start the process of adding a new zigbee device
  • you can also start the process by pressing the physical button on the gateway three times
  • you can also start the process from the Mi Home app
• Zigbee force pairing - similar to default pairing, but without cloud verification of the device. So some unsupported lumi devices can be added this way. But they still won't work without a proper converter.
• Zigbee parent scan - update the zigbee parents info manually (it updates automatically every 1h when stats sensors enabled)

Only for Xiaomi Multimode Gateway 1:

• Gateway firmware Lock - block the gateway firmware update (read more)
• Zigbee flash EZSP - update zigbee chip firmare (incompatible with MiHome mode)

Settings > Integrations > Xiaomi Gateway 3 > CONFIGURE

• Host - gateway IP-address, should be fixed on your Wi-Fi router
• Token - gateway Mi Home token, changed only when you add gateway to Mi Home app
• Key - gateway secret key, read more
• Add statistic sensors - read more
• Debug logs - enable different levels of logging (read more)