本页是产品维度的设备接入引导。从创建产品开始，按此引导可独立完成一台原生 MQTT 设备的接入与验收。 设备端接入语法细节见各子文档：设备身份认证、MQTT 认证、HTTP 接入、设备动态注册。

一、前置：创建产品与物模型

1. 在控制台创建产品，数据协议选内置物模型协议（urMqtt），认证方式选密钥认证（或证书认证）。
2. 进入产品详情“物模型”，至少定义一个属性（例如 temperature），记下大小写敏感的标识符；事件和行为不能代替属性验收。见物模型协议。
3. 创建后进入产品详情，拿到 产品ID（productID）。

二、密钥体系（两类，别混用）

联犀接入涉及两个密钥，用途与用法不同：

密钥	用途	使用阶段	签名/解码规则
产品密钥 ProductSecret	一型一密设备动态注册鉴权	设备首次启动注册时	直接用字符串 ASCII 字节，不解码；签名 Base64(HEX(HMAC-SHA1(...)))，勿漏 HEX
设备密钥 DevicePsk / psk	每台设备正式 MQTT/HTTP 接入	设备连接上报时	先 Base64 解码得到 raw_key，再 HMAC-SHA1/256 对 username 签名

⚠️ 最容易错的一点：动态注册用 ProductSecret（不解码、Base64(HEX(...))）；正式 MQTT 接入用 psk（先 Base64 解码密钥，HMAC 摘要转十六进制，再加算法后缀）。详见设备动态注册：区别。

三、设备注册（两条路）

方式一：一机一密（逐台创建设备）

控制台手动创建设备，每台获得设备密钥（三元组）。

• 步骤：产品详情 → 设备 → 添加设备 → 记录该设备密钥
• 参考：设备接入指引（MQTT X 快速接入）：创建设备后，设备详情「设备接入」页会自动生成三元组（clientID/username/password），直接填入 MQTT 客户端即可。

方式二：一型一密（设备动态注册）

工厂只预置产品密钥，设备首次开机联网后自动注册，省去逐台烧录。

• 步骤：控制台使能产品动态注册 → 拿到产品密钥 → 设备发起动态注册 → 解密返回 psk → 保存到安全存储
• 动态注册支持 HTTP（/api/v1/things/device/auth/register）与 MQTT（$ext/up/register/{productID}/{deviceName}），详见设备动态注册

四、设备接入（HTTP + MQTT 两条路）

设备拿到 productID + deviceName + psk 后，用以下任一方式接入。

MQTT 接入（推荐）

• 服务器地址：device.unitedrhino.com（本地测试替换为实际部署地址）
• 端口：MQTT 明文 1883，MQTTS 加密 8883；WebSocket MQTT 明文 8083，加密 8084
• clientID：${productID}&${deviceName}
• username：${clientID};12010126;${connid};${expiry}（sdkappid 固定 12010126，connid 为随机串，expiry 为秒级过期时间戳）
• password：对 username 用 raw_key（psk 先 Base64 解码）做 HMAC-SHA1/256 的十六进制摘要；选 SHA1 时为 ${token};hmacsha1，选 SHA256 时为 ${token};hmacsha256
• 签名参考：MQTT 认证（多语言示例）
• 上行/下行主题：$thing/up/property/{productID}/{deviceName}（设备上报）、$thing/down/property/{productID}/{deviceName}（云端下发）

MQTT 上报与接入验收

1. 在设备详情“设备接入”复制当前设备的 MQTT 地址、ClientID、Username、Password；不要把产品密钥当成设备密钥。将四项填入 MQTTX 或固件并连接。连接后在设备列表确认该设备当前在线。
2. 向 $thing/up/property/{productID}/{deviceName} 发布 QoS 1 消息。把下面的 temperature 换成产品物模型中实际存在的属性标识符，并按其数据类型填写值：

{"method":"report","msgToken":"access-1","params":{"temperature":25}}

3. 进入设备详情“属性”查看同名属性的实际值和平台接收时间；再到“日志”核对上行原始报文与解析结果。在线但没有属性值不算通过；离线但有历史值也不算通过。刷新状态后应同时满足：当前在线、至少一个已定义属性有非空实值、该值有有效接收时间。

连不上：核对平台配置中的 MQTT 主机和端口、ClientID 的 产品ID&设备名 格式、用户名过期时间（秒）、设备密钥 Base64 解码与 HMAC 算法后缀、网络端口放行。

在线无数据：核对 Topic、method=report、params 内标识符的大小写和类型；在设备日志中区分未到达、解析失败和物模型校验失败。属性上报时间以平台接收时间为准。

数值异常：核对单位、枚举值、协议脚本转换和原始报文；如需转换，先在协议脚本模拟调试中验证。

HTTP 接入

• 认证：Basic Auth，username/password 即 MQTT 认证算出的账号密码
• 上行接口：POST /api/v1/things/device/edge/send/{handle}/{type}（如 thing/property）
• 文件上传：POST /api/v1/things/device/edge/upload-file（multipart）
• 限制：HTTP 仅支持设备上行上报，下发的属性/控制不支持
• 详见HTTP 协议接入

五、代码示例（对接参考，非封装 SDK）

以下为设备端对接参考代码，按各自语言实现 MQTT 认证/HTTP 上报。

MQTT 认证签名（Python）

import base64, hashlib, hmac, random, string, time

def RandomConnid(length):
    return ''.join(random.choice(string.ascii_uppercase + string.digits) for _ in range(length))

def IotHmac(productID, deviceName, devicePsk):
    connid = RandomConnid(5)
    expiry = int(time.time()) + 3600
    clientid = f"{productID}&{deviceName}"
    username = f"{clientid};12010126;{connid};{expiry}"
    raw_key = base64.b64decode(devicePsk.encode('utf-8'))  # psk 先 Base64 解码
    token = hmac.new(raw_key, username.encode('utf-8'), hashlib.sha256).hexdigest()
    password = f"{token};hmacsha256"
    return {"clientid": clientid, "username": username, "password": password}

Java / Node.js / JavaScript / C 示例见 MQTT 认证，MQTT X 图形化验证见 设备接入指引。

HTTP 设备注册（一型一密）

curl -X POST "http://<host>:7777/api/v1/things/device/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "productID": "<产品ID>",
    "deviceName": "<设备ID>",
    "nonce": 2125656451,
    "timestamp": 1687525491,
    "signature": "<Base64(HEX(HMAC-SHA1(productSecret, \"deviceName=..&nonce=..&productID=..&timestamp=..\")))>"
  }'

HTTP 上报

curl --location --request POST 'http://<host>:7777/api/v1/things/device/edge/send/thing/property' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64(username:password)>' \
--data-raw '{"method":"report","msgToken":"123","params":{"<属性标识>":"<值>"}}'

六、完整接入流程

1. 创建产品（MQTT 协议、密钥认证）→ 拿到 productID
2. 配置物模型属性
3. 选设备注册方式：
   - 一机一密：控制台创建设备 → 拿设备密钥（psk）
   - 一型一密：使能动态注册 → 拿产品密钥 → 设备注册拿 psk
4. 设备按 MQTT/HTTP 接入（签名、连接、上报）
5. 上报主题 $thing/up/... → 控制台查看已定义属性的实际值、接收时间和日志
6. 当前在线且属性有值和接收时间后验收通过；下发控制另走 $thing/down/...

七、常见问题

• psk 要不要 Base64 解码：动态注册阶段不用；正式 MQTT 认证先解码。见上表。
• 签名编码：动态注册是 Base64(HEX(HMAC-SHA1(...)))，勿漏 HEX；正式接入 MQTT 是 HMAC-... 十六进制摘要，后缀与算法一致。
• HTTP 无法接收下发：HTTP 仅支持上行，控制下发需用 MQTT。
• 产品密钥在哪看：产品详情 → 使能动态注册后可见（ProductSecret）。

接入成功后，欢迎在 Gitee 为 物联网模块 点亮 Star；遇到问题可提交 Issue。

更新日志

2026/10/1 17:34

查看所有更新日志

• 9c9b0-feat(文档站): 精简导航并完善物联网模块接入与关注引导于 2026/10/1
• 020ad-Merge #28 into master from docs/device-access-guide于 2026/8/24

贡献者: 杨磊

上一页设备接入

下一页设备身份认证