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

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 }
+}
+```

formats/mqtt.md

@@ -0,0 +1,38 @@
+# MQTT — conventions
+
+> **Statut** : squelette. À compléter au premier déploiement MQTT AirCarto.
+
+## Broker
+
+- À définir : URL, port (1883 / 8883 TLS), credentials.
+
+## Topics
+
+Convention proposée :
+
+```
+aircarto/<projet>/<token>/<canal>
+```
+
+- `projet` : `nebuleair`, `moduleair`, `mobileair`, …
+- `token` : identifiant unique du capteur.
+- `canal` :
+  - `telemetry` : mesures périodiques (publish capteur → broker), payload JSON conforme à [`json-payload.md`](json-payload.md).
+  - `status` : en ligne / hors ligne, version firmware (retain, LWT).
+  - `cmd` : commandes broker → capteur (ex. reboot, changer la fréquence).
+  - `ack` : accusés capteur → broker.
+
+Exemple : `aircarto/nebuleair/001/telemetry`.
+
+## QoS et retain
+
+- `telemetry` : **QoS 0** (fire-and-forget, InfluxDB tolère les pertes occasionnelles).
+- `status` : **QoS 1** + **retain = true** + LWT pour détecter les déconnexions.
+- `cmd` : **QoS 1**, pas de retain.
+
+## À faire
+
+- [ ] Nommer le broker de référence (Mosquitto ? HiveMQ ? EMQX ?).
+- [ ] Documenter l'authentification (username+password, certificats ?).
+- [ ] Schéma exact des payloads `status` et `cmd`.
+- [ ] Exemple de wildcard subscription côté backend.