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>
39 lines
2.4 KiB
Markdown
39 lines
2.4 KiB
Markdown
# Conventions
|
||
|
||
## Nommage des fichiers
|
||
|
||
- Un capteur = un fichier `sensors/<nom>.md` en 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>.md` dé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 `vX` aprè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 |
|