diff --git a/formats/json-payload.md b/formats/json-payload.md index 5782dca..199807b 100644 --- a/formats/json-payload.md +++ b/formats/json-payload.md @@ -32,7 +32,20 @@ Le **type de capteur** est passé en query string. Modèles supportés : |------------------|--------|--------------------------------------------------------------------------------------------------| | `device_id` | string | Identifiant unique, **représentation hexadécimale** de 16 caractères (8 octets ASCII). Convertir hex → ASCII pour obtenir le numéro de série imprimé sur le boîtier. Ex. `"4430353234313938"` → `"D0524198"`. | | `signal_quality` | int | Qualité du signal réseau (dB, souvent RSSI négatif). | -| `version` | int | Version du protocole de communication (pas la version firmware — voir `version_*` plus bas). | +| `command` | int | Type de trame. `0x00` = données mesure (les autres champs sont valides). `0x01` = ping test (trame émise volontairement par le firmware pour vérifier le lien capteur → Miotiq → backend ; le backend ne doit pas archiver les mesures associées). Voir [Commande / type de trame](#commande--type-de-trame). | + +## Commande / type de trame + +Le champ `command` (1 octet, offset 9 du payload binaire) discrimine la nature de la trame. + +| Valeur | Sens | Action backend attendue | +|---------|--------------|---------------------------------------------------------------------------------------------------------------| +| `0x00` | données | Trame de mesure normale. Décoder et persister les champs métier comme d'habitude. | +| `0x01` | ping test | Trame de diagnostic émise par le firmware pour vérifier le chemin capteur → Miotiq → backend. Logger la réception (timestamp, `device_id`, `signal_quality`) puis **ne pas archiver** les autres champs comme mesures réelles — leur contenu n'est pas garanti significatif. | + +Toute autre valeur doit être traitée comme une trame de données (`0x00`) en attendant qu'elle soit officiellement allouée — éviter de rejeter la trame sur la seule base d'un `command` inconnu pour rester forward-compatible. + +**Note historique** : ce champ s'appelait `version` avant 2026-04-27 et était hardcodé `0x01` côté firmware. Le versioning du protocole est exclusivement porté par `version_major/minor/patch` (voir [Version firmware](#version-firmware)). ## Polluants (codes ISO LCSQA) @@ -182,7 +195,7 @@ Enum extensible — de nouvelles valeurs peuvent être ajoutées (7, 8, …) san "device_id": "4430353234313938", "signal_quality": -22, "signal_quality_unit": "-22 dB", - "version": 1, + "command": 0, "ISO_68": 0.8, "ISO_68_unit": "0,8 ugm3", "ISO_54": 25.5, "ISO_54_unit": "25.5 °C", "noise_cur_leq": 25.5, "noise_cur_leq_unit": "25,5 dB", @@ -227,6 +240,7 @@ Enum extensible — de nouvelles valeurs peuvent être ajoutées (7, 8, …) san - Ignorer `error_flags`, `npm_status`, `device_status` si `== 255` — c'est un firmware ancien, l'absence de diagnostic n'est pas une alarme. - Les `_unit` sont purement informatifs / de debug. La valeur métier est toujours le champ sans suffixe. - `device_id` est **hex** dans le JSON ; convertir en ASCII (`bytes.fromhex(v).decode('ascii')`) pour afficher le numéro de série lisible. +- Lire `command` **avant** de persister la trame : si `command == 0x01` (ping test), logger la réception (timestamp, `device_id`, `signal_quality`) sans archiver les mesures. Une trame `command` absent ou `0x00` est une trame de données normale. ## Historique @@ -234,3 +248,4 @@ Enum extensible — de nouvelles valeurs peuvent être ajoutées (7, 8, …) san |------------|----------|---------------------------------------------------------------------------| | 2026-04-23 | v1 | Version initiale inventée (schéma imbriqué avec `token`/`ts`/`measurements`) — remplacée. | | 2026-04-23 | v2 | **Format officiel AirCarto 2026** : schéma plat, bitfields détaillés, compat firmware ancien. | +| 2026-04-27 | v3 | Champ `version` (offset 9 du binaire, hardcodé `0x01` côté firmware) renommé `command` et réaffecté à un type de trame : `0x00` = données, `0x01` = ping test. Ajout de la section « Commande / type de trame ». Versioning protocole reste sur `version_major/minor/patch`. | diff --git a/formats/udp-miotiq.md b/formats/udp-miotiq.md index 23d0c68..097afdb 100644 --- a/formats/udp-miotiq.md +++ b/formats/udp-miotiq.md @@ -64,7 +64,7 @@ Descripteur de référence : ``` 16|device_id|string|||W 2|signal_quality|hex2dec|dB|| -2|version|hex2dec|||W +2|command|hex2dec|||W 4|ISO_68|hex2dec|ugm3|x/10| 4|ISO_39|hex2dec|ugm3|x/10| 4|ISO_24|hex2dec|ugm3|x/10| @@ -122,7 +122,7 @@ Layout octet par octet : |--------|--------|-------------------|---------|--------|------------------------------------------| | 0 | 8 | `device_id` | | | Hex 16 chars, converti en ASCII côté client (ex. `"D0524198"`) | | 8 | 1 | `signal_quality` | dB | | Signal cellulaire | -| 9 | 1 | `version` | | | Version du protocole de communication | +| 9 | 1 | `command` | | | Type de trame — `0x00` = données mesure, `0x01` = ping test (déclenché par le firmware pour vérifier le lien capteur → Miotiq → backend). Voir [`json-payload.md`](json-payload.md#commande--type-de-trame). | | 10 | 2 | `ISO_68` | µg/m³ | /10 | PM1 | | 12 | 2 | `ISO_39` | µg/m³ | /10 | PM2.5 | | 14 | 2 | `ISO_24` | µg/m³ | /10 | PM10 | @@ -219,3 +219,4 @@ Valeurs manquantes codées `-1` (sentinelle legacy). À **ne pas reproduire** po | 2026-04-23 | v4 | Correction : `string` produit du hex (pas ASCII). Correction ISO_39=PM2.5 et ISO_24=PM10 (inversion). Gaz confirmés (NO₂/CO/H₂S/NH₃/O₃). Lien vers JSON canonique AirCarto 2026. | | 2026-04-23 | v5 | Extension prévue du descripteur NebuleAir Pro 4G avec `latitude`, `longitude`, `misc` dans le bloc `reserved` — proposition d'encodage dans la section À faire. | | 2026-04-24 | v6 | Intégration effective de `latitude` (4B), `longitude` (4B), `misc` (1B) dans le descripteur NebuleAir Pro 4G. Encodage offset unsigned (`raw = (deg + 90|180) * 1e6`, équation `x/1000000-90|180`) pour contourner l'absence de signed sur `hex2dec` Miotiq. « No fix » géré par le bit `GPS_NO_FIX` de `device_status`. Reste 2B `reserved`. | +| 2026-04-27 | v7 | Octet 9 renommé `version` → `command`. Ce champ était hardcodé `0x01` côté firmware (jamais une vraie version de protocole). Réaffecté à un type de trame : `0x00` = données mesure, `0x01` = ping test. Permet au firmware de déclencher une trame de bout en bout (capteur → Miotiq → backend) sans envoyer de mesures réelles. Versioning protocole assuré par `version_major/minor/patch` (offsets 69-71). |