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.
The devices are very affordable and you can get them from your favourite chinese marktes like [AliExpress](https://www.aliexpress.com/) or [GearBest](https://www.gearbest.com).
The sensors run on a coincell battery for over a year.
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 posible.
Zigbee2Mqtt provides an alternative method to integrate Xiaomi devices.
| Gateway v2 (with radio support) or v3 |  |
| Mijia Temperature and Humidity Sensor | |
| Aqara Temperature, Humidity and Pressure Sensor |  |
| Mijia Human Body Sensor |  |
* 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 Paper UI -> Configuration -> 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
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
* With the binding
1. After adding the gateway make sure you have entered the right developer key
2. In Paper 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!
## Removing devices from the gateway
If you remove a Thing in PapaerUI it will also trigger the gateway to unpair the device.
It will only reappear in your Inbox, if you connect it to the gateway again.
Just follow the instructions in ["Connecting devices to the gateway"](#connecting-devices-to-the-gateway).
## Network configuration
- 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
_Example for a raw message from the gateway: ```{"cmd":"heartbeat","model":"gateway","sid":"xxx","short_id":"0","token":"xxx","data":"{\"ip\":\"192.168.0.124\"}"}```_
_Example for the same message from the heartbeat channel - only the data is returned: ```{"ip":"192.168.0.124"}```_
These messages are in JSON format, which also gives you the ability to parse single values.
_Example for the retrieved IP from the heartbeat message and transformed with JSONPATH transfomration: ```String Gateway_IP {channel="mihome:basic:xxx:heartbeatMessage"[profile="transform:JSONPATH", function="$.ip"]}```_
The item will get the value `192.168.0.124`.
### Write commands to a basic device
You can write commands to devices which support it, usually all battery powered devices are not able to receive commands.
The commands have to be issued as attributes of a JSON Object, e.g. instead of writing ```{"attr":"value"}``` you have to write ```"attr":"value"``` or ```"channel_0":"on", "channel_1":"on"``` to the item.
The following example uses a rule to enable device pairing on the gateway:
