Connectivité des appareils
Ce chapitre est le contrat que votre matériel doit respecter pour parler à SensoCAN. Votre appareil envoie des relevés, SensoCAN rattache chacun d'eux à un capteur que vous avez configuré, puis le remet à la chaîne de règles de ce capteur. Les tableaux de bord, les alarmes et les exports reposent tous sur ce qui arrive ici.
Deux protocoles transportent la même charge utile (payload) :
- MQTT — une connexion persistante, publiez dès que vous avez des données.
- HTTP — une requête par relevé ou par lot, aucune connexion à garder ouverte.
Vous utilisez une passerelle BLE prise en charge plutôt que votre propre firmware ? Voir le chapitre Passerelles et balises.
Choisir un protocole
| MQTT | HTTP | |
|---|---|---|
| Connexion | Persistante, maintenue ouverte | Une requête à la fois |
| Retour d'information par message | Aucun | Complet : le nombre de relevés acceptés, en doublon et rejetés |
| Surcharge par relevé | Très faible | Une poignée de main TLS et des en-têtes à chaque requête |
| Compatibilité avec les pare-feux | Nécessite un port sortant ouvert | HTTPS ordinaire |
| Rattrapage hors ligne | Pris en charge | Pris en charge |
| Idéal pour | Les appareils sur batterie, les cadences de transmission élevées, les liaisons cellulaires | Les appareils derrière des réseaux restrictifs, les passerelles ne disposant que d'une pile HTTP, la mise en route et le débogage |
Une publication MQTT vous indique que le message a quitté l'appareil ; elle ne peut pas vous dire que le relevé a été compris, faute de canal de réponse. Chaque requête HTTP, elle, répond en indiquant ce qu'il est advenu de chacun des relevés qu'elle contient. Au moment de mettre votre firmware en route, envoyez d'abord une requête HTTP et lisez la réponse, puis basculez vers MQTT une fois la charge utile correcte.
Ce que la plateforme doit vous fournir d'abord
Tout ce dont votre firmware a besoin se trouve sur la page Détails de l'appareil : ouvrez Appareils et cliquez sur le nom de l'appareil.
| Valeur | Où la trouver | Utilisation |
|---|---|---|
| UUID de l'appareil | Carte Informations sur l'appareil, avec un bouton de copie | Identifiant client MQTT ; partie de chaque URL HTTP |
| Topic MQTT | Carte Informations sur l'appareil, affiché en entier avec un bouton de copie | Le topic de publication au niveau de l'appareil |
| Nom d'utilisateur et mot de passe MQTT | Bouton Identifiants MQTT | Se connecter à l'hôte MQTT |
| Jeton d'accès | Bouton Afficher le jeton | L'en-tête HTTP Authorization |
| Slug et UUID du capteur | Tableau des capteurs → ouvrir un capteur | Adresser un relevé à un capteur précis |
N'assemblez pas les topics ni les URL à la main. La page affiche le topic déjà assemblé, et le bouton Exemples de charges utiles MQTT placé à côté ouvre des topics et des charges utiles prêts à l'emploi, renseignés avec les identifiants réels de cet appareil.
Toute personne détenant le jeton d'accès ou le mot de passe MQTT peut envoyer des relevés au nom de cet appareil. Le jeton d'accès peut être régénéré à tout moment depuis Afficher le jeton : l'ancien est invalidé immédiatement et l'appareil reste bloqué tant que vous n'avez pas flashé la nouvelle valeur. Le mot de passe MQTT ne peut pas être renouvelé de la même manière ; s'il doit changer, il n'est réémis automatiquement que si l'identifiant stocké vient à être perdu ou ne peut plus être déchiffré.
Les règles de charge utile communes aux deux protocoles
Enveloppez les relevés dans data. Chaque charge utile comporte une clé data de premier niveau qui contient soit un objet relevé, soit un tableau d'objets relevés. Rien en dehors de data n'est traité comme un relevé.
value est obligatoire, et devrait être un nombre. En HTTP, une valeur non numérique est rejetée. En MQTT, rien ne la rejette, mais les règles, les graphiques et les exports attendent tous un nombre.
timestamp est optionnel. Envoyez une date ISO 8601 (2026-09-03T10:00:00Z). Omettez-la et le relevé est horodaté à son heure d'arrivée.
Les horloges des appareils sont corrigées, pas sanctionnées. Si l'horodatage le plus récent d'une charge utile est en avance sur l'heure à laquelle elle arrive — une horloge d'appareil qui avance —, toute la charge utile est décalée en arrière de ce seul écart : le relevé le plus récent se pose à l'heure d'arrivée et l'espacement entre les relevés est préservé. Rien n'est écarté au motif d'un horodatage dans le futur, si bien que vous n'avez jamais à vérifier l'horloge avant de vider un tampon. Les relevés corrigés conservent l'écart qui leur a été appliqué dans clock_offset_seconds, au sein de leurs métadonnées enregistrées, de sorte que les données corrigées restent distinguables des données mesurées. Les horodatages passés sont enregistrés tels qu'ils ont été envoyés, ce qui est le rattrapage hors ligne ordinaire.
battery_voltage se place à côté de data, et non à l'intérieur. Envoyez la tension en volts sous forme de nombre ; de 0 à 100 est accepté, si bien qu'une batterie au lithium annonçant 3.7 est un cas courant. La page Détails de l'appareil l'affiche sous Tension, en regard du type de batterie configuré pour l'appareil, et en déduit le pourcentage Niveau. Elle est ignorée pour les appareils réglés sur l'alimentation directe. En MQTT, vous pouvez aussi publier battery_voltage seul, sans aucune clé data, sur n'importe quel topic. En HTTP, chaque requête doit comporter un objet ou un tableau data — il n'existe pas de point de terminaison (endpoint) réservé à la batterie.
Les clés supplémentaires voyagent avec le relevé. Toute autre clé placée dans un objet relevé est conservée en métadonnées et peut être lue par les règles : version du firmware, puissance du signal, nombre d'échantillons. Jusqu'à 30 clés par relevé, des valeurs simples uniquement (ni objets ni tableaux imbriqués), des noms de clé de 64 caractères au plus, un texte tronqué à 512 caractères.
Les répétitions sont supprimées. Pour certains types de capteurs, une même valeur renvoyée pour le même capteur en l'espace de quelques secondes n'est pas traitée deux fois. Rejouer un tampon est sans risque : un doublon n'est jamais une erreur.
Accepté ne veut pas dire enregistré
Un relevé accepté est remis à la chaîne de règles qui s'applique à ce capteur, et c'est cette chaîne qui décide de la suite — y compris de l'enregistrement du relevé. Chaque compte démarre avec une Chaîne de règles par défaut qui enregistre tout ce qu'elle reçoit. Remplacez-la par une chaîne à vous, dépourvue d'étape d'enregistrement, et votre appareil continuera de s'entendre dire que ses relevés ont été acceptés alors que rien n'apparaît sur la page de l'appareil. Vérifiez la chaîne dans Gestion → Chaînes de règles avant de soupçonner votre firmware.