При розробці мобільного IoT-додатку часто виникає задача інтеграції з ThingsBoard — популярною open-source платформою для збору та аналізу телеметрії. Пряме використання її веб-інтерфейсу не підходить для мобільних клієнтів: потрібна кастомна інтеграція через REST API та WebSocket. Ми розповімо, як правильно організувати такий зв'язок, щоб додаток працював стабільно, без втрати даних та з мінімальною затримкою.
ThingsBoard надає REST API v2 для авторизації, роботи з телеметрією, RPC-командами та управлінням пристроями. Однак є підводні камені: timeouts, reconnection logic, ієрархія активів. У цій статті ми детально розберемо типові сценарії та дамо робочі приклади коду на Flutter (Dart). Наш досвід — 5+ років інтеграції ThingsBoard у проектах розумного дому, промислового IoT та Asset Tracking. Ми гарантуємо, що запропоновані рішення перевірені в бою.
Як авторизуватися в ThingsBoard 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 телеметрії кожні 5 секунд — неправильний підхід. 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, повторна підписка на всі активні канали.
WebSocket у 10 разів ефективніший за polling за навантаженням на мережу та батарею. У таблиці нижче — порівняння.
| Параметр | Polling (кожні 5 сек) | WebSocket |
|---|---|---|
| Завантаження мережі | Високе (запит+відповідь) | Низьке (тільки зміни) |
| Затримка | До 5 секунд | <1 секунда |
| Навантаження на сервер | N запитів/сек | 0 при idle |
| Енергоспоживання | Вище (часті пробудження радіо) | Нижче (постійне з'єднання) |
Як керувати пристроями через 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 — для команд, де потрібно знати результат: отримати поточні показники, перевірити статус.
| Характеристика | One-way RPC | Two-way RPC |
|---|---|---|
| Очікування відповіді | Ні | Так (до 10 сек) |
| Використання | Команди без підтвердження | Команди, де потрібен результат |
| Таймаут | Не застосовується | Налаштовуваний |
| Приклад | Ввімкнути світло | Запросити температуру |
Чому ієрархія Assets вимагає рекурсивного завантаження?
ThingsBoard підтримує Assets — логічні групування пристроїв (будівля → поверх → приміщення → пристрій). Для додатку розумної будівлі це природна модель.
GET /api/relations?fromId={assetId}&fromType=ASSET&relationType=Contains — отримуємо всі дочірні об'єкти Asset. Будуємо дерево на клієнті. Важливо: API не повертає дерево за один запит — потрібне рекурсивне завантаження або денормалізований endpoint на вашому бекенді-проксі.
Типові проблеми та їх вирішення
- WebSocket закривається після 30 хвилин бездіяльності — реалізуйте пінг кожні 5 хвилин через відправлення subscription update.
- Multi-tenancy в Community Edition — для споживчих додатків потрібен Customer на кожного користувача. Якщо пристроїв >1000, розгляньте Professional Edition.
- RPC таймаути — завжди вказуйте timeout у запиті, інакше можна заблокувати UI.
Процес інтеграції
- Аналітика та проектування архітектури (3-5 днів).
- Розробка модуля авторизації та REST-клієнта (5-7 днів).
- Реалізація WebSocket-підписки з реконнектом (3-5 днів).
- Інтеграція RPC-команд (2-3 дні).
- Робота з ієрархією Assets (3-5 днів).
- Тестування на стенді та завантаження в магазини (3-5 днів).
Що входить в роботу?
- Документація з архітектури інтеграції та API.
- Вихідний код модуля для Flutter (або React Native) з підтримкою REST + WebSocket.
- Тестовий стенд з демо-пристроями для налагодження.
- Навчання вашої команди (2-годинна сесія).
- Гарантія 3 місяці на працездатність інтеграції.
Наші компетенції: 5+ років досвіду в IoT-розробці, 30+ проектів з ThingsBoard, сертифіковані спеціалісти з Flutter та Kotlin. Цитата з документації ThingsBoard: 'Платформа забезпечує надійний збір телеметрії та віддалене управління пристроями.'
Строки та вартість (індивідуальний розрахунок)
REST API інтеграція, WebSocket телеметрія, RPC-команди — 2–3 тижні. Ієрархія Assets, багатокористувацький режим, кешування — ще 2 тижні. Вартість залежить від використовуваного видання ThingsBoard та кількості пристроїв. Ми оцінимо ваш проект безкоштовно. Зв'яжіться з нами для консультації. Замовте інтеграцію ThingsBoard — отримайте надійне мобільне рішення з гарантією.