# Format JSON canonique — mesures capteurs

Format recommandé pour tout nouvel envoi de mesures d'un capteur AirCarto vers un backend (HTTP POST, MQTT publish, webhook…).

> Les chemins d'envoi existants (Miotiq binaire 17 octets, CSV) restent documentés dans [`parsers/udp-miotiq.md`](../parsers/udp-miotiq.md) pour compatibilité. **Ce JSON est la cible** pour les nouveaux développements.

## Schéma

```json
{
  "token": "string",
  "ts": 1713830400,
  "type_conn": "LTE-M",
  "measurements": {
    "pm1": 0.0,
    "pm25": 0.0,
    "pm10": 0.0,
    "temperature": 0.0,
    "humidity": 0.0
  },
  "gps": {
    "lat": 43.605,
    "lon": 1.444,
    "sats": 8
  },
  "link": {
    "signal": -78,
    "imsi": "208xxxxxxxxxxx"
  },
  "fw": "1.4.2"
}
```

## Champs

| Champ                   | Type    | Obligatoire | Description                                                        |
|-------------------------|---------|-------------|--------------------------------------------------------------------|
| `token`                 | string  | oui         | Identifiant unique du capteur (= clé en base `capteurs.capteurs`). |
| `ts`                    | integer | oui         | Timestamp Unix UTC en secondes de la mesure (pas de la réception). |
| `type_conn`             | string  | oui         | Un des : `WiFi`, `LTE-M`, `LTE-BIN`, `NB-IoT`, `LoRa`, `Ethernet`. |
| `measurements.pm1`      | number  | si mesuré   | µg/m³                                                              |
| `measurements.pm25`     | number  | si mesuré   | µg/m³                                                              |
| `measurements.pm10`     | number  | si mesuré   | µg/m³                                                              |
| `measurements.temperature` | number | si mesuré | °C                                                                 |
| `measurements.humidity` | number  | si mesuré   | % HR                                                               |
| `gps.lat`               | number  | si GPS      | Degrés décimaux WGS84, 6 décimales.                                |
| `gps.lon`               | number  | si GPS      | Idem.                                                              |
| `gps.sats`              | integer | si GPS      | Nombre de satellites vus.                                          |
| `link.signal`           | integer | non         | RSSI en dBm (négatif) **ou** % de qualité ; préciser dans `type_conn`. |
| `link.imsi`             | string  | non         | IMSI de la SIM (modem cellulaire uniquement).                      |
| `fw`                    | string  | non         | Version firmware du capteur, ex. `1.4.2`.                          |

## Règles

- Omettre un champ si non mesuré. Ne pas envoyer `null` ni `-1` comme valeur sentinelle (hérité du legacy CSV Miotiq).
- `ts` côté capteur si dispo (GPS / NTP), sinon côté serveur à la réception — documenter au cas par cas dans la doc du capteur.
- Toutes les valeurs numériques utilisent le point `.` comme séparateur décimal.
- Un seul capteur par message. Pas de batch (à revoir si besoin).

## Réponse attendue du serveur

```json
{ "ok": true }
```

Ou en cas d'erreur :

```json
{ "ok": false, "error": "token inconnu" }
```

HTTP 200 dans les deux cas pour ne pas déclencher de retry cellulaire côté modem ; le `ok: false` indique à la supervision qu'il y a un problème applicatif.

## Exemple minimal

```json
{
  "token": "001",
  "ts": 1713830400,
  "type_conn": "WiFi",
  "measurements": { "pm25": 12.3 }
}
```