设备接入教程引导
本页是产品维度的设备接入引导。创建好联犀协议产品后，按此引导即可完成设备接入。 设备端接入语法细节见各子文档：设备身份认证、MQTT 认证、HTTP 接入、设备动态注册。
一、前置：创建产品与物模型
- 在控制台创建产品，传输协议选
MQTT，认证方式选密钥认证（或证书认证）。
- 为产品配置物模型属性（属性/事件/行为，见物模型协议）。
- 创建后进入产品详情，拿到 产品ID（productID）。
二、密钥体系（两类，别混用）
联犀接入涉及两个密钥，用途与用法不同：
| 密钥 | 用途 | 使用阶段 | 签名/解码规则 |
|---|---|---|---|
| 产品密钥 ProductSecret | 一型一密设备动态注册鉴权 | 设备首次启动注册时 | 直接用字符串 ASCII 字节，不解码；签名 Base64(HEX(HMAC-SHA1(...)))，勿漏 HEX |
| 设备密钥 DevicePsk / psk | 每台设备正式 MQTT/HTTP 接入 | 设备连接上报时 | 先 Base64 解码得到 raw_key，再 HMAC-SHA1/256 对 username 签名 |
⚠️ 最容易错的一点：动态注册用 ProductSecret（不解码、
Base64(HEX(...))）；正式接入用 psk（先解码、直接Base64(HMAC(...))不需 HEX）。详见设备动态注册：区别。
三、设备注册（两条路）
方式一：一机一密（逐台创建设备）
控制台手动创建设备，每台获得设备密钥（三元组）。
- 步骤：产品详情 → 设备 → 添加设备 → 记录该设备密钥
- 参考：设备接入指引（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 →${token};hmacsha256 - 签名参考：MQTT 认证（多语言示例）
- 上行/下行主题：
$thing/up/property/{productID}/{deviceName}（设备上报）、$thing/down/property/{productID}/{deviceName}（云端下发）
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=..×tamp=..\")))>"
}'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/...（仅 MQTT 支持下发）七、常见问题
- psk 要不要 Base64 解码：动态注册阶段不用；正式 MQTT 认证先解码。见上表。
- 签名编码：动态注册是
Base64(HEX(HMAC-SHA1(...)))，勿漏 HEX；正式接入 MQTT 是HMAC-...直接 hex。 - HTTP 无法接收下发：HTTP 仅支持上行，控制下发需用 MQTT。
- 产品密钥在哪看：产品详情 → 使能动态注册后可见（ProductSecret）。
更新日志
2026/8/24 02:57
查看所有更新日志
020ad-于
