Интеграция ThingsBoard в мобильное IoT-приложение
ThingsBoard — open-source IoT-платформа с готовым дашбордом, Rule Engine, Device Management и REST/WebSocket API. Её часто разворачивают self-hosted в корпоративных IoT-проектах, где данные нельзя отдавать в облака AWS/Azure. Интегрировать ThingsBoard в мобильное приложение — значит работать с его REST API v2 и WebSocket telemetry endpoint, минуя встроенный веб-UI.
REST API ThingsBoard: что использовать
ThingsBoard REST API покрывает всё необходимое: получение telemetry, атрибутов устройства, отправка RPC-команд, управление активами. Базовый URL: https://your-thingsboard-host/api.
Авторизация: POST /api/auth/login с {"username": "...", "password": "..."} → JWT token + refresh token. Токен живёт 2,5 часа, refresh — 7 дней. Ошибка 401 по истечении токена — делаем silent refresh через interceptor.
На Flutter используем dio с interceptor:
_dio.interceptors.add(InterceptorsWrapper(
onError: (err, handler) async {
if (err.response?.statusCode == 401) {
final newToken = await _refreshToken();
err.requestOptions.headers['X-Authorization'] = 'Bearer $newToken';
return handler.resolve(await _dio.fetch(err.requestOptions));
}
return handler.next(err);
},
));
Основные endpoints для мобильного приложения:
-
GET /api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries— последние значения телеметрии -
GET /api/plugins/telemetry/DEVICE/{deviceId}/values/attributes— атрибуты (конфигурация, фиксированные параметры) -
POST /api/plugins/rpc/twoway/{deviceId}— RPC-команда с ожиданием ответа от устройства -
POST /api/plugins/rpc/oneway/{deviceId}— RPC без ожидания ответа
WebSocket для реалтайм-телеметрии
Polling телеметрии каждые N секунд — неправильный подход. ThingsBoard поддерживает WebSocket API для подписки на изменения:
wss://your-host/api/ws/plugins/telemetry?token=JWT_TOKEN
После подключения отправляем subscription request:
{
"tsSubCmds": [{
"entityType": "DEVICE",
"entityId": "device-uuid",
"scope": "LATEST_TELEMETRY",
"cmdId": 1
}]
}
Сервер присылает обновления при каждом изменении телеметрии. На Flutter управляем подключением через web_socket_channel. Один WebSocket на всё приложение — мультиплексирование через cmdId. При потере соединения — reconnect с exponential backoff, повторная подписка на все активные каналы.
RPC: управление устройствами
Two-way RPC — это синхронный запрос к устройству через ThingsBoard Rule Engine. Устройство должно быть онлайн и подписано на v1/devices/me/rpc/request/+. Таймаут по умолчанию 10 секунд, настраивается в запросе.
final response = await _dio.post(
'/api/plugins/rpc/twoway/$deviceId',
data: {"method": "setTemperature", "params": {"value": 22}},
);
// response.data содержит ответ от устройства
One-way RPC используем для команд без подтверждения: включить/выключить, открыть/закрыть. Two-way — для команд, где нужно знать результат: получить текущие показания, проверить статус.
Работа с Assets и иерархией
ThingsBoard поддерживает Assets — логические группировки устройств (здание → этаж → помещение → устройство). Для приложения умного здания это естественная модель.
GET /api/relations?fromId={assetId}&fromType=ASSET&relationType=Contains — получаем все дочерние объекты Asset. Строим дерево на клиенте. Важно: API не возвращает дерево за один запрос — нужна рекурсивная загрузка или денормализованный endpoint на вашем бэкенде-прокси.
Типичные проблемы
ThingsBoard Community Edition не поддерживает multi-tenancy нормально для конечных пользователей — нет изоляции на уровне Customer по умолчанию в API. Для потребительских приложений (каждый пользователь видит только свои устройства) нужно создавать TB Customer на каждого пользователя и назначать устройства. Это не масштабируется без Professional Edition.
WebSocket соединение закрывается сервером при неактивности после ~30 минут. Приложение должно слать ping или периодические subscription updates.
Сроки
REST API интеграция, WebSocket телеметрия, RPC-команды — 2–3 недели. Иерархия Assets, мультипользовательский режим, кэширование — ещё 2 недели. Стоимость зависит от используемого издания ThingsBoard и числа устройств.