Wysyłanie pomiarów przez API HTTP

Każdy system, który potrafi wysłać żądanie HTTP z treścią JSON, może zasilać FreeMaint Connect: Node-RED, Home Assistant, bramka odczytująca Modbus, sterownik PLC lub Twój własny skrypt. Utwórz połączenie typu „API HTTP (Node-RED, skrypt…)”, aby otrzymać jego adres URL i klucz dostępu.

Żądanie

Metoda: POST, na adres URL wyświetlony przy tworzeniu połączenia (kończy się na /connect/ingest/generic).
Nagłówek Authorization: Bearer, a po nim klucz dostępu.
Nagłówek Content-Type: application/json.
Gdy dane zostaną przyjęte, FreeMaint odpowiada kodem 202; są zapisywane w ciągu kilku sekund.

Treść żądania

Treść wymienia urządzenia w tablicy items. Każde urządzenie ma identyfikator (device), opcjonalną nazwę wyświetlaną, opcjonalny czas (ts, ISO 8601) oraz swoje punkty. Każdy punkt ma key, value oraz – najlepiej – unit i quantity. Ekran tworzenia połączenia pokazuje kompletny przykład do skopiowania.

Pola punktu

key

Nazwa kanału w tym urządzeniu, np. power lub energy_total. Ten sam key zawsze trafia do tego samego kanału.

value

Liczba.

unit

Na przykład W, kWh, °C lub mm/s. Energia w Wh lub MWh jest przeliczana na kWh, temperatury na °C, a prędkość drgań na mm/s. Ciśnienia w Pa, hPa, kPa, mbar, psi, inH2O, inWC lub mmH2O są przeliczane na bar. Aby odczytywać kanał w innej jednostce, wybierz jego pole „Jednostka wyświetlania” w FreeMaint. Strona kanału pokazuje jednostkę ostatniego odczytu w polu „Jednostka odebrana”. Przy mili i mega liczy się wielkość liter: mW i mWh to mili, MW i MWh to mega. Akceptowane są też nazwy jednostek BACnet, niezależnie od wielkości liter: „PASCALS”, „inches-of-water”, „kilowatt-hours”…

quantity

Mierzona wielkość, np. power, energy, temperature lub vibration_velocity. Dzięki niej FreeMaint dobiera właściwą jednostkę i wykres.

kind

CUMULATIVE dla licznika, który tylko rośnie (suma energii, motogodziny). FreeMaint wylicza wtedy zużycie między odczytami. Pomiń to pole w przypadku zwykłej wartości mierzonej.

Limity

Do 500 urządzeń i 5 000 punktów w jednym żądaniu.
Do 120 żądań na minutę na połączenie; powyżej tego progu FreeMaint odpowiada kodem 429, a Twój system powinien ponowić próbę później.
Nieprawidłowo sformułowane żądanie otrzymuje odpowiedź 400 ze wskazaniem problemu, więc źle skonfigurowaną bramkę łatwo poprawić.
Każdy nowy kanał wlicza się do limitu aktywnych kanałów w Twoim planie.

Wskazówka

Typowe konfiguracje: przepływ Node-RED, który co minutę odczytuje licznik energii Modbus i wysyła jego wartości; automatyzacja Home Assistant przekazująca dane z czujnika; router Teltonika, którego funkcja Data to Server wysyła odczyty.

Ostrzeżenie

Chroń klucz dostępu: każdy, kto go zna, może wysyłać dane do tego połączenia. Jeśli mógł wyciec, wygeneruj nowy klucz i wybierz „Unieważnij go teraz”.