106 lines
4.3 KiB
Markdown
106 lines
4.3 KiB
Markdown
# 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.
|