# 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              |