How rsaikali/linkystat works
This repository is an edge/IoT monitoring stack deployed via Docker Compose (intended for a Raspberry Pi running 24/7). Its purpose is to:
• Read electricity meter telemetry from a Linky meter via a Micro Teleinfo USB dongle (LINKY_USB_DEVICE).
• Enrich/compare with weather data via OpenWeather API.
• Persist time-series-ish measurements into MySQL.
So the “system” is not a classical web app with frontend/backend; it’s a containerized ingestion + storage + visualization architecture running close to hardware.
From the tree:
Runtime / deployment orchestration
• compose.yaml, compose.dev.yaml: defines services, networks, volumes, device passthrough (USB), env vars.
• Dockerfile: likely for the Python ingestion image.
• env/.env.sample (README mentions .env.example): runtime configuration (device path, OpenWeather creds, DB creds, Grafana admin creds).
• .devcontainer/*: dev environment (not runtime, but mentionable in a “Dev tooling” side note if needed).
Data ingestion & integration (Python)
• src/linky2db.py: core teleinfo → DB pipeline (serial read, parse, insert).
• src/weather.py: OpenWeather → DB or enrichment logic.
• requirements.txt, pyproject.toml: Python deps/build.
Storage
• files/mysql/init-script.sh: DB initialization, schema/users, permissions.
• scripts/migrate_to_optimized_schema.sh: schema evolution/optimization.
• scripts/mysql_backup.sh, scripts/mysql_restore.sh, scripts/sync_dev_db.sh: operational lifecycle.
Observability / visualization
• files/grafana/etc/grafana.ini: Grafana config
• files/grafana/etc/provisioning/datasources/datasource.yaml: pre-configured MySQL datasource
• files/grafana/etc/provisioning/dashboards/dashboard.yaml + dashboards JSON: pre-provisioned dashboards
CI/CD & ops automation (optional layer
• .github/workflows/main.yml (deploy to production), backup.yml, restore.yml: automation around deploy and DB backup/restore.
This is the most important for linkystat.
Hardware / External
• Linky meter
• Micro Teleinfo USB dongle
• OpenWeather API (external cloud)
• User’s Browser
• (Optional) Reverse proxy (Traefik/Caddy/nginx) as an *external* recommended component (README mentions it)
Host
• Raspberry Pi / Linux host running Docker Engine + Docker Compose
Docker Compose application (logical boundary)
• Ingestion service (Python container) built from Dockerfile
• sub-label: src/linky2db.py
• sub-label: src/weather.py
• inputs: /dev/ttyACM0 (or configured device)
• MySQL container
• init script: files/mysql/init-script.sh
• Grafana container
• provisioning: dashboards + datasource
• exposed port: 3000 (from README)
• persistent volume for Grafana data (if in compose)
• Linky meter → Teleinfo dongle → (USB) → Ingestion container
• Ingestion container → MySQL
• Ingestion container → OpenWeather API
• Grafana → MySQL
• Browser → Grafana
Important: add boundaries
• A boundary around “Docker network” (Compose network).
• A boundary around “Host OS”.
• A boundary around “External services”.
This communicates the system accurately in one page.
This is the second most useful view because the core value is “telemetry → structured DB → dashboards”.
Acquisition
• Serial read from USB device (Teleinfo)
Parsing/Validation
• parse teleinfo frames, handle sampling rate, errors
Enrichment
• fetch weather from OpenWeather (keyed by lat/long)
Persistence
• write to MySQL tables (optionally show “raw readings” vs “optimized schema” if migration script indicates new structure)
Query/Visualization
• Grafana dashboard panels query MySQL
• Backup script reads MySQL → writes backup artifact (local file / remote depending on workflow)
• Restore script reads artifact → writes MySQL
• Migration script alters schema
Relationships & interactions to call out explicitly (don’t omit these)
• USB device passthrough into container: this is a defining architectural constraint. Show it as a physical link from host device node to ingestion container.
• Grafana is not the data store: Grafana only queries MySQL; it’s provisioned via files under files/grafana/....
• MySQL initialization and user separation:
• App credentials (MYSQL_USER/MYSQL_PASSWORD)
• Grafana credentials (GRAFANA_MYSQL_USER/GRAFANA_MYSQL_PASSWORD)
• Port exposure: Grafana on 3000 (public LAN), MySQL likely internal-only (show as internal to docker network unless exposed).
• Configuration via .env: show .env feeding Compose/services (as a config input artifact).
• Edge deployment: compute runs near hardware; limited dependencies.
• Separation of concerns:
• ingestion (Python) vs storage (MySQL) vs visualization (Grafana)
• Infrastructure-as-code via Docker Compose + provisioning files:
• Grafana dashboards/datasource are declarative artifacts in repo.
• “Pull” visualization model: Grafana pulls from MySQL; ingestion pushes to MySQL.
• Operational automation:
Shows container boundaries and which service talks to which.
3. Shows configuration/provisioning as first-class artifacts (Grafana dashboards/datasource, MySQL init).
Middle row (Host + Docker Compose boundary)
• Ingestion container (left)
• MySQL (center, with volume under it)
• Grafana (right, with provisioning docs attached)