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:secretpassword@127.0.0.1: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 or closed.
  • For buttons this will contain unknown, clicked, double_clicked, pressed or relesed.
  • For motion sensors this will contain motion or no_motion.
  • For leak sensors this will contain leaking or not_leaking
• 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 Either All closed or comma seperated list of magnet names with open status.
• ids the ids of the magnets with the status open 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.