Xiaomi Gateway 3 for Home Assistant

Gateway	Xiaomi Mijia Smart Multi-Mode Gateway	Aqara Hub E1	Aqara Camera Hub G3
China model	ZNDMWG03LM supported	ZHWG16LM in development	ZNSXJ13LM in plans (waiting)
Euro model	ZNDMWG02LM supported	HE1-G01 can't be supported	CH-H03 don't know yet
Mi Home	yes	yes	no
Aqara Home	no	no	yes
Xiaomi/Aqara Zigbee	yes	yes
Xiaomi Bluetooth BLE	yes	no
Xiaomi Bluetooth Mesh	yes	no

Real user config with 3 Gateways

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.

Note: Use another integrations for support:

• Xiaomi Gateway 2 (DGNWG02LM) - external link
• Xiaomi Gateway EU (DGNWG05LM), Aqara Hub (ZHWG11LM) - external link
• Aqara E1 CN (ZHWG16LM), Aqara G2H (ZNSXJ12LM), Aqara H1 CN (QBCZWG11LM), Aqara M1S CN (ZHWG15LM), Aqara M2 CN (ZHWG12LM), Aqara P3 CN (KTBL12LM) - external link

Attention: The component is under active development. Breaking changes may appear.

Table of Contents

• FAQ
• Requirements
• Supported Firmwares
• Regional Restrictions
• Supported Zigbee Devices
• Supported BLE Devices
• Supported Bluetooth Mesh Devices
• Installation
• Configuration
• Zigbee and BLE performance table
• Advanced config
• Add and remove Zigbee devices
• Add third-party Zigbee devices
• Zigbee Home Automation Mode
• Zigbee2MQTT Mode
• Handle Button Actions
• Handle BLE Locks
• Obtain Mi Home device token
• Disable Buzzer
• Advanced commands
• How it works
• Troubleshouting
• Debug mode
• Useful links

FAQ

Q. Does this integration support hubs DGNWG02LM, DGNWG05LM, Aqara Hub...?
A. No. The integration only supports ZNDMWG03LM (China version) and ZNDMWG02LM (Euro version).

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 may not work new Zigbee devices E1/H1/T1-series and some Mesh devices. You can connect Euro Gateway to China region or China Gateway to Euro region if you want.

Q. What means device beeps?
A. Beeps AFTER adding Zigbee devices:

1. No new devices found, the pair is stopped.
2. New device successfully added.
3. Unsupported device model.

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

Q. Does the integration work without internet?
A. Partially. The component connects to a hub on the local network. Zigbee devices work without internet. But adding new Zigbee devices to Mi Home requires Internet. Updating BLE device data may not work without 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. Read supported firmwares section.

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. Does the component support decoupled mode for switches?
A. Yes, but it needs to be turned on in the Mi Home app.

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.

Requirements

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

• Xiaomi Mijia Smart Multi-Mode Gateway ZNDMWG03LM (China) or ZNDMWG02LM (Euro)
• Gateway firmware v1.4.7 and more
• Home Assistant v2021.7 and more
• 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
  • Authentication: WPA2
  • Group key update interval: 1 hour and more

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

Important: Integration supports gateway on ORIGINAL firmware. You don't need to solder, or custom firmware!

Additionally, the integration supports custom firmware. The custom firmware works the same way as the original firmware and will not give you new features or support for new devices. Use it only if you know why you need it.

Supported Firmwares

The component is only tested with these firmware versions:

• v1.5.0_0102 - you should use custom open telnet command, safe to update

If you have problems with other firmware, don't even ask to fix it.

The component can work with these firmware versions, but they may have bugs: v1.4.7_0063, v1.4.7_0065, v1.4.7_0115, v1.4.7_0160, v1.5.0_0026, v1.5.1_0032.

If your Mi Home doesn't offer to you new firmware - you can update using telnet.

Component can block fw updates with Lock Firmware switch. Mi Home app will continue to offer you update. But won't be able to install it. It should fail at 0%.

Regional Restrictions

Device	MiHome EU	MiHome CN	Vevs EU	Vevs CN
Gateway 3 (CN and EU)	supported	supported	supported	supported
Zigbee old series	supported	supported	supported	supported
Zigbee E1 series (CN and EU)	no	supported	no	supported
Zigbee H1 and T1 series (CN and EU)	no	partially	no	some models
Bluetooth BLE and Mesh	some models	supported	supported	supported

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.

Supported Devices

The integration can work in two modes:

Mi Home (default)

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

Zigbee Home Automation (ZHA)

• Support for Zigbee devices of hundreds of brands only in Hass
• Support Xiaomi BLE devices simultaneously in Mi Home and Hass
• Support Xiaomi Mesh devices simultaneously in Mi Home and Hass

Zigbee devices in ZHA mode doesn't controlled by this integration!

Other Zigbee, BLE and Mesh devices not from the list below also may work with limited support of functionality.

Some BLE devices have no known default entities (asterisk in the list). Their entities appear when receiving data from the devices.

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 and BLE devices has optional zigbee and ble that shows last_seen time in state and may useful intormation in attributes.

Every device has support level (column S):

• 5 - The device can do everything it can do
• 4 - The device works well, missing some settings
• 3 - The device works, but it is missing some functionality
• empty - Unknown level, but device may work well
• 1/2 - The device doesn't work well (they don't show in the table)

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.

Supported Gateways

Total devices: 2

Brand	Name	Model	Entities	S
Aqara	Hub E1 CN	ZHWG16LM	command, data, gateway	3
Xiaomi	Gateway 3	ZNDMWG03LM ZNDMWG02LM	alarm, command, data, cloud_link, led, gateway	4

Supported Xiaomi Zigbee

Total devices: 82

Brand	Name	Model	Entities	S
Aqara	Air Quality Monitor CN	VOCKQJK11LM	temperature, humidity, tvoc, battery, battery_low, display_unit
Aqara	Bulb CN	ZNLDP12LM	light, power_on_state
Aqara	Button CN	WXKG11LM	action, battery, battery_low, chip_temperature
Aqara	Cube EU	MFKZQ01LM	action, battery	5
Aqara	Curtain	ZNCLDJ11LM	motor
Aqara	Curtain B1 EU	ZNCLDJ12LM	motor, battery
Aqara	Door Lock S1	ZNMS11LM	square, reverse, latch, battery, key_id
Aqara	Door Lock S2 CN	ZNMS12LM	square, reverse, latch, battery, key_id
Aqara	Door Lock S2 Pro CN	ZNMS13LM	lock, square, reverse, latch, battery, action
Aqara	Door/Window Sensor	MCCGQ11LM	contact, battery, battery_low, chip_temperature
Aqara	Door/Window Sensor E1 CN	MCCGQ14LM	contact, battery, battery_low
Aqara	Double Wall Button	WXKG02LM	action, battery, battery_low, chip_temperature
Aqara	Double Wall Button D1 CN	WXKG07LM	action, battery, battery_low, chip_temperature
Aqara	Double Wall Button E1 CN	WXKG17LM	action, battery
Aqara	Double Wall Button H1	WRS-R02	action, battery, battery_low, mode
Aqara	Double Wall Switch	QBKG12LM	channel_1, channel_2, power, energy, action, wireless_1, wireless_2, power_on_state, led
Aqara	Double Wall Switch (no N)	QBKG03LM	channel_1, channel_2, action, wireless_1, wireless_2, led
Aqara	Double Wall Switch D1 CN (no N)	QBKG22LM	channel_1, channel_2, action, wireless_1, wireless_2, led
Aqara	Double Wall Switch D1 CN (with N)	QBKG24LM	channel_1, channel_2, power, energy, action, wireless_1, wireless_2, power_on_state, led
Aqara	Double Wall Switch E1 (no N)	QBKG39LM	channel_1, channel_2, action, wireless_1, wireless_2, led, power_on_state, mode
Aqara	Double Wall Switch E1 (with N)	QBKG41LM	channel_1, channel_2, action, led, led_reverse, power_on_state, wireless_1, wireless_2
Aqara	Double Wall Switch H1 CN (no N)	QBKG28LM	channel_1, channel_2, action, led, power_on_state, wireless_1, wireless_2
Aqara	Double Wall Switch H1 CN (with N)	QBKG31LM	channel_1, channel_2, energy, power, action, led, led_reverse, power_on_state, wireless_1, wireless_2
Aqara	Double Wall Switch H1 EU (no N)	WS-EUK02	channel_1, channel_2, action, led, power_on_state, wireless_1, wireless_2
Aqara	Double Wall Switch H1 EU (with N)	WS-EUK04	channel_1, channel_2, energy, power, action, led, led_reverse, power_on_state, wireless_1, wireless_2
Aqara	Double Wall Switch US (with N)	WS-USC04	channel_1, channel_2, action, energy, power, led, power_on_state, wireless_1, wireless_2
Aqara	Motion Sensor	RTCGQ11LM	motion, illuminance, battery
Aqara	Opple Four Button CN	WXCJKG12LM	mode, action, battery, battery_low, chip_temperature
Aqara	Opple MX480 CN	XDD13LM	light
Aqara	Opple MX650 CN	XDD12LM	light
Aqara	Opple Six Button CN	WXCJKG13LM	mode, action, battery, battery_low, chip_temperature
Aqara	Opple Two Button CN	WXCJKG11LM	mode, action, battery, battery_low, chip_temperature
Aqara	Plug EU	SP-EUC01	plug, energy, power, led, power_on_state
Aqara	Precision Motion Sensor EU	RTCGQ13LM	motion, battery, sensitivity, blind_time, battery_low, idle_time
Aqara	Relay CN	LLKZMK11LM	channel_1, channel_2, current, power, voltage, energy, action, chip_temperature, interlock	4
Aqara	Relay T1 CN (with N)	DLKZMK11LM	switch, energy, power, led, power_on_state
Aqara	Relay T1 EU (no N)	SSM-U02	switch, chip_temperature
Aqara	Relay T1 EU (with N)	SSM-U01	switch, energy, power, led, power_on_state
Aqara	Roller Shade	ZNGZDJ11LM	motor
Aqara	Roller Shade E1 CN	ZNJLBL01LM	motor, battery, motor_reverse, battery_low, battery_voltage, battery_charging, motor_speed
Aqara	Shake Button	WXKG12LM	action, battery, battery_low, chip_temperature
Aqara	Single Wall Button CN	WXKG03LM	action, battery, battery_low, chip_temperature
Aqara	Single Wall Button D1 CN	WXKG06LM	action, battery, battery_low, chip_temperature
Aqara	Single Wall Button E1 CN	WXKG16LM	action, battery
Aqara	Single Wall Switch	QBKG04LM	switch, action, wireless, led
Aqara	Single Wall Switch	QBKG11LM	switch, power, energy, action, wireless, led
Aqara	Single Wall Switch D1 CN (no N)	QBKG21LM	switch, action, wireless, led
Aqara	Single Wall Switch D1 CN (with N)	QBKG23LM	switch, power, energy, action, wireless, led
Aqara	Single Wall Switch E1 (no N)	QBKG38LM	switch, action, led, power_on_state, wireless, mode
Aqara	Single Wall Switch E1 (with N)	QBKG40LM	switch, action, led, led_reverse, power_on_state, wireless
Aqara	Single Wall Switch H1 CN (no N)	QBKG27LM	switch, action, led, power_on_state, wireless
Aqara	Single Wall Switch H1 CN (with N)	QBKG30LM	switch, energy, power, action, led, led_reverse, power_on_state, wireless
Aqara	Single Wall Switch H1 EU (no N)	WS-EUK01	switch, action, led, power_on_state, wireless
Aqara	Single Wall Switch H1 EU (with N)	WS-EUK03	switch, energy, power, action, led, led_reverse, power_on_state, wireless
Aqara	TH Sensor	WSDCGQ11LM	temperature, humidity, battery, pressure
Aqara	TH Sensor	WSDCGQ12LM	temperature, humidity, battery, pressure
Aqara	Thermostat S2 CN	KTWKQ03ES	climate
Aqara	Triple Wall Switch D1 CN (no N)	QBKG25LM	channel_1, channel_2, channel_3, action, wireless_1, wireless_2, wireless_3, power_on_state, led
Aqara	Triple Wall Switch D1 CN (with N)	QBKG26LM	channel_1, channel_2, channel_3, power, voltage, energy, action, wireless_1, wireless_2, wireless_3, power_on_state, led
Aqara	Triple Wall Switch H1 CN (no N)	QBKG29LM	channel_1, channel_2, channel_3, action, led, power_on_state, wireless_1, wireless_2, wireless_3
Aqara	Triple Wall Switch H1 CN (with N)	QBKG32LM	channel_1, channel_2, channel_3, energy, power, action, led, led_reverse, power_on_state, wireless_1, wireless_2, wireless_3
Aqara	Vibration Sensor	DJT11LM	action, battery, battery_low	3
Aqara	Wall Outlet	QBCZ11LM	outlet, power, energy, chip_temperature, power_on_state, charge_protect, led, wireless
Aqara	Water Leak Sensor	SJCGQ11LM	moisture, battery
Honeywell	Gas Sensor	JTQJ-BF-01LM/BW	gas_density, gas, sensitivity	4
Honeywell	Smoke Sensor	JTYJ-GD-01LM/BW	smoke_density, smoke, battery
IKEA	Bulb E14 400 lm	LED1536G5	light
IKEA	Bulb E14 400 lm	LED1649C5	light
IKEA	Bulb E27 1000 lm	LED1623G12	light
IKEA	Bulb E27 950 lm	LED1546G12	light
IKEA	Bulb E27 980 lm	LED1545G12	light
IKEA	Bulb GU10 400 lm	LED1537R6	light
IKEA	Bulb GU10 400 lm	LED1650R5	light
Xiaomi	Button	WXKG01LM	action, battery, battery_low, chip_temperature
Xiaomi	Door/Window Sensor	MCCGQ01LM	contact, battery, battery_low, chip_temperature
Xiaomi	Light Sensor EU	GZCGQ01LM	illuminance, battery
Xiaomi	Motion Sensor	RTCGQ01LM	motion, battery, battery_low, chip_temperature
Xiaomi	Plug CN	ZNCZ02LM	plug, power, energy, chip_temperature, power_on_state, charge_protect, led	5
Xiaomi	Plug EU	ZNCZ04LM	plug, power, voltage, energy
Xiaomi	Plug TW	ZNCZ03LM	plug, power, energy, chip_temperature, power_on_state, charge_protect, led	5
Xiaomi	Plug US	ZNCZ12LM	plug, power, energy, chip_temperature, power_on_state, charge_protect, led	5
Xiaomi	TH Sensor	WSDCGQ01LM	temperature, humidity, battery, battery_low, chip_temperature

Supported Other Zigbee

Total devices: 13

Brand	Name	Model	Entities	S
BlitzWolf	Plug	BW-SHP13	plug, current, power, voltage, energy, power_on_state	5
IKEA	Bulb E27 1000 lm	LED1623G12	light	3
Ksentry Electronics	OnOff Controller	KS-SM001	switch
Lonsonho	Switch w/o neutral	TS0011	switch	5
Philips	Hue motion sensor	9290012607	occupancy, illuminance, temperature, battery, occupancy_timeout	4
Sonoff	Button	SNZB-01	action, battery	5
Sonoff	Door/Window Sensor	SNZB-04	contact, battery	5
Sonoff	Mini	ZBMINI	switch	5
Sonoff	Motion Sensor	SNZB-03	occupancy, battery	5
Sonoff	TH Sensor	SNZB-02	temperature, humidity, battery
Unknown	Dimmer	LXZ8-02A	light	3
UseeLink	Power Strip	SM-SO306E	channel_1, channel_2, channel_3, channel_4, usb, power_on_state	5
eWeLink	Zigbee OnOff Controller	SA-003-Zigbee	switch	5

Supported Xiaomi BLE

Total devices: 33

Brand	Name	Model	Entities	S
Aqara	Door Lock D100	ZNMS20LM	*
Aqara	Door Lock N100 (Bluetooth)	ZNMS16LM	*
Aqara	Door Lock N200	ZNMS17LM	*
Honeywell	Smoke Alarm	JTYJ-GD-03MI	*
Loock	Door Lock Classic 2X Pro	loock.lock.cc2xpro	*
Unknown	Lock M2	ydhome.lock.m2silver	*
Xiaomi	Alarm Clock	CGD1	temperature, humidity, battery*
Xiaomi	Door Lock	MJZNMS02LM	*
Xiaomi	Door Lock	MJZNMS03LM	*
Xiaomi	Door Lock	XMZNMST02YD	*
Xiaomi	Door/Window Sensor 2	MCCGQ02HL	contact, light, battery
Xiaomi	Flower Care	HHCCJCY01	temperature, moisture, conductivity, illuminance, battery*
Xiaomi	Flower Pot	HHCCPOT002	moisture, conductivity, battery*
Xiaomi	Kettle	YM-K1501	power, temperature
Xiaomi	Magic Cube	XMMF01JQD	action
Xiaomi	Mosquito Repellent	WX08ZM	*
Xiaomi	Motion Sensor 2	RTCGQ02LM	motion, illuminance, battery, action, idle_time
Xiaomi	Night Light 2	MJYD02YL-A	battery, light, motion, idle_time
Xiaomi	Qingping Door Sensor	CGH1	*
Xiaomi	Qingping Motion Sensor	CGPR1	motion, light, illuminance, battery, idle_time
Xiaomi	Qingping TH Lite	CGDK2	temperature, humidity, battery*
Xiaomi	Qingping TH Sensor	CGG1	temperature, humidity, battery*
Xiaomi	Safe Box	BGX-5/X1-3001	*
Xiaomi	TH Clock	LYWSD02MMC	temperature, humidity, battery*
Xiaomi	TH Sensor	LYWSDCGQ/01ZM	temperature, humidity, battery*
Xiaomi	TH Sensor	XMWSDJ04MMC	temperature, humidity, battery*
Xiaomi	TH Sensor 2	LYWSD03MMC	temperature, humidity, battery*
Xiaomi	Toothbrush T500	MES601	*
Xiaomi	Viomi Kettle	V-SK152	power, temperature
Xiaomi	Water Leak Sensor	SJWS01LM	*
Xiaomi	ZenMeasure Clock	MHO-C303	temperature, humidity, battery*
Xiaomi	ZenMeasure TH	MHO-C401	temperature, humidity, battery*
Yeelight	Button S1	YLAI003	action, battery

Supported Xiaomi Mesh

Total devices: 29

Brand	Name	Model	Entities	S
LeMesh	Mesh Downlight	lemesh.light.wy0c05	light
LeMesh	Mesh Light	lemesh.light.wy0c08	light
LeMesh	Mesh Light (RF ready)	lemesh.light.wy0c02	light
LeMesh	Mesh Light (RF ready)	lemesh.light.wy0c07	light
PTX	Mesh Double Wall Switch	PTX-SK2M	channel_1, channel_2, led, wireless_1, wireless_2
PTX	Mesh Downlight	090615.light.mlig01	light
PTX	Mesh Single Wall Switch	PTX-SK1M	switch, led, wireless
PTX	Mesh Triple Wall Switch	PTX-SK3M	channel_1, channel_2, channel_3, led, wireless_1, wireless_2, wireless_3
PTX	Mesh Triple Wall Switch	PTX-TK3/M	channel_1, channel_2, channel_3, led, wireless_1, wireless_2, wireless_3
Unknown	Mesh Lightstrip (RF ready)	crzm.light.wy0a01	light
Unknown	Mesh Switch Controller	lemesh.switch.sw0a01	switch
Unknown	Mesh Wall Switch	DHKG01ZM	switch, led
Xiaomi	Electrical Outlet	ZNCZ01ZM	outlet, power, led, power_protect, power_value
Xiaomi	Mesh Bulb	MJDP09YL	light, flex_switch, power_on_state	4
Xiaomi	Mesh Double Wall Switch	DHKG02ZM	channel_1, channel_2, led, wireless_1, wireless_2
Xiaomi	Mesh Double Wall Switch	ZNKG02HL	channel_1, channel_2, humidity, temperature
Xiaomi	Mesh Downlight	MJTS01YL/MJTS003	light, flex_switch, power_on_state	4
Xiaomi	Mesh Group	yeelink.light.mb1grp	group	4
Xiaomi	Mesh Single Wall Switch	ZNKG01HL	switch, humidity, temperature
Xiaomi	Mesh Triple Wall Switch	ZNKG03HL/ISA-KG03HL	channel_1, channel_2, channel_3, humidity, temperature, wireless_1, wireless_2, wireless_3, baby_mode
Xiaomi	Mosquito Repeller 2	WX10ZM	switch, battery, supply, led, power_mode
XinGuang	Mesh Switch	wainft.switch.sw0a01	switch
XinGuang	Smart Light	LIBMDA09X	light
Yeelight	Mesh Bulb E14	YLDP09YL	light, flex_switch, power_on_state	4
Yeelight	Mesh Bulb E27	YLDP10YL	light, flex_switch, power_on_state	4
Yeelight	Mesh Bulb M2	YLDP25YL/YLDP26YL	light, flex_switch, power_on_state	4
Yeelight	Mesh Downlight	YLSD01YL	light, flex_switch, power_on_state	4
Yeelight	Mesh Downlight M2	YLTS02YL/YLTS04YL	light, flex_switch, power_on_state	4
Yeelight	Mesh Spotlight	YLSD04YL	light, flex_switch, power_on_state	4

Installation

Video DEMO

Method 1. HACS:

HACS > Integrations > Plus > XiaomiGateway3 > Install

Method 2. Manually copy xiaomi_gateway3 folder from latest release to /config/custom_components folder.

Configuration

Video DEMO

Configuration > Integrations > Add Integration > **Xiaomi Gateway3 **

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

You need to install 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.

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

Zigbee and BLE performance table

1. To enable stats sensors go to:

   Configuration > Integrations > Xiaomi Gateway 3 > Options > Zigbee and BLE performance data

2. Install Flex Table from HACS

3. Add new Lovelace tab with Panel Mode

4. Add new Lovelace card:

   • example 1
   • example 2

How it works:

• for each Zigbee and BLE device, a sensor will be created with the time of receiving the last message from this sensor
• there will also be a lot of useful information in the sensor attributes
• for the Gateway, the sensor state shows the uptime of the gateway connection, so you can check the stability of your Wi-Fi
• the uptime in gateway sensor attributes means time after reboot gateway
• the msg_missed may not always show correct data if you reboot the gate or device
• dash in the type means that the device is not directly connected to the hub
• the parent can be updated within a few hours

Advanced config

Support custom occupancy timeout for motion sensor and invert state for door sensor (for DIY purposes).

Config through built-in customizing UI or YAML.

It's important to add these lines to your configuration.yaml. Otherwise, changes to the UI will not be read when you restart Home Assistant.

homeassistant:
  customize: !include customize.yaml

To enable customizing UI, you need to enable Advanced Mode in your user profile.

Occupancy timeout for moving sensor.

• a simple timer starts every time a person moves
• the progressive timer starts with a new value with each new movement of the person, the more you move - the longer the timer
• fast back timer starts with doubled value if the person moves immediately after the timer is off

# /config/customize.yaml
binary_sensor.0x158d0003456789_motion:
  occupancy_timeout: 180  # simple mode
binary_sensor.0x158d0003456788_motion:
  occupancy_timeout: -120  # fast back mode
binary_sensor.0x158d0003456787_motion:
  occupancy_timeout: [-120, 240, 300]  # progressive timer
binary_sensor.0x158d0003456786_motion:
  occupancy_timeout: 1  # for hacked 5 sec sensors

Invert state for contact sensor.

# /config/customize.yaml
binary_sensor.0x158d0003456789_contact:
  invert_state: 1  # any non-empty value will reverse the logic

Ignore offline device status.

# /config/customize.yaml
switch.0x158d0003456789_switch:
  ignore_offline: 1  # any non-empty value

Zigbee bulb default transition.

light.0x86bd7fffe000000_light:
  default_transition: 5

Add and remove Zigbee devices

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!

Add third-party Zigbee devices

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.

Zigbee Home Automation Mode

You do not need to solder or flash the gate. It is ready to work with the ZHA out of the box.

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.

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 active 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 (BLE and Mesh) will continue to work in Mi Home and Hass.

To switch the mode go to:

Configuration > Integrations > Xiaomi Gateway 3 > Options > 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. This mode will flash firmware of Gateway Zigbee chip to a new version with reduced speed, to avoid errors in the data. And flash it back when you switch back to Mi Home mode. Switch back before any Gateway firmware updates via Mi Home.

Thanks to @zvldz for help with socat.

Zigbee2MQTT Mode

Important: The zigbee chip of this gateway (EFR32 EZSP v8) is supported in zigbee2mqtt in experimental mode. At the moment it is not working well and not recommended for use.

Video DEMO

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

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

Attention: Zigbee2MQTT mode cannot work simultaneously with Mi Home!

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

To switch the mode go to:

Configuration > Integrations > Xiaomi Gateway 3 > Options > Mode

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

This mode will flash firmware of Gateway Zigbee chip automatically! And flash it back when you switch back to Mi Home mode. Becuse Zigbee2MQTT support only new EZSP firmware and Xiaomi works with old one.

You can use this mode with thank to this peoples:

• @kirovilya - developed support EFR32 chips in z2m project
• @CODeRUS and @zvldz - adapted the script to flash the chip
• @faronov - complied a new version of firmware

Handle Button Actions

Video DEMO

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.

Depending on the button model, its state may be:

• single button: single, double, triple, quadruple, many, hold, release, shake
• double button: button_1_single, button_2_single, button_both_single, etc.
• triple button: button_1_single, button_12_single, button_23_single, etc.

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

Handle BLE Locks

Read more in wiki.

Obtain Mi Home device token

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:

• LAN key for old Xiaomi Mijia Gateway (lumi.gateway.v3)
• room names for Vacuums that support room with names
• Bindkey for BLE devices that has it

Multiple Hass

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

• You should use the same integration version and same integration settings on both servers
• You may use different Hass versions on both servers
• If you using ZHA mode:
  • ZHA integration should be installed only on one Hass
  • Gateway integration may be installed only on one Hass or on both, but with same integration version and same integration settings

Disable Buzzer

This option disable only beeps from hacked motion sensor (5 sec):

Configuration > Integrations > Xiaomi Gateway 3 > Options > Disable buzzer

Advanced commands

Reboot Gateway

script:
  reboot_gateway:
    sequence:
    - service: remote.send_command
      entity_id: remote.0x0123456789abcdef_pair  # change to your gateway
      data:
        command: reboot

Attention: I don’t know if it’s safe to change the channel and power of the gateway. Use at your own risk.

The information in the attributes of the pair object is updated within a minute!

Change Zigbee channel

command: channel 15  # I saw values: 11, 15, 20, 25

Change Zigbee TX power

command: power 7  # I saw values: 0, 7, 30

How it works

The component enables Telnet on Gateway via Miio protocol.

The component starts the MQTT Server on the public port of the Gateway. All the Zigbee 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.

Troubleshooting

Can't connect to gateway

• Check Requirements readme section
• Check if the Gateway really has the IP-address you set in the configuration
• Check if the Gateway really use the MiHome token you set in the configuration. When you add a hub to MiHome - its token changes. The integration only updates tokens when Hass starts. And only if there are no problems with connection to the cloud servers. If there are problems, the old (wrong) token value will be shown.

Lost connection with Zigbee and Bluetooth devices

• Check Requirements readme section, gateway and Wi-Fi router settings must be fully matched to all items in the section
• Turn on stat sesors (Configuration > Integrations > Gateway 3 > Configure > Add statisic sensors)
• Check that the connection to the Gateway is not dropped for weeks (_gateway sensor value means connection uptime)
• Check that the zigbee error rate is not increasing at a high rate (zigbee_oe attribute in _gateway sensor, normal rate: 1-2 errors per hour)
• Check that CPU utilisation is within normal values (load_avg attribute in _gateway sensor (first 3 items), normal value: below 3)
• Check that message skip rate for your zigbee device are not high (msg_missed attribute in _zigbee sensor)
• Check that your zigbee device is connected via a router, the most stable operation when your devices are connected directly to the gateway (parent attribute in _zigbee sensor)
• Make sure there are no other electronic devices within 0.5 meter from your Gateway
• Check the distance between the Gateway and the device, greater distances and barriers - the less stable the operation
• Check the gateway zigbee TX power, you can try to increase it if you need (radio_tx_power attribute in _gateway sensor)

Debug mode

Logging can be setup from:

1. Integration config (GUI)

Configuration > Integrations > Xiaomi Gateway 3 > Configure > Debug

Shows only component logs. The link to the logs is always random and will apear in Notifications.

By adding params to url, you can filter data in the logs, enable auto refresh (in seconds) and tail last lines.

http://192.168.1.123:8123/c4e99cfc-0c83-4a39-b7f0-278b0e719bd1?q=ble_event&r=2&t=100

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
    debug_mode: true,miio,mqtt  # global modes for all gateways, default empty

Additional settings

    level: debug  # default
    mode: a  # a - append to file, w - write new file, default
    format: "%(asctime)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

Useful links

• Russian Telegram Community
• Italian Telegram Community
• Russian video about instal integration
• Russian article about flash gateway
• Home Assistant Community