docs(miotiq): repurpose payload byte 9 as command (ping test trigger)

Le champ `version` (offset 9 du payload NebuleAir Pro 4G) était hardcodé
`0x01` côté firmware et n'a jamais porté un vrai versioning protocole.
Renommé en `command` et réaffecté à un type de trame :

- 0x00 = données mesure
- 0x01 = ping test (firmware → Miotiq → backend, pas d'archivage)

Versioning protocole reste sur `version_major/minor/patch`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

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`. |

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). |