About to push

2026-06-01 21:08:01 +01:00
parent 4224a535ef
commit 9607eac224
6 changed files with 319 additions and 3 deletions
@@ -0,0 +1,130 @@
+# Project Context
+
+This project is a Dockerised SwitchBot temperature dashboard built from an
+initial SwitchBot API v1.1 Python proof of concept.
+
+## Current Shape
+
+- `docker-compose.yml` starts three services:
+  - `db`: MySQL 8.4 with the `mysql_data` volume.
+  - `web`: Flask app served by Gunicorn on port 8000.
+  - `collector`: Python polling loop.
+- `app/switchbot.py` contains the SwitchBot v1.1 signed request client.
+- `app/collector.py` syncs devices from SwitchBot and records sensor readings.
+- `app/web.py` serves the dashboard, reports, CSV export, and per-device views.
+- `switchbot_poc.py` remains as a low-level API sanity-check script.
+
+## Configuration
+
+Runtime config is provided by `.env`, copied from `.env.example`.
+
+Required values:
+
+```env
+SWITCHBOT_TOKEN=...
+SWITCHBOT_SECRET=...
+FLASK_SECRET_KEY=...
+```
+
+Important: do not commit `.env`; it is intentionally ignored.
+
+The default polling interval is:
+
+```env
+COLLECT_INTERVAL_SECONDS=900
+```
+
+The default timezone is:
+
+```env
+APP_TIMEZONE=Europe/London
+```
+
+## SwitchBot Notes
+
+The SwitchBot API only exposes devices owned by the account that generated the
+token/secret. Devices merely shared with the account do not appear in
+`/devices`.
+
+Working discovered devices were:
+
+- `CB11A9610CFB`: `Hub Mini FB`, `Hub Mini2`
+- `EE2E01862061`: `Meds Cupboard`, `WoIOSensor`
+- `EE2E0446360E`: `Fridge Med`, `WoIOSensor`
+- `EE2E05C6434C`: `Main Room`, `WoIOSensor`
+
+`Hub Mini2` is treated as infrastructure. It is stored in the database when
+discovered, but hidden from the dashboard/reports and skipped by the collector
+for readings.
+
+Current sensor allow-list:
+
+```python
+SENSOR_DEVICE_TYPES = {"WoIOSensor"}
+```
+
+## Features Implemented
+
+- Responsive dashboard at `/`.
+- Sensor cards show latest reading, day low, day high, and battery.
+- Hub devices are suppressed from the dashboard.
+- Day-so-far graph rendered with local canvas JavaScript, no CDN.
+- Clicking a sensor card opens `/devices/<device_id>`.
+- Per-device page shows:
+  - selected day
+  - samples
+  - low/high temperature
+  - graph for that device/day
+  - timestamped readings table
+- Reports at `/reports`.
+- CSV export at `/reports.csv`.
+
+## Common Commands
+
+Start or restart:
+
+```sh
+docker compose up --build -d
+```
+
+Follow collector logs:
+
+```sh
+docker compose logs -f collector
+```
+
+Check row counts:
+
+```sh
+docker compose exec -T db mysql -uswitchbot -pswitchbot_password switchbot \
+  -e "select count(*) as devices from devices; select count(*) as readings from readings;"
+```
+
+Run the original POC:
+
+```sh
+python3 switchbot_poc.py
+python3 switchbot_poc.py --endpoint /devices/EE2E01862061/status
+```
+
+## Verification Performed
+
+- Python syntax checks pass for the app modules.
+- Docker build succeeded.
+- MySQL became healthy.
+- Web app responded with `HTTP 200 OK`.
+- Reports and CSV endpoints responded with `HTTP 200 OK`.
+- Collector successfully recorded readings for the three `WoIOSensor` devices.
+- Browser verification confirmed:
+  - dashboard shows only the three sensors
+  - Hub Mini is hidden
+  - clicking a tile opens the device/day readings page
+  - timestamped readings display in local time
+
+## Likely Next Improvements
+
+- Add migrations instead of using `Base.metadata.create_all`.
+- Add a manual "collect now" endpoint/button.
+- Add CSV export for a single device/day readings table.
+- Add alert thresholds for fridge/medicine storage temperatures.
+- Add authentication if exposed beyond a trusted local network.