chore: initial skeleton — NextPM sensor, JSON format, Miotiq UDP parser

2026-04-23 00:36:19 +02:00
commit 278775e7e8
8 changed files with 649 additions and 0 deletions
--- a/formats/json-payload.md
+++ b/formats/json-payload.md
@@ -0,0 +1,83 @@
+# Format JSON canonique — mesures capteurs
+
+Format recommandé pour tout nouvel envoi de mesures d'un capteur AirCarto vers un backend (HTTP POST, MQTT publish, webhook…).
+
+> Les chemins d'envoi existants (Miotiq binaire 17 octets, CSV) restent documentés dans [`parsers/udp-miotiq.md`](../parsers/udp-miotiq.md) pour compatibilité. **Ce JSON est la cible** pour les nouveaux développements.
+
+## Schéma
+
+```json
+{
+  "token": "string",
+  "ts": 1713830400,
+  "type_conn": "LTE-M",
+  "measurements": {
+    "pm1": 0.0,
+    "pm25": 0.0,
+    "pm10": 0.0,
+    "temperature": 0.0,
+    "humidity": 0.0
+  },
+  "gps": {
+    "lat": 43.605,
+    "lon": 1.444,
+    "sats": 8
+  },
+  "link": {
+    "signal": -78,
+    "imsi": "208xxxxxxxxxxx"
+  },
+  "fw": "1.4.2"
+}
+```
+
+## Champs
+
+| Champ                   | Type    | Obligatoire | Description                                                        |
+|-------------------------|---------|-------------|--------------------------------------------------------------------|
+| `token`                 | string  | oui         | Identifiant unique du capteur (= clé en base `capteurs.capteurs`). |
+| `ts`                    | integer | oui         | Timestamp Unix UTC en secondes de la mesure (pas de la réception). |
+| `type_conn`             | string  | oui         | Un des : `WiFi`, `LTE-M`, `LTE-BIN`, `NB-IoT`, `LoRa`, `Ethernet`. |
+| `measurements.pm1`      | number  | si mesuré   | µg/m³                                                              |
+| `measurements.pm25`     | number  | si mesuré   | µg/m³                                                              |
+| `measurements.pm10`     | number  | si mesuré   | µg/m³                                                              |
+| `measurements.temperature` | number | si mesuré | °C                                                                 |
+| `measurements.humidity` | number  | si mesuré   | % HR                                                               |
+| `gps.lat`               | number  | si GPS      | Degrés décimaux WGS84, 6 décimales.                                |
+| `gps.lon`               | number  | si GPS      | Idem.                                                              |
+| `gps.sats`              | integer | si GPS      | Nombre de satellites vus.                                          |
+| `link.signal`           | integer | non         | RSSI en dBm (négatif) **ou** % de qualité ; préciser dans `type_conn`. |
+| `link.imsi`             | string  | non         | IMSI de la SIM (modem cellulaire uniquement).                      |
+| `fw`                    | string  | non         | Version firmware du capteur, ex. `1.4.2`.                          |
+
+## Règles
+
+- Omettre un champ si non mesuré. Ne pas envoyer `null` ni `-1` comme valeur sentinelle (hérité du legacy CSV Miotiq).
+- `ts` côté capteur si dispo (GPS / NTP), sinon côté serveur à la réception — documenter au cas par cas dans la doc du capteur.
+- Toutes les valeurs numériques utilisent le point `.` comme séparateur décimal.
+- Un seul capteur par message. Pas de batch (à revoir si besoin).
+
+## Réponse attendue du serveur
+
+```json
+{ "ok": true }
+```
+
+Ou en cas d'erreur :
+
+```json
+{ "ok": false, "error": "token inconnu" }
+```
+
+HTTP 200 dans les deux cas pour ne pas déclencher de retry cellulaire côté modem ; le `ok: false` indique à la supervision qu'il y a un problème applicatif.
+
+## Exemple minimal
+
+```json
+{
+  "token": "001",
+  "ts": 1713830400,
+  "type_conn": "WiFi",
+  "measurements": { "pm25": 12.3 }
+}
+```