# 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 `netatmo_outdoor.rrd`, `netatmo_wind.rrd`,
`netatmo_bedroom.rrd`, `netatmo_study.rrd`, and `netatmo_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 config.example.yaml config.yaml
```

Add the client ID and secret for the Netatmo application **GetNetatmoData v2**
to the private `config.yaml`. Ensure `netatmo.redirect_uri` exactly matches a
redirect URI configured for that application, then perform the initial
`read_station` authorization:

```sh
.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 YAML. Client credentials remain in the private configuration and are never written to
the token file or an RRD.

Run the service; host, port, and URL prefix all come from `config.yaml`:

```sh
.venv/bin/python wsgi.py
```

With the example settings, open <http://localhost:30225/w/>. Keep one application worker because the polling
scheduler runs inside the service process. Alternatively set
`collector.enabled: false` in web workers and invoke this from a system timer:

```sh
.venv/bin/flask --app wsgi collect-now
```

`storage.rrd_folder` configures the database directory (default `./rrd`). The
`modules` section allows the five Netatmo display names to be changed.
Set `server.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.

`logging.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. `logging.max_bytes` defaults to 5 MiB and `backup_count` to five.
The service account must have write permission on the log directory. Console
logging remains enabled by default so `python wsgi.py` displays its listening
address; set `logging.console: false` to use only the logfile.

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