C# Library for using xiaomi smart gateway in your automation scenarious

Build project Tests Nuget License

This library provides simple and flexible C# API for Xiaomi smart devices.

Currently supports only Gateway version 2 (DGNWG02LM), Gateway version 3 (ZNDMWG03LM), Air Humidifier (zhimi.humidifier.v1), Mi Robot vacuum (rockrobo.vacuum.v1) and several sensors. See table below.

xiaomi-gateway-2

Supported gateway devices/sensors

| Device| Gateway 2 support| Gateway 3 support | |:—: |:—: |:—: | | Xiaomi Door/Window Sensor

MCCGQ01LM | yes | yes | | Xiaomi Door/Window Sensor 2

MCCGQ02HL | no | yes | | Aqara Door/Window Sensor

MCCGQ11LM | yes | yes | | Xiaomi TH Sensor

WSDCGQ01LM | yes | yes | | Xiaomi TH Sensor 2

LYWSD03MMC | no | yes | | Aqara TH Sensor

WSDCGQ11LM | yes | yes | | Aqara Water Leak Sensor

SJCGQ11LM | yes | yes | | Xiaomi Motion Sensor

RTCGQ01LM | yes | yes | | Xiaomi Motion Sensor 2

RTCGQ02LM | no | yes | | Aqara Relay T1 EU (with N)

SSM-U01 | no | yes | | Aqara Relay CN

LLKZMK11LM | no | yes | | Aqara Opple Switch (2 buttons)

WXCJKG11LM | no | yes | | Aqara Opple Switch (4 buttons)

WXCJKG12LM | no | yes | | Honeywell Smoke Sensor

JTYJ-GD-01LM/BW | yes | yes | | Honeywell Smoke Alarm

JTYJ-GD-03MI | no | yes | | Xiaomi Wireless Button

WXKG01LM | yes | yes | | Xiaomi Plug CN

ZNCZ02LM | yes | yes | | Aqara Double Wall Switch (no N)

QBKG03LM | yes | no | | Aqara Double Wall Button CN

WXKG02LM | yes | no | | Aqara Cube EU

MFKZQ01LM | yes | no |

Installation

via nuget package manager

Install-Package MiHomeLib

or

dotnet add package MiHomeLib

or install via GitHub packages

Setup Xiaomi Gateway 2

Before using this library you should setup development mode on your gateway, instructions how to do this.
This mode allows to work with the gateway via UDP multicast protocol.

Warning 1: If you bought a newer revision of Mi Home Gateway (labels in a circle)

It could be possible that ports on your gateway required for UDP multicast traffic are closed.
Before using this library ports must be opened. Check this instruction.

Warning 2: Mi Home Gateway uses udp multicast for messages handling, so your app must be hosted in the same LAN as your gateway. If it is not you have to use multicast routers like udproxy or igmpproxy or vpn bridging.

Warning 3: If your app is running on windows machine, make sure that you disabled virtual network adapters like VirtualBox, Hyper-V, Npcap, pcap etc. Because these adapters may prevent proper work of multicast traffic between your machine and gateway

Setup Xiaomi Gateway 3

Before using this library:

  1. Open telnet on your gateway
  2. Expose MQTT broker to the world
  3. Extract token to work with your gateway

The easisest way is to setup/configure this HA integration (it does all aforementioned things automatically).

The way of warrior:

  1. Enable telnet on your gateway
  2. Download this openmiio_agent and upload it to your gateway (for example to /data/openmiio_agent) via telnet
  3. Login to your gateway via telnet telnet <gateway ip> 23 (login: admin, pwd: empty)
  4. Kill embedded mosquitto mqtt broker and run openmiio_agent (it will expose mqtt port 1883 to the world) kill -9 <pid of mosquitto> && /data/openmiio_agent mqtt &
  5. Check that mosquitto is binded to 0.0.0.0 1883 netstat -ntlp | grep mosquitto
  6. Extract token instructions

Basic scenarios

Get all devices in the network from the Xiaomi Gateway 2

public static void Main(string[] args)
{
    // gateway password is optional, needed only to send commands to your devices
    // gateway sid is optional, use only when you have 2 gateways in your LAN
    // using var gw2 = new XiaomiGateway2("gateway password", "gateway sid");
    using var gw2 = new XiaomiGateway2();
   
    gw2.OnAnyDevice += (_, device) =>
    {
        Console.WriteLine($"{device.Sid}, {device.GetType()}, {device}"); // all discovered devices
    };

    Console.ReadLine();
}

Get all devices in the network from the Xiaomi Gateway 3

public static void Main(string[] args)
{
    using var gw3 = new XiaomiGateway3("<gateway ip>", "<gateway token>");

    gw3.OnDeviceDiscovered += gw3SubDevice =>
    {
        Console.WriteLine(gw3SubDevice.ToString()); // all discovered devices
    };

    gw3.DiscoverDevices();

    Console.ReadLine();
}

Documentation

Check detailed documentation on how to work with different devices in the project’s WIKI

Contribution

Your pull requests are welcome to replenish the database of supported devices