Homebridge plugin for the Xiaomi Mi Bluetooth Temperature and Humidity Sensor
Clone or download
Latest commit c24acc1 Nov 26, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add issue template Nov 26, 2018
images Transparent background Apr 6, 2018
lib Better error message Nov 23, 2018
test Nicer characteristic bindings Nov 20, 2018
.eslintrc Use prettier May 7, 2018
.gitignore Initial Mar 12, 2018
.travis.yml Clarify not supporting Node 10 at the moment Nov 3, 2018
CHANGELOG.md Bump version Nov 23, 2018
LICENSE Initial Mar 12, 2018
README.md Add forceDiscoveringDelay configuration parameter Nov 12, 2018
config-sample.json Use default timeout Nov 26, 2018
index.js Remove old eslint disables May 7, 2018
package-lock.json Bump version Nov 23, 2018
package.json Bump version Nov 23, 2018

README.md

homebridge-mi-hygrothermograph

npm npm Travis Coveralls github

Homebridge plugin for exposing measured temperature and humidity from the Xiaomi Mi Bluetooth Temperature and Humidity Sensor as a HomeKit accessory.

alt text

Installation

Make sure your system matches the prerequisites. You need to have a C compiler and Node.js installed. Until some issues in Noble are resolved Node.js 10 and later are not supported. See Known issues for details.

Noble is BLE central module library for Node.js used to discover and read values from the sensor.

These libraries and their dependencies are required by Noble package and provide access to the kernel Bluetooth subsystem:

sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev

For more detailed information and descriptions for other platforms please see the Noble documentation.

Known issues

Install homebridge and this plugin

[sudo] npm install -g --unsafe-perm homebridge
[sudo] npm install -g --unsafe-perm homebridge-mi-hygrothermograph

Note: depending on your platform you might need to run npm install -g with root privileges.

See the Homebridge documentation for more information.

If you are running Homebridge as another user than root (you should) then some additional configuration needs to be made to allow Node.js access to the kernel Bluetooth subsystem without root privileges. Please see the Noble documentation for instructions.

Issues

Homebridge configuration

Update your Homebridge config.json file. See config-sample.json for a complete example.

"accessories": [
    {
      "accessory": "Hygrotermograph",
      "name": "Temperature & Humidity"
    }
]
Key Default Description
accessory                     Mandatory. The name provided to Homebridge. Must be "Hygrotermograph".
name                         Mandatory. The name of this accessory. This will appear in your Home-app.
address                       Optional. The address of the device. Used when running multiple devices.
timeout         15           Time in minutes after last contact when the accessory should be regarded as unreachable. If set to 0, timeout will be disabled.
humidityName   "Humidity"   Name of the humidity sensor as it will appear in your Home-app.
temperatureName "Temperature" Name of the temperature sensor as it will appear in your Home-app.
fakeGatoEnabled false If historical data should be reported to the Elgato Eve App.
fakeGatoStoragePath Optional. Custom path where to save fakegato history.
mqtt Optional. Configuration for publishing values to an MQTT-broker. See the MQTT section for details.
forceDiscovering true Retry start scanning for devices when stopped. For some users scanning will be stopped when connecting to other BLE devices. Setting forceDiscovering to true will start scanning again in these cases.
forceDiscoveringDelay 2500 The delay for when to start scanning again when stopped. Only applicable if forceDiscovering is true.

Multiple sensors

When running just one Hygrotermograph accessory there is no need to specify the address of the BLE device. But if you want to run multiple Hygrotermograph accessories you need to specify the BLE address for each of them. If the address is not specified they will interfere with each other.

The easiest way to find the address of the device is to use [sudo] hcitool lescan. It will start a scan for all advertising BLE peripherals within range. Look for MJ_HT_V1 and copy the address. The address is in the format of 4c:64:a8:d0:ae:65.

Update your Homebridge config.json and specify the address key:

"accessories": [
    {
      "accessory": "Hygrotermograph",
      "name": "Room 1",
      "address": "4c:64:a8:d0:ae:65"
    },
    {
      "accessory": "Hygrotermograph",
      "name": "Room 2",
      "address": "2c:34:b3:d4:a1:61"
    }
]

Note that this step is also required when running Mi Flora devices in the same location as they use the same protocol and their data will be intercepted by this plugin.

MacOS

On MacOS hcitool can't be used since MacOS does not provide a way to read the MAC-address of a BLE device. Instead MacOS assigns a device unique identifier for each BLE device in the format of 5C61F8CE-9F0B-4371-B996-5C9AE0E0D14B. This identifier can be found using iOS apps like nRF Connect or MacOS tools like Bluetooth Explorer. Use this identifier as address in the configuration file.

Timeout

If the accessory has not received an updated value from the sensor within the specified timeout it will inform Homekit that the accessory is not responsive by returning an error until it receives an updated value.

The default timeout is 15 minutes but can be changed by specifying the number of minutes under the timeout parameter in config.json:

"accessories": [
    {
      "accessory": "Hygrotermograph",
      "name": "Temperature & Humidity",
      "timeout": 30
    }
]

If the timeout parameter is set to 0 timeouts are disabled and and devices will not be reported as unresponsive to Homekit.

Naming

By default the Humidity and Temperature accessories visible in the Home-app will have the names "Humidity" and "Temperature". They can be changed in the Home-app if wanted.

It is also possible to set custom initial values by specifying the humidityName and temperatureName parameters in config.json:

{
  "humidityName": "Luftfuktighet",
  "temperatureName": "Temperatur"
}

Elgato Eve

This plugin has support for adding historical data to the Elgato Eve App by using the excellent module fakegato-history.

When using this feature it's required to specify the address of the device as described in Multiple sensors. This is required because fakegato-history requires a unique serial number for each device.

When restarting Homebridge the Eve app will show the Accessories as having 0% battery until the sensor actually reports its battery status. This can sometimes take a couple of minutes. Just be patient and the actual battery status will show up.

To enable the Elgato Eve feature set fakeGatoEnabled to true in config.json

{
  "fakeGatoEnabled": true
}

fakegato-history caches historical values into a json-file. Usually located in /var/lib/homebridge or ~/.homebridge. To customise this one can set fakeGatoStoragePath to the desired path:

{
  "fakeGatoStoragePath": "/tmp/"
}

MQTT

The plugin can be configured to publish temperature/humidity/battery values to an MQTT-broker.

Basic configuration:

{
  "mqtt": {
    "url": "mqtt://test.mosquitto.org",
    "temperatureTopic": "sensors/temperature",
    "humidityTopic": "sensors/humidity",
    "batteryTopic": "sensors/battery"
  }
}

If one is interested in only publishing a specific value just skip configuring the topics wished to ignore:

{
  "mqtt": {
    "url": "mqtt://test.mosquitto.org",
    "temperatureTopic": "sensors/temperature"
  }
}

To enable authentication specify the username and password parameters:

{
  "mqtt": {
    "url": "mqtt://test.mosquitto.org",
    "username": "admin",
    "password": "hunter2",
    "temperatureTopic": "sensors/temperature"
  }
}

For more options see the MQTT.js documentation. Everything set in mqtt will be passed to the options argument on Client.

Technical details

The plugin scans for Bluetooth Low Energy peripherals and check the broadcast advertisement packets. By only reading the advertisement packet there is no need to establish a connection to the peripheral. Inside each packet discovered we look for Service Data with a UUID of 0xfe95. If found we start trying to parse the actual Service Data to find the temperature and humidity.

By using a Bluetooth LE Sniffer it is possible to see that the peripheral advertises 3 different sized Service Data:

  1. 50:20:aa:01:be:64:ae:d0:a8:65:4c:0d:10:04:cc:00:8a:01
  2. 50:20:aa:01:ba:64:ae:d0:a8:65:4c:06:10:02:84:01
  3. 50:20:aa:01:c0:64:ae:d0:a8:65:4c:0a:10:01:5d

Some bytes stay the same and some bytes change over time. By placing the peripheral in different temperated places it could be established that the last bytes contain the sensor data.

These were the observations:

  • In the first example the last two bytes 8a:01 contains the humidity data. 8a:01 as an little endian 16-bit integer is equal to 394 as in 39.4 % relative humidity. If we check the next two bytes cc:00 they equal to 204 as in 20.4 celsius.
  • In the second example 84:01 equals to 388 as in 38.8 % relative humidity. No temperature could be found in this data, more on that later.
  • In the shortest and third example 5d equals to 93 and this very much looks like the charge level on the battery in percent.
  • If we start looking at the other bytes in order the next one looks like a length indicator for the following bytes with 04, 02 and 01 as values.
  • The following two bytes almost always stays the same for each sized packet except for the 16 bytes sized data here they alterate between 06:10 and 04:10. After some investigation it is established that these bytes indicate what type of sensor data that will follow. 06:10 will have humidity data and 04:10 will have temperature data. 0d:10 indicate that both humidity and temperature data will follow and 0a:10 that battery data is to be expected.

So we actually have 4 different packets that contains the sensor data:

  1. 50:20:aa:01:be:64:ae:d0:a8:65:4c:0d:10:04:cc:00:8a:01
  2. 50:20:aa:01:ba:64:ae:d0:a8:65:4c:06:10:02:84:01
  3. 50:20:aa:01:bf:65:ae:d0:a8:65:4c:04:10:02:cc:00
  4. 50:20:aa:01:c0:64:ae:d0:a8:65:4c:0a:10:01:5d

After some investigation and thanks to node-xiaomi-gap-parser it is probable that the data of 50:20:aa:01:be:64:ae:d0:a8:65:4c:0d:10:04:cc:00:8a:01 represents the following:

byte function type
1-2 Frame control bit field
3-4 ID uint16LE
5 Index uint8LE
6-11 MAC-address string
12-13 Type of data uint16LE
14 Length uint8LE
15-16 Temperature int16LE
17-18 Humidity uint16LE

Bytes 1-14 have the same function for all 4 variations but the following bytes contain different sensor data.

Legal

Xiaomi and Mi are registered trademarks of BEIJING XIAOMI TECHNOLOGY CO., LTD.

This project is in no way affiliated with, authorized, maintained, sponsored or endorsed by Xiaomi or any of its affiliates or subsidiaries.