Overview
Dart ThingsBoard PE API Client package is a Dart library providing model objects and services to communicate with ThingsBoard PE platform using RESTful APIs and WebSocket protocol. With Dart Client you can programmatically access ThingsBoard PE API to manage entities, query telemetry data and get real-time updates via WebSocket API. The Dart ThingsBoard PE API Client is also a part of ThingsBoard PE Mobile Application.
The version of the Dart ThingsBoard PE API Client depends on the version of the platform that you are using.
Installing Dart ThingsBoard API Client (Professional Edition)
To use Dart ThingsBoard PE API Client package in your Dart/Flutter project run this command:
With Dart:
1
dart pub add thingsboard_pe_client
With Flutter:
1
flutter pub add thingsboard_pe_client
This will add a line like this to your package’s pubspec.yaml (and run an implicit dart pub get):
1
2
dependencies:
thingsboard_pe_client: ^1.3.0
Alternatively, your editor might support dart pub get or flutter pub get. Check the docs for your editor to learn more.
Now in your Dart code, you can use:
1
import 'package:thingsboard_pe_client/thingsboard_client.dart';
Basic Usage
The next sample code shows how to instantiate ThingsBoard Client, perform login and get user details of current logged in user.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import 'package:thingsboard_pe_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
print('isAuthenticated=${tbClient.isAuthenticated()}');
print('authUser: ${tbClient.getAuthUser()}');
// Get user details of current logged in user
var currentUserDetails = await tbClient.getUserService().getUser();
print('currentUserDetails: $currentUserDetails');
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
Examples
Get user permissions
The following sample code shows how to get allowed permissions of current logged in user and then check sample permission.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import 'package:thingsboard_pe_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
// Get allowed user permissions
var allowedUserPermissions =
await tbClient.getUserPermissionsService().getAllowedPermissions();
print('Allowed user permissions: ${allowedUserPermissions.userPermissions}');
// Get if user has generic read permission on device entities
print(
'Has generic devices read permission: ${allowedUserPermissions.hasGenericPermission(Resource.DEVICE, Operation.READ)}');
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
Fetch user devices
The following sample code shows how to fetch user devices via page link.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import 'package:thingsboard_pe_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
var pageLink = PageLink(10);
PageData<Device> devices;
do {
// Fetch user devices using current page link
devices = await tbClient.getDeviceService().getUserDevices(pageLink);
print('devices: $devices');
pageLink = pageLink.nextPageLink();
} while (devices.hasNext);
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
Fetch user dashboards
The following sample code shows how to fetch user dashboards via page link.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
import 'package:thingsboard_pe_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
var pageLink = PageLink(10);
PageData<DashboardInfo> dashboards;
do {
// Fetch user dashboards using current page link
dashboards = await tbClient.getDashboardService().getUserDashboards(pageLink);
print('dashboards: $dashboards');
pageLink = pageLink.nextPageLink();
} while (devices.hasNext);
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
Fetch entity groups
The following sample code shows how to fetch entity groups.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
import 'package:thingsboard_pe_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
// Iterate over all available entity group types
for (var groupType in [
EntityType.DEVICE,
EntityType.ASSET,
EntityType.ENTITY_VIEW,
EntityType.DASHBOARD,
EntityType.CUSTOMER,
EntityType.USER,
EntityType.EDGE
]) {
// Fetch all entity groups of specified type
var entityGroups =
await tbClient.getEntityGroupService().getEntityGroupsByType(groupType);
print('found ${groupType.toShortString()} groups: $entityGroups');
}
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
Count entities using Entity Data Query API
The following sample code shows how to use Entity Data Query API to count total devices, total active devices and total inactive devices.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
import 'package:thingsboard_pe_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
// Create entity filter to get all devices
var entityFilter = EntityTypeFilter(entityType: EntityType.DEVICE);
// Create entity count query with provided filter
var devicesQuery = EntityCountQuery(entityFilter: entityFilter);
// Execute entity count query and get total devices count
var totalDevicesCount =
await tbClient.getEntityQueryService().countEntitiesByQuery(devicesQuery);
print('Total devices: $totalDevicesCount');
// Set key filter to existing query to get only active devices
var activeDeviceKeyFilter = KeyFilter(
key: EntityKey(type: EntityKeyType.ATTRIBUTE, key: 'active'),
valueType: EntityKeyValueType.BOOLEAN,
predicate: BooleanFilterPredicate(
operation: BooleanOperation.EQUAL,
value: FilterPredicateValue(true)));
devicesQuery.keyFilters = [activeDeviceKeyFilter];
// Execute entity count query and get total active devices count
var activeDevicesCount =
await tbClient.getEntityQueryService().countEntitiesByQuery(devicesQuery);
print('Active devices: $activeDevicesCount');
// Set key filter to existing query to get only inactive devices
var inactiveDeviceKeyFilter = KeyFilter(
key: EntityKey(type: EntityKeyType.ATTRIBUTE, key: 'active'),
valueType: EntityKeyValueType.BOOLEAN,
predicate: BooleanFilterPredicate(
operation: BooleanOperation.EQUAL,
value: FilterPredicateValue(false)));
devicesQuery.keyFilters = [inactiveDeviceKeyFilter];
// Execute entity count query and get total inactive devices count
var inactiveDevicesCount =
await tbClient.getEntityQueryService().countEntitiesByQuery(devicesQuery);
print('Inactive devices: $inactiveDevicesCount');
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
Query entities using Entity Data Query API
The following sample code shows how to use Entity Data Query API to get all active devices.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
import 'package:thingsboard_pe_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
// Create entity filter to get only devices
var entityFilter = EntityTypeFilter(entityType: EntityType.DEVICE);
// Create key filter to query only active devices
var activeDeviceKeyFilter = KeyFilter(
key: EntityKey(type: EntityKeyType.ATTRIBUTE, key: 'active'),
valueType: EntityKeyValueType.BOOLEAN,
predicate: BooleanFilterPredicate(
operation: BooleanOperation.EQUAL,
value: FilterPredicateValue(true)));
// Prepare list of queried device fields
var deviceFields = <EntityKey>[
EntityKey(type: EntityKeyType.ENTITY_FIELD, key: 'name'),
EntityKey(type: EntityKeyType.ENTITY_FIELD, key: 'type'),
EntityKey(type: EntityKeyType.ENTITY_FIELD, key: 'createdTime')
];
// Prepare list of queried device attributes
var deviceAttributes = <EntityKey>[
EntityKey(type: EntityKeyType.ATTRIBUTE, key: 'active')
];
// Create entity query with provided entity filter, key filter, queried fields and page link
var devicesQuery = EntityDataQuery(
entityFilter: entityFilter,
keyFilters: [inactiveDeviceKeyFilter],
entityFields: deviceFields,
latestValues: deviceAttributes,
pageLink: EntityDataPageLink(
pageSize: 10,
sortOrder: EntityDataSortOrder(
key: EntityKey(
type: EntityKeyType.ENTITY_FIELD, key: 'createdTime'),
direction: EntityDataSortOrderDirection.DESC)));
PageData<EntityData> devices;
do {
// Fetch active devices using entities query with current page link
devices = await tbClient
.getEntityQueryService()
.findEntityDataByQuery(devicesQuery);
print('Active devices entities data:');
devices.data.forEach((device) {
print(
'id: ${device.entityId.id}, createdTime: ${device.createdTime}, name: ${device.field('name')!}, type: ${device.field('type')!}, active: ${device.attribute('active')}');
});
devicesQuery = devicesQuery.next();
} while (devices.hasNext);
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
Manage Device example
The following sample code demonstrates basic concepts of device management API (add/get/delete device, get/save device attributes).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
import 'package:thingsboard_pe_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
var deviceName = 'My test device';
// Construct device object
var device = Device(deviceName, 'default');
device.additionalInfo = {'description': 'My test device!'};
// Add device
var savedDevice = await tbClient.getDeviceService().saveDevice(device);
print('savedDevice: $savedDevice');
// Find device by device id
var foundDevice =
await tbClient.getDeviceService().getDeviceInfo(savedDevice.id!.id!);
print('foundDevice: $foundDevice');
// Save device shared attributes
var res = await tbClient.getAttributeService().saveEntityAttributesV2(
foundDevice!.id!,
AttributeScope.SHARED_SCOPE.toShortString(),
{'targetTemperature': 22.4, 'targetHumidity': 57.8});
print('Save attributes result: $res');
// Get device shared attributes
var attributes = await tbClient.getAttributeService().getAttributesByScope(
foundDevice.id!,
AttributeScope.SHARED_SCOPE.toShortString(),
['targetTemperature', 'targetHumidity']);
print('Found device attributes: $attributes');
// Delete the device
await tbClient.getDeviceService().deleteDevice(savedDevice.id!.id!);
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
WebSocket API example
The following sample code demonstrates basic concepts of WebSocket API. In this code we are going to create new device, create subscription to get device data and telemetry updates using Entity Data Query API over WebSocket API. Finally post sample telemetry and get data updates by listening data stream of subscription.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
import 'dart:math';
import 'package:thingsboard_pe_client/thingsboard_client.dart';
// ThingsBoard REST API URL
const thingsBoardApiEndpoint = 'http://localhost:8080';
void main() async {
try {
// Create instance of ThingsBoard API Client
var tbClient = ThingsboardClient(thingsBoardApiEndpoint);
// Perform login with default Tenant Administrator credentials
await tbClient.login(LoginRequest('tenant@thingsboard.org', 'tenant'));
var deviceName = 'My test device';
// Construct device object
var device = Device(deviceName, 'default');
device.additionalInfo = {'description': 'My test device!'};
// Add device
var savedDevice = await tbClient.getDeviceService().saveDevice(device);
print('savedDevice: $savedDevice');
// Create entity filter to get device by its name
var entityFilter = EntityNameFilter(
entityType: EntityType.DEVICE, entityNameFilter: deviceName);
// Prepare list of queried device fields
var deviceFields = <EntityKey>[
EntityKey(type: EntityKeyType.ENTITY_FIELD, key: 'name'),
EntityKey(type: EntityKeyType.ENTITY_FIELD, key: 'type'),
EntityKey(type: EntityKeyType.ENTITY_FIELD, key: 'createdTime')
];
// Prepare list of queried device time series
var deviceTelemetry = <EntityKey>[
EntityKey(type: EntityKeyType.TIME_SERIES, key: 'temperature'),
EntityKey(type: EntityKeyType.TIME_SERIES, key: 'humidity')
];
// Create entity query with provided entity filter, queried fields and page link
var devicesQuery = EntityDataQuery(
entityFilter: entityFilter,
entityFields: deviceFields,
latestValues: deviceTelemetry,
pageLink: EntityDataPageLink(
pageSize: 10,
sortOrder: EntityDataSortOrder(
key: EntityKey(
type: EntityKeyType.ENTITY_FIELD, key: 'createdTime'),
direction: EntityDataSortOrderDirection.DESC)));
// Create time series subscription command to get data for 'temperature' and 'humidity' keys for last hour with realtime updates
var currentTime = DateTime.now().millisecondsSinceEpoch;
var timeWindow = Duration(hours: 1).inMilliseconds;
var tsCmd = TimeSeriesCmd(
keys: ['temperature', 'humidity'],
startTs: currentTime - timeWindow,
timeWindow: timeWindow);
// Create subscription command with entities query and time series subscription
var cmd = EntityDataCmd(query: devicesQuery, tsCmd: tsCmd);
// Create subscription with provided subscription command
var telemetryService = tbClient.getTelemetryService();
var subscription = TelemetrySubscriber(telemetryService, [cmd]);
// Create listener to get data updates from WebSocket
subscription.entityDataStream.listen((entityDataUpdate) {
print('Received entity data update: $entityDataUpdate');
});
// Perform subscribe (send subscription command via WebSocket API and listen for responses)
subscription.subscribe();
// Post sample telemetry
var rng = Random();
for (var i = 0; i < 5; i++) {
await Future.delayed(Duration(seconds: 1));
var temperature = 10 + 20 * rng.nextDouble();
var humidity = 30 + 40 * rng.nextDouble();
var telemetryRequest = {'temperature': temperature, 'humidity': humidity};
print('Save telemetry request: $telemetryRequest');
var res = await tbClient
.getAttributeService()
.saveEntityTelemetry(savedDevice.id!, 'TELEMETRY', telemetryRequest);
print('Save telemetry result: $res');
}
// Wait few seconds to show data updates are received by subscription listener
await Future.delayed(Duration(seconds: 2));
// Finally unsubscribe to release subscription
subscription.unsubscribe();
// Delete the device
await tbClient.getDeviceService().deleteDevice(savedDevice.id!.id!);
// Finally perform logout to clear credentials
await tbClient.logout();
} catch (e, s) {
print('Error: $e');
print('Stack: $s');
}
}
More examples
You can find more examples to learn how to use Dart ThingsBoard PE API Client here.