设备动态注册

约 3081 字大约 10 分钟

2025-03-03

应用场景

一机一密场景：需要在生产环节为每一个设备烧录由平台生成的唯一设备信息。
一型一密场景：同一产品类型的设备只要预置产品级密钥，可省去工厂的设备信息烧录。设备出厂后，在第一次开机且成功联网的情况下，可发起动态注册，通过产品密钥鉴权，从平台获取设备信息，然后存在本地，达成和工厂烧录一样的效果。

使用步骤

在控制台使能产品的动态注册功能
使能动态注册后才有产品密钥。
产品密钥：
选择是否使能自动设备创建
这个选项决定动态注册时的设备名，是设备自定义的（需要保证统一产品下设备名唯一），还是使用平台预定义的设备名。
调用设备动态注册接口进行设备注册

MQTT自动注册

参数说明

{productID}：产品ID。
{deviceName}：设备ID。
通用请求参数

参数	类型	必填	说明
msgToken	String	是	用于上下行消息配对标识
sys.noAsk	bool	否	云端是否回复设备
sys.retMsg	bool	否	是否返回错误信息,字段为msg
示例:

{
  "method": "reportInfo",
  "msgToken": "1234567",
  "sys": {
     "noAsk": false,
     "retMsg": true
  }
}

说明：
clientID 格式固定为 register&{productID}&{deviceName}，userName 和 password 可填任意值。
动态注册连接与正式设备连接是两次不同的 MQTT 连接，动态注册成功后应断开本次连接，再按《MQTT 认证》文档建立正式连接。详见文末“完整流程说明”。
下例中 MQTT Broker 地址为正式环境示例 device.unitedrhino.com:1883（SDK 中通常写作 mqtt://device.unitedrhino.com:1883），本地调试时请替换为实际部署地址。

连接示例（以 mosquitto 命令行工具为例）：

# 先在另一个终端订阅下行响应 Topic
mosquitto_sub -h device.unitedrhino.com -p 1883 \
  -i "register&pxxxxxxxxxxxxx&my-device-001" \
  -u "any" -P "any" \
  -t '$ext/down/register/pxxxxxxxxxxxxx/my-device-001'

# 发布上行注册请求
mosquitto_pub -h device.unitedrhino.com -p 1883 \
  -i "register&pxxxxxxxxxxxxx&my-device-001" \
  -u "any" -P "any" \
  -t '$ext/up/register/pxxxxxxxxxxxxx/my-device-001' \
  -m '{
    "msgToken": "1234567",
    "payload": {
      "nonce": 2125656451,
      "timestamp": 1687525491,
      "signature": "<Base64(HMAC-SHA1(productSecret, \"deviceName=my-device-001&nonce=2125656451&productID=pxxxxxxxxxxxxx&timestamp=1687525491\"))>",
      "retEnc": "aes128cbc"
    }
  }'

Topic

设备属性上行请求 Topic： $ext/up/register/{productID}/{deviceName}
设备属性下行响应 Topic： $ext/down/register/{productID}/{deviceName}

请求参数

示例：

{
  "payload": {
    "nonce": 123,
    "timestamp": 123123123,
    "signature": "wefwefwegefsfsef",
    "retEnc": "aes128cbc",    // 返回使用的加密方式: aes128cbc(默认) aes128ecb
    "tenantCode": "your-tenant-code"  // 可选：指定设备归属租户
  }
}

参数名称	类型	必须	说明
nonce	int64	是	随机数
timestamp	int64	是	秒级时间戳
signature	string	是	签名信息
retEnc	string	否	返回使用的加密方式: aes128cbc(默认) aes128ecb
tenantCode	string	否	租户号（可选）：若填写，要求产品的租户号为 `common` 或与该值一致，否则返回错误；不填则使用产品的默认租户

tenantCode 使用规则
不填（默认）：设备归属产品所在租户
产品租户为 common（全局共享产品）：可填入任意目标租户号，设备将注册到该租户
产品租户与 tenantCode 一致：允许（幂等，等同不填）
产品租户既非 common 又与 tenantCode 不一致：返回错误"设备注册租户号与产品租户号不一致"

签名生成步骤

对参数（deviceName、nonce、productID、timestamp）按字典序升序排序。
将以上参数，按 参数名称=参数值&参数名称=参数值 拼接成字符串，如：”deviceName=xxx&nonce=2125656451&productID=xxx&timestamp=1687525491”。
以 ProductSecret 字符串的 ASCII 字节作为 HMAC 密钥（注意：不需要对 ProductSecret 进行 Base64 解码，控制台显示的是什么字符串就直接用什么字符串），使用 HMAC-SHA1 算法对上一步的字符串进行计算，得到原始字节。
将原始字节转为十六进制（HEX）字符串。
对十六进制字符串的 ASCII 字节进行 Base64 编码，即可获得最终签名，填入 signature 字段。

重要说明：签名编码流程为 Base64( HEX( HMAC-SHA1(data, key) ) )，而非直接 Base64( HMAC-SHA1(data, key) )，中间有一步十六进制编码，请勿遗漏。

Python 示例：

import hmac
import hashlib
import base64

def calc_signature(product_secret: str, data: str) -> str:
    “””
    计算动态注册签名

    参数:
        product_secret: 控制台获取的产品密钥（Base64格式，直接使用，不要解码！）
        data: 拼接好的待签名字符串
    返回:
        signature 字段值
    “””
    # 密钥直接使用 ProductSecret 字符串的 ASCII 字节，不要 base64.b64decode！
    key = product_secret.encode('ascii')

    # Step 1: HMAC-SHA1，得到原始字节
    raw_bytes = hmac.new(key, data.encode('utf-8'), hashlib.sha1).digest()

    # Step 2: 十六进制编码
    hex_str = raw_bytes.hex()  # 等价于 binascii.hexlify(raw_bytes).decode()

    # Step 3: 对十六进制字符串进行 Base64 编码
    signature = base64.b64encode(hex_str.encode('ascii')).decode('ascii')
    return signature


if __name__ == “__main__”:
    product_secret = “3q4zRdjdfe5U2G3HX8VTbLCZuOE=”   # 控制台复制的产品密钥
    device_name = “my-device-001”
    product_id  = “pxxxxxxxxxxxxx”
    nonce       = 2125656451
    timestamp   = 1687525491

    # 参数按字典序排序后拼接
    data = f”deviceName={device_name}&nonce={nonce}&productID={product_id}&timestamp={timestamp}”

    sig = calc_signature(product_secret, data)
    print(f”signature: {sig}”)

平台返回参数

示例：

{
  “timestamp”: 1709968346811,
  “code”: 200,
  “msg”: “ok”,
  “data”: {
    “len”: 10,
    “payload”: “xxxxxxx”
  }
}

参数名称	类型	描述
code	string	错误码
msg	string	错误信息
data	object
- len	int64	长度
- payload	string	设备连接信息的 AES 加密后内容

说明：加密过程将原始 JSON 格式的 payload 转为字符串后进行 AES 加密，再进行 Base64 编码。AES 加密算法根据请求的 retEnc 方式（aes128cbc 或 aes128ecb），密钥长度 128 位（16 字节），取 ProductSecret 字符串的前 16 个 ASCII 字符（不需要解码），偏移量（IV）为 16 个 ASCII 字符 ”0”（即 bytes.Repeat([]byte(“0”), 16)）。

原始 payload 内容说明：

key	value	描述
encryptionType	1	加密类型，当前版本固定返回 `1`，请勿以该字段判断认证方式，应以 `psk` / `clientCert` 是否非空为准。详见下方 ⚠️ 注意事项。
psk	1239465801	设备密钥，当产品认证类型为签名认证时有此参数。值为 base64 编码的随机字节串。动态注册阶段直接保存该字符串；后续按《MQTT 认证》文档生成正式连接密码时，需先对其进行 Base64 解码得到原始密钥。详见下方 ⚠️ 注意事项。
clientCert	-	设备证书文件字符串格式，当产品认证类型为证书认证时有此参数
clientKey	-	设备私钥文件字符串格式，当产品认证类型为证书认证时有此参数

⚠️ 注意事项
1. 请先以 psk / clientCert 是否非空判断认证方式，不要依赖 encryptionType
当前版本无论产品认证方式如何，encryptionType 均返回 1。设备端应 以 psk 是否非空 来判断实际认证类型：
psk 非空，clientCert/clientKey 为空 → 签名认证（PSK 模式），使用 psk 连接
clientCert/clientKey 非空，psk 为空 → 证书认证，使用证书连接
2. psk 的格式与使用方式
psk 的值是平台生成的 base64 编码的随机字节串（20 字节随机数经 base64 编码），格式形如 KiB+/WCfAGpwKoqqJ1Js3aAWtxk=。
psk 在不同阶段的用法不同，请勿混淆：
动态注册阶段：将 psk 作为字符串保存到设备安全存储即可，不需要做任何解码。
正式 MQTT 密钥认证阶段：应按照《MQTT 认证》文档，先对 psk 进行 Base64 解码 得到原始密钥 raw_key，再用 raw_key 对 username 生成 HMAC 摘要，最终得到 password。
简单对照：
# ✅ 动态注册签名：ProductSecret 直接使用 ASCII 字节，不解码
register_key = product_secret.encode('ascii')

# ✅ 正式 MQTT 认证：psk 先 Base64 解码得到 raw_key
mqtt_key = base64.b64decode(psk)
具体用途（如 MQTT 密码签名）请参考《MQTT 认证》文档。

payload 解密后原始内容示例（签名认证产品）：

{
  "encryptionType": 1,
  "psk": "KiB+/WCfAGpwKoqqJ1Js3aAWtxk=",
  "clientCert": "",
  "clientKey": ""
}

上例中 encryptionType 为 1 但 psk 非空、cert 为空，说明是签名认证产品。判断逻辑以 psk 是否非空为准。

payload 解密后原始内容示例（证书认证产品）：

{
  "encryptionType": 1,
  "psk": "",
  "clientCert": "-----BEGIN CERTIFICATE-----\n...",
  "clientKey":  "-----BEGIN PRIVATE KEY-----\n..."
}

动态注册与正式 MQTT 接入的区别

阶段	MQTT clientID	username/password	使用密钥	签名规则
动态注册	`register&{productID}&{deviceName}`	可任意填写	`ProductSecret`	`Base64(HEX(HMAC-SHA1(...)))`，ProductSecret 不解码
正式接入	`{productID}&{deviceName}`	按 MQTT 认证规则生成	`DevicePsk / psk`	先按 MQTT 认证文档对 `psk` Base64 解码，再生成 `password`

完整流程说明

一型一密设备首次启动时，本地不存在 DevicePsk，应按以下流程完成动态注册并建立正式 MQTT 连接：

1. 设备首次启动，本地无 DevicePsk。
2. 使用 register&{productID}&{deviceName} 作为 clientID 建立动态注册 MQTT 连接。
3. 发布动态注册请求到 $ext/up/register/{productID}/{deviceName}，订阅 $ext/down/register/{productID}/{deviceName}。
4. 获取并解密返回 payload，得到 psk / 证书信息。
5. 断开本次动态注册 MQTT 连接。
6. 使用 {productID}&{deviceName} 作为正式 clientID。
7. 按《MQTT 认证》文档重新构造 username/password（psk 需先 Base64 解码）。
8. 建立正式设备 MQTT 连接。

量产注意：设备必须将动态注册获取到的 psk / 证书持久化到安全存储，避免每次启动都重复动态注册。

HTTP自动注册

参数说明

设备动态注册时需携带 ProductID、ProductSecret 和 DeviceName 向平台发起 HTTP/HTTPS 请求，请求接口及参数如下：

请求的 URL 为：

https://127.0.0.1:7777/api/v1/things/device/auth/register
http://127.0.0.1:7777/api/v1/things/device/auth/register

请求方式： POST

请求头：

Header	Value
Content-Type	application/json

参数传递方式： 所有参数均以 JSON 格式放在请求体（Body）中，不使用 URL Query String 或 HTTP Header 传参。

请求参数

参数名称	类型	必须	说明
productID	string	是	产品ID
deviceName	string	是	设备ID
nonce	int64	是	随机数
timestamp	int64	是	秒级时间戳
signature	string	是	签名信息
retEnc	string	否	返回 payload 的加密方式：`aes128cbc`（默认，CBC 模式）或 `aes128ecb`（ECB 模式）
tenantCode	string	否	租户号（可选）：若填写，要求产品的租户号为 `common` 或与该值一致，否则返回错误；不填则使用产品的默认租户

请求示例：

curl -X POST "http://127.0.0.1:7777/api/v1/things/device/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "productID":  "pxxxxxxxxxxxxx",
    "deviceName": "my-device-001",
    "nonce":      2125656451,
    "timestamp":  1687525491,
    "signature":  "<Base64(HMAC-SHA1(productSecret, \"deviceName=my-device-001&nonce=2125656451&productID=pxxxxxxxxxxxxx&timestamp=1687525491\"))>",
    "retEnc":     "aes128cbc",
    "tenantCode": "your-tenant-code"
  }'

签名生成步骤

与 MQTT 注册完全相同，见上方"签名生成步骤"说明，算法为 Base64( HEX( HMAC-SHA1(data, key) ) )，密钥直接使用 ProductSecret 字符串的 ASCII 字节（不解码）。

平台返回参数

参数名称	类型	描述
code	string	错误码
msg	string	错误信息
data	object
- len	int64	长度
- payload	string	设备连接信息的 AES 加密后内容

说明：加密过程将原始 JSON 格式的 payload 转为字符串后进行 AES 加密，再进行 Base64 编码。AES 加密算法为 CBC 模式，密钥长度 128 位（16 字节），取 ProductSecret 字符串的前 16 个 ASCII 字符（不解码），偏移量（IV）为 16 个 ASCII 字符 ”0”。

原始 payload 内容说明：

key	value	描述
encryptionType	1	加密类型，当前版本固定返回 `1`，请勿以该字段判断认证方式，应以 `psk` / `clientCert` 是否非空为准。
psk	1239465801	设备密钥，当产品认证类型为签名认证时有此参数。值为 base64 编码的随机字节串。动态注册阶段直接保存该字符串；后续按《MQTT 认证》文档生成正式连接密码时，需先对其进行 Base64 解码得到原始密钥。
clientCert	-	设备证书文件字符串格式，当产品认证类型为证书认证时有此参数
clientKey	-	设备私钥文件字符串格式，当产品认证类型为证书认证时有此参数

响应示例：

{
  “code”: “OK”,
  “msg”: “success”,
  “data”: {
    “len”: 42,
    “payload”: “<Base64(AES-CBC加密后的设备连接信息)>”
  }
}

payload 解密后原始内容示例（签名认证产品）：

{
  “encryptionType”: 1,
  “psk”: “KiB+/WCfAGpwKoqqJ1Js3aAWtxk=”,
  “clientCert”: “”,
  “clientKey”: “”
}

psk 为 base64 编码的随机字节串。动态注册阶段直接保存；正式 MQTT 密钥认证时需先 Base64 解码，再按《MQTT 认证》文档生成 password。

payload 解密后原始内容示例（证书认证产品）：

{
  “encryptionType”: 1,
  “psk”: “”,
  “clientCert”: “-----BEGIN CERTIFICATE-----\n...”,
  “clientKey”:  “-----BEGIN PRIVATE KEY-----\n...”
}

更新日志

2026/8/4 07:04

查看所有更新日志

7e927-文档站全面重构：目录重排、首页重写、案例独立成站、应用市场下线于 2026/8/4
2c8b5-Merge #5 into master from fix/mqtt-dynamic-register-doc于 2026/7/3
584fa-docs(device-register): 新增可选 tenantCode 参数说明于 2026/3/18
ece9c-docs(动态注册): 补充 psk 格式说明及 encryptionType 当前行为注意事项于 2026/3/12
3f121-docs: 修正设备动态注册签名算法描述与 Python 示例于 2026/3/12
fc2b7-docs: 补充设备动态注册 HTTP/MQTT 接口说明与示例于 2026/3/10
bddea-docs: 更新文档结构、添加新内容并优化现有文档于 2025/12/28
706e5-doc于 2025/11/27
6fa0c-doc于 2025/9/1
80b39-doc于 2025/3/11
d4fa0-doc: 更换皮肤到最新版于 2025/3/3
82830-doc于 2025/2/17
12463-feat: 支持pg于 2024/12/24
4066c-doc: 完善文档于 2024/11/12
65a22-doc: 完善文档于 2024/11/11
8794f-feat: 完善项目`于 2024/8/30
df9b4-初始化于 2024/8/29

平台认知

基本概念

物模型

架构与开源

定价与更新

联犀协议

AI交互

第三方协议

网关接入

音视频

物联卡

组态大屏

设备动态注册

简介

应用场景

使用步骤

MQTT自动注册

参数说明

登录

Topic

请求参数

签名生成步骤

平台返回参数

动态注册与正式 MQTT 接入的区别

完整流程说明

HTTP自动注册

参数说明

请求参数

签名生成步骤

平台返回参数

更新日志