Envoyer des mesures avec l'API HTTP

Tout système capable d'envoyer une requête HTTP avec un corps JSON peut alimenter FreeMaint Connect : Node-RED, Home Assistant, une passerelle qui lit du Modbus, un automate ou un script maison. Créez une connexion de type API HTTP (Node-RED, script…) pour obtenir son URL et sa clé d'accès.

La requête

Méthode : POST, vers l'URL affichée à la création de la connexion (elle se termine par /connect/ingest/generic).
En-tête Authorization: Bearer suivi de la clé d'accès.
En-tête Content-Type: application/json.
FreeMaint répond 202 lorsque les données sont acceptées ; elles sont enregistrées en quelques secondes.

Le corps

Le corps liste les appareils sous items. Chaque appareil a un identifiant (device), un nom d'affichage facultatif, un horodatage facultatif (ts, ISO 8601) et ses points. Chaque point a une clé (key), une valeur (value) et, idéalement, une unité (unit) et une grandeur (quantity). L'écran de création affiche un exemple complet à copier.

Champs d'un point

key

Le nom du canal sur cet appareil, par exemple power ou energy_total. Une même clé aboutit toujours au même canal.

value

Un nombre.

unit

Par exemple W, kWh, °C ou mm/s. L'énergie en Wh ou en MWh est convertie en kWh, les températures en °C, la vitesse vibratoire en mm/s. Les pressions en Pa, hPa, kPa, mbar, psi, inH2O, inWC ou mmH2O sont converties en bar. Pour lire un canal dans une autre unité, choisissez son Unité d'affichage dans FreeMaint. La page du canal affiche l'unité du dernier relevé sous « Unité reçue ». La casse compte pour milli et méga : mW et mWh sont des milli, MW et MWh des méga. Les noms d'unités BACnet sont aussi acceptés, quelle que soit la casse : « PASCALS », « inches-of-water », « kilowatt-hours »…

quantity

La grandeur mesurée, par exemple power, energy, temperature ou vibration_velocity. Elle permet à FreeMaint de choisir la bonne unité et le bon graphique.

kind

CUMULATIVE pour un compteur qui ne fait qu'augmenter (un total d'énergie, des heures de fonctionnement). FreeMaint calcule alors la consommation entre deux relevés. Omettez ce champ pour une simple valeur mesurée.

Limites

Jusqu'à 500 appareils et 5 000 points par requête.
Jusqu'à 120 requêtes par minute et par connexion ; au-delà, FreeMaint répond 429 et votre système doit réessayer plus tard.
Une requête mal formée reçoit une réponse 400 qui indique le problème : une passerelle mal configurée se corrige donc facilement.
Chaque nouveau canal compte dans la limite de canaux actifs de votre plan.

Astuce

Montages typiques : un flux Node-RED qui lit un compteur d'énergie Modbus chaque minute et envoie ses valeurs ; une automatisation Home Assistant qui transmet un capteur ; un routeur Teltonika dont la fonction Data to Server envoie les relevés.

Avertissement

Gardez la clé d'accès secrète : quiconque la détient peut envoyer des données à cette connexion. Si elle a pu fuiter, générez une nouvelle clé et choisissez La révoquer maintenant.