33c4472350
Parsers and formats are tightly linked (a parser produces a format) and the split made cross-links heavy for a single parser file. Also removed the confusing "Enveloppe JSON" block in udp-miotiq.md that mixed the raw webhook wrapper with what the backend actually consumes — the decoded payload schema lives in json-payload.md and is now referenced directly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2.4 KiB
2.4 KiB
Conventions
Nommage des fichiers
- Un capteur = un fichier
sensors/<nom>.mden minuscules, sans tiret dans le nom s'il n'est pas dans la marque (nextpm.md,sps30.md,bme280.md). - Un format = un fichier
formats/<nom>.mddécrivant le schéma et les exemples. Les parsers associés (ex. descripteur binaire Miotiq) vivent dans le même dossier, nommés par transport :formats/<transport>-<origine>.md(udp-miotiq.md,mqtt-tb.md).
Style Markdown
- Titre de niveau 1 unique en haut du fichier.
- Tables pour les registres, commandes, champs de payload.
- Blocs de code annotés du langage (
```c,```python,```json). - Unités explicites dans chaque champ :
µg/m³,°C,%HR,ms. - Endianness toujours précisée pour les champs multi-octets.
Versioning
- Ce repo suit la branche
main. Pas de tag de version pour l'instant. - Si un protocole évolue de façon incompatible, créer une section « Historique » en bas du fichier capteur/format, dater le changement et décrire le breaking change. Les firmwares référencent la révision du fichier qu'ils implémentent.
- Pour les breaking changes majeurs (nouvelle structure payload, renommage de champ), ouvrir une PR et taguer le repo
vXaprès merge.
Code d'exemple
- Les snippets dans cette doc sont illustratifs. Le code de production vit dans les repos firmware/backend.
- Toujours lier vers le fichier source réel quand c'est possible (ex :
server/sites/data.mobileair.fr/udp_miotiq_byte.php). - Éviter les exemples qui dépendent de constantes secrètes (clés API, tokens) — remplacer par
<API_KEY>.
Unités et types de données canoniques
| Grandeur | Unité | Type JSON | Notes |
|---|---|---|---|
| PM1 / PM2.5 / PM10 | µg/m³ | number | 1 décimale suffit |
| Température | °C | number | 1 décimale |
| Humidité relative | % | number | 0–100 |
| Pression | hPa | number | |
| Latitude / Longitude | degrés | number | WGS84, 6 décimales |
| Timestamp | secondes UTC | integer | Unix epoch, UTC toujours |
| Signal cellulaire | dBm ou % | integer | préciser selon capteur |