first commit

README.md

@@ -0,0 +1,79 @@
+# lywsd03mmc-exporter — a MQTT exporter for the LYWSD03MMC BLE thermometer
+
+lywsd03mmc-exporter is a small tool to scan and keep track of
+Bluetooth beacons the LYWSD03MMC BLE thermometer sends periodically.
+
+Data are publised to an MQTT broker
+
+## Modes of operation
+
+Due to talking to lower levels of the Bluetooth stack,
+lywsd03mmc-exporter needs to be run as `root` or with CAP_NET_ADMIN.
+
+### Stock firmware
+
+To use lywsd03mmc-exporter with the
+[stock firmware](https://github.com/custom-components/sensor.mitemp_bt/files/4022697/d4135e135443ba86e403ecb2af2bf0af_upd_miaomiaoce.sensor_ht.t2.zip),
+you need to *activate* your device and extract the *Mi Bindkey*.  You
+can either use the Xiaomi Home software for that (requires an account
+and a HTTPS MITM attack on your phone), or more easily, use the
+[TelinkFlasher](https://atc1441.github.io/TelinkFlasher.html) provided
+by [@atc1441](https://github.com/atc1441).
+
+You will need to create a keyfile in a format like this,
+and use `-k file`:
+
+```
+# format: MAC KEY, hex digits only
+A4C138FFFFFF 00112233445566778899aabbccddeeff
+```
+
+This mode sends measurements every 10 minutes.
+
+Note: Supposedly, the battery ratio is always 100% unless the battery
+is really empty.
+
+### Custom firmware
+
+@atc1441 wrote a [custom firmware](https://github.com/atc1441/ATC_MiThermometer)
+for the LYWSD03MMC.  It sends data unencrypted in beacons.
+Negative temperatures are supported.
+
+You can flash it easily with above TelinkFlasher.
+
+This mode sends measurements every 10 seconds.
+
+### Polling mode
+
+This requires an active connection to the device.
+Pass the MAC addresses of the devices as arguments to lywsd03mmc-exporter.
+This is currently limited to one device (bug in go-ble?).
+
+## Config file
+
+```
+[MQTT]
+host=localhost
+port=1883
+#user=user
+#pass=pass
+```
+
+## Copying
+
+lywsd03mmc-exporter is licensed under the MIT license.
+
+## Thanks
+
+This software would not be possible without the help of code and
+documentation in:
+
+* https://github.com/atc1441/ATC_MiThermometer
+* https://github.com/danielkucera/mi-standardauth
+* https://github.com/ahpohl/xiaomi_lywsd03mmc
+* https://github.com/custom-components/sensor.mitemp_bt
+* https://github.com/JsBergbau/MiTemperature2
+* https://github.com/lcsfelix/reading-xiaomi-temp
+* https://tasmota.github.io/docs/Bluetooth/
+* https://github.com/DazWilkin/gomijia2
+* https://github.com/leahneukirchen/lywsd03mmc-exporter