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.

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.

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:

HOWTO get token read here

HOWTO get key

Please, not ask me why you need it.

Gateway Zigbee chip can work in three modes:

1. Mi Home (default)

2. Zigbee Home Automation (ZHA)

3. Zigbee2mqtt

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:

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.

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.

To enable stats sensors go to:

Install Flex Table from HACS

Add new Lovelace tab with Panel Mode

Add new Lovelace card:

Gateway binary sensor

Read more about additional attributes from openmiio .

Available commands:

Only for Xiaomi Multimode Gateway 1:

Settings > Integrations > Xiaomi Gateway 3 > CONFIGURE

This options configured in the configuration.yaml . Section: xiaomi_gateway3 > devices > IEEE or MAC .

As a device you can specify:

Overwrite device model

This is useful if:

xiaomi_gateway3:
  devices:
    "0x00158d0001d82999":  # match device by IEEE or MAC
      model: 01MINIZB

Change switch to light

Depending on the model of the device, your entity may be called: switch , plug , outlet , channel_1 , etc.

xiaomi_gateway3:
  devices:
    "0x00158d0001d82999":  # match device by IEEE or MAC
      entities:
        channel_1: light   # change entity domain (switch to light)

Create sensors from attributes

xiaomi_gateway3:
  devices:
    "lumi.sensor_motion.aq2":  # match device by model
      entities:
        zigbee: sensor         # adds stat entity only for this device
        parent: sensor         # adds entity from attribute value
        linkquality: sensor    # adds entity from attribute value

Change device or entity name

Attention! You can change device name, entity name and entity_id safely from GUI. But if you want, you can change the device name and the entity_id part of the YAML.

xiaomi_gateway3:
  devices:
    "0x00158d0001d82999":  # match device by IEEE or MAC
      name: Kitchen Refrigerator         # overwrite device name
      entity_name: kitchen_refrigerator  # overwrite entity_id part

Additional attributes for entities

Useful if you want to:

Attention! Template is calculated only at the start of the Hass.

xiaomi_gateway3:
  attributes_template: |
    {% if attr in ('zigbee', 'ble', 'mesh') %}
      "integration": "gw3",
      "name": device.human_name,
      "device_fw_ver": device.firmware,
      "device_model": device.model,
      "device_market_model": device.human_model,
      "device_manufacturer": device.extra.market_brand,
      "gate": gateway.human_name,
      "gateway_model": gateway.model,
      "gateway_fw_ver": gateway.firmware
    {% elif attr == 'gateway' %}
      "integration": "gw3",
      "gate": gateway.human_name,
      "gateway_model": gateway.human_model,
      "gateway_fw_ver": gateway.firmware
    {% elif attr == 'battery' %}
      "integration": "gw3",
      "name": device.human_name,
      "gate": gateway.human_name,
      "battery": "true"
    {% endif %}

Occupancy timeout for moving sensor.

xiaomi_gateway3:
  devices:
    "0x00158d0003456789":
      occupancy_timeout: 180  # simple mode
    "0x00158d0003456788":
      occupancy_timeout: -120  # fast back mode
    "0x00158d0003456787":
      occupancy_timeout: [-120, 240, 300]  # progressive timer
    "0x00158d0003456786":
      occupancy_timeout: 1  # for hacked 5 sec sensors

Invert state for contact sensor.

xiaomi_gateway3:
  devices:
    "0x00158d0003456789":
      invert_state: 1  # any non-empty value will reverse the logic

Zigbee bulb default transition .

xiaomi_gateway3:
  devices:
    "0x86bd7fffe0000000":
      default_transition: 5

Zigbee Home Automation (ZHA) is a standard Home Assistant component for managing Zigbee devices.

Note: ZHA developers do not recommend using ZHA with EZSP radios for WiFi-based bridges because of possible stability problems. But a range of users use the gate in this mode without issues.

Starting with version 3, there is no operation mode switch. To turn it on, configure the ZHA integration. To turn off, remove the ZHA integration. Sometimes it is necessary to reset the gateway to factory settings.

Settings > Integrations > Add > Zigbee Home Automation > EZSP:

When you turn on ZHA mode - Zigbee devices in Mi Home will stop working. BLE and Mesh devices will continue to work in Mi Home and Hass.

Zigbee devices will not migrate from Mi Home to ZHA. You will need to pair them again with ZHA.

IMPORTANT . According to real user reviews zigbee2mqtt does not work well with EFR32 chips. More positive feedback when working with ZHA.

Zigbee2MQTT is a bigest project that support hundreds Zigbee devices from different vendors. And can be integrate with a lot of home automation projects.

Note: The zigbee chip of this gateway (EFR32 EZSP) is supported in zigbee2mqtt in experimental mode .

Starting with version 3, there is no operation mode switch. To turn it on, configure the z2m add-on. To turn off, remove the z2m add-on. Sometimes it is necessary to reset the gateway to factory settings.

Unlike the ZHA you should install to your host or Hass.io system: Mosquitto broker and Zigbee2MQTT Addon . Also you should setup MQTT integration.

serial:
  port: tcp://{gatewayIP}:8888
  adapter: ezsp

When you turn on Zigbee2MQTT mode - Zigbee devices in Mi Home will stop working. BLE and Mesh will continue to work in Mi Home and Hass.

Zigbee devices will not migrate from Mi Home to Zigbee2MQTT. You will need to pair them again.

You can use this mode with thanks to @kirovilya - developed support EFR32 chips in z2m project

Xiaomi Multimode Gateway support flashing custom firmware for Zigbee chip. It works only with ZHA/z2m modes. And it can increase the stability of the network, because this gateway uses pretty glitchy hardware. The other gateways have no hardware problems and do not require custom zigbee firmware.

You can flash custom firmware from Gateway select entity.

To return to MiHome mode - be sure to flash the default firmware!

It is possible because of these people:

Buttons, vibration sensor, cube, locks and other - create an action entity. The entity changes its state for half a second and returns to an empty state. The attributes contain useful data, they are not cleared after the event is triggered.

Depending on the button model, its state may be:

Your button may not have all of these options! Check available values in action -sensor attributes when you interact with button.

automation:
- alias: Turn off all lights
  trigger:
  - platform: state
    entity_id: sensor.0x158d0002fa99fd_action  # change to your button
    to: button_1_single  # change to your button state
  action:
  - service: light.turn_off
    entity_id: all
  mode: single

Read more in wiki .

You can run beeper/buzzer with service:

service: alarm_control_panel.alarm_trigger
data:
  code: "10,3"  # 10 seconds, volume 3
target:
  entity_id: alarm_control_panel.gateway_alarm

Video DEMO

You can use this integration to get a token for any of your Xiaomi devices . You don't need to have Xiaomi Gateway 3. Just install and add the integration, enter the username / password from your Mi Home account. And use the integration settings to view your account's device tokens.

Also you can get:

It's safe to use multiple Hass servers (main and reserve) with integration, but:

The component enables Telnet on Gateway via Miio protocol .

Starting with version 3, the component installs a special daemon application on the gateway - openmiio_agent . You can read more in the separate project repository.

After rebooting the gateway, all changes will be reset. The component will launch Telnet and daemon every time it detects that they are disabled.

Put your Gateways and your child bluetooth/zigbee devices far away from USB 3.0 devices and cables, SSDs, WiFi routers , etc. USB3 hub can almost completely block the Zigbee signal from your Xiaomi Plug up to 20 centimeters away.

Can't connect to gateway

Lost connection with Zigbee and Bluetooth devices

Logging can be setup from:

1. Integration config (GUI)

Enable:

2. Integration config (YAML)

Component can log different debug events from different gateways. You can set global debug_mode for all gateways or config custom modes for custom gateways from GUI.

Recommended config:

xiaomi_gateway3:
  logger:
    filename: xiaomi_gateway3.log  # default empty
    propagate: False               # if False - disable log to home-assistant.log and console, default True
    max_bytes: 100000000           # file size, default 0
    backup_count: 3                # file rotation count, default 0

Additional settings

    level: debug  # default
    mode: a       # a - append to file, w - write new file, default
    format: "%(asctime)s %(levelname)s [%(name)s] %(message)s"  # default

3. Hass default config

You can set custom modes for custom gateways from GUI. Witout custom modes you won't see gateways logs.

logger:
  logs:
    custom_components.xiaomi_gateway3: debug

Q. Does this integration support Xiaomi Robot Vacuum, Xiaomi Philips Bulb...?
A. No. The integration does not support Xiaomi Wi-Fi devices.

Q. Which Mi Home region is best to use?
A. Most devices are supported in the China region. In European regions the new Zigbee devices E1/H1/T1-series and some Mesh devices may not work. Read more about regional restrictions .

Q. What do multimode gateway beeps mean?
A. Beeps AFTER adding Zigbee devices:

Also, if you are using hacked motion sensor - the gateway will periodically beeps. You can disable it .

Q. Does the integration work without internet?
A. Partially. The component connects to a hub on the local network. Adding new devices from/to Mi Home requires Internet.

Q. Does the integration support non Xiaomi Zigbee devices?
A. Yes. There are three ways to connect third party Zigbee devices. All methods have a different set of supported devices. There is no exact supported list. Don't expect absolutely every device on the market to be supported in any of these methods.

Q. Will the Zigbee devices continue to work in Mi Home?
A. Yes. If you do not enable ZHA or z2m mode, the devices will continue to work in Mi Home. And you can use automation in both Mi Home and Hass.

Q. Do I need to receive a token or enable Telnet manually?
A. No. The token is obtained automatically using the login / password from the Mi Home account. Telnet turns on automatically using token.

Q. Should I open or solder the hub?
A. No.

Q. Should I use ZHA mode?
A. You decide. If all of your Zigbee devices are supported in Mi Home, it is best to use it. If you have two hubs - you can use one of them in Mi Home mode, and the second in ZHA mode. Or you can also use the hub in Mi Home mode with Xiaomi devices and a Zigbee USB Dongle for other Zigbee devices.

Q. How many Zigbee devices does the hub support?
A. The hub can connect directly up to 32 battery-powered devices (end devices). And additionaly up to 26 powered devices (routers). Other devices on your network can work through routers. The maximum number of devices is unknown. Official Xiaomi documentation writes about 128 devices.

Q. Why does the two-button switch only have one entity action?
A. All button clicks are displayed in the status of that one entity.