{"id":14985171,"url":"https://github.com/alexxit/xiaomigateway3","last_synced_at":"2025-05-13T23:09:15.055Z","repository":{"id":37467685,"uuid":"291484700","full_name":"AlexxIT/XiaomiGateway3","owner":"AlexxIT","description":"Home Assistant custom component for control Xiaomi Multimode Gateway (aka Gateway 3), Xiaomi Multimode Gateway 2, Aqara Hub E1 on default firmwares over LAN","archived":false,"fork":false,"pushed_at":"2025-04-09T09:56:14.000Z","size":2972,"stargazers_count":2575,"open_issues_count":135,"forks_count":370,"subscribers_count":49,"default_branch":"master","last_synced_at":"2025-04-10T02:12:29.389Z","etag":null,"topics":["aqara","ble","hacs","home-assistant","matter","mesh","mihome","xiaomi","zha","zigbee","zigbee2mqtt"],"latest_commit_sha":null,"homepage":"https://github.com/AlexxIT/Blog","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlexxIT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-30T14:19:34.000Z","updated_at":"2025-04-09T09:56:18.000Z","dependencies_parsed_at":"2023-12-28T12:42:24.696Z","dependency_job_id":"fc0a1ce3-da0c-4bc9-b985-02718aeb5192","html_url":"https://github.com/AlexxIT/XiaomiGateway3","commit_stats":{"total_commits":1571,"total_committers":98,"mean_commits":16.03061224489796,"dds":0.1737746658179503,"last_synced_commit":"82ad2d9055c35ea714ae7ed275bbba02a9be57f0"},"previous_names":[],"tags_count":121,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexxIT%2FXiaomiGateway3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexxIT%2FXiaomiGateway3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexxIT%2FXiaomiGateway3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlexxIT%2FXiaomiGateway3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlexxIT","download_url":"https://codeload.github.com/AlexxIT/XiaomiGateway3/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254042039,"owners_count":22004831,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aqara","ble","hacs","home-assistant","matter","mesh","mihome","xiaomi","zha","zigbee","zigbee2mqtt"],"created_at":"2024-09-24T14:10:25.204Z","updated_at":"2025-05-13T23:09:10.023Z","avatar_url":"https://github.com/AlexxIT.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Xiaomi Gateway 3 for Home Assistant\n\n[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg)](https://github.com/hacs/integration)\n\nHome Assistant custom component for control **Xiaomi Multimode Gateway** (aka Gateway 3), **Xiaomi Multimode Gateway 2**, **Aqara Hub E1** on default firmwares over LAN.\n\n| Gateway                         | Model                 | Supported         |\n|---------------------------------|-----------------------|-------------------|\n| Xiaomi Multimode Gateway (CN)   | ZNDMWG03LM            | **yes**           |\n| Xiaomi Multimode Gateway (EU)   | ZNDMWG02LM, YTC4044GL | **yes**           |\n| Xiaomi Multimode Gateway 2 (CN) | DMWG03LM              | **yes**           |\n| Xiaomi Multimode Gateway 2 (EU) | ZNDMWG04LM, BHR6765GL | **yes**           |\n| Aqara Hub E1 (CN)               | ZHWG16LM              | **yes**           |\n| Xiaomi Gateway 2 (CN)           | DGNWG02LM             | **no**, [goto][1] |\n| Xiaomi Gateway (EU)             | DGNWG05LM             | **no**, [goto][2] |\n\n**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][3]\n\n[1]: https://www.home-assistant.io/integrations/xiaomi_aqara/\n[2]: https://openlumi.github.io/\n[3]: https://github.com/niceboygithub/AqaraGateway\n\nThanks to [@Serrj](https://community.home-assistant.io/u/serrj-sv/) for [instruction](https://community.home-assistant.io/t/xiaomi-mijia-smart-multi-mode-gateway-zndmwg03lm-support/159586/61) how to enable Telnet on old firmwares. And thanks to an unknown researcher for [instruction](https://gist.github.com/zvldz/1bd6b21539f84339c218f9427e022709) how to open telnet on new firmwares.\n\n---\n\n* [Supported Firmwares](#supported-firmwares)\n* [Supported Devices](#supported-devices)\n  * [Add new device](#add-new-device) \n* [Installation](#installation)\n* [Configuration](#configuration)\n* [Network configuration](#network-configuration)\n* [Regional Restrictions](#regional-restrictions)\n* [Statistics table](#statistics-table)\n* [Gateway controls](#gateway-controls)\n* [Advanced config](#advanced-config)\n  * [Integration config](#integration-config)\n  * [Devices config](#devices-config)\n  * [Entities customize](#entities-customize)\n* [Zigbee Home Automation Mode](#zigbee-home-automation-mode)\n* [Zigbee2MQTT Mode](#zigbee2mqtt-mode)\n* [Zigbee custom firmware](#zigbee-custom-firmware)\n* [Handle Button Actions](#handle-button-actions)\n* [Handle BLE Locks](#handle-ble-locks)\n* [Obtain Mi Home device token](#obtain-mi-home-device-token)\n* [Multiple Hass](#multiple-hass)\n* [Disable Buzzer](#disable-buzzer)\n* [How it works](#how-it-works)\n* [Troubleshooting](#troubleshooting)\n* [Debug mode](#debug-mode)\n* [FAQ](#faq)\n* [Useful links](#useful-links)\n\n## Supported Firmwares\n\n| Gateway                            | Firmwares     | Required      |\n|------------------------------------|---------------|---------------|\n| Xiaomi Multimode Gateway (CN/EU)   | 1.5.0 - 1.5.4 | only Token    |\n| Xiaomi Multimode Gateway 2 (CN/EU) | 1.0.3 - 1.0.6 | only Token    |\n| Aqara Hub E1 (CN)                  | 4.0.1         | only Token    |\n| Xiaomi Multimode Gateway (CN/EU)   | 1.5.5 - 1.5.6 | Token and Key |\n| Xiaomi Multimode Gateway 2 (CN/EU) | 1.0.7         | Token and Key |\n\n**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.\n\n**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.\n\nRecommended firmwares:\n- Xiaomi Multimode Gateway (CN/EU) - 1.5.4 - 1.5.6\n- Xiaomi Multimode Gateway 2 (CN/EU) - 1.0.6 - 1.0.7\n- Aqara Hub E1 (CN) - 4.0.1\n\n**HOWTO get token** [read here](#obtain-mi-home-device-token)\n\n**HOWTO get key**\n\n| Gateway                                                                                 | Situation                                                                           | Solution                                                             |\n|-----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|----------------------------------------------------------------------|\n| Xiaomi Multimode Gateway (CN/EU)                                                        | firmware 1.5.4 and lower                                                            | setup integration and use only Token                                 |\n| Xiaomi Multimode Gateway 2 (CN/EU)                                                      | firmware 1.0.6 and lower                                                            | setup integration and use only Token                                 |\n| Aqara Hub E1 (CN)                                                                       | firmware 4.0.1 and lower                                                            | setup integration and use only Token                                 |\n| 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](https://github.com/AlexxIT/Blog/issues/13) |\n| 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](https://github.com/AlexxIT/Blog/issues/13) |\n| Xiaomi Multimode Gateway (CN/EU)                                                        | firmware 1.5.5 and more, never worked in the Hass                                   | [use UART](https://github.com/AlexxIT/XiaomiGateway3/issues/1057)    |\n| Xiaomi Multimode Gateway 2 (CN/EU)                                                      | firmware 1.0.7 and more, never worked in the Hass                                   | [use UART](https://github.com/AlexxIT/XiaomiGateway3/issues/1166)    |\n| Aqara Hub E1 (CN)                                                                       | firmware 4.0.4 and more, never worked in the Hass                                   | no solution                                                          |\n\n- Read more https://github.com/AlexxIT/Blog/issues/13\n\nFor Xiaomi Multimode Gateway you also can:\n\n- optional update firmware via [Telnet](https://github.com/zvldz/mgl03_fw/tree/main/firmware)\n- optional install [custom firmware](https://github.com/zvldz/mgl03_fw/tree/main/firmware)\n\nPlease, not ask me why you need it.\n\n## Supported Devices\n\nGateway Zigbee chip can work in three modes:\n\n**1. Mi Home (default)**\n\n   - Support Xiaomi/Aqara Zigbee devices simultaneously in Mi Home and Hass\n   - Support some Zigbee devices from other brands only in Hass\n   \n**2. Zigbee Home Automation (ZHA)**\n\n   - Support for [Zigbee devices of hundreds of brands](https://zigbee.blakadder.com/zha.html) only in Hass ([read more](#zigbee-home-automation-mode))\n\n**3. Zigbee2mqtt**\n\n   - Support for [Zigbee devices of hundreds of brands](https://www.zigbee2mqtt.io/supported-devices/) in MQTT ([read more](#zigbee2mqtt-mode))\n\nZigbee devices in ZHA or z2m modes doesn't controlled by this integration!\n\nXiaomi BLE and Mesh devices works simultaneously in Mi Home and Hass. No matter which zigbee mode is used.\n\nMatter devices supported only for Xiaomi Multimode Gateway 2 (EU) with fw 1.0.7_0019 and higher.\n\nSome BLE devices may or may not have battery data depending on the device firmware.\n\nGateway entity shows connection state to gateway. It has many useful information in attributes.\n\nZigbee, BLE, Mesh and Matter devices has optional `zigbee`, `ble`, `mesh`, `matter` that shows `last_report` time in state and may useful intormation in attributes.\n\n### Add new device\n\nYou 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](https://github.com/AlexxIT/XiaomiGateway3/wiki/Converters).\n\nIt is welcomed if you return a working converter to integration. You can create an issue or make a pull request.\n\n## Installation\n\n[HACS](https://hacs.xyz/) \u003e Integrations \u003e Plus \u003e **XiaomiGateway3** \u003e Install\n\nOr manually copy `xiaomi_gateway3` folder from [latest release](https://github.com/AlexxIT/XiaomiGateway3/releases/latest) to `/config/custom_components` folder.\n\n## Configuration\n\n[Settings](https://my.home-assistant.io/redirect/config/) \u003e [Integrations](https://my.home-assistant.io/redirect/integrations/) \u003e Add Integration \u003e [Xiaomi Gateway3](https://my.home-assistant.io/redirect/config_flow_start/?domain=xiaomi_gateway3)\n\nIf the integration is not in the list, you need to clear the browser cache.\n\nYou need to add integration two times:\n\n1. Cloud version. It used ONLY to load tokens and names for your devices from cloud.\n2. Gateway. It adds your gateway and all connected Zigbee, BLE and Mesh devices.\n\nYou may skip 1st step if you know token for you Gateway. If you have multiple Gateways - repeat step 2 for each of them.\n\nYou need gateway `key` only for Xiaomi Multimode Gateway on fw 1.5.5, [read more](https://github.com/AlexxIT/Blog/issues/13).\n\n**ATTENTION:** If you using two Hass with one gateway - you should use same integration version on both of them! \n\n## Network configuration \n\nAll settings are **important** or you may have an unstable operation of the gateway.\n\n- **Shared LAN** between Gateway and Hass server. You may use VPN, but both IP-address should be in **same network subnet**!\n- **Open ping** (accept ICMP) from Gateway to Router\n- **Fixed IP-address** for Gateway on your Router\n- Wi-Fi Router settings:\n   - **Fixed channel** from 1 to 11\n   - Channel width: **20MHz** (don't use 40MHz)\n   - Authentication: WPA2 (don't use WPA3)\n- MikroTik Router settings:\n   - Wireless \u003e Security Profiles \u003e Group Key Update: **01:00:00** (1 hour or more)\n- Keenetic Router settings: \n   - Disable \"[Airtime Fairness](https://help.keenetic.com/hc/en-us/articles/360009149400)\" for 2.4GHz\n   - Disable \"[256-QAM](https://help.keenetic.com/hc/en-us/articles/4402854785170)\" for 2.4GHz\n\nWith the following settings the operation of the gateway may be **unstable**: different subnets, closed ping to router, Wi-Fi channel 40MHz, WPA3.\n\n## Regional Restrictions\n\n| Device                              | MiHome EU   | MiHome CN | Vevs EU   | Vevs CN     |\n|-------------------------------------|-------------|-----------|-----------|-------------|\n | Gateway 3 (CN and EU)               | supported   | supported | supported | supported   |\n | Zigbee old series                   | supported   | supported | supported | supported   |\n | Zigbee E1 series (CN and EU)        | no          | supported | no        | supported   |\n | Zigbee H1 and T1 series (CN and EU) | no          | partially | no        | some models |\n | Bluetooth BLE and Mesh              | some models | supported | supported | supported   |\n\n**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.\n\n**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.\n\nMost **older Xiaomi/Aqara Zigbee devices** can also be added to China and to Euro cloud servers.\n\nNew **Zigbee devices from E1 series** can be added ONLY to China cloud servers. They supported in official Mi Home application.\n\nNew **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](https://www.kapiba.ru/2017/11/mi-home.html).\n\nSome of **Bluetooth BLE and Mesh** can be added ONLY to China cloud. But with [Mi Home by Vevs](https://www.kapiba.ru/2017/11/mi-home.html) they can be added to any cloud.\n\n**PS.** You can't add **Zigbee devices E1/H1/T1** to Euro cloud even with **Mi Home by Vevs**.\n\nIf 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.\n\n**PS.** Some Aqara devices are not supported at all in Mi Home in any version, e.g. **Aqara Door Lock N100 Zigbee version**.\n\n## Multiple Gateways\n\nIntegration support multiple gateways in one MiHome account.\n\nZigbee 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.\n\nBluetooth BLE and Mesh devices can work simultaneously with all gateways. In this technology, there is no binding to the gateway.\n\nIf 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.\n\n## Device command select\n\n**Device info** - displays device information in notification.\n\n```yaml\nextra:\n  cloud_fw: 2.1.1_0025               # device firmware from cloud integration\n  cloud_name: Dev Presence Sensor 2  # device name from cloud integration\n  did: '1005xxxxxx'                  # device ID from MiHome\n  mac: 64:9e:31:xx:xx:xx\n  market_brand: Linptech\n  market_model: ES1ZB, linp.sensor_occupy.hb01\n  market_name: Presence Sensor ES1\n  rssi_54ef44xxxxxx: -69             # rssi for each gateway\n  rssi_54ef55xxxxxx: -79\n  seq: 185                           # message sequence number\n  type: mesh                         # device type: gateway, zigbee, ble, mesh, group, matter\nlast_report:                         # last decoded report from device\n  not_occupancy_duration: 11\nlast_report_gw:                      # the gateway that received the last report\n  fw_ver: 1.0.7_0021\n  host: 192.168.1.123\n  mac: 54:ef:44:xx:xx:xx\n  model: lumi.gateway.mcn001\n  name: Gateway 2\nlast_report_ts: 48s                  # how long ago was the last message\nlast_seen:\n  54ef44xxxxxx: 48s                  # how long ago each gateway seen device\n  54ef55xxxxxx: 48s\nlisteners: 7                         # subscribers for device updates (internal logic)\nmodel: 10441                         # device model (number for BLE and Mesh, string for Zigbee and Matter)\nparams:                              # all decoded params in one message\n  action: away\n  distance: 5.15\n  illuminance: 237.0\n  not_occupancy_duration: 11\n  occupancy: false\n  occupancy_duration: 0\nttl: 50m                             # time to live (TTL) - available timeout (maximum last_seen value)\nuid: 649e31xxxxxx                    # hass UID - \"12 hex mac\" for BLE and Mesh, \"0x + 16 hex IEEE\" for Zigbee \n```\n\n**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.\n\n**Zigbee reconfig** - start the initial setup process for 3rd party Zigbee devices\n\n**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.\n\n## Statistics table\n\n![](assets/zigbee_table.png)\n\n1. To enable stats sensors go to:\n   - [Settings](https://my.home-assistant.io/redirect/config/) \u003e [Integrations](https://my.home-assistant.io/redirect/integrations/) \u003e Xiaomi Gateway 3 \u003e Options \u003e Add statistic sensors\n\n2. Install [Flex Table](https://github.com/custom-cards/flex-table-card) from HACS\n\n3. Add new Lovelace tab with **Panel Mode**\n\n4. Add new Lovelace card:\n   - [example 1](https://gist.github.com/AlexxIT/120f20eef4f39071e67f698207490db9)\n   - [example 2](https://github.com/avbor/HomeAssistantConfig/blob/master/lovelace/views/vi_radio_quality_gw3.yaml)\n   - [example 3](https://gist.github.com/DJTerentjev/c8733478c616524a8db539565c2d669e)\n\n**Gateway binary sensor**\n\n- sensor shows connection to gateway, so you can check the stability of your Wi-Fi\n- **radio_tx_power** - zigbee chip power\n- **radio_channel** - zigbee chip channel\n- **free_mem** - gateway free memory in bytes\n- **load_avg** - gateway CPU `/proc/loadavg`\n- **rssi** - gateway Wi-Fi signal strength\n- **uptime** - gateway uptime after reboot\n\nRead more about additional attributes from [openmiio](https://github.com/AlexxIT/openmiio_agent#openmiioreport).\n\n## Gateway controls\n\nAvailable commands:\n\n- **Gateway run FTP** - enable FTP on gateway\n- **Gateway reboot** - reboot gateway\n- **Gateway disable/enable** - just for test, so you can check gateway offline logic\n- **OpenmiIO reload** - restart [openmiio](https://github.com/AlexxIT/openmiio_agent) app on gateway\n- **Zigbee pairing** - start the process of adding a new zigbee device\n   - you can also start the process by pressing the physical button on the gateway three times\n   - you can also start the process from the Mi Home app\n- **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.\n- **Zigbee parent scan** - update the zigbee parents info manually (it updates automatically every 1h when stats sensors enabled)\n\nOnly for Xiaomi Multimode Gateway 1:\n\n- **Gateway firmware Lock** - block the gateway firmware update ([read more](#supported-firmwares))\n- **Zigbee flash EZSP** - update zigbee chip firmare (incompatible with MiHome mode)\n\n## Advanced config\n\n### Integration config\n\n[Settings](https://my.home-assistant.io/redirect/config/) \u003e [Integrations](https://my.home-assistant.io/redirect/integrations/) \u003e Xiaomi Gateway 3 \u003e CONFIGURE\n\n- **Host** - gateway IP-address, should be fixed on your Wi-Fi router\n- **Token** - gateway Mi Home token, changed only when you add gateway to Mi Home app\n- **Key** - gateway secret key, [read more](https://github.com/AlexxIT/Blog/issues/13)\n- **Add statistic sensors** - [read more](#statistics-table)\n- **Debug logs** - enable different levels of logging ([read more](#debug-mode))\n\n### Devices config\n\nThis options configured in the `configuration.yaml`. Section: `xiaomi_gateway3 \u003e devices \u003e IEEE or MAC`.\n\nAs a device you can specify:\n\n- device UID - you can check it in the entities name\n- model - string for zigbee devices and number for BLE and Mesh devices\n- type - gateway, zigbee, ble, mesh, matter\n\n**Overwrite device model**\n\nThis is useful if:\n\n- you have unsupported device with exact same functionality as supported device, example:\n   - for simple relay use model: `01MINIZB`\n   - for bulb with brightness use model: `TRADFRI bulb E27 W opal 1000lm`\n   - for bulb with color temp use model: `TRADFRI bulb E14 WS opal 600lm`\n- you have Sonoff device with wrong firmware ([example](https://github.com/Koenkk/zigbee-herdsman-converters/issues/1449))\n- you have Tuya device with same model for many different devices\n- you want to use external converters only for one device\n\n```yaml\nxiaomi_gateway3:\n  devices:\n    \"0x00158d0001d82999\":  # match device by IEEE or MAC\n      model: 01MINIZB\n```\n\n**Change switch to light**\n\nDepending on the model of the device, your entity may be called: `switch`, `plug`, `outlet`, `channel_1`, etc.\n\n```yaml\nxiaomi_gateway3:\n  devices:\n    \"0x00158d0001d82999\":  # match device by IEEE or MAC\n      entities:\n        channel_1: light   # change entity domain (switch to light)\n```\n\n**Create sensors from attributes**\n\n```yaml\nxiaomi_gateway3:\n  devices:\n    \"lumi.sensor_motion.aq2\":  # match device by model\n      entities:\n        zigbee: sensor         # adds stat entity only for this device\n        parent: sensor         # adds entity from attribute value\n        linkquality: sensor    # adds entity from attribute value\n```\n\n**Change device or entity name**\n\nAttention! 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.\n\n```yaml\nxiaomi_gateway3:\n  devices:\n    \"0x00158d0001d82999\":  # match device by IEEE or MAC\n      name: Kitchen Refrigerator         # overwrite device name\n      entity_name: kitchen_refrigerator  # overwrite entity_id part\n```\n\n**Additional attributes for entities**\n\nUseful if you want to:\n\n- put additional data in the [statistics table](#statistics-table)\n- collect entities data in scripts and automations\n\nAttention! Template is calculated only at the start of the Hass.\n\n```yaml\nxiaomi_gateway3:\n  attributes_template: |\n    {% if attr in ('zigbee', 'ble', 'mesh') %}\n    {{{\n      \"integration\": \"gw3\",\n      \"name\": device.human_name,\n      \"device_fw_ver\": device.firmware,\n      \"device_model\": device.model,\n      \"device_market_model\": device.human_model,\n      \"device_manufacturer\": device.extra.market_brand,\n      \"gate\": gateway.human_name,\n      \"gateway_model\": gateway.model,\n      \"gateway_fw_ver\": gateway.firmware\n    }}}\n    {% elif attr == 'gateway' %}\n    {{{\n      \"integration\": \"gw3\",\n      \"gate\": gateway.human_name,\n      \"gateway_model\": gateway.human_model,\n      \"gateway_fw_ver\": gateway.firmware\n    }}}\n    {% elif attr == 'battery' %}\n    {{{\n      \"integration\": \"gw3\",\n      \"name\": device.human_name,\n      \"gate\": gateway.human_name,\n      \"battery\": \"true\"\n    }}}\n    {% endif %}\n```\n\n### Entities customize\n\n**Occupancy timeout** for moving sensor.\n\n![](assets/occupancy_timeout.png)\n\n- a **simple timer** starts every time a person moves\n- the **progressive timer** starts with a new value with each new movement of the person, the more you move - the longer the timer\n- **fast back timer** starts with doubled value if the person moves immediately after the timer is off\n\n```yaml\nxiaomi_gateway3:\n  devices:\n    \"0x00158d0003456789\":\n      occupancy_timeout: 180  # simple mode\n    \"0x00158d0003456788\":\n      occupancy_timeout: -120  # fast back mode\n    \"0x00158d0003456787\":\n      occupancy_timeout: [-120, 240, 300]  # progressive timer\n    \"0x00158d0003456786\":\n      occupancy_timeout: 1  # for hacked 5 sec sensors\n```\n\n**Invert state** for contact sensor.\n\n```yaml\nxiaomi_gateway3:\n  devices:\n    \"0x00158d0003456789\":\n      invert_state: 1  # any non-empty value will reverse the logic\n```\n\n**Zigbee bulb default transition**.\n\n```yaml\nxiaomi_gateway3:\n  devices:\n    \"0x86bd7fffe0000000\":\n      default_transition: 5\n```\n\n## Zigbee Home Automation Mode\n\n[Zigbee Home Automation](https://www.home-assistant.io/integrations/zha/) (ZHA) is a standard Home Assistant component for managing Zigbee devices.\n\n**Note:** ZHA developers [do not recommend](https://github.com/zigpy/bellows#hardware-requirement) 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.\n\nStarting 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.\n\nSettings \u003e Integrations \u003e Add \u003e Zigbee Home Automation \u003e EZSP:\n\n- **Serial device path:** `socket://{gatewayIP}:8888`\n- **port speed:** any\n- **data flow control**: any\n\nWhen 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.\n\nZigbee devices will not migrate from Mi Home to ZHA. You will need to pair them again with ZHA.\n\n## Zigbee2MQTT Mode\n\n**IMPORTANT**. According to real user reviews zigbee2mqtt does not work well with EFR32 chips. More positive feedback when working with ZHA.\n\n[Zigbee2MQTT](https://www.zigbee2mqtt.io/) is a bigest project that support [hundreds](https://www.zigbee2mqtt.io/information/supported_devices.html) Zigbee devices from different vendors. And can be integrate with a lot of home automation projects.\n\n**Note:** The zigbee chip of this gateway (EFR32 EZSP) is supported in zigbee2mqtt in [experimental mode](https://www.zigbee2mqtt.io/guide/adapters/#experimental).\n\nStarting 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.\n\nUnlike the ZHA you should install to your host or Hass.io system: [Mosquitto broker](https://github.com/home-assistant/addons/tree/master/mosquitto) and [Zigbee2MQTT Addon](https://github.com/zigbee2mqtt/hassio-zigbee2mqtt). Also you should setup [MQTT](https://www.home-assistant.io/integrations/mqtt/) integration.\n\n```yaml\nserial:\n  port: tcp://{gatewayIP}:8888\n  adapter: ezsp\n```\n\nWhen 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.\n\nZigbee devices will not migrate from Mi Home to Zigbee2MQTT. You will need to pair them again.\n\nYou can use this mode with thanks to [@kirovilya](https://github.com/kirovilya) - developed support EFR32 chips in z2m project\n\n## Zigbee custom firmware\n\n### Firmwares 6.6.2.0 and 6.7.10.0\n\n**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.\n\nYou can flash custom firmware from Gateway select entity.\n\nTo return to MiHome mode - be sure to flash the default firmware!\n\nIt is possible because of these people:\n\n- [@CODeRUS](https://github.com/CODeRUS) and [@zvldz](https://github.com/zvldz) - adapted the script to flash the chip\n- [@faronov](https://github.com/faronov) - complied a new version of firmware\n\n### Firmware 7.3.1.0 MultiPAN RCP\n\n[Read more](https://github.com/AlexxIT/XiaomiGateway3/issues/1328)\n\n## Handle Button Actions\n\nButtons, 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.\n\nDepending on the button model, its state may be:\n- single button: `single`, `double`, `triple`, `quadruple`, `many`, `hold`, `release`, `shake`\n- double button: `button_1_single`, `button_2_single`, `button_both_single`, etc.\n- triple button: `button_1_single`, `button_12_single`, `button_23_single`, etc.\n\nYour button may not have all of these options! Check available values in `action`-sensor attributes when you interact with button.\n\n```yaml\nautomation:\n- alias: Turn off all lights\n  trigger:\n  - platform: state\n    entity_id: sensor.0x158d0002fa99fd_action  # change to your button\n    to: button_1_single  # change to your button state\n  action:\n  - service: light.turn_off\n    entity_id: all\n  mode: single\n```\n\n## Handle BLE Locks\n\n\u003cimg src=\"assets/bluetooth_lock.png\" width=\"810\"\u003e\n\nRead more in [wiki](https://github.com/AlexxIT/XiaomiGateway3/wiki/Handle-BLE-Locks).\n\n## Xiaomi Multimode Gateway beeper\n\nYou can run beeper/buzzer with service: \n\n- duration in seconds\n- volume from 1 to 3\n- send `code: 0` for stop\n\n```yaml\nservice: alarm_control_panel.alarm_trigger\ndata:\n  code: \"10,3\"  # 10 seconds, volume 3\ntarget:\n  entity_id: alarm_control_panel.gateway_alarm\n```\n\n## Obtain Mi Home device token\n\n**Video DEMO**\n\n[![Mi Cloud authorization in Home Assistant with Xiaomi Gateway 3](https://img.youtube.com/vi/rU_ATCVKx78/mqdefault.jpg)](https://www.youtube.com/watch?v=rU_ATCVKx78)\n\nYou 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.\n\nAlso you can get:\n\n- **LAN key** for old [Xiaomi Mijia Gateway](https://www.home-assistant.io/integrations/xiaomi_aqara/) (lumi.gateway.v3)\n- **room names** for Vacuums that support room with names\n- **Bindkey** for BLE devices that has it\n\n\u003cimg src=\"assets/cloud_tokens.png\" width=\"1202\"\u003e\n\n## Multiple Hass\n\nIt's safe to use multiple Hass servers (main and reserve) with integration, but:\n\n- You should use the same integration version and same integration settings on both servers\n- You may use different Hass versions on both servers\n- If you using ZHA mode:\n   - ZHA integration should be installed only on one Hass\n   - Gateway integration may be installed only on one Hass or on both, but with same integration version and same integration settings\n\n## How it works\n\nThe component enables **Telnet** on Gateway via [Miio protocol](https://github.com/rytilahti/python-miio).\n\nStarting with version 3, the component installs a special daemon application on the gateway - [openmiio_agent](https://github.com/AlexxIT/openmiio_agent). You can read more in the separate project repository.\n\nAfter rebooting the gateway, all changes will be reset. The component will launch Telnet and daemon every time it detects that they are disabled.\n\n## Troubleshooting\n\nPut 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. \n\n[![](https://img.youtube.com/vi/tHqZhNcFEvA/mqdefault.jpg)](https://www.youtube.com/watch?v=tHqZhNcFEvA)\n\n**Can't connect to gateway**\n\n- Check [network config](#network-configuration) readme section\n- Check if the Gateway really has the IP-address you set in the configuration\n- 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.\n\n**Lost connection with Zigbee and Bluetooth devices**\n\n- Check [network config](#network-configuration) readme section, gateway and Wi-Fi router settings must be fully matched to all items in the section\n- Turn on stat sesors ([Settings](https://my.home-assistant.io/redirect/config/) \u003e [Integrations](https://my.home-assistant.io/redirect/integrations/) \u003e Gateway 3 \u003e Configure \u003e Add statisic sensors)\n- Check that the connection to the Gateway is not dropped for weeks (`_gateway` sensor value means connection uptime)\n- 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)\n- Check that CPU utilisation is within normal values (`load_avg` attribute in `_gateway` sensor (first 3 items), normal value: below 3)\n- Check that message skip rate for your zigbee device are not high (`msg_missed` attribute in `_zigbee` sensor)\n- 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)\n- Make sure there are no other electronic devices within 0.5 meter from your Gateway\n- Check the distance between the Gateway and the device, greater distances and barriers - the less stable the operation\n- Check the gateway zigbee TX power, you can try to increase it if you need (`radio_tx_power` attribute in `_gateway` sensor)\n\n## Debug mode\n\nLogging can be setup from:\n\n**1. Integration config (GUI)**\n\n**Enable:**\n\n- [Settings](https://my.home-assistant.io/redirect/config/) \u003e [Integrations](https://my.home-assistant.io/redirect/integrations/) \u003e **Xiaomi Gateway 3** \u003e Configure \u003e Debug logs: Basic, MQTT, Zigbee \u003e Refresh the Home Assistant web page.\n\n**2. Integration config (YAML)**\n\nComponent 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.\n\nRecommended config:\n\n```yaml\nxiaomi_gateway3:\n  logger:\n    filename: xiaomi_gateway3.log  # default empty\n    propagate: False               # if False - disable log to home-assistant.log and console, default True\n    max_bytes: 100000000           # file size, default 0\n    backup_count: 3                # file rotation count, default 0\n```\n\nAdditional settings\n\n```yaml\n    level: debug  # default\n    mode: a       # a - append to file, w - write new file, default\n    format: \"%(asctime)s %(levelname)s [%(name)s] %(message)s\"  # default\n```\n\n**3. Hass default config**\n\nYou can set custom modes for custom gateways from GUI. Witout custom modes you won't see gateways logs.\n\n```yaml\nlogger:\n  logs:\n    custom_components.xiaomi_gateway3: debug\n```\n\n## FAQ\n\n**Q. Does this integration support Xiaomi Robot Vacuum, Xiaomi Philips Bulb...?**  \nA. No. The integration does not support Xiaomi Wi-Fi devices.\n\n**Q. Which Mi Home region is best to use?**  \nA. 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](#regional-restrictions).\n\n**Q. What do multimode gateway beeps mean?**  \nA. Beeps AFTER adding Zigbee devices:\n1. No new devices found, the pair is stopped.\n2. New device successfully added.\n3. Unsupported device model.\n\nAlso, if you are using hacked motion sensor - the gateway will periodically beeps. You can [disable it](https://github.com/AlexxIT/XiaomiGateway3/issues/919). \n\n**Q. Does the integration work without internet?**  \nA. Partially. The component connects to a hub on the local network. Adding new devices from/to Mi Home requires Internet.\n\n**Q. Does the integration support non Xiaomi Zigbee devices?**  \nA. 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.\n\n**Q. Will the Zigbee devices continue to work in Mi Home?**  \nA. 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.\n\n**Q. Do I need to receive a token or enable Telnet manually?**  \nA. No. The token is obtained automatically using the login / password from the Mi Home account. Telnet turns on automatically using token.\n\n**Q. Should I open or solder the hub?**  \nA. No.\n\n**Q. Should I use ZHA mode?**  \nA. 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.\n\n**Q. How many Zigbee devices does the hub support?**  \nA. 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.\n\n**Q. Why does the two-button switch only have one entity action?**  \nA. All button clicks are displayed in the status of that one entity.\n\n## Useful links\n\n- [Russian Telegram Community](https://t.me/xiaomi_gw_v3_hack)\n- [Italian Telegram Community](https://t.me/HassioHelp)\n- [Russian video about instal integration](https://youtu.be/FVWfjE5tx2g)\n- [Russian article about flash gateway](https://simple-ha.ru/posts/261)\n- [Home Assistant Community](https://community.home-assistant.io/t/xiaomi-mijia-smart-multi-mode-gateway-zndmwg03lm-support/159586)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexxit%2Fxiaomigateway3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexxit%2Fxiaomigateway3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexxit%2Fxiaomigateway3/lists"}