Audience : developpeurs & integrateurs externes
Cette page documente le protocole de communication entre capteurs Canarin et le serveur d'ingestion Birdhouse, ainsi que l'API REST cote frontend Plumage. Pour le panneau utilisateur, voir le mode d'emploi.
1. Endpoints d'ingestion (UDP)
Le serveur Birdhouse ecoute les paquets UDP envoyes par les capteurs IoT sur deux ports :
Production : ingest.canarin-sensors.com:59004 (UDP)
Dev / staging : ingest.dev.canarin-sensors.com:59005 (UDP)
Le choix UDP est dicte par la nature des capteurs LPWAN/batterie : pas de handshake TCP, paquets < 512 octets, ACK applicatif optionnel. Les retransmissions sont tolerees (deduplication cote serveur par cle composite device_id + time_bucket + pollutant_id).
2. Format de paquet
Tous les paquets utilisent un format texte ASCII separe par virgules :
Avec :
code— type de message (voir tableau ci-dessous)native_id— identifiant materiel unique 6 caracteres hex, grave en usine (ex.1A2B3C)proj_id— identifiant projet alloue lors du pairing (entier)timestamp— epoch Unix UTC en secondes (entier)key:value— paires polluant / mesure (cf. section 4)
3. Codes de message
| Code | Sens | Usage |
|---|---|---|
| 0 | device → serveur | Enregistrement / declaration de capteur |
| 1 | device → serveur | Paquet de donnees (mesures temps reel) |
| 2 | serveur → device | Push de configuration / OTA URL |
4. Cles polluant (legacy IDs)
Les cles numeriques identifient le type de mesure. Cette enumeration est historique ; pour les nouveaux integrateurs, utilisez plutot le schema declaratif pollutant_id (cf. section 6).
5. Exemple complet
Capteur Pico WiFi 1A2B3C du projet 42, paquet emis le 2026-05-12 12:00:00 UTC, avec GPS, PM2.5 = 12.5 ug/m3, temperature 21.3 degC :
6. EPIC Pollutant : schema declaratif (recommande)
Le nouveau schema permet aux capteurs de declarer leurs polluants avant emission, avec gestion multi-instance (ex. 2 capteurs PM2.5 sur un meme device), normalisation des magnitudes, et resolution d'alias. Cette declaration vit cote frontend Plumage :
Reponse : un pollutant_id entier par polluant declare. Le capteur peut ensuite emettre ses paquets UDP en utilisant ces IDs comme cles (au lieu des legacy IDs section 4). Idempotent sur payload identique.
7. API REST (Bearer token)
Endpoints accessibles avec un token genere depuis api/manage :
| Methode | Endpoint | Description |
|---|---|---|
| GET | /api/verify | Verifie le token et retourne les infos user |
| GET | /api/sensors | Liste des capteurs du user |
| GET | /api/projects | Liste des projets du user |
| POST | /api/data | Push de mesures (alternative HTTP a UDP) |
| POST/GET | /api/devices | Enregistrer/lister les capteurs |
| GET | /api/v2/projects/{id}/devices/updates | Long-polling mobile (Sprint 3 Plan C.5) |
8. Quotas & rate limits
- UDP : pas de quota stricte cote capteur, mais granularite minimale recommandee = 60 s (anti-flood).
- API REST : 100 requetes / minute / token. Header
X-RateLimit-Remainingretourne dans chaque reponse. - Payload UDP : 512 octets max (limite typique MTU LoRa/GSM). Au-dela, le paquet est silencieusement tronque.
9. Validation & quarantaine
Le serveur d'ingestion (Birdhouse, Run 3 EPIC Pollutant) applique cette pipeline de validation :
- Resolution du
pollutant_idvia cache Redis (TTL 5 min) ou fallback DB. - Validation min/max selon les bornes declarees sur
pollutants. - Conversion canonique :
value = raw_value × pollutants.scale_factor. - Insertion dans
data_points_canonical(PK compositee = dedup). - Sur echec : copie dans
data_points_quarantineavec raison (below_min,above_max,cache_miss,nan_or_inf, etc.).
Pour debug, contactez contact@canarin.eu en mentionnant le native_id et l'horodatage : nous pouvons exposer la trace de quarantaine sur demande.
10. Limites & usages exclus
Le protocole Canarin est concu pour des mesures environnementales indicatives. Voir disclaimer pour la liste exhaustive des usages exclus (medical, ATEX, securite incendie, etc.).