DOCSEARCHbyAlgolia
Submit Docs

Xiaomi Gateway 3

repository·master·Indexed 25 days ago

https://github.com/alexxit/xiaomigateway3

A Home Assistant custom component to control Xiaomi Multimode Gateways (Gateway 3), Multimode Gateway 2, and Aqara Hub E1 over LAN using default firmwares. It supports Zigbee, BLE, and Mesh devices, and provides options for Mi Home, ZHA, or Zigbee2MQTT operation modes. The integration allows for local control, token retrieval via cloud login, and detailed gateway statistics monitoring.

Tokens
13K
Snippets
13
Records
30
Agent score
83%

What's inside xiaomigateway3

  1. Understand Zigbee Operation Modes

    master

    The Gateway Zigbee chip can operate in three distinct modes. Note that devices controlled via ZHA or Zigbee2MQTT are not controlled by this integration:

    1. Mi Home (default): Supports Xiaomi/Aqara Zigbee devices simultaneously in both Mi Home and Home Assistant. Also supports select third-party Zigbee devices in Home Assistant.
    2. Zigbee Home Automation (ZHA): Supports hundreds of Zigbee brands via the ZHA integration in Home Assistant.
    3. Zigbee2MQTT: Supports hundreds of Zigbee brands via MQTT.

    Note: Xiaomi BLE and Mesh devices work in both Mi Home and Home Assistant regardless of the Zigbee mode selected.

  2. Frequently Asked Questions about Xiaomi Gateway 3

    master

    Device Support

    • Wi-Fi Devices: This integration does not support Xiaomi Wi-Fi devices (e.g., Robot Vacuums, Philips Bulbs).
    • Third-party Zigbee: Supported via three different methods, though not every device is guaranteed to work.
    • Zigbee Capacity: Supports up to 32 battery-powered end devices and up to 26 powered routers directly. Total capacity is higher via routers.

    Regional & Connectivity

    • Mi Home Region: The China region offers the most support. European regions may have issues with new E1/H1/T1-series and Mesh devices.
    • Internet Requirement: Works partially without internet. Local connection to the hub is maintained, but adding/removing devices via Mi Home requires internet.
    • Mi Home Coexistence: Zigbee devices will continue to work in Mi Home if you do not enable ZHA or z2m mode.

    Hardware & Setup

    • Tokens & Telnet: Tokens are obtained automatically via Mi Home login/password. Telnet is enabled automatically using the token.
    • Beep Codes: After adding Zigbee devices, beeps indicate:
      1. No new devices found (pairing stopped).
      2. New device successfully added.
      3. Unsupported device model.
    • Button Switches: For two-button switches, all click actions are reported within the status of a single entity.

  3. Configure the Xiaomi Gateway 3 Integration

    master

    Configure the integration via the Home Assistant UI: Settings > Integrations > Xiaomi Gateway 3 > CONFIGURE.

    Required settings:

    • Host: The gateway's IP address (ensure it is fixed in your router settings).
    • Token: The gateway's Mi Home token.
    • Key: The gateway's secret key.

    Additional options:

    • Add statistic sensors: Enables extra sensor data (see Statistics Table).
    • Debug logs: Enables different logging levels.

  4. Enable Zigbee Home Automation (ZHA) mode

    master

    To use the gateway with the ZHA integration, configure ZHA in Home Assistant using the EZSP radio type.

    Note: Using ZHA with WiFi-based bridges may have stability issues. When ZHA is active, Zigbee devices will stop working in the Mi Home app and must be re-paired with ZHA. BLE and Mesh devices will continue to work in both Mi Home and Home Assistant.

    ZHA Configuration Settings:

    • Serial device path: socket://{gatewayIP}:8888
    • port speed: any
    • data flow control: any

  6. Enable Zigbee2MQTT mode

    master

    To use the gateway with Zigbee2MQTT, configure the Z2M add-on and the MQTT integration. The EFR32 EZSP chip is supported in experimental mode.

    Note: When Z2M is active, Zigbee devices will stop working in the Mi Home app and must be re-paired. BLE and Mesh devices will continue to work in both Mi Home and Home Assistant.

    Zigbee2MQTT Serial Configuration:

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

  7. Configure Network Settings for Gateway Stability

    master

    To ensure stable operation of the gateway, follow these network configuration requirements:

    • Network Topology: The Gateway and Home Assistant server must be on a Shared LAN. If using a VPN, both IP addresses must be in the same network subnet.
    • Connectivity:
      • Enable ping (ICMP) from the Gateway to the Router.
      • Assign a Fixed IP-address to the Gateway on your Router.
    • Wi-Fi Router Settings (2.4GHz):
      • Fixed channel: Use channels 1 through 11.
      • Channel width: Set to 20MHz (do not use 40MHz).
      • Authentication: Use WPA2 (do not use WPA3).
    • Specific Router Hardware:
      • MikroTik: Set Wireless > Security Profiles > Group Key Update to 01:00:00 (1 hour or more).
      • Keenetic: Disable Airtime Fairness and 256-QAM for the 2.4GHz band.

  8. Configure the Xiaomi Gateway 3 Integration

    master

    To set up the integration, go to Settings > Integrations > Add Integration > Xiaomi Gateway3.

    Important Setup Steps:

    • Two-step configuration: You typically need to add the integration twice:
      1. Cloud version: Used ONLY to load tokens and device names from the cloud. You can skip this if you already have your gateway token.
      2. Gateway: Adds your physical gateway and all connected Zigbee, BLE, and Mesh devices.
    • Multiple Gateways: If you have more than one gateway, repeat the 'Gateway' step for each one.
    • Keys: You only need a gateway key if you are using a Xiaomi Multimode Gateway on firmware 1.5.5 or higher.

  9. Install Xiaomi Gateway 3 via HACS or Manual Installation

    master

    You can install the Xiaomi Gateway 3 custom component for Home Assistant using one of two methods:

    1. HACS: Navigate to HACS > Integrations > Plus > search for XiaomiGateway3 > Install.
    2. Manual: Download the latest release from the GitHub repository and copy the xiaomi_gateway3 folder into your /config/custom_components directory.

  10. Enable and Display Gateway Statistics

    master

    To view gateway health and Zigbee statistics in a table format:

    1. Enable statistics sensors: Settings > Integrations > Xiaomi Gateway 3 > Options > Add statistic sensors.
    2. Install Flex Table via HACS.
    3. Create a new Lovelace tab in Panel Mode.
    4. Add a Lovelace card using one of the following configuration examples:

    Available Gateway Binary Sensor Attributes:

    • radio_tx_power: Zigbee chip power.
    • radio_channel: Zigbee chip channel.
    • free_mem: Gateway free memory in bytes.
    • load_avg: Gateway CPU load.
    • rssi: Gateway Wi-Fi signal strength.
    • uptime: Gateway uptime since last reboot.

  11. Configure Multiple Gateways

    master

    The integration supports multiple MiHome accounts and multiple gateways.

    • Zigbee: Devices can only be paired to one gateway. It is recommended to split Zigbee networks across several gateways for stability. Avoid mixing battery-powered and mains-powered devices in the same network.
    • Bluetooth (BLE/Mesh): These devices are not bound to a specific gateway and can work with all gateways simultaneously.
    • Bluetooth Mesh Data: If multiple Bluetooth Mesh Gateways are present, only one sends data to the cloud, but this integration collects Bluetooth data from all gateways locally.

  12. Understand Regional Restrictions for Xiaomi/Aqara Devices

    master

    Device compatibility depends on the MiHome cloud server (EU vs CN) and the application used (Official MiHome vs Mi Home by Vevs).

    • Gateway 3 (CN/EU): Supported on all platforms.
    • Zigbee E1 series: Supported ONLY on China (CN) cloud servers.
    • Zigbee H1/T1 series: Not officially supported in MiHome. Can be added ONLY to China (CN) cloud servers. They can be controlled via Home Assistant (check supported list) but not via the stock MiHome app.
    • Bluetooth BLE/Mesh: Most are supported on CN cloud. Using Mi Home by Vevs allows adding some to any cloud.
    • Note: You cannot add Zigbee E1/H1/T1 devices to the Euro cloud even with Mi Home by Vevs.

    Important: If you control devices via Home Assistant, the cloud region does not matter; devices are controlled locally and without delay regardless of the cloud used.