/mijia-homie

A Homie MQTT bridge for the Xiaomi Mijia 2 hygrometer-thermometer. This repo also serves as the monorepo for a handful of helper crates related to Homie and Bluetooth.

Primary LanguageRustOtherNOASSERTION

About this project

This is a project for capturing BLE data from a Xiaomi Mijia 2 hygrometer-thermometer and publishing it. The repository includes a number of related crates:

  • mijia-homie, a service to connect to a number of Mijia sensors over BLE and publish their readings to an MQTT broker following the Homie convention.
  • homie-influx, a service to discover devices on an MQTT broker following the Homie convention and record their property value changes to an InfluxDB database.
  • homie-device, a library for implementing Homie devices.
  • homie-controller, a library for implementing Homie controllers.
  • mijia, a library for reading Mijia sensors.

The project originated from a blog post, and some ideas came from a Python utility for talking to the same sensors, especially this issue thread.

If you want a bit more back-story, there is also a slide deck.

Serving Suggestion

Setup

To run this code on your Raspberry Pi, you will need:

  • Some Xiaomi Mijia version 2 Bluetooth temperature and humidity sensors.
  • A working Rust toolchain and Docker on your laptop.
  • An MQTT broker to connect to (test.mosquitto.org works okay for testing, but you will want to deploy your own if you're monitoring your house).
  • Something to read the measurements from MQTT. Homie Device Discovery is probably easiest for debugging.

After following these steps, you should end up with something that looks like this:

System overview

  • Start by finding out which sensors you have:

    TARGET_SSH=pi@raspberrypi.local EXAMPLE=list-sensors ./run.sh
    
  • Add each of the sensors to /home/pi/sensor-names.toml on the Raspberry Pi. Each line should be of the form:

    "A4:C1:38:D7:21:17"="Landing"
    

    If you don't know the sensor names yet, just make some names up for now.

  • You will also want to copy mijia-homie/mijia-homie.example.toml to /home/pi/mijia-homie.example.toml and edit it to suit your needs.

  • You should then be able to run the publisher using run.sh with default arguments:

    TARGET_SSH=pi@raspberrypi.local ./run.sh
    

    This will start the publisher under systemd and show you the logs.

  • It takes a while to connect to all of the sensors and start getting readings. Once everything is running, you can use HoDD to see your readings.

  • If everything is visible in HoDD then you can add other integrations. Anything that understands Homie should be able to read your sensors. OpenHAB is what we're using, but take a look at the Homie Implementations page and see if anything inspires you.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.