xiaomi-mqtt
A Bridge between the Xiaomi Mi Smart Home Gateway and the Mqtt broker.
Xiaomi-mqtt exchanges data between the xiaomi gateway and the mqtt-broker at a low-level, principally based on the device sid
(Security Identifier?). The automation and dashboard tasks are implemented at a higher level. Node-RED is the perfect tool to use for this purpose.
Installation
sudo npm install -g xiaomi-mqtt
Installation from GitHub
Clone the source repository directly from GitHub to a local folder:
git clone https://github.com/cflurin/xiaomi-mqtt.git
Local Installation:
cd xiaomi-mqttnpm install
Configuration
Copy the config.json
file to the .xiaomi-mqtt
folder inside of your home folder.
mkdir ~/.xiaomi-mqttcp config.json ~/.xiaomi-mqtt/
On Linux the full path for your config.json would be ~/.xiaomi-mqtt/config.json
.
Edit ~/xiaomi-mqtt/config.json
to fit your requirements:
"topic_mode": <"short"> | <"full"> | <"both">
short
defaultfull
allow you to do some topic filtering directly on client side.both
2 topics are sent,short
andfull
.
"loglevel": <"debug"> | <"info"> | <"warn"> | <"error">
Replace 127.0.0.1
with the address of your mqtt broker.
Set dataFormat
to raw
to get data without parsing.
By default the gateway send heartbeat every 10s which can do some pollution when testing/debug, the counter parameter in config named heartbeatfreq
avoid this, in the example above set to 6 means only send a MQTT message each 6 heartbeat, so each 60s. Note this apply only to gateway heartbeat not the device's one.
Usage (global installation)
Use xiaomi-mqtt
or xm
to run xiaomi-mqtt.
Use ctrl c
to stop xiaomi-mqtt.
Usage (local installation)
In the xiaomi-mqtt
folder.
Use npm start
to run xiaomi-mqtt.
Use ctrl c
to stop xiaomi-mqtt.
mqtt API
If the configuration option topic_mode
is set to short
or both
, the data (payload) is sent/received in a JSON format using following topics:
- xiaomi/from
- xiaomi/to/read
- xiaomi/to/write
- xiaomi/to/get_id_list
Note: Have look at: How to benefit of the full topic option
Howto examples
At start and stop xiaomi-mqtt sends following messages.
start
topic: xiaomi/frompayload: {"cmd":"xm","msg":"xiaomi-mqtt started."}
and
topic: xiaomi/frompayload:
stop
topic: xiaomi/frompayload: {"cmd":"xm","msg":"xiaomi-mqtt stopped."}
heartbeat
gateway
topic: xiaomi/frompayload:
cube
topic: xiaomi/frompayload:
reporting
Xiaomi-mqtt sends periodically or on events device reports.
gateway
topic: xiaomi/frompayload:
sensor_ht
topic: xiaomi/frompayload:
"data": {"voltage":3005,"temperature":16.7,"humidity":null}or"data": {"voltage":3005,"temperature":null,"humidity":51.7}
magnet
topic: xiaomi/frompayload:
"status": "close", "open"
switch
topic: xiaomi/frompayload:
"status": "click", "double_click", "long_click_press", "long_click_release"
86sw2
topic: xiaomi/frompayload:
"data":{"channel_0":"click"}or"data":{"channel_1":"click"}
cube
topic: xiaomi/frompayload:
"status": "move", "flip90", "flip180", "tape_twice", "shake_air", "alert"or"rotate": "99,999", "-99.999"
read
gateway
topic: xiaomi/to/readpayload: {"sid":"fff..."}
response
topic: xiaomi/frompayload:
sensor_ht
topic: xiaomi/to/readpayload: {"sid":"158d00017118ac"}
response
topic: xiaomi/frompayload:
switch
topic: xiaomi/to/readpayload: {"sid":"158d0001f35b90"}
response
topic: xiaomi/frompayload:
write
topic: xiaomi/to/writepayload:
Note: rgb = [brightness] [red] [green] [blue] - each hex 00 to FF
response
topic: xiaomi/frompayload:
get_id_list:
topic: xiaomi/to/get_id_listpayload: {"sid":"fff..."}
Note: sid = gateway sid.
response
topic: xiaomi/frompayload:
Tested devices (models):
- gateway
- sensor_ht
- motion
- sensor_motion.aq2
- sensor_wleak.aq1
- magnet
- switch
- 86sw1
- 86sw2
- cube
- ctrl_neutral1
- ctrl_neutral2
- ctrl_ln1.aq1
Note: Untested devices using the same format will also send a payload.
Node-RED examples
basic
write gateway
Flow:
[{"id":"9339669d.8e38b8","type":"mqtt out","z":"d0877ed4.9e0cc","name":"","topic":"xiaomi/to/write","qos":"","retain":"","broker":"325f5be5.555734","x":560,"y":480,"wires":[]},{"id":"c508a302.61467","type":"ui_colour_picker","z":"d0877ed4.9e0cc","name":"","label":"gateway color","group":"4d5fcade.c527d4","format":"hex","outformat":"string","showSwatch":true,"showPicker":false,"showValue":true,"showAlpha":false,"showLightness":true,"dynOutput":"false","order":0,"width":0,"height":0,"passthru":true,"topic":"","x":220,"y":480,"wires":},{"id":"dcd9ac95.fd93","type":"template","z":"d0877ed4.9e0cc","name":"map","field":"payload","fieldType":"msg","format":"handlebars","syntax":"mustache","template":"{\n \"cmd\": \"write\",\n \"model\": \"gateway\",\n \"sid\": \"fff...\",\n \"data\": {\n \"rgb\": \"10{{payload}}\"\n }\n}","output":"json","x":390,"y":480,"wires":},{"id":"325f5be5.555734","type":"mqtt-broker","z":"","broker":"127.0.0.1","port":"1883","clientid":"","usetls":false,"compatmode":false,"keepalive":"60","cleansession":true,"willTopic":"","willQos":"0","willPayload":"","birthTopic":"","birthQos":"0","birthPayload":""},{"id":"4d5fcade.c527d4","type":"ui_group","z":"","name":"Xiaomi","tab":"f3d46e49.beaec","order":1,"disp":true,"width":"6"},{"id":"f3d46e49.beaec","type":"ui_tab","z":"","name":"Main","icon":"dashboard","order":1}]
Flow:
[{"id":"aacbdba0.0519f8","type":"inject","z":"d0877ed4.9e0cc","name":"doorbell","topic":"","payload":"{\"cmd\":\"write\",\"model\":\"gateway\",\"sid\":\"fff...\",\"short_id\":0,\"key\":\"8\",\"data\":{\"mid\":10}}","payloadType":"json","repeat":"","crontab":"","once":false,"onceDelay":0.1,"x":120,"y":580,"wires":},{"id":"8f56c43e.16c048","type":"inject","z":"d0877ed4.9e0cc","name":"police","topic":"","payload":"{\"cmd\":\"write\",\"model\":\"gateway\",\"sid\":\"fff...\",\"short_id\":0,\"key\":\"8\",\"data\":{\"mid\":1}}","payloadType":"json","repeat":"","crontab":"","once":false,"onceDelay":0.1,"x":110,"y":620,"wires":},{"id":"83a2b4f.eb0d748","type":"mqtt out","z":"d0877ed4.9e0cc","name":"","topic":"xiaomi/to/write","qos":"","retain":"","broker":"325f5be5.555734","x":340,"y":580,"wires":[]},{"id":"325f5be5.555734","type":"mqtt-broker","z":"","broker":"192.168.0.35","port":"1883","clientid":"","usetls":false,"compatmode":false,"keepalive":"60","cleansession":true,"willTopic":"","willQos":"0","willPayload":"","birthTopic":"","birthQos":"0","birthPayload":""}]