При разработке мобильного 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 — получите надёжное мобильное решение с гарантией.