Enviar mediciones con la API HTTP

Cualquier sistema capaz de enviar una petición HTTP con un cuerpo JSON puede alimentar FreeMaint Connect: Node-RED, Home Assistant, un gateway que lea Modbus, un PLC o un script propio. Cree una conexión del tipo API HTTP (Node-RED, script…) para obtener su URL y su clave de acceso.

La petición

Método: POST, a la URL que se muestra al crear la conexión (termina en /connect/ingest/generic).
Cabecera Authorization: Bearer seguida de la clave de acceso.
Cabecera Content-Type: application/json.
FreeMaint responde 202 cuando acepta los datos; se guardan en pocos segundos.

El cuerpo

El cuerpo enumera los dispositivos en items. Cada dispositivo tiene un identificador (device), un nombre visible opcional, una marca de tiempo opcional (ts, ISO 8601) y sus puntos. Cada punto tiene una clave (key), un valor (value) y, idealmente, una unidad (unit) y una magnitud (quantity). La pantalla de creación muestra un ejemplo completo que puede copiar.

Campos de un punto

key

El nombre del canal en este dispositivo, por ejemplo power o energy_total. La misma clave llega siempre al mismo canal.

value

Un número.

unit

Por ejemplo W, kWh, °C o mm/s. La energía en Wh o MWh se convierte a kWh, las temperaturas a °C y la velocidad de vibración a mm/s. Las presiones en Pa, hPa, kPa, mbar, psi, inH2O, inWC o mmH2O se convierten a bar. Para leer un canal en otra unidad, elija su Unidad de visualización en FreeMaint. La página del canal muestra la unidad de la última lectura en «Unidad recibida». Las mayúsculas importan para mili y mega: mW y mWh son mili, MW y MWh son mega. También se aceptan los nombres de unidades BACnet, en mayúsculas o minúsculas: «PASCALS», «inches-of-water», «kilowatt-hours»…

quantity

La magnitud medida, por ejemplo power, energy, temperature o vibration_velocity. Permite a FreeMaint elegir la unidad y el gráfico adecuados.

kind

CUMULATIVE para un contador que solo aumenta (un total de energía, horas de funcionamiento). FreeMaint calcula entonces el consumo entre lecturas. Omítalo para un valor medido simple.

Límites

Hasta 500 dispositivos y 5.000 puntos por petición.
Hasta 120 peticiones por minuto y por conexión; por encima, FreeMaint responde 429 y su sistema debe reintentar más tarde.
Una petición mal formada recibe una respuesta 400 que indica el problema, por lo que un gateway mal configurado es fácil de corregir.
Cada canal nuevo cuenta para el límite de canales activos de su plan.

Consejo

Configuraciones habituales: un flujo de Node-RED que lee un medidor de energía Modbus cada minuto y publica sus valores; una automatización de Home Assistant que reenvía un sensor; un router Teltonika cuya función Data to Server publica las lecturas.

Advertencia

Mantenga en secreto la clave de acceso: cualquiera que la tenga puede enviar datos a esta conexión. Si ha podido filtrarse, genere una clave nueva y elija Revocarla ahora.