From 5c43ece91778f5f3bb4bb45f44c51355d1238d3f Mon Sep 17 00:00:00 2001 From: matt Date: Tue, 13 Oct 2026 02:06:30 -0700 Subject: [PATCH] add api details to readme --- README.md | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 160 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0d24be2..91bb93a 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,167 @@ -This is currently an API for monitoring Temperature and Humidity data for Xiaomii BLE sensors. +# Xiaomii BLE Sensor API + +## Summary + +This is an API for monitoring Temperature and Humidity data for Xiaomii LYWSD03MMC BLE sensors. The app will scan for any of these devices by looking for the Bluetooth MAC octet and then filtering by model. Once it has a list of MACs, it will then attempt to read the Temp/Humidity data for each MAC and record it. This data can be interacted with through an API. Some product info can be found here at my Knowledgebase: + https://kb.matt-cloud.com/books/07-saved-articles/page/xiaomii-temperaturehumidity-sensor +## API Details + +There are several primary API endpoints with varying levels of details. + +`0.0.0.0:5000/macs` is the endpoint for a simple list of MACs. This will return a list of MACs and a count. +``` +{ + "count": 4, + "macs": [ + "A4:C1:38:00:11:10", + "A4:C1:38:00:11:11", + "A4:C1:38:00:11:12", + "A4:C1:38:00:11:13" + ] +} +``` + +`0.0.0.0:5000/summary` will return a summary of devices and current data. +``` +{ + "sensors": [ + { + "comment": "A4:C1:38:00:11:10", + "data": { + "humidity": 50, + "temp": 17.4 + }, + "name": "A4:C1:38:00:11:10" + }, + { + "comment": "A4:C1:38:24:00:11:11", + "data": { + "humidity": 50, + "temp": 18.03 + }, + "name": "A4:C1:38:00:11:11" + }, + { + "comment": "A4:C1:38:00:11:12", + "data": { + "humidity": 49, + "temp": 17.99 + }, + "name": "A4:C1:38:00:11:12" + }, + { + "comment": "A4:C1:38:00:11:13", + "data": { + "humidity": 49, + "temp": 18.12 + }, + "name": "A4:C1:38:00:11:13" + } + ] +} +``` + +`0.0.0.0:5000/details` returns the summary info along with timestamps for first seen and last seen dates for each MAC and each data. + +``` +{ + "sensors": [ + { + "comment": "A4:C1:38:100:11:10", + "data": { + "data": [ + { + "first_seen": 1791856362, + "last_seen": 1791882172, + "name": "temp", + "value": 17.4 + }, + { + "first_seen": 1791856362, + "last_seen": 1791882172, + "name": "humidity", + "value": 50 + } + ] + }, + "first_seen": 1791856072, + "last_seen": 1791882172, + "name": "A4:C1:38:100:11:10" + }, + { + "comment": "A4:C1:38:00:11:11", + "data": { + "data": [ + { + "first_seen": 1791856362, + "last_seen": 1791882239, + "name": "temp", + "value": 17.97 + }, + { + "first_seen": 1791856362, + "last_seen": 1791882239, + "name": "humidity", + "value": 50 + } + ] + }, + "first_seen": 1791856072, + "last_seen": 1791882239, + "name": "A4:C1:38:00:11:11" + }, + { + "comment": "A4:C1:38:00:11:12", + "data": { + "data": [ + { + "first_seen": 1791856300, + "last_seen": 1791882239, + "name": "temp", + "value": 17.97 + }, + { + "first_seen": 1791856300, + "last_seen": 1791882239, + "name": "humidity", + "value": 50 + } + ] + }, + "first_seen": 1791856072, + "last_seen": 1791882239, + "name": "A4:C1:38:00:11:12" + }, + { + "comment": "A4:C1:38:00:11:13", + "data": { + "data": [ + { + "first_seen": 1791856224, + "last_seen": 1791882239, + "name": "temp", + "value": 18.07 + }, + { + "first_seen": 1791856224, + "last_seen": 1791882239, + "name": "humidity", + "value": 49 + } + ] + }, + "first_seen": 1791856072, + "last_seen": 1791882239, + "name": "A4:C1:38:00:11:13" + } + ] +} +``` + ``` ble-scanner/ ├─ app.py # Flask + Scheduler + API