D API du cockpit

Les 13 routes servies par la passerelle elle-même : ce qu'elles font, ce qu'elles exigent, ce qu'elles répondent. Page vérifiée contre le flux le 2026-09-23.

Une seule API, deux portes

Les 13 routes sont servies à l'identique sur les deux ports (8888 et 8889). Ce n'est pas le port qui décide de ce qui est permis, mais le rôle du compte avec lequel on s'est connecté.

Conséquence à connaître : un compte « opérateur » n'est pas un accès en lecture seule. Il peut modifier la configuration d'une balise, en déclarer une nouvelle et envoyer un réglage. Seule l'écriture des variables globales lui est refusée.

Authentification

Deux couches, avec les mêmes identifiants. Le serveur HTTP demande d'abord une authentification au navigateur. Ensuite, POST /cockpit/login ouvre une session applicative et renvoie un jeton, valable huit heures, à placer dans l'en-tête X-Session de chaque appel suivant.

jeton=$(curl -s -u <compte>:<mot de passe> \
  -X POST http://<passerelle>:8888/cockpit/login \
  -H 'Content-Type: application/json' \
  -d '{"user":"<compte>","password":"<mot de passe>"}' \
  | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')

curl -s -u <compte>:<mot de passe> -H "X-Session: $jeton" \
  http://<passerelle>:8888/cockpit/health

Routes

Route	Accès	Objet	Réponses	Traitée par
`GET /`	public	La page du cockpit.	200	fichier servi tel quel
`GET /app.js`	public	Le code de l'interface.	200	fichier servi tel quel
`POST /cockpit/balise`	session requise	Déclare une nouvelle balise. Le corps porte `name`, `deveui` et `appkey`. Répond `202` : la déclaration est lancée, pas terminée — elle réécrit le flux et redémarre toutes les chaînes. Plusieurs garde-fous peuvent la refuser ; le message dit lequel.	`202`, `400`, `401`	`post_balise`
`GET /cockpit/balises`	session requise	État de chaque balise : dernière trame, compteurs, qualité radio, réglage en cours, historique récent et compteurs horaires sur 24 h.	`200`, `401`	`cockpit_balises`
`POST /cockpit/downlink`	session requise	Met un réglage ou un redémarrage en file pour une balise. La commande part au prochain réveil de celle-ci.	`200`, `202`, `401`	`cockpit_downlink`
`GET /cockpit/globals`	session requise	Variables globales. Les secrets ne sont jamais renvoyés en clair : ils apparaissent masqués.	`200`, `401`	`cockpit_globals`
`POST /cockpit/globals`	rôle admin	Écrit les variables globales. Seule route réservée au rôle admin. Seules les clés d'une liste blanche sont acceptées ; les autres sont ignorées. Un champ secret laissé vide conserve la valeur en place.	`400`, `401`, `403`	`post_globals_stash`
`GET /cockpit/health`	public	État général : temps de fonctionnement, réception radio, santé des envois vers IoBase et Asystom, authentification, liaison cellulaire, et les environnements IoBase déclarés. C'est ce que lit le tableau de bord.	200	fichier servi tel quel
`POST /cockpit/login`	ouverte	Ouvre une session. Le corps porte `user` et `password` ; la réponse renvoie un jeton et le rôle associé. Ce jeton se place ensuite dans l'en-tête `X-Session` de tous les autres appels.	`200`, `401`	`cockpit_login`
`GET /cockpit/meta`	public	Configuration des balises, telle qu'elle est stockée sur la passerelle.	200	fichier servi tel quel
`POST /cockpit/meta`	session requise	Écrit la configuration des balises. Le corps porte l'ensemble des balises, pas seulement celle qu'on modifie : envoyer un objet partiel effacerait les autres. Chaque champ est validé, et une destination inconnue est refusée plutôt que ramenée au défaut.	`200`, `400`, `401`	`post_meta`
`GET /cockpit/whoami`	session requise	Rôle de la session en cours. Sert à l'interface pour décider ce qu'elle affiche.	`200`, `401`	`whoami_session`
`GET /style.css`	public	La feuille de style de l'interface.	200	fichier servi tel quel

Codes de réponse

Code	Signification
`200`	Succès.
`202`	Demande acceptée, traitement lancé — le résultat n'est pas encore connu.
`400`	Requête refusée : contenu invalide, ou garde-fou déclenché. Le corps donne le motif.
`401`	Session absente, invalide ou expirée. Se reconnecter.
`403`	Session valide mais rôle insuffisant.