Messwerte über die HTTP-API senden

Jedes System, das eine HTTP-Anfrage mit JSON-Body senden kann, lässt sich an FreeMaint Connect anbinden: Node-RED, Home Assistant, ein Gateway, das Modbus ausliest, eine SPS oder ein eigenes Skript. Legen Sie eine Verbindung vom Typ „HTTP-API (Node-RED, Skript…)“ an, um deren URL und Zugangsschlüssel zu erhalten.

Die Anfrage

Methode: POST, an die URL, die beim Anlegen der Verbindung angezeigt wird (sie endet auf /connect/ingest/generic).
Header Authorization: Bearer, gefolgt vom Zugangsschlüssel.
Header Content-Type: application/json.
FreeMaint antwortet mit 202, wenn die Daten angenommen wurden; sie sind innerhalb weniger Sekunden gespeichert.

Der Body

Der Body listet die Geräte unter items auf. Jedes Gerät hat eine Kennung (device), optional einen Anzeigenamen, optional einen Zeitstempel (ts, ISO 8601) und seine Messpunkte. Jeder Messpunkt hat einen key, einen value und idealerweise eine unit und eine quantity. Der Einrichtungsbildschirm zeigt ein vollständiges Beispiel zum Kopieren.

Felder eines Messpunkts

key

Der Name des Kanals auf diesem Gerät, zum Beispiel power oder energy_total. Derselbe key landet immer auf demselben Kanal.

value

Eine Zahl.

unit

Zum Beispiel W, kWh, °C oder mm/s. Energie in Wh oder MWh wird in kWh umgerechnet, Temperaturen in °C, Schwinggeschwindigkeit in mm/s. Drücke in Pa, hPa, kPa, mbar, psi, inH2O, inWC oder mmH2O werden in bar umgerechnet. Um einen Kanal in einer anderen Einheit zu lesen, wählen Sie in FreeMaint seine Anzeigeeinheit. Die Kanalseite zeigt unter „Empfangene Einheit“ die Einheit des letzten Messwerts. Bei Milli und Mega zählt die Groß- und Kleinschreibung: mW und mWh sind Milli, MW und MWh Mega. BACnet-Einheitennamen werden ebenfalls akzeptiert, unabhängig von der Schreibweise: „PASCALS“, „inches-of-water“, „kilowatt-hours“…

quantity

Die Messgröße, zum Beispiel power, energy, temperature oder vibration_velocity. Damit wählt FreeMaint die passende Einheit und das passende Diagramm.

kind

CUMULATIVE für einen Zähler, der nur steigt (eine Energiesumme, Betriebsstunden). FreeMaint berechnet dann den Verbrauch zwischen zwei Ablesungen. Lassen Sie das Feld bei einem einfachen Messwert weg.

Grenzen

Bis zu 500 Geräte und 5.000 Messpunkte pro Anfrage.
Bis zu 120 Anfragen pro Minute und Verbindung; darüber hinaus antwortet FreeMaint mit 429, und Ihr System sollte es später erneut versuchen.
Eine fehlerhafte Anfrage erhält eine 400-Antwort mit der Ursache, sodass sich ein falsch konfiguriertes Gateway leicht korrigieren lässt.
Jeder neue Kanal zählt zum Limit aktiver Kanäle Ihres Tarifs.

Tipp

Typische Einsatzszenarien: ein Node-RED-Flow, der jede Minute einen Modbus-Energiezähler ausliest und dessen Werte sendet; eine Home-Assistant-Automatisierung, die einen Sensor weiterleitet; ein Teltonika-Router, dessen Funktion Data to Server die Messwerte übermittelt.

Warnung

Halten Sie den Zugangsschlüssel geheim: Wer ihn besitzt, kann Daten an diese Verbindung senden. Falls er offengelegt worden sein könnte, erzeugen Sie einen neuen Schlüssel und wählen Sie „Sofort widerrufen“.