Enviar medições com a API HTTP

Qualquer sistema capaz de enviar um pedido HTTP com um corpo JSON pode alimentar o FreeMaint Connect: Node-RED, Home Assistant, um gateway que lê Modbus, um autómato ou um script seu. Crie uma ligação do tipo API HTTP (Node-RED, script…) para obter o respetivo URL e a chave de acesso.

O pedido

Método: POST, para o URL apresentado quando cria a ligação (termina em /connect/ingest/generic).
Cabeçalho Authorization: Bearer seguido da chave de acesso.
Cabeçalho Content-Type: application/json.
O FreeMaint responde 202 quando os dados são aceites; ficam guardados em poucos segundos.

O corpo

O corpo lista os dispositivos em items. Cada dispositivo tem um identificador (device), um nome de apresentação opcional, uma data e hora opcional (ts, ISO 8601) e os seus pontos. Cada ponto tem uma key, um value e, idealmente, uma unit e uma quantity. O ecrã de criação mostra um exemplo completo que pode copiar.

Campos de um ponto

key

O nome do canal neste dispositivo, por exemplo power ou energy_total. A mesma key vai sempre parar ao mesmo canal.

value

Um número.

unit

Por exemplo W, kWh, °C ou mm/s. A energia em Wh ou MWh é convertida em kWh, as temperaturas em °C e a velocidade de vibração em mm/s. As pressões em Pa, hPa, kPa, mbar, psi, inH2O, inWC ou mmH2O são convertidas em bar. Para ler um canal noutra unidade, escolha a sua Unidade de apresentação no FreeMaint. A página do canal mostra a unidade da última leitura em «Unidade recebida». Maiúsculas e minúsculas contam para mili e mega: mW e mWh são mili, MW e MWh são mega. Os nomes de unidades BACnet também são aceites, em maiúsculas ou minúsculas: «PASCALS», «inches-of-water», «kilowatt-hours»…

quantity

A grandeza medida, por exemplo power, energy, temperature ou vibration_velocity. Permite ao FreeMaint escolher a unidade e o gráfico adequados.

kind

CUMULATIVE para um contador que só aumenta (um total de energia, horas de funcionamento). O FreeMaint calcula então o consumo entre leituras. Omita-o para um simples valor medido.

Limites

Até 500 dispositivos e 5 000 pontos por pedido.
Até 120 pedidos por minuto e por ligação; acima disso, o FreeMaint responde 429 e o seu sistema deve tentar novamente mais tarde.
Um pedido mal formado recebe uma resposta 400 que indica o problema, para que um gateway mal configurado seja fácil de corrigir.
Cada novo canal conta para o limite de canais ativos do seu plano.

Dica

Configurações típicas: um fluxo Node-RED que lê um contador de energia Modbus a cada minuto e publica os valores; uma automação do Home Assistant que reencaminha um sensor; um router Teltonika cuja função Data to Server envia as leituras.

Aviso

Mantenha a chave de acesso em segredo: quem a tiver pode enviar dados para esta ligação. Se ela puder ter sido divulgada, gere uma nova chave e escolha Revogar já.