https://github.com/sergey-brutsky/mi-home
С# API for Xiaomi Mi Home devices
https://github.com/sergey-brutsky/mi-home
airhumidifier aqara csharp dgnwg02lm door-window-sensor gateway mi-robot-vacuum motion-sensor multimode-gateway multimode-gateway-2 smoke-sensor temperature-sensor water-sensor xiaomi xiaomi-gateway xiaomi-smart-home zndmwg03lm zndmwg04lm
Last synced: 5 months ago
JSON representation
С# API for Xiaomi Mi Home devices
- Host: GitHub
- URL: https://github.com/sergey-brutsky/mi-home
- Owner: sergey-brutsky
- License: mit
- Created: 2017-08-26T12:39:04.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2025-09-14T10:25:47.000Z (9 months ago)
- Last Synced: 2025-09-15T00:47:03.939Z (9 months ago)
- Topics: airhumidifier, aqara, csharp, dgnwg02lm, door-window-sensor, gateway, mi-robot-vacuum, motion-sensor, multimode-gateway, multimode-gateway-2, smoke-sensor, temperature-sensor, water-sensor, xiaomi, xiaomi-gateway, xiaomi-smart-home, zndmwg03lm, zndmwg04lm
- Language: C#
- Homepage:
- Size: 515 KB
- Stars: 153
- Watchers: 22
- Forks: 37
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# C# Library for using xiaomi/aqara gateways in your automation scenarious
[](https://github.com/sergey-brutsky/mi-home/actions/workflows/main.yml)
[](https://github.com/sergey-brutsky/mi-home/actions/workflows/main.yml)
[](https://github.com/sergey-brutsky/mi-home/actions/workflows/main.yml)
[](https://github.com/sergey-brutsky/mi-home/actions/workflows/github-code-scanning/codeql)
[](https://www.nuget.org/packages/MiHomeLib)
[](https://www.nuget.org/packages/MiHomeLib)
[](https://github.com/sergey-brutsky/mi-home/blob/master/LICENSE.md)
This library provides simple and flexible C# API for Xiaomi/Aqara gateways and smart devices.
## Supported gateways
| Gateway | Market Model | Model |
|:--- |:---|:---|
[Xiaomi Gateway 2 China](https://github.com/sergey-brutsky/mi-home/wiki/Xiaomi-Gateway-2) | DGNWG02LM | lumi.gateway.v3 |
[Multimode Gateway](https://github.com/sergey-brutsky/mi-home/wiki/Multimode-Gateway) | ZNDMWG03LM | lumi.gateway.mgl03 |
[Multimode Gateway 2 Global](https://github.com/sergey-brutsky/mi-home/wiki/Multimode-Gateway-2-Global) | ZNDMWG04LM | lumi.gateway.mgl001 |
[Multimode Gateway 2 China](https://github.com/sergey-brutsky/mi-home/wiki/Multimode-Gateway-2-China) | DMWG03LM | lumi.gateway.mcn001 |
[Aqara Hub E1 China](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-Hub-E1-China) | ZHWG16LM | lumi.gateway.aqcn02 |
## Supported wifi devices
| Device | Market Model | Model |
|:--- |:---|:---|
[Xiaomi Mijia Smart Sterilization](https://github.com/sergey-brutsky/mi-home/wiki/Air-Humidifier-(MJJSQ03DY)) | MJJSQ03DY | zhimi.humidifier.v1 |
[Xiaomi Mi Robot Vacuum Cleaner](https://github.com/sergey-brutsky/mi-home/wiki/Mi-Robot-Vacuum-(SDJQR02RR)) | SDJQR02RR | rockrobo.vacuum.v1 |
[Mi Robot Mop 3C](https://github.com/sergey-brutsky/mi-home/wiki/Mi-Robot-Mop3C-(B106CN)) | B106CN | ijai.vacuum.v18 |
[Xiaomi Smart Plug 2 Euro](https://github.com/sergey-brutsky/mi-home/wiki/Xiaomi-Smart-Plug-2-Euro-(ZNCZ302KK)) | ZNCZ302KK | cuco.plug.v2eur |
[Mijia Smart Socket 2 China](https://github.com/sergey-brutsky/mi-home/wiki/Mijia-Smart-Socket-2-China-(ZNCZ07CM)) | ZNCZ07CM | chuangmi.plug.212a01 |
## Supported zigbee/ble devices
| Device support | Gateway 2 | Multimode Gateway | Multimode Gateway 2| Aqara Hub E1
|:---: |:---: |:---: |:---: |:---: |
| [Aqara Vibration Sensor](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-Vibration-sensor-(DJT11LM))
DJT11LM | yes | yes | yes | yes
| [Xiaomi Door/Window Sensor](https://github.com/sergey-brutsky/mi-home/wiki/Xiaomi-Door-Window-sensor-(MCCGQ01LM))
MCCGQ01LM | yes | yes | yes | yes
| [Xiaomi Door/Window Sensor 2](https://github.com/sergey-brutsky/mi-home/wiki/Xiaomi-Door-Window-sensor-2-(MCCGQ02HL))
MCCGQ02HL | no | yes | yes | no
| [Aqara Door/Window Sensor](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-Door-Window-sensor-(MCCGQ11LM))
MCCGQ11LM | yes | yes | yes | yes
| [Xiaomi TH Sensor](https://github.com/sergey-brutsky/mi-home/wiki/Xiaomi-TH-sensor-(WSDCGQ01LM))
WSDCGQ01LM | yes | yes | yes | yes
| [Xiaomi TH Sensor 2](https://github.com/sergey-brutsky/mi-home/wiki/Xiaomi-TH-sensor-2-(LYWSD03MMC))
LYWSD03MMC | no | yes | yes | no
| [Aqara TH Sensor](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-TH-sensor-(WSDCGQ11LM))
WSDCGQ11LM | yes | yes | yes | yes
| [Aqara Water Leak Sensor](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-Water-Leak-sensor-(SJCGQ11LM))
SJCGQ11LM | yes | yes | yes | yes
| [Xiaomi Motion Sensor](https://github.com/sergey-brutsky/mi-home/wiki/Xiaomi-Motion-sensor-(RTCGQ01LM))
RTCGQ01LM | yes | yes | yes | yes
| [Xiaomi Motion Sensor 2](https://github.com/sergey-brutsky/mi-home/wiki/Xiaomi-Motion-sensor-2-(RTCGQ02LM))
RTCGQ02LM | no | yes | yes | no
| [Aqara Relay T1 EU (with N)](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-Relay-T1-EU-(SSM%E2%80%90U01))
SSM-U01 | no | yes | yes | yes
| [Aqara Relay CN](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-Relay-CN-(LLKZMK11LM))
LLKZMK11LM | no | yes | yes | yes
| [Aqara Opple Switch (2 buttons)](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-Opple-Switch-(2-buttons)-(WXCJKG11LM))
WXCJKG11LM | no | yes | yes | yes
| [Aqara Opple Switch (4 buttons)](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-Opple-Switch-(4-buttons)-(WXCJKG12LM))
WXCJKG12LM | no | yes | yes | yes
| [Honeywell Smoke Sensor](https://github.com/sergey-brutsky/mi-home/wiki/Honeywell-Smoke-Sensor-(JTYJ%E2%80%90GD%E2%80%9001LM-BW))
JTYJ-GD-01LM/BW | yes | yes | yes | yes
| [Honeywell Smoke Alarm](https://github.com/sergey-brutsky/mi-home/wiki/Honeywell-Smoke-Alarm-(JTYJ%E2%80%90GD%E2%80%9003MI))
JTYJ-GD-03MI | no | yes | yes | no
| [Xiaomi Wireless Button](https://github.com/sergey-brutsky/mi-home/wiki/Xiaomi-Wireless-Button-(WXKG01LM))
WXKG01LM | yes | yes | yes | yes
| [Xiaomi Plug CN](https://github.com/sergey-brutsky/mi-home/wiki/Xiaomi-Plug-CN-(ZNCZ02LM))
ZNCZ02LM | yes | yes | yes | yes
| [Aqara Double Wall Switch (no N)](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-Double-Wall-Switch-(no-N)-(QBKG03LM))
QBKG03LM | yes | no | no | no
| [Aqara Double Wall Button CN](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-Double-Wall-Button-CN-(WXKG02LM))
WXKG02LM | yes | no | no | no
| [Aqara Cube EU](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-Cube-EU-(MFKZQ01LM))
MFKZQ01LM | yes | no | no | no
## Installation
via nuget package manager
```nuget
Install-Package MiHomeLib
```
or
```nuget
dotnet add package MiHomeLib
```
or install via [GitHub packages](https://github.com/sergey-brutsky/mi-home/pkgs/nuget/MiHomeLib)
Before using this library you should setup **development mode** on your gateway, [instructions how to do this](https://www.domoticz.com/wiki/Xiaomi_Gateway_(Aqara)).\
This mode allows to work with the gateway via UDP multicast protocol.
**Warning 1**:
If you bought a newer revision of Xiaomi Gateway 2 (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](https://community.openhab.org/t/solved-openhab2-xiaomi-mi-gateway-does-not-respond/52963/114).
**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](https://github.com/pcherenkov/udpxy) or [igmpproxy](https://github.com/pali/igmpproxy) or [vpn bridging](https://forums.openvpn.net/viewtopic.php?t=21509).
**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 Multimode Gateway (same for Multimode Gateway 2)
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](https://github.com/AlexxIT/XiaomiGateway3/) (it does all aforementioned things automatically).
The way of warrior:
1. [Enable telnet on your gateway](https://gist.github.com/zvldz/1bd6b21539f84339c218f9427e022709)
2. Download this [openmiio_agent](http://github.com/AlexxIT/openmiio_agent/releases/download/v1.2.1/openmiio_agent_mips) and upload it to your gateway (for example to /data/openmiio_agent) via telnet
3. Login to your gateway via telnet `telnet 23` (login: admin or root, pwd: empty)
4. Kill embedded mosquitto mqtt broker and run openmiio_agent (it will expose mqtt port 1883 to the world) `kill -9 && /data/openmiio_agent mqtt &`
5. Check that mosquitto is binded to `0.0.0.0 1883` `netstat -ntlp | grep mosquitto`
6. [Extract token instructions](https://github.com/jghaanstra/com.xiaomi-miio/blob/master/docs/obtain_token.md)
Before using this library you need:
1. [Open telnet on your gateway](https://gist.github.com/zvldz/1bd6b21539f84339c218f9427e022709#aqara-hub-e1-zhwg16lm-usb-stick)
2. [Find out device id (did) of the gateway](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-Hub-E1-China)
3. [Find ip and token of the gateway](https://blog.matterxiaomi.com/blog/how-get-mi-home-devices-token/)
More details in the [project's WIKI](https://github.com/sergey-brutsky/mi-home/wiki/Aqara-Hub-E1-China)
Get all devices in the network from the **Xiaomi Gateway 2**
```csharp
public static void Main(string[] args)
{
// gateway sid is optional, use only when you have 2 or more gateways in your LAN
// using var gw2 = new XiaomiGateway2("ip", "token", "gateway sid");
using var gw2 = new XiaomiGateway2("", "");
{
gw2.OnDeviceDiscoveredAsync += d =>
{
Console.WriteLine(d.ToString());
return Task.CompletedTask;
};
gw2.DiscoverDevices();
}
}
```
Get all devices in the network from the **Xiaomi Multimode Gateway**
```csharp
public static void Main(string[] args)
{
using var multimodeGw = new MultimodeGateway("", "", "");
{
multimodeGw.OnDeviceDiscoveredAsync += d =>
{
Console.WriteLine(d.ToString());
return Task.CompletedTask;
};
multimodeGw.DiscoverDevices();
}
}
```
Get all devices in the network from the **Xiaomi Multimode Gateway 2 Global**
```csharp
public static void Main(string[] args)
{
using var multimodeGw2 = new MultimodeGateway2Global("", "", "");
{
multimodeGw2.OnDeviceDiscoveredAsync += d =>
{
Console.WriteLine(d.ToString());
return Task.CompletedTask;
};
multimodeGw2.DiscoverDevices();
}
}
```
Get all devices in the network from the **Xiaomi Multimode Gateway 2 China**
```csharp
public static void Main(string[] args)
{
using var multimodeGw2 = new MultimodeGateway2China("", "", "");
{
multimodeGw2.OnDeviceDiscoveredAsync += d =>
{
Console.WriteLine(d.ToString());
return Task.CompletedTask;
};
multimodeGw2.DiscoverDevices();
}
}
```
Get all devices in the network from the **Aqara Hub E1 Gateway**
```csharp
public static void Main()
{
using var gw = new AqaraHubE1China("ip", "token", "did");
{
gw.OnDeviceDiscoveredAsync += d =>
{
Console.WriteLine(d.ToString());
return Task.CompletedTask;
};
gw.DiscoverDevices();
}
Console.ReadLine();
}
```
Check detailed documentation on how to work with different devices in the [project's WIKI](https://github.com/sergey-brutsky/mi-home/wiki)
## Contribution
Your pull requests are welcome to replenish the database of supported devices