README.md

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

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.

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