Передача измерений через HTTP API

Передавать данные в FreeMaint Connect может любая система, способная отправить HTTP-запрос с телом в формате JSON: Node-RED, Home Assistant, шлюз, считывающий Modbus, ПЛК или ваш собственный скрипт. Создайте подключение типа «HTTP API (Node-RED, скрипт…)», чтобы получить его URL-адрес и ключ доступа.

Запрос

Метод: POST, на URL-адрес, показанный при создании подключения (он заканчивается на /connect/ingest/generic).
Заголовок Authorization: Bearer, за которым следует ключ доступа.
Заголовок Content-Type: application/json.
Если данные приняты, FreeMaint отвечает кодом 202; они сохраняются в течение нескольких секунд.

Тело запроса

В теле запроса устройства перечисляются в items. У каждого устройства есть идентификатор (device), необязательное отображаемое название, необязательное время (ts, в формате ISO 8601) и его точки. У каждой точки есть key, value и желательно unit и quantity. На экране создания подключения приведён полный пример, который можно скопировать.

Поля точки

key

Название канала на этом устройстве, например power или energy_total. Один и тот же ключ всегда попадает в один и тот же канал.

value

Число.

unit

Например, W, kWh, °C или mm/s. Энергия в Wh или MWh пересчитывается в kWh, температура — в °C, виброскорость — в mm/s. Давление в Pa, hPa, kPa, mbar, psi, inH2O, inWC или mmH2O пересчитывается в bar. Чтобы видеть канал в другой единице, выберите «Единица отображения» в FreeMaint. На странице канала в поле «Полученная единица» показана единица последнего показания. Для милли и мега важен регистр: mW и mWh — милли, MW и MWh — мега. Принимаются и названия единиц BACnet в любом регистре: «PASCALS», «inches-of-water», «kilowatt-hours»…

quantity

Измеряемая величина, например power, energy, temperature или vibration_velocity. По ней FreeMaint выбирает подходящую единицу и вид графика.

kind

CUMULATIVE — для счётчика, значение которого только растёт (суммарная энергия, моточасы). Тогда FreeMaint вычисляет расход между показаниями. Для обычного измеряемого значения это поле не указывайте.

Лимиты

До 500 устройств и 5 000 точек в одном запросе.
До 120 запросов в минуту на одно подключение; сверх этого FreeMaint отвечает кодом 429, и ваша система должна повторить попытку позже.
На некорректный запрос возвращается ответ 400 с описанием проблемы, поэтому неправильно настроенный шлюз легко исправить.
Каждый новый канал учитывается в лимите активных каналов вашего тарифа.

Совет

Типичные варианты: поток Node-RED, который каждую минуту считывает счётчик электроэнергии по Modbus и отправляет его показания; автоматизация Home Assistant, пересылающая данные датчика; маршрутизатор Teltonika, который отправляет показания с помощью функции Data to Server.

Внимание

Храните ключ доступа в секрете: любой, у кого он есть, может отправлять данные в это подключение. Если ключ мог утечь, создайте новый и выберите «Отозвать сейчас».