aircarto-protocols/CONVENTIONS.md

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 parser = un fichier parsers/<transport>-<origine>.md (udp-miotiq.md, mqtt-tb.md).
• Un format = un fichier formats/<nom>.md décrivant le schéma et les exemples.

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