xiaomi2mqtt
v1.5.2
Published
A bridge between the Xiaomi home-automation gateway and a MQTT server.
Downloads
24
Maintainers
Readme
Xiaomi2mqtt
Looking for maintainers, I moved to Zigbee2mqtt and got rid of my Chinese xioami gateway (I can recomment this to everybody). So I'm no longer actively using the gateway. If someone else wants to maintain this library I'll grant you the rights to the repo and the NPM package.
This node.js application is a bridge between the Xiaomi Smart Home Gateway Aquara and a mqtt server. The statuses off all the (sub)devices (door magnets & buttons) connected to this gateway will be published to the mqtt server.
It's intended as a building block in heterogenous smart home environments where an MQTT message broker is used as the centralized message bus. See MQTT Smarthome on Github for a rationale and architectural overview.
Check out the other bridges in the software list
Installation
Using xiaomi2mqtt is really easy, but it requires at least Node.js v6 or higher. (This app is tested against v8 and v9).
sudo npm install -g xiaomi2mqtt
Configure the gateway
Before you can actually use the Xiaomi gateway you'll have to configure it. You'll do this by setting the Mi Home application to Chinese Mainland
(or else you cannot add the gateway).
Enable local network mode
The gateway also needs to have Local network mode enabled. This can be done from within the application. How to enable network mode
Usage
Usage: xiaomi2mqtt [options]
Options:
-d, --devices File location of device list (must end with .json).
-h, --help Show help [boolean]
-l, --logging Logging level [choices: "error", "warn", "info", "debug"] [default: "info"]
-m, --mqtt mqtt broker url. See https://github.com/mqttjs/MQTT.js#connect-using-a-url [default: "mqtt://127.0.0.1"]
-k, --insecure accept self singed-certificates when using TLS. See https://github.com/mqttjs/MQTT.js#mqttclientstreambuilder-options [boolean] [default: false]
-n, --name instance name. used as mqtt client id and as topic prefix [default: "xiaomi"]
--version Show version number [boolean]
MQTT Url
Use the MQTT url to connect to your specific mqtt server. Check out mqtt.connect for the full description.
Connection without port (port 1883 gets used)
[protocol]://[address] (eg. mqtt://127.0.0.1)
Connection with port
[protocol]://[address]:[port] (eg. mqtt://127.0.0.1:1883)
Secure connection with username/password and port
[protocol]://[username]:[password]@[address]:[port] (eg. mqtts://myuser:[email protected]:8883)
Device list
At this moment is seems impossible to retrieve the device name for all subdevices from the gateway. If you want to have decent names for your devices, you'll have to create a json file that looks like this, and tell xiaomi2mqtt to use it with the -d [filename-here]
argument. Apparently this file needs the be called something.json
, because of the way it parses this file.
This file can also be used to set the gateway password(s), in case you want to be able to set the lights.
{
"device_id": "Nice name",
"158d000aaa2888": "Bedroom window",
"158d000aaa5b35": "Frontdoor",
"gateways": {
"gateway_id": "password"
}
}
Topics
Every message starts with the instance name (specified with the -n
argument), which defaults to xiaomi
so we'll asume the default.
Connect messages
This bridge uses the xiaomi/connected
topic to send retained connection messages. Use this topic to check your if your hue bridge is still running.
0
or missing is not connected (set by will functionality).1
is connected to mqtt, but not to the xiaomi hardware.2
is connected to mqtt and xiaomi hardware. (ultimate success!)
Status messages
The status of each device will be published to xiaomi/status/[device_kind]/[device_id]
as a JSON object containing the following fields.
The temperature/humidity/pressure sensor will be published to three topics.
name
If you defined a name in the config.battery
The calculated battery percentage of the sensor.val
current state of the device.- For magnets this will contain
open
orclosed
. - For buttons this will contain
unknown
,clicked
,double_clicked
,pressed
orrelesed
. - For motion sensors this will contain
motion
orno_motion
. - For leak sensors this will contain
leaking
ornot_leaking
- For magnets this will contain
ts
timestamp of last update.
Each status message is retained, so if you subscribe after a status message, you will always get the last status.
The statuses of the devices are multicasted over the network if you enbaled this (you SHOULD!!). So all the updates to mqtt are near instant.
Security message
The total count of magnet sensors with the open
state will be emitted to: xiaomi/status/magnets
as a JSON object containing the following fields.
name
EitherAll closed
or comma seperated list of magnet names with open status.ids
the ids of the magnets with the statusopen
as array.val
number of open devices
Setting the gateway light
You can control the gateway light (if you've set-up the gateway password) by sending a message to xiaomi/set/gateway_id/light
, send one of these:
- a single brightness value. (Number between 0 and 100, 0 for off)
- a json object containing (some of) the following properties:
intensity
brightness (0-100) (0 = off)color
as json containing all 3 colors.{ "r": 0-255, "g": 0-255, "b": 0-255 }
// Sending this will result in a red light at 40% brightness
{
"intensity": 40,
"color": {"r":255,"g":0,"b":0}
}
Use PM2 to run in background
If everything works as expected, you should make the app run in the background automatically. Personally I use PM2 for this. And they have a great guide for this.
Special thanks
The latest version of this bridge is inspired on hue2mqtt.js by Sabastian Raff. That was a great sample on how to create a globally installed, command-line, something2mqtt bridge.
Beer
This bridge took me quite some time, so I invite everyone using this bridge to Buy me a beer.