描述
租户可以通过脚本或界面对设备进行预定义假如客户购买设备之后扫描二维码并激活设备并得到物理的访问权限，一旦设备被激活之后客户就成设备的所有者并可以获取数据和控制设备。
场景
ThingsBoard提供了Secret和expirationTime用于设备声明假如用户知道设备名称和密钥则可以对比设备声明操作。
提供两种方式提供密钥：
- 设备端 - 设备发送带有声明数据的请求并包含带有过期时间戳的expireTime的服务器属性并且客户能够使用声明部件进行操作。
- 服务端 - 设备发送带有声明数据的请求并包含带有claimingData的服务端属性使用声明设备部件进行操作。
请参阅下面的更多细节：
|
设备需要根据某些触发事件生成密钥一旦设备启动或按下某个物理按钮会生成Secret并且具有一定有效期，同时需要设备向服务器发送包含Secret和duration声明信息。  默认情况将到期日期设置为进行加1天作为最大值如要设置更长的时间修改thingsboard.yaml文件中的 caffeine.specs.claimDevices.timeToLiveInMinutes参数值。 声明时序图
设备支持平台所有的传输协议发送声明信息但是消息体必须包含两个参数分别是secretKey和durationMs声明信息可以是任务字符，如果未指定secretKey则采用默认值，如果未指定durationMs参数则使用系统参数device.claim.duration，管理员可以在/etc/thingsboard/conf/thingsboard.yml进行配置。 通过系统参数security.claim.allowClaimingByDefaul（请参阅配置指南）设置为true表示启用设备声明功能，对于已经配置的设备值为true的服务端属性claimingAllowed强制生效。 参见设备API了解更多关于设备声明信息的消息结构和主题同时也可以使用网关的MQTT API对声明多个设备。 设备声明发送后可以用二维码或者文本显示密钥方便用户发送声明信息设备名称必须是全局唯一，请在此处查看如何发送声明请求的说明。 注意： 密钥可以是一个空字符串这样可以让用户在设备上的声明按钮长按30秒内确定设备声明响应成功的操作状态和设备ID。 配置声明信息后客户可以使用声明设备部件进行操作。 |
权限
在PE版中指定的必须具有声明权限才可以进行设备声明操作：
- 资源: Device
- 操作符: Claim devices
为用户组添加自定义声明权限。
- Create a generic role.
- Assign that role for a user group.
部件
- You are able to find Device Claiming Widget in Static widget section of Input widgets bundle.
- Claim device widget is quite simple and allows to input device name and Secret Key.
- It is possible to "hide" Secret Key input field and change the labels in "General settings".
- It is also possible to configure all sorts of messages to the user in "Message settings".
- Finally, you can relate the claimed device to the current state entity of the dashboard.
This is useful if you have multiple assets and would like to relate your device to one of them.
声明
声明请求作为POST请求发送到以下URL：
1
http(s)://host:port/api/customer/device/$DEVICE_NAME/claim
支持的数据格式为：
1
2
3
{
"secretKey":"value"
}
注意：消息不包含可选的durationMs和secretKey参数。
如果声明成功后设备将会分配特定的客户如果系统参数allowClaimingByDefault为false则claimingAllowed属性会自动删除。
回收设备是将不再分配给客户如果allowClaimingByDefault为false则claimingAllowed属性将再次出现。
有关上述步骤的更多详细信息请参阅以下内容。
回收
回收设备可以向以下URL发送DELETE请求（不要忘记用正确的名称替换设备名称）：
1
curl -X DELETE https://thingsboard.cloud/api/customer/device/$DEVICE_NAME/claim
响应如下：
1
2
3
4
{
"result": {},
"setOrExpired": true
}
Python实例
你可以获得用于声明设备功能的代码示例。
我们将使用tb-mqtt-client python模块来连接和声明设备。
安装命令:
1
pip3 install tb-mqtt-client --user
基础实例
假设我们有一个租户级别的设备和配置的客户想要连接设备并发送声明请求将其分配给客户。
描述
我们在ThingsBord中有一个名称为Test claiming device的设备。
设备具有访问令牌凭据 - Eypdinl1gUF5fSerOPJF。
我们应该下载脚本并运行它来向服务器发送声明请求。
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
#
# Copyright © 2016-2020 The Thingsboard Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
from tb_device_mqtt import TBDeviceMqttClient
def collect_required_data():
config = {}
print("\n\n", "="*80, sep="")
print(" "*20, "ThingsBoard basic device claiming example script.", sep="")
print("="*80, "\n\n", sep="")
host = input("Please write your ThingsBoard host or leave it blank to use default (thingsboard.cloud): ")
config["host"] = host if host else "mqtt.thingsboard.cloud"
token = ""
while not token:
token = input("Please write accessToken for device: ")
if not token:
print("Access token is required!")
config["token"] = token
config["secret_key"] = input("Please write secret key for claiming request: ")
if not config["secret_key"]:
print("Please make sure that you have claimData in server attributes for device to use this feature without device secret in the claiming request.")
duration_ms = input("Please write duration in milliseconds for claiming request or leave it blank to use default (30000): ")
config["duration_ms"] = int(duration_ms) if duration_ms else 30000
print("\n", "="*80, "\n", sep="")
return config
if __name__ == '__main__':
config = collect_required_data()
client = TBDeviceMqttClient(host=config["host"], token=config["token"])
client.connect()
client.claim(secret_key=config["secret_key"], duration=config["duration_ms"]).get()
print("Claiming request was sent, now you should use claiming device widget to finish the claiming process.")
然后可以使用设备声明部件。
下一步
-
入门指南 - 快速学习ThingsBoard相关功能。
-
安装指南 - 学习如何在各种操作系统上安装ThingsBoard。
-
连接设备 - 学习如何根据你的连接方式或解决方案连接设备。
-
可 视 化 - 学习如何配置复杂的ThingsBoard仪表板说明。
-
数据处理 - 学习如何使用ThingsBoard规则引擎。
-
数据分析 - 学习如何使用规则引擎执行基本的分析任务。
-
硬件样品 - 学习如何将各种硬件平台连接到ThingsBoard。
-
开发指南 - 学习ThingsBoard中的贡献和开发。
