131 lines
3.4 KiB
Markdown
131 lines
3.4 KiB
Markdown
# 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.
|