service_netatmo/README.md

# 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**
to `.env`. Ensure `NETATMO_REDIRECT_URI` exactly matches a redirect URI configured
for that application, then perform the initial `read_station` authorization:

```sh
set -a
. ./.env
set +a
.venv/bin/python scripts/get_netatmo_token.py
```

The helper opens Netatmo's consent page. After approval, paste the complete URL
from the browser's address bar back into the prompt. This works even if the local
callback page itself cannot be reached. The script exchanges the authorization
code and writes the token file with mode `0600`.

The service loads `NETATMO_TOKEN_FILE` at startup. Before an access token expires,
it refreshes it and atomically saves both the new access token and any rotated
refresh token. Values in the token file take precedence over initial token values
in `.env`. Client credentials remain environment-only and are never written to
the token file or 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.
Set `URL_PREFIX=/w` to mount the dashboard, static assets, and every API endpoint
below `/w`; leave it empty to serve from the site root. When a prefix is set,
open <http://localhost:5000/w/> instead.

`LOG_FILE` selects a rotating application log (by default
`RRD_FOLDER/netatmo_service.log`). Every Netatmo HTTP attempt records success or
failure, HTTP status, endpoint, and duration without credentials. Collector,
Flask, uncaught main-thread, and uncaught worker-thread exceptions are written to
the same log. `LOG_MAX_BYTES` defaults to 5 MiB and `LOG_BACKUP_COUNT` to five.
The service account must have write permission on the log directory.

## 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.