用例描述

作为租户，我想通过脚本或UI预配置我的设备。我的客户直接从我这里或通过分销商购买设备。我希望客户一旦获得对设备的物理访问权，便可以根据QR码或类似技术声明其设备。
索取设备后，客户将成为其所有者，客户用户可以访问设备数据并控制设备。

设备声明方案

ThingsBoard用户可以在“知道”设备名称和密钥的情况下声明该设备的所有权。密钥是可选的，始终具有到期时间，并且也可能随时间变化。
可以通过两种不同的方式来配置密钥：

  1. 设备端密钥方案-设备包含带有到期时间戳记的expirationTime服务器属性。仅在该客户能够使用设备声明小部件声明设备之后，设备才会将声明请求和声明数据发送到ThingsBoard。
  2. 服务器端关键方案-设备包含带有索赔数据的ClaimingData服务器属性，以及使用索赔设备小部件的客户索赔设备。

请参阅下面的更多细节。
声明使用设备端关键场景

声明使用服务器端关键场景

此过程要求设备根据某个触发事件生成密钥。例如，一旦启动设备或按下某个物理按钮。密钥生成后，在一定时间内有效。设备将包含密钥和密钥有效期的索赔信息发送到服务器。
默认情况下，您可以将到期日期设置为收到请求的日期和时间，再加上1天作为最大值。要增加时间，您应该增加Thingsboard.yaml文件中参数caffeine.specs.claimDevices.timeToLiveInMinutes的值。
ThingsBoard服务器在密钥有效期内存储Claiming Information。参见下图。
声明设备 - 图1
设备可以使用所有受支持的传输协议将“声明信息”发送给TB。消息正文具有两个参数：secretKey和durationMs，可以选择指定这些参数。该秘密密钥参数增加了安全的声明过程。所述DURATION毫秒参数确定声称时间期满。如果未指定secretKey，则使用空字符串作为默认值。万一DURATION毫秒未指定时，系统参数device.claim.duration被使用（在文件/etc/thingsboard/conf/thingsboard.yml）。
为了使声明设备具有系统参数security.claim.allowClaimingByDefault（请参阅配置指南），应将其设置为true，否则对于已设置的设备，必须设置值为true的服务器端ClaimingAllowed属性。
请参阅设备API参考以获得有关消息结构以及将声明消息发送到的主题/ URL的信息。您也可以使用MQTT Gateway API，该API也允许每次启动多个设备的声明。

发送声明信息后，设备可以以纯文本形式或使用QR码显示密钥。用户应扫描此密钥并使用它发送索赔请求。声明请求由设备名称和密钥组成。您可以使用MAC地址或其他唯一属性作为设备名称。在此处查看如何发送声明请求的说明。
注意：密钥也可以是一个空字符串。如果您的设备没有任何显示密钥的方法，则此功能很有用。例如，您可以允许在设备上的“声明”按钮被按下后的30秒内对设备进行声明。在这种情况下，用户只需要知道设备名称（MAC地址等）。
服务器验证索偿请求并使用索偿响应进行回复。声明响应包含声明操作的状态和设备ID（如果操作成功）。
供应索赔信息后，客户用户可以使用“索赔设备”窗口小部件。

假设您使用ThingsBoard集成之一连接了数千台NB IoT / LoRaWAN / Sigfox设备。集成层将在ThingsBoard中自动配置它们。假设Tenant Admin知道DevEUI（LoRaWAN）或任何其他设备标识符的列表，则可以为每个设备生成随机密钥，然后使用REST API或UI将该密钥作为服务器端属性上传到ThingsBoard 。完成此操作后，租户管理员可以通过电子邮件将这些密钥发送给客户，或将其放入设备包装盒中。
声明设备 - 图2
为了供应设备密钥，租户管理员应将服务器端属性“ claimingData”设置为以下值：
{“secretKey”: “YOUR_SECRET_KEY”, “expirationTime”: 1640995200000}
，其中到期日期是可以声明该设备的时间的结束时间，它是毫秒精度的unix时间戳记01/01/2022。
设置服务器端属性后，客户用户可以使用“索赔设备”小部件。

PE中的设备声明权限

重要的是要知道，对于PE版本，试图声明特定设备的用户必须具有这样做的必要权限。在这种情况下，所需的权限如下：

  • 资源：设备
  • 操作：索取设备

让我们为自定义声明用户组添加以上权限。

  • 创建一个通用角色。
  • 为用户组分配该角色。 | 声明设备 - 图3 | 声明设备 - 图4 | | —- | —- |

设备声明小部件

  • 您可以在输入窗口小部件捆绑包的静态窗口小部件部分中找到设备声明窗口小部件。
  • 索赔设备小部件非常简单，可以输入设备名称和秘密密钥。
  • 可以“隐藏”密钥输入字段并在“常规设置”中更改标签。
  • 也可以在“消息设置”中为用户配置各种消息。
  • 最后，您可以将要求保护的设备与仪表板的当前状态实体相关联。
    如果您有多个资产，并且想要将设备与其中之一关联，这将很有用。 | 声明设备 - 图5 | 声明设备 - 图6 | 声明设备 - 图7 | 声明设备 - 图8 | 声明设备 - 图9 | | —- | —- | —- | —- | —- |

设备声明API请求

Claiming Request作为POST请求发送到以下URL：

  1. http(s)://host:port/api/customer/device/$DEVICE_NAME/claim

支持的数据格式为：

  1. {
  2.   "secretKey":"value"
  3. }

注意：该消息不包含durationMs参数，secretKey参数是可选的。
只要索赔成功，就会将设备分配给特定客户。该claimingAllowed属性的情况下，自动删除系统参数allowClaimingByDefault是假的。
此外，还可以回收该设备，这意味着该设备将不会从客户处转让。该claimingAllowed属性将再次的情况下出现allowClaimingByDefault是假的。
有关上述步骤的更多详细信息，请参见以下内容。

设备回收API请求

为了收回设备，您可以将DELETE请求发送到以下URL（不要忘记用正确的名称替换设备名称）：

  1. curl -X DELETE https://thingsboard.cloud/api/customer/device/$DEVICE_NAME/claim

您将收到以下响应：

  1. {
  2.   "result": {},
  3.   "setOrExpired": true
  4. }

Python示例脚本

在本节中，您可能会获得用于声明设备功能的代码示例。
我们将使用tb-mqtt-client python模块连接并声明设备。
您可以使用以下命令进行安装：

  1. pip3 install tb-mqtt-client --user

基本索赔示例

假设像上面描述的那样，我们有一个处于租户级别的设备并配置了客户。
目前，我们想连接设备并发送索赔请求以将其分配给客户。
案例描述：在ThingsBord上有一个设备，其名称为Test Claiming device。
设备具有访问令牌凭据-Eypdinl1gUF5fSerOPJF。
我们应该下载上面的脚本并运行它，以将声明请求发送到服务器。

  1. #
  2. # Copyright © 2016-2020 The Thingsboard Authors
  3. #
  4. # Licensed under the Apache License, Version 2.0 (the "License");
  5. # you may not use this file except in compliance with the License.
  6. # You may obtain a copy of the License at
  7. #
  8. #     http://www.apache.org/licenses/LICENSE-2.0
  9. #
  10. # Unless required by applicable law or agreed to in writing, software
  11. # distributed under the License is distributed on an "AS IS" BASIS,
  12. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13. # See the License for the specific language governing permissions and
  14. # limitations under the License.
  15. #
  16. from tb_device_mqtt import TBDeviceMqttClient
  17. def collect_required_data():
  18.     config = {}
  19.     print("\n\n", "="*80, sep="")
  20.     print(" "*20, "ThingsBoard basic device claiming example script.", sep="")
  21.     print("="*80, "\n\n", sep="")
  22.     host = input("Please write your ThingsBoard host or leave it blank to use default (thingsboard.cloud): ")
  23.     config["host"] = host if host else "thingsboard.cloud"
  24.     token = ""
  25.     while not token:
  26.         token = input("Please write accessToken for device: ")
  27.         if not token:
  28.             print("Access token is required!")
  29.     config["token"] = token
  30.     config["secret_key"] = input("Please write secret key for claiming request: ")
  31.     if not config["secret_key"]:
  32.         print("Please make sure that you have claimData in server attributes for device to use this feature without device secret in the claiming request.")
  33.     duration_ms = input("Please write duration in milliseconds for claiming request or leave it blank to use default (30000): ")
  34.     config["duration_ms"] = int(duration_ms) if duration_ms else 30000
  35.     print("\n", "="*80, "\n", sep="")
  36.     return config
  37. if __name__ == '__main__':
  38.     config = collect_required_data()
  39.     client = TBDeviceMqttClient(host=config["host"], token=config["token"])
  40.     client.connect()
  41.     client.claim(secret_key=config["secret_key"], duration=config["duration_ms"]).get()
  42.     print("Claiming request was sent, now you should use claiming device widget to finish the claiming process.")

然后我们就可以使用Device Claiming Widget了。

下一步

  • 入门指南-这些指南提供了ThingsBoard主要功能的快速概述。设计在15至30分钟内完成。
  • 安装指南-了解如何在各种可用的操作系统上设置ThingsBoard。
  • 连接设备-了解如何根据连接技术或解决方案连接设备。
  • 数据可视化-这些指南包含有关如何配置复杂的ThingsBoard仪表板的说明。
  • 数据处理和操作-了解如何使用ThingsBoard规则引擎。
  • 物联网数据分析-了解如何使用规则引擎执行基本分析任务。
  • 硬件样本-了解如何将各种硬件平台连接到ThingsBoard。
  • 贡献和发展-了解ThingsBoard中的贡献和发展。