ThingsBoard Integration in Mobile IoT Applications
ThingsBoard — open-source IoT platform with ready dashboard, Rule Engine, Device Management, and REST/WebSocket API. Often self-hosted in enterprise IoT projects where data can't go to AWS/Azure clouds. Integrating ThingsBoard into mobile app means working with its REST API v2 and WebSocket telemetry endpoint, bypassing built-in web UI.
ThingsBoard REST API: What to Use
ThingsBoard REST API covers all necessary: get telemetry, device attributes, send RPC commands, manage assets. Base URL: https://your-thingsboard-host/api.
Authorization: POST /api/auth/login with {"username": "...", "password": "..."} → JWT token + refresh token. Token lives 2.5 hours, refresh — 7 days. 401 error on token expiry — silent refresh via interceptor.
On Flutter use dio with 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);
},
));
Main endpoints for mobile:
-
GET /api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries— latest telemetry values -
GET /api/plugins/telemetry/DEVICE/{deviceId}/values/attributes— attributes (config, fixed parameters) -
POST /api/plugins/rpc/twoway/{deviceId}— RPC command awaiting device response -
POST /api/plugins/rpc/oneway/{deviceId}— RPC without waiting
WebSocket for Real-Time Telemetry
Polling telemetry every N seconds — wrong approach. ThingsBoard supports WebSocket API for change subscriptions:
wss://your-host/api/ws/plugins/telemetry?token=JWT_TOKEN
After connection send subscription request:
{
"tsSubCmds": [{
"entityType": "DEVICE",
"entityId": "device-uuid",
"scope": "LATEST_TELEMETRY",
"cmdId": 1
}]
}
Server sends updates on telemetry change. On Flutter manage connection via web_socket_channel. One WebSocket per app — multiplex via cmdId. On disconnection — reconnect with exponential backoff, resubscribe to all active channels.
RPC: Device Control
Two-way RPC is synchronous request to device via ThingsBoard Rule Engine. Device must be online and subscribed to v1/devices/me/rpc/request/+. Default timeout 10 seconds, configurable in request.
final response = await _dio.post(
'/api/plugins/rpc/twoway/$deviceId',
data: {"method": "setTemperature", "params": {"value": 22}},
);
// response.data contains device response
One-way RPC for commands without confirmation: turn on/off, open/close. Two-way — for commands needing result: get readings, check status.
Working with Assets and Hierarchy
ThingsBoard supports Assets — logical device groupings (building → floor → room → device). For smart building app this is natural model.
GET /api/relations?fromId={assetId}&fromType=ASSET&relationType=Contains — get all child objects of Asset. Build tree on client. Important: API doesn't return full tree per request — need recursive loading or denormalized endpoint on your proxy backend.
Typical Problems
ThingsBoard Community Edition doesn't support multi-tenancy well for end users — no Customer-level isolation by default in API. For consumer apps (each user sees only their devices) need create TB Customer per user and assign devices. Doesn't scale without Professional Edition.
WebSocket connection closes on server after ~30 minutes inactivity. App should send ping or periodic subscription updates.
Timeline
REST API integration, WebSocket telemetry, RPC commands — 2–3 weeks. Asset hierarchy, multi-user mode, caching — another 2 weeks. Pricing depends on ThingsBoard edition and device count.