Paul Vuarambon
efd1aa438a
formats/json-payload.md: full rewrite around the actual server-side template
(endpoint api.aircarto.com/receive_data?device_type=<model>, flat schema,
_unit suffix companions, -1 and 255 sentinel semantics, full bitfield
tables for error_flags/npm_status/device_status, misc context codes).
formats/iso-pollutant-codes.md: fill in the LCSQA mapping. Fixes my earlier
inversion — ISO_39=PM2.5 and ISO_24=PM10 (not the other way). Add gases:
ISO_03=NO2, ISO_04=CO, ISO_05=H2S, ISO_08=O3, ISO_21=NH3.
parsers/udp-miotiq.md:
- string base function outputs hex (not ASCII) — update description and
generic Python parser accordingly.
- Fix ISO_39/ISO_24 labels in NebuleAir Pro 4G byte layout.
- Name the 5 gases by offset, cross-link bitfield docs and JSON canonical.
- New TODO: origin of latitude/longitude/misc in final JSON (not in 83B
descriptor).
README.md: reflect the new file layout and data flow summary.
53 lines
3.1 KiB
Markdown
53 lines
3.1 KiB
Markdown
# aircarto-protocols
|
|
|
|
Documentation de référence pour tous les capteurs AirCarto : protocoles de communication (UART, I2C, UDP, HTTP, MQTT…), formats de données, parsers et conventions.
|
|
|
|
**Public visé** — chaque projet firmware ou backend AirCarto consomme cette doc pour intégrer la logique commune (dialogue capteur, format d'envoi, parsing côté serveur) sans réinventer ni diverger.
|
|
|
|
## Structure
|
|
|
|
```
|
|
aircarto-protocols/
|
|
├── CONVENTIONS.md Nommage, versioning, style doc
|
|
├── formats/ Formats d'échange de données
|
|
│ ├── json-payload.md Format JSON canonique des mesures
|
|
│ ├── iso-pollutant-codes.md Mapping ISO_XX → polluant / grandeur
|
|
│ └── mqtt.md Topics et conventions MQTT
|
|
├── sensors/ Un fichier par capteur
|
|
│ ├── _TEMPLATE.md Gabarit à copier pour tout nouveau capteur
|
|
│ └── nextpm.md NextPM (Tera Sensor) — UART
|
|
└── parsers/ Parsers côté serveur / passerelle
|
|
└── udp-miotiq.md Webhook Miotiq (UDP → HTTPS JSON)
|
|
```
|
|
|
|
## Index des capteurs
|
|
|
|
| Capteur | Interface | Doc | État |
|
|
|-------------|-----------|-----------------------------------|------------|
|
|
| NextPM | UART | [sensors/nextpm.md](sensors/nextpm.md) | Complet |
|
|
|
|
## Index des parsers
|
|
|
|
| Nom | Transport | Doc | État |
|
|
|-----------------|------------------|-----------------------------------------------|-------------------------------|
|
|
| UDP Miotiq | UDP → HTTPS JSON | [parsers/udp-miotiq.md](parsers/udp-miotiq.md) | Descripteur NebuleAir Pro 4G + legacy MobileAir |
|
|
|
|
## Comment ajouter une entrée
|
|
|
|
- **Nouveau capteur** : copier `sensors/_TEMPLATE.md` vers `sensors/<nom>.md`, remplir les sections, mettre à jour l'index ci-dessus.
|
|
- **Nouveau format / parser** : créer le fichier sous `formats/` ou `parsers/`, mettre à jour l'index.
|
|
- Voir [CONVENTIONS.md](CONVENTIONS.md) pour le style et le nommage.
|
|
|
|
## Pourquoi ce repo
|
|
|
|
Avant : chaque firmware AirCarto (NebuleAir, ModuleAir, MobileAir…) redéfinissait ses trames et son format JSON dans son coin. Les parsers côté serveur (`data.mobileair.fr/udp_miotiq_*.php`, `gestion.aircarto.fr`) devaient suivre. Résultat : dérives silencieuses entre capteurs, bugs d'intégration.
|
|
|
|
Ici on centralise la **spécification** :
|
|
|
|
- **Capteur → Miotiq** : payload UDP binaire, décodé côté Miotiq via un *descripteur* ([`parsers/udp-miotiq.md`](parsers/udp-miotiq.md)).
|
|
- **Miotiq → serveur AirCarto** : JSON canonique 2026 ([`formats/json-payload.md`](formats/json-payload.md)) posté sur `api.aircarto.com/receive_data`.
|
|
- **Vocabulaire polluants** : codes ISO LCSQA ([`formats/iso-pollutant-codes.md`](formats/iso-pollutant-codes.md)).
|
|
- **Capteurs physiques** : docs individuelles sous `sensors/` (protocole UART/I2C, câblage, commandes).
|
|
|
|
Le code de référence reste dans les repos des projets (firmwares, backends) ; ce repo décrit ce qui est attendu sur le fil.
|