Інтеграція 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— останні значення telemetry -
GET /api/plugins/telemetry/DEVICE/{deviceId}/values/attributes— атрибути (конфігурація, фіксовані параметри) -
POST /api/plugins/rpc/twoway/{deviceId}— RPC-команда з очікуванням відповіді від пристрою -
POST /api/plugins/rpc/oneway/{deviceId}— RPC без очікування відповіді
WebSocket для realtime-телеметрії
Polling telemetry кожні 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
}]
}
Сервер присилає оновлення при кожній зміні telemetry. На Flutter управляємо підключенням через web_socket_channel. Один WebSocket на весь додаток — мультиплексування через cmdId. При втраті з'єднання — переподключення з 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 telemetry, RPC-команди — 2–3 тижні. Іерархія Assets, мультипользовательский режим, кеширование — ще 2 тижні. Стоимость зависит от используемого издания ThingsBoard и числа устройств.