1st POC

README.md

@@ -1,2 +1,81 @@
-# service_netatmo
+# GetNetatmoData v2
 
+A small Flask service that polls Netatmo's Weather API every ten minutes, stores
+the readings in RRDtool databases, and serves a responsive graph dashboard.
+
+## What it stores
+
+The service creates `outdoor.rrd`, `wind.rrd`, `bedroom.rrd`, `study.rrd`, and
+`living.rrd`. Each has ten-minute archives for the last two weeks and six-hour
+archives covering a year. Day, two-week, and year PNG graphs are rendered on
+demand. The wind graph splits average wind into 12 colored direction bands and
+draws gusts as a line.
+
+The Outdoor module does not contain a pressure sensor, so `outdoor.rrd` combines
+its temperature/humidity with pressure from the main station. A module without
+`dashboard_data` is skipped until it becomes reachable again.
+
+## Prerequisites and setup
+
+Install the RRDtool Python binding and native library using your operating
+system package manager (for example `apt install python3-rrdtool` on Debian or
+Ubuntu), then set up the Python application. If your distribution does not
+provide the binding, `pip install -r requirements.txt` installs its PyPI package
+but may require the RRDtool development headers and a C compiler.
+
+```sh
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+cp .env.example .env
+```
+
+Add the client ID and secret for the Netatmo application **GetNetatmoData v2**
+and a refresh token to `.env`. Netatmo's OAuth authorization step must be used to
+obtain the initial refresh token with the `read_station` scope. Secrets are read
+from environment variables and are never stored in an RRD.
+
+Export the file and run Flask:
+
+```sh
+set -a
+. ./.env
+set +a
+.venv/bin/flask --app wsgi run --host 0.0.0.0
+```
+
+Open <http://localhost:5000/>. Keep one application worker because the polling
+scheduler runs inside the service process. Alternatively set
+`START_COLLECTOR=false` in web workers and invoke this from a system timer:
+
+```sh
+.venv/bin/flask --app wsgi collect-now
+```
+
+`RRD_FOLDER` configures the database directory (default `./rrd`). The module
+variables in `.env.example` allow the five Netatmo display names to be changed.
+
+## HTTP API
+
+```text
+GET /last/<rrd-name>/<data-point>
+GET /graph/<rrd-name>/<period>
+GET /graph/<rrd-name><period>       # compact compatibility form
+GET /health
+```
+
+Periods are `day`, `2weeks`, and `year`. Examples:
+
+```sh
+curl http://localhost:5000/last/outdoor/humidity
+curl --output wind.png http://localhost:5000/graph/wind/2weeks
+```
+
+Data points are:
+
+- `outdoor`: `min_temp`, `max_temp`, `humidity`, `pressure`
+- `wind`: `gust`, `average`, `angle`
+- `bedroom`, `study`, `living`: `temperature`, `co2`, `humidity`
+
+The service creates missing RRDs at startup but deliberately does not alter an
+existing RRD schema. If a schema is changed in code, migrate or archive the old
+files before restarting.