[Documentation] Markdown improvements f to m (#13866)
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
This commit is contained in:
Jerome Luckenbach
committed by
GitHub
GitHub
parent
3c236b3103
commit
0e68936663
@@ -1,12 +1,12 @@
|
||||
# Xiaomi Mi Smart Home Binding
|
||||
|
||||
This binding allows your openHAB to communicate with the Xiaomi Smart Home Suite.
|
||||
It consists of devices communicating over a ZigBee network with a ZigBee - WiFi gateway.
|
||||
It consists of devices communicating over a ZigBee network with a ZigBee - WiFi gateway.
|
||||
|
||||
The devices are very affordable and you can get them from your favourite Chinese markets like [AliExpress](https://www.aliexpress.com/) or [GearBest](https://www.gearbest.com).
|
||||
The sensors run on a coin cell battery for over a year.
|
||||
The sensors run on a coin cell battery for over a year.
|
||||
|
||||
After setup, you can disconnect the gateway from the internet to keep your sensor information private.
|
||||
After setup, you can disconnect the gateway from the internet to keep your sensor information private.
|
||||
|
||||
Please note that using the Xiaomi gateway with openHAB requires enabling the developer mode and that multiple user reports suggest that it is no longer possible.
|
||||
Zigbee2Mqtt provides an alternative method to integrate Xiaomi devices.
|
||||
@@ -15,90 +15,81 @@ Zigbee2Mqtt provides an alternative method to integrate Xiaomi devices.
|
||||
|
||||
| Device | Picture |
|
||||
| --- | --- |
|
||||
| Gateway v2 (with radio support) or v3 |  |
|
||||
| Mijia Temperature and Humidity Sensor | |
|
||||
| Aqara Temperature, Humidity and Pressure Sensor |  |
|
||||
| Mijia Door/Window Sensor |  |
|
||||
| Aqara Door/Window Sensor |  |
|
||||
| Mijia Human Body Sensor |  |
|
||||
| Aqara Motion Sensor (with light intensity support) |  |
|
||||
| Smart Socket (Zigbee version) |  |
|
||||
| Magic Cube Controller |  |
|
||||
| Aqara Magic Cube Controller |  |
|
||||
| Aqara Vibration Sensor |  |
|
||||
| Mijia Wireless Switch |  |
|
||||
| Aqara Wireless Switch |  |
|
||||
| Aqara Wireless Switch (with acceleration sensor) |  |
|
||||
| Aqara Wall Switch (1 & 2 Button / With or Without Neutral Line) |  |
|
||||
| Aqara Wireless Light Control (1 & 2 Button) |  |
|
||||
| Aqara Curtain Motor |  |
|
||||
| Aqara Water Leak Sensor |  |
|
||||
| Honeywell Gas Detector |  |
|
||||
| Honeywell Smoke Detector |  |
|
||||
| Aqara Fingerprint & Keyless Card & PIN Lock |  |
|
||||
| Gateway v2 (with radio support) or v3 |  |
|
||||
| Mijia Temperature and Humidity Sensor | |
|
||||
| Aqara Temperature, Humidity and Pressure Sensor |  |
|
||||
| Mijia Door/Window Sensor |  |
|
||||
| Aqara Door/Window Sensor |  |
|
||||
| Mijia Human Body Sensor |  |
|
||||
| Aqara Motion Sensor (with light intensity support) |  |
|
||||
| Smart Socket (Zigbee version) |  |
|
||||
| Magic Cube Controller |  |
|
||||
| Aqara Magic Cube Controller |  |
|
||||
| Aqara Vibration Sensor |  |
|
||||
| Mijia Wireless Switch |  |
|
||||
| Aqara Wireless Switch |  |
|
||||
| Aqara Wireless Switch (with acceleration sensor) |  |
|
||||
| Aqara Wall Switch (1 & 2 Button / With or Without Neutral Line) |  |
|
||||
| Aqara Wireless Light Control (1 & 2 Button) |  |
|
||||
| Aqara Curtain Motor |  |
|
||||
| Aqara Water Leak Sensor |  |
|
||||
| Honeywell Gas Detector |  |
|
||||
| Honeywell Smoke Detector |  |
|
||||
| Aqara Fingerprint & Keyless Card & PIN Lock |  |
|
||||
|
||||
## Setup
|
||||
|
||||
* Install the binding
|
||||
* Is your gateway already configured to connect to your WiFi? If not:
|
||||
|
||||
1. Install MiHome app from [Google Play](https://play.google.com/store/apps/details?id=com.xiaomi.smarthome) or [AppStore](https://itunes.apple.com/app/mi-home-xiaomi-for-your-smarthome/id957323480) (your phone may need to be changed to English language first)
|
||||
2. In the app create a Mi Home account and make sure to set your region to Mainland (China) under Settings -> Locale
|
||||
3. If asked, do NOT update your gateway to the latest firmware (note that update window may pop up sequentially). If you update, you may not be able to access the developer mode below.
|
||||
|
||||
* Enable developer mode of your gateway:
|
||||
|
||||
1. Select your Gateway in the MiHome app
|
||||
2. Go to the "..." menu on the top right corner and click "About"
|
||||
3. You now see two options "Smart Home Kit Forum" and "Gameplay Tutorial". Tap 5 times below the "Gameplay Tutorial" in the empty space (not the button itself) until you enable developer mode
|
||||
4. You should now have 2 extra options listed: `wireless communication protocol` and `hub info`, it may appear in Chinese
|
||||
5. Choose `wireless communication protocol`
|
||||
6. Tap the toggle switch to enable WiFi functions. Note down the developer key (aka password), something like: 91bg8zfkf9vd6uw7
|
||||
7. Make sure you hit the OK button (to the right of the cancel button) to save your changes
|
||||
8. Now update the gateway to the latest firmware
|
||||
|
||||
* Enable developer mode of your gateway (legacy app):
|
||||
|
||||
1. Select your Gateway in the MiHome app
|
||||
2. Go to the "..." menu on the top right corner and click "About"
|
||||
3. Tap the version number "Plug-in version : 2.XX.X" at the bottom of the screen repeatedly until you enable developer mode
|
||||
4. You should now have 2 extra options listed: `wireless communication protocol` and `hub info`
|
||||
5. Choose `wireless communication protocol`
|
||||
6. Tap the toggle switch to enable WiFi functions. Note down the developer key (aka password), something like: 91bg8zfkf9vd6uw7
|
||||
7. Make sure you hit the OK button (to the right of the cancel button) to save your changes
|
||||
8. Now update the gateway to the latest firmware
|
||||
|
||||
* In openHAB you should now be able to discover the Xiaomi Gateway
|
||||
* From now on you don't really need the app anymore. Only if you want to update the gateway firmware or if you want to add devices (see below). But adding devices can also be done without the app (see below)
|
||||
* Enter the previously noted developer key in openHAB Administration -> Settings -> Things -> Xiaomi Gateway -> Edit -> Developer Key. Save (This is required if you want to be able to send controls to the devices like the light of the gateway)
|
||||
- Install the binding
|
||||
- Is your gateway already configured to connect to your WiFi? If not:
|
||||
1. Install MiHome app from [Google Play](https://play.google.com/store/apps/details?id=com.xiaomi.smarthome) or [AppStore](https://itunes.apple.com/app/mi-home-xiaomi-for-your-smarthome/id957323480) (your phone may need to be changed to English language first)
|
||||
1. In the app create a Mi Home account and make sure to set your region to Mainland (China) under Settings -> Locale
|
||||
1. If asked, do NOT update your gateway to the latest firmware (note that update window may pop up sequentially). If you update, you may not be able to access the developer mode below.
|
||||
- Enable developer mode of your gateway:
|
||||
1. Select your Gateway in the MiHome app
|
||||
1. Go to the "..." menu on the top right corner and click "About"
|
||||
1. You now see two options "Smart Home Kit Forum" and "Gameplay Tutorial". Tap 5 times below the "Gameplay Tutorial" in the empty space (not the button itself) until you enable developer mode
|
||||
1. You should now have 2 extra options listed: `wireless communication protocol` and `hub info`, it may appear in Chinese
|
||||
1. Choose `wireless communication protocol`
|
||||
1. Tap the toggle switch to enable WiFi functions. Note down the developer key (aka password), something like: 91bg8zfkf9vd6uw7
|
||||
1. Make sure you hit the OK button (to the right of the cancel button) to save your changes
|
||||
1. Now update the gateway to the latest firmware
|
||||
- Enable developer mode of your gateway (legacy app):
|
||||
1. Select your Gateway in the MiHome app
|
||||
1. Go to the "..." menu on the top right corner and click "About"
|
||||
1. Tap the version number "Plug-in version : 2.XX.X" at the bottom of the screen repeatedly until you enable developer mode
|
||||
1. You should now have 2 extra options listed: `wireless communication protocol` and `hub info`
|
||||
1. Choose `wireless communication protocol`
|
||||
1. Tap the toggle switch to enable WiFi functions. Note down the developer key (aka password), something like: 91bg8zfkf9vd6uw7
|
||||
1. Make sure you hit the OK button (to the right of the cancel button) to save your changes
|
||||
1. Now update the gateway to the latest firmware
|
||||
- In openHAB you should now be able to discover the Xiaomi Gateway
|
||||
- From now on you don't really need the app anymore. Only if you want to update the gateway firmware or if you want to add devices (see below). But adding devices can also be done without the app (see below)
|
||||
- Enter the previously noted developer key in openHAB Administration -> Settings -> Things -> Xiaomi Gateway -> Edit -> Developer Key. Save (This is required if you want to be able to send controls to the devices like the light of the gateway)
|
||||
|
||||
## Connecting devices to the gateway
|
||||
|
||||
There are three ways of connecting supported devices to the gateway:
|
||||
|
||||
* Online - within the MiHome App
|
||||
* Offline - manual
|
||||
- Online - within the MiHome App
|
||||
- Offline - manual
|
||||
1. Click 3 times on the Gateway's button
|
||||
1. Gateway will flash in blue and you will hear female voice in Chinese, you have 30 seconds to include your new device
|
||||
1. Place the needle into the sensor and hold it for at least 3 seconds
|
||||
1. You will hear confirmation message in Chinese
|
||||
1. The device appears in openHAB thing Inbox
|
||||
- With the binding
|
||||
1. After adding the gateway make sure you have entered the right developer key
|
||||
1. In the UI, go to your Inbox and trigger a discovery for the binding
|
||||
1. The gateway flashes in blue and you hear a female voice in Chinese, you have 30 seconds to include your new device
|
||||
1. Follow the instructions for your device to pair it to the gateway
|
||||
1. You will hear a confirmation message in Chinese
|
||||
1. The device appears in openHAB thing Inbox
|
||||
|
||||
1. Click 3 times on the Gateway's button
|
||||
2. Gateway will flash in blue and you will hear female voice in Chinese, you have 30 seconds to include your new device
|
||||
3. Place the needle into the sensor and hold it for at least 3 seconds
|
||||
4. You will hear confirmation message in Chinese
|
||||
5. The device appears in openHAB thing Inbox
|
||||
**Hints:**
|
||||
|
||||
* With the binding
|
||||
- If you don't want to hear the Chinese voice every time, you can disable it by setting the volume to minimum in the MiHome App (same for the blinking light)
|
||||
|
||||
1. After adding the gateway make sure you have entered the right developer key
|
||||
2. In the UI, go to your Inbox and trigger a discovery for the binding
|
||||
3. The gateway flashes in blue and you hear a female voice in Chinese, you have 30 seconds to include your new device
|
||||
4. Follow the instructions for your device to pair it to the gateway
|
||||
5. You will hear a confirmation message in Chinese
|
||||
6. The device appears in openHAB thing Inbox
|
||||
|
||||
__Hints:__
|
||||
|
||||
* If you don't want to hear the Chinese voice every time, you can disable it by setting the volume to minimum in the MiHome App (same for the blinking light)
|
||||
|
||||
* The devices don't need an Internet connection to be working after you have set up the developer mode BUT you will not be able to connect to them via App anymore - easiest way is to block their outgoing Internet connection in your router and enable it later, when you want to check for updates etc. This will ensure that your smart home data stays only with you!
|
||||
- The devices don't need an Internet connection to be working after you have set up the developer mode BUT you will not be able to connect to them via App anymore - easiest way is to block their outgoing Internet connection in your router and enable it later, when you want to check for updates etc. This will ensure that your smart home data stays only with you!
|
||||
|
||||
## Removing devices from the gateway
|
||||
|
||||
@@ -111,7 +102,8 @@ Just follow the instructions in ["Connecting devices to the gateway"](#connectin
|
||||
- The binding requires port `9898` to not be used by any other service on the system.
|
||||
- Make sure multicast traffic is correctly routed between the gateway and your openHAB instance
|
||||
- To correctly receive multicast traffic, when your openHAB machine is using multiple network interfaces, you might need to configure the optional `interface` property on the `Bridge` Thing, like so:
|
||||
```
|
||||
|
||||
```java
|
||||
Bridge mihome:bridge:f0b429XXXXXX "Xiaomi Gateway" [ ..., interface="eth0", ... ] {
|
||||
```
|
||||
|
||||
@@ -119,7 +111,7 @@ Bridge mihome:bridge:f0b429XXXXXX "Xiaomi Gateway" [ ..., interface="eth0", ...
|
||||
|
||||
### xiaomi.things:
|
||||
|
||||
```
|
||||
```java
|
||||
Bridge mihome:bridge:f0b429XXXXXX "Xiaomi Gateway" [ serialNumber="f0b429XXXXXX", ipAddress="192.168.0.3", port=9898, key="XXXXXXXXXXXXXXXX" ] {
|
||||
Things:
|
||||
gateway f0b429XXXXXX "Xiaomi Mi Smart Home Gateway" [itemId="f0b429XXXXXX"]
|
||||
@@ -135,7 +127,7 @@ Bridge mihome:bridge:f0b429XXXXXX "Xiaomi Gateway" [ serialNumber="f0b429XXXXXX"
|
||||
|
||||
### xiaomi.items:
|
||||
|
||||
```
|
||||
```java
|
||||
// Replace <GwID> with itemId of gateway from Things file
|
||||
// Replace <ID> with itemId of item from Things file
|
||||
// Gateway
|
||||
@@ -241,7 +233,7 @@ Rollershutter CurtainMotorControl <blinds> { channel="curtain:<GwID>:<ID>:curtai
|
||||
|
||||
### xiaomi.rules:
|
||||
|
||||
```
|
||||
```java
|
||||
rule "Mijia & Aqara Wireless Switch"
|
||||
when
|
||||
Channel "mihome:sensor_switch:<GwID>:<ID>:button" triggered
|
||||
@@ -395,10 +387,10 @@ end
|
||||
|
||||
### xiaomi.sitemap:
|
||||
|
||||
```
|
||||
```perl
|
||||
sitemap xiaomi label="Xiaomi" {
|
||||
// Example for selection of predefined sound file - you can also upload your own files with the official MiHome App and play them!
|
||||
Frame {
|
||||
Frame {
|
||||
...
|
||||
|
||||
// Selection for Xiaomi Gateway Sounds
|
||||
@@ -445,9 +437,9 @@ Make sure you have connected your gateway to openHAB and the communication is wo
|
||||
- Go through the normal procedure to add a device to the gateway
|
||||
- The device will show up in your inbox as a new unsupported device and its model name
|
||||
- Add the device as a new thing of type "basic device", now you have different channels to receive and send messages from/to the device
|
||||
- raw messages from the device
|
||||
- the data from the four different type of messages (see their details in the next chapter)
|
||||
- parameters you can send to the device
|
||||
- raw messages from the device
|
||||
- the data from the four different type of messages (see their details in the next chapter)
|
||||
- parameters you can send to the device
|
||||
|
||||
### Gather information about the new device for future support
|
||||
|
||||
@@ -455,14 +447,15 @@ The devices send different types of messages to the gateway.
|
||||
You have to capture as many of them as possible, so that the device is fully supported in the end.
|
||||
|
||||
1. Heartbeat (usually transmitted every 60 minutes)
|
||||
2. Report (device reports new sensor or status values)
|
||||
3. Read ACK (binding refreshes all sensor values after a restart of openHAB)
|
||||
4. Write ACK (device has received a command) __not available for sensor-only devices__
|
||||
1. Report (device reports new sensor or status values)
|
||||
1. Read ACK (binding refreshes all sensor values after a restart of openHAB)
|
||||
1. Write ACK (device has received a command) **not available for sensor-only devices**
|
||||
|
||||
### Open a new issue or get your hands dirty
|
||||
|
||||
Every little help is welcome, be part of the community!
|
||||
Every little help is welcome, be part of the community!
|
||||
Post an issue in the GitHub repository with as much information as possible about the new device:
|
||||
|
||||
- brand and link to device description
|
||||
- model name
|
||||
- content of all the different message types
|
||||
@@ -475,7 +468,7 @@ You can access the whole message contents of the basic device thing with String
|
||||
That way you can make use of your device, even if it is not supported yet!
|
||||
The following examples are a demonstration, where a basic device thing for the gateway was manually added.
|
||||
|
||||
```
|
||||
```java
|
||||
String Gateway_Raw { channel="mihome:basic:xxx:lastMessage" }
|
||||
String Gateway_Heartbeat { channel="mihome:basic:xxx:heartbeatMessage" }
|
||||
```
|
||||
@@ -497,16 +490,16 @@ The commands have to be issued as attributes of a JSON Object, e.g. instead of w
|
||||
|
||||
The following example uses a rule to enable device pairing on the gateway:
|
||||
|
||||
__mihome.items__
|
||||
#### mihome.items
|
||||
|
||||
```
|
||||
```java
|
||||
String Gateway_Write { channel="mihome:basic:xxx:writeMessage" }
|
||||
Switch Gateway_AddDevicesSwitch
|
||||
```
|
||||
|
||||
__mihome.rules__
|
||||
#### mihome.rules
|
||||
|
||||
```
|
||||
```java
|
||||
rule "Enable device pairing with gateway as basic device thing"
|
||||
when
|
||||
Item Gateway_AddDevicesSwitch changed to ON
|
||||
@@ -514,8 +507,10 @@ then
|
||||
Gateway_Write.sendCommand("\"join_permission\":\"yes\"")
|
||||
end
|
||||
```
|
||||
|
||||
You can also send multiple command at once:
|
||||
```
|
||||
|
||||
```java
|
||||
GatewayWrite.sendCommand("\"rgb\":150000,\"join_permission\":\"yes\"")
|
||||
```
|
||||
|
||||
@@ -539,12 +534,13 @@ This makes possible following the communication between the binding and the gate
|
||||
|
||||
For the binding to function properly it is very important, that your network config allows the machine running openHAB to receive multicast traffic.
|
||||
In case you want to check if the communication between the machine and the gateway is working, you can find some hints here.
|
||||
|
||||
- Set up the developer communication as described in the Setup section
|
||||
|
||||
### Check if your Linux machine receives multicast traffic
|
||||
|
||||
- Login to the Linux console
|
||||
- make sure you have __netcat__ installed
|
||||
- make sure you have **netcat** installed
|
||||
- Enter ```netcat -ukl 9898```
|
||||
- At least every 10 seconds you should see a message coming in from the gateway which looks like
|
||||
```{"cmd":"heartbeat","model":"gateway","sid":"`xxx","short_id":"0","token":"xxx","data":"{\"ip\":\"`xxx\"}"}```
|
||||
@@ -554,10 +550,12 @@ In case you want to check if the communication between the machine and the gatew
|
||||
When the computer running openHAB has more than one network interface configured (typically, a VLAN for your segregated IoT devices, and the other for your regular traffic like internet, openHAB panel access, etc), it could be that openHAB will attempt to listen for Multicast traffic of the Gateway on the wrong network interface. That will prevent openHAB and `netcat` from receiving the messages from the Xiaomi Gateway. Within openHAB this manifests by seeing the Gateway and its devices online for a brief period after openHAB startup, after which they timeout and are shown Offline. No channel triggers from the Gateway work in this case.
|
||||
|
||||
In order to verify that traffic is actually received by the machine use `tcpdump` on each interface:
|
||||
|
||||
- List your network interfaces `ifconfig | grep MULTICAST` or `ip link | grep MULTICAST`
|
||||
- Use `tcpdump -i <interface> port 9898` for each interface to verify if you receive traffic
|
||||
|
||||
If you already know the correct interface, or you found the correct one through tcpdump:
|
||||
|
||||
- Configure the `interface` property of the `Bridge` Thing with the correct name (for example `eth0`, etc)
|
||||
|
||||
### Check if your Windows/Mac machine receives multicast traffic
|
||||
@@ -568,16 +566,18 @@ If you already know the correct interface, or you found the correct one through
|
||||
- At least every 10 seconds you should see a message coming in from the gateway which looks like
|
||||
```{"cmd":"heartbeat","model":"gateway","sid":"`xxx","short_id":"0","token":"xxx","data":"{\"ip\":\"`xxx\"}"}```
|
||||
|
||||
__My gateway shows up in openHAB and I have added all devices, but I don't get any value updates:__
|
||||
**My gateway shows up in openHAB and I have added all devices, but I don't get any value updates:**
|
||||
|
||||
- Most likely your machine is not receiving multicast messages
|
||||
- Check your network config:
|
||||
- Routers often block multicast - enable it
|
||||
- Make sure the gateway and the machine are in the same subnet
|
||||
- Try to connect your machine via Ethernet instead of Wifi
|
||||
- Make sure you don't have any firewall rules blocking multicast
|
||||
- If you have multiple network interfaces, try to configure the `interface` property of the `Bridge` Thing
|
||||
- Routers often block multicast - enable it
|
||||
- Make sure the gateway and the machine are in the same subnet
|
||||
- Try to connect your machine via Ethernet instead of Wifi
|
||||
- Make sure you don't have any firewall rules blocking multicast
|
||||
- If you have multiple network interfaces, try to configure the `interface` property of the `Bridge` Thing
|
||||
|
||||
**I have connected my gateway to the network but it doesn't show up in openHAB:**
|
||||
|
||||
__I have connected my gateway to the network but it doesn't show up in openHAB:__
|
||||
- Make sure to have the developer mode enabled in the MiHome app
|
||||
- Reinstall the binding
|
||||
- Try to update the firmware of the gateway
|
||||
@@ -585,7 +585,8 @@ __I have connected my gateway to the network but it doesn't show up in openHAB:_
|
||||
- Search the openHAB Community forum
|
||||
- Contact Xiaomi support - get your gateway replaced
|
||||
|
||||
__Nothing works, I'm frustrated and have thrown my gateway into the bin. Now I don't know what to do with all the sensors:__
|
||||
**Nothing works, I'm frustrated and have thrown my gateway into the bin. Now I don't know what to do with all the sensors:**
|
||||
|
||||
Check out the Zigbee2Mqtt project on GitHub.
|
||||
It allows you to use the sensors without the gateway and get their values through MQTT.
|
||||
You will need some hardware to act as a gateway which is not expensive.
|
||||
|
||||
Reference in New Issue
Block a user