IoT设备属性

• 为实体分配自定义属性及属性管理
• 属性名称
• 属性类型
  • Server-side属性
    • Administration UI
    • REST API
  • 共享属性
    • 设备如何与共享属性交互
    • 通信协议示例
    • Administration UI
    • REST API
    • 设备固件或应用程序的API：
  • 客户端属性
    • 通过REST API获取客户端属性
    • 设备固件或应用程序的API：
• 属性持久化
• 数据查询API
• 数据可视化
• 规则引擎
• 视频教程

为实体分配自定义属性及属性管理

ThingsBoard支持为实体分配并管理自定义属性。属性存储在数据库中，可用于数据可视化和处理。

属性以key-value形式存储。key-value的灵活性和简洁性便于与IoT设备集成。 key始终为字符串，即属性名；value可为string、boolean、double、integer或JSON。 例如：

1
2
3
4
5
6
7
8
9
10
11
{
 "firmwareVersion": "v2.3.1", 
 "booleanParameter": true, 
 "doubleParameter": 42.0, 
 "longParameter": 73, 
 "configuration": {
    "someNumber": 42,
    "someArray": [1, 2, 3],
    "someNestedObject": { "key": "value" }
 }
}

属性名称

作为平台用户，可自定义任意属性名称。 建议使用camelCase，便于编写数据处理与可视化的自定义JS函数。

属性类型

ThingsBoard支持三种属性类型：server-side（服务端属性）、shared（共享属性）和client-side（客户端属性）。 各类别有各自的用途、访问规则和典型场景，下文分别说明。

Server-side属性

该类型几乎适用于所有平台实体：Device、Asset、Customer、Tenant、User等。 Server-side属性可通过管理界面或RESTAPI配置。 设备固件无法访问server-side属性。

以下是建筑物监测解决方案中的几个服务端属性示例：

1. latitude（纬度）、longitude（经度）和address（地址）是分配给代表建筑物或其他房产的资产的好例子。您可以在仪表盘的地图部件上使用这些属性，可视化建筑物的位置。
2. floorPlanImage可能包含平面图的URL。您可以使用此属性在图像地图部件上可视化楼层平面图。
3. maxTemperatureThreshold（最大温度阈值）和temperatureAlarmEnabled（温度告警启用）可用于配置和启用/禁用特定设备或资产的告警。

Administration UI

• Go to Entities → Devices and open the device you want to edit by clicking its row. In the device details, open the "Attributes" tab, select the "Server attributes" scope, and click the "+" icon to add a new attribute.
• In the dialog, enter the attribute key, select the value type (for example, String), and provide a value.
• After saving, the new attribute appears in the list with its key, value, and last update time. Sort using "Last update time" to quickly locate the newly created attribute.

Bulk provisioning feature allows you to quickly create multiple devices and assets and their attributes from CSV file.

REST API

参考REST API文档获取JWT令牌的值。您需要用它来填充’X-Authorization’请求头，对您的REST API调用请求进行身份验证。

发送POST请求，将属性的JSON表示发送到以下URL：

1
https://$YOUR_THINGSBOARD_HOST/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/SERVER_SCOPE

以下示例为ID为’ad17c410-914c-11eb-af0c-d5862211a5f6’的设备和ThingsBoard Cloud服务器创建名称为”newAttributeName”、值为”newAttributeValue”的属性：

1
2
3
4
curl -v 'https://eu.thingsboard.cloud/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/SERVER_SCOPE' \
-H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
-H 'content-type: application/json' \
--data-raw '{"newAttributeName":"newAttributeValue"}'

同样，您可以使用以下命令获取所有服务端属性：

1
2
3
curl -v -X GET 'https://eu.thingsboard.cloud/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/values/attributes/SERVER_SCOPE' \
  -H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
  -H 'content-type: application/json' 

输出将包含’key’（属性名）、’value’（属性值）和最后更新的时间戳：

1
2
3
4
5
6
7
[
    {
        "lastUpdateTs": 1617633139380,
        "key": "newAttributeName",
        "value": "newAttributeValue"
    }
]

作为curl的替代方案，您可以使用Java或PythonREST客户端。

共享属性

共享属性仅对设备类型的实体可用，其他实体类型（如资产或客户）不可用。共享属性用于从服务端向设备发送配置或运行参数，例如阈值。

设备如何与共享属性交互

设备无法发布或更改共享属性的值。从设备的角度来看，这些属性是只读的。设备固件或应用程序可以通过以下方式与共享属性交互：

• 请求当前值：设备可以向服务端发送请求，以检索一个或多个共享属性的当前值。
• 订阅更新：设备可以订阅以接收共享属性值在服务端更改时的通知。
• 通过下行消息接收更新：对于某些网络集成，共享属性更新可以作为下行消息被推送到设备。

通信协议示例

接收更新的方法通常取决于设备使用的通信协议：

• 实时订阅（例如MQTT）：使用双向协议（如MQTT）的设备可以订阅属性更新，并在值更改时实时接收通知。
• 周期轮询（例如HTTP）：使用请求-响应协议（如HTTP）的设备可以定期轮询服务端，以获取其共享属性的最新值。

共享属性最常见的用例是存储设备设置。以建筑物监测解决方案为例，共享属性的几个示例如下：

1. targetFirmwareVersion属性可用于存储特定设备的固件版本。
2. 设备可以监测maxTemperatureThreshold属性，当温度超过设定限制时激活冷却系统。

用户可以通过UI更改属性值。脚本或其他服务端应用程序可以通过REST API更改属性值。

Administration UI

• Go to Entities → Devices and open the device you want to edit by clicking its row. In the device details, open the "Attributes" tab, select the "Shared attributes" scope, and click the "+" icon to add a new attribute.
• In the dialog, enter the attribute key, select the value type (for example, Double), and provide a value.
• After saving, the new attribute appears in the list with its key, value, and last update time.

Bulk provisioning feature allows you to quickly create multiple devices and assets and their attributes from CSV file.

REST API

参考REST API文档获取JWT令牌的值。您需要用它来填充’X-Authorization’请求头，对您的REST API调用请求进行身份验证。

发送POST请求，将属性的JSON表示发送到以下URL：

1
https://$YOUR_THINGSBOARD_HOST/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/SHARED_SCOPE

以下示例为ID为’ad17c410-914c-11eb-af0c-d5862211a5f6’的设备和ThingsBoard Cloud服务器创建名称为”newAttributeName”、值为”newAttributeValue”的属性：

1
2
3
4
curl -v 'https://eu.thingsboard.cloud/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/SHARED_SCOPE' \
-H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
-H 'content-type: application/json' \
--data-raw '{"newAttributeName":"newAttributeValue"}'

同样，您可以使用以下命令获取所有共享属性：

1
2
3
curl -v -X GET 'https://eu.thingsboard.cloud/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/values/attributes/SHARED_SCOPE' \
  -H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
  -H 'content-type: application/json' \

输出将包含’key’（属性名）、’value’（属性值）和最后更新的时间戳：

1
2
3
4
5
6
7
[
    {
        "lastUpdateTs": 1617633139380,
        "key": "newAttributeName",
        "value": "newAttributeValue"
    }
]

作为curl的替代方案，您可以使用Java或PythonREST客户端。

设备固件或应用程序的API：

• 从服务端请求共享属性：MQTTAPI、CoAPAPI、HTTPAPI、LwM2MAPI；
• 订阅来自服务端的共享属性更新：MQTTAPI、CoAPAPI、HTTPAPI、LwM2MAPI。

如果设备离线，可能会错过重要的属性更新通知。
我们建议在应用程序启动时订阅属性更新，并在每次连接或重新连接后请求属性的最新值。

客户端属性

此类属性仅对设备可用，用于设备（客户端）向ThingsBoard（服务端）报告各种半静态数据。 它类似于共享属性，但有一个重要的区别： 设备固件/应用程序可以将属性值从设备发送到平台。

客户端属性最常见的用例是报告设备状态。以建筑物监测解决方案为例，客户端属性的几个示例如下：

1. currentFirmwareVersion属性可用于向平台报告设备已安装的固件/应用程序版本。
2. currentConfiguration属性可用于向平台报告当前固件/应用程序配置。
3. currentState可用于在设备没有持久化存储时通过网络持久化和恢复当前固件/应用程序状态。

用户和服务端应用程序可以通过UI/REST API浏览客户端属性，但无法更改它们。 基本上，客户端属性的值对于UI/REST API是只读的。

通过REST API获取客户端属性

参考REST API文档获取JWT令牌的值。您需要用它来填充’X-Authorization’请求头，对您的REST API调用请求进行身份验证。

发送GET请求到以下URL：

1
https://$YOUR_THINGSBOARD_HOST/api/plugins/telemetry/$ENTITY_TYPE/$ENTITY_ID/CLIENT_SCOPE

以下示例获取ID为’ad17c410-914c-11eb-af0c-d5862211a5f6’的设备和ThingsBoard Cloud服务器的所有属性：

1
2
3
curl -v -X GET 'https://eu.thingsboard.cloud/api/plugins/telemetry/DEVICE/ad17c410-914c-11eb-af0c-d5862211a5f6/values/attributes/CLIENT_SCOPE' \
  -H 'x-authorization: Bearer $YOUR_JWT_TOKEN_HERE' \
  -H 'content-type: application/json' \

输出将包含’key’（属性名）、’value’（属性值）和最后更新的时间戳：

1
2
3
4
5
6
7
[
    {
        "lastUpdateTs": 1617633139380,
        "key": "newAttributeName",
        "value": "newAttributeValue"
    }
]

作为curl的替代方案，您可以使用Java或PythonREST客户端。

设备固件或应用程序的API：

• 向服务端发布客户端属性：MQTT API、CoAP API、HTTP API；
• 从服务端请求客户端属性：MQTT API、CoAP API、HTTP API。

属性持久化

ThingsBoard在SQL数据库中存储属性的最新值和最后修改时间。这使得在仪表盘中能够使用实体过滤器。 用户对属性进行的更改会被记录在审计日志中。

数据查询API

遥测控制器提供以下REST API来获取实体数据：

注意：上述列出的API可通过Swagger UI获取。有关更多详情，请查看REST API文档。 API与ThingsBoard v1.0+向后兼容，这也是API调用URL包含”plugin”的主要原因。

数据可视化

假设您已经配置好设备属性。现在您可以在仪表盘中使用它们。我们建议首先查看仪表盘概览来入门。 一旦您熟悉了如何创建仪表盘和配置数据源， 您可以使用数字和模拟仪表来可视化 温度、速度、压力或其他数值。您也可以使用卡片来可视化多个属性，或使用实体表。

您也可以使用输入部件来允许仪表盘用户更改属性值。

规则引擎

规则引擎负责处理所有传入数据和事件。 下面是在规则引擎中使用属性的最常见场景：

基于属性值的逻辑表达式生成告警

使用告警规则通过UI配置最常见的告警条件， 或使用过滤节点通过自定义JS函数配置更特殊的用例。

在存储到数据库之前修改传入的客户端属性

使用消息类型切换规则节点来过滤包含”Post attributes”请求的消息。 然后使用转换规则节点来修改特定消息。

对服务端属性变更做出响应

使用消息类型切换规则节点来过滤包含”Attributes Updated”通知的消息。 然后使用动作或外部节点对传入事件做出响应。

获取属性值以分析来自设备的传入遥测数据

使用增强规则节点使用设备、相关资产、客户或租户的属性来增强传入的遥测消息。 这是一种非常强大的技术，允许根据存储在属性中的设置修改处理逻辑和参数。

视频教程