设备注册
首次注册
按需配置:仅使用设备自动注册的产品需要实现。 已获得平台发放的访问令牌时,可以直接进入连接认证流程。
未注册设备使用临时用户名 provision 连接,密码留空。设备必须生成全新的请求编号,提交对应的注册响应主题订阅,并在服务端确认订阅成功后发布注册申请。
订阅主题:
provision/response/{requestId}
发布主题:
provision/request/{requestId}
注册请求:
{
"productKey": "产品标识",
"provisionSecret": "产品注册密钥",
"deviceSn": "设备序列号",
"name": "设备名称"
}
产品标识、产品注册密钥、设备序列号和设备名称均为必填字符串。相同请求编号在五分钟内不能重复使用;同一产品和设备序列号在一分钟内最多尝试五次。已经注册的设备序列号不会再次返回访问令牌。
注册成功响应:
{
"status": "SUCCESS",
"deviceSn": "设备序列号",
"deviceId": 1,
"credentials": {
"token": "设备访问令牌",
"authType": "ACCESS_TOKEN"
}
}
设备收到访问令牌后应先确认持久化成功,再替换本机旧令牌并断开临时注册连接,随后使用新令牌重新连接平台。保存失败时保留已收到的新令牌并重试本地保存,不再次申请注册。
自动注册成功只表示设备已经取得访问令牌,此时设备仍处于待认领状态。设备必须按数据上报流程上报稳定且唯一的机器码,租户使用该机器码和租户认领密钥完成认领后,平台才会处理普通遥测和后续业务规则。
接入恢复查询
按需配置:自动注册设备建议实现。 MQTT 认证只向设备表示允许或拒绝连接,不会携带平台的详细业务原因。认证被拒绝不能直接判断设备已经删除;断网、连接超时和服务暂时不可用只执行普通重连,不清空令牌、不申请注册。
确认认证被拒绝后,保留原令牌,使用临时用户名 provision 建立连接。每次生成新的请求编号,先订阅 provision/response/{requestId} 并等待订阅确认,再向 provision/request/{requestId} 发布恢复查询。没有本地令牌的设备也可以先查询,再决定是否注册。
{
"type": "recovery",
"productKey": "产品标识",
"provisionSecret": "产品注册密钥",
"deviceSn": "设备序列号",
"token": "本机保存的原访问令牌"
}
恢复查询只接受以上字段。productKey、provisionSecret 和 deviceSn 为必填非空字符串;token 为可选字符串,没有本地令牌时省略或传空字符串,不传设备名称。平台验证产品注册密钥后,读取设备及凭据状态,不创建设备、不签发或返回令牌、不修改凭据状态。查询与注册共用前述防重放和频率限制。
查询响应示例:
{
"status": "RECOVERY",
"code": "DEVICE_IN_RECYCLE_BIN",
"message": "设备在回收站,请联系管理员恢复或彻底删除",
"retryable": false,
"nextAction": "WAIT_ADMIN"
}
status=RECOVERY 表示查询已完成,具体处理方式以 nextAction 为准,不表示设备已恢复接入。retryable 表示是否适合自动重试本次请求;设备判断使用 code 和 nextAction,不要解析中文提示文字。
原因码 code | 处理指引 nextAction | 可重试 | 设备处理 |
|---|---|---|---|
REGISTRATION_ALLOWED | REGISTER | 否 | 设备不存在且产品允许创建,或预注册设备尚未领取凭据;使用新的请求编号提交首次注册格式的申请。 |
CREDENTIAL_VALID | RECONNECT | 否 | 原令牌仍有效,继续使用原令牌重连,不申请新令牌;若仍被拒绝,应检查代理服务及认证配置。 |
DEVICE_IN_RECYCLE_BIN | WAIT_ADMIN | 否 | 等待管理员恢复原设备,或彻底删除后重新查询。 |
DEVICE_DISABLED | WAIT_ADMIN | 否 | 等待管理员解除设备禁用。 |
CREDENTIAL_INVALID | WAIT_ADMIN | 否 | 设备存在但令牌缺失、不匹配或无效;由管理员签发凭据并安全配置到设备。 |
CREDENTIAL_REVOKED | WAIT_ADMIN | 否 | 令牌已吊销或轮换,由管理员配置新凭据。 |
CREDENTIAL_EXPIRED | WAIT_ADMIN | 否 | 令牌过期,由管理员配置新凭据。 |
DEVICE_ALREADY_REGISTERED | WAIT_ADMIN | 否 | 已有记录不满足领取条件,停止重复注册。 |
DEVICE_PRODUCT_MISMATCH | WAIT_ADMIN | 否 | 序列号属于其他产品,管理员核对设备产品归属。 |
PRE_PROVISION_REQUIRED | WAIT_ADMIN | 否 | 管理员先准备预注册设备。 |
REGISTRATION_DISABLED | WAIT_ADMIN | 否 | 产品不允许自注册,管理员处理。 |
PRODUCT_NOT_FOUND、INVALID_PROVISION_SECRET、PRODUCT_NOT_READY、INVALID_PROVISION_STRATEGY | WAIT_ADMIN | 否 | 核对产品标识、注册密钥、产品启用状态、通信协议和注册策略。 |
INVALID_REQUEST | WAIT_ADMIN | 否 | 修正固件请求格式后再查询,不重复发送原错误报文。 |
SERVICE_UNAVAILABLE | RETRY | 是 | 平台或安全保护存储暂时不可用,保留旧令牌并退避重试查询。 |
RATE_LIMITED | RETRY | 是 | 等待频率窗口恢复后,使用新的请求编号重试。 |
REQUEST_REPLAYED | RETRY | 是 | 使用新的请求编号,退避重试。 |
只有合法查询响应明确返回 REGISTRATION_ALLOWED 和 REGISTER 时,恢复流程才进入注册。WAIT_ADMIN 停止自动注册,可以低频重新查询以发现管理员的处理结果;查询超时、格式错误、未知指引均保留原令牌并退避重试。不得因多次普通断线而清除凭据。
当前智能控制电箱固件在暂时性故障后约三十秒重新查询,等待管理员期间约六十秒重新查询;“检查接入”按钮可主动查询,不会清空令牌。
平台删除设备后的重新自注册
普通删除是软删除,设备仍在回收站,原序列号继续受唯一约束占用,不能立即创建同序列号的新设备。 恢复查询返回 DEVICE_IN_RECYCLE_BIN,设备保留令牌并等待管理员处理。管理员恢复原设备后,若原凭据仍有效且设备未禁用,查询返回 CREDENTIAL_VALID,使用原令牌重连。
需要重新创建时,由管理员彻底删除原记录,释放序列号后再查询。产品允许注册时,平台返回 REGISTRATION_ALLOWED,设备再提交注册申请。序列号和机器码保持稳定,不通过修改编号绕过重复注册限制。
注册成功后,先持久化新令牌,再切换正式连接的用户名与设备主题,恢复已启用能力的订阅。按数据上报上报原机器码;新建设备需要重新认领,原租户归属、共享配置和联动配置不会因此恢复。使用共享配置的设备应按共享属性读取当前配置。
注册策略与失败处理
| 产品注册策略 | 重新注册条件 |
|---|---|
ALLOW_NEW | 默认策略,只允许创建不存在的设备。管理员彻底删除原设备记录、释放序列号后,才能使用原序列号重新创建。 |
PRE_PROVISIONED | 管理员先准备属于该产品、注册状态为 PENDING 的预注册设备记录,再由设备提交注册申请。已完成注册的记录不能重复领取令牌。 |
DISABLED | 禁止设备自注册,需要管理员处理设备和凭据。 |
恢复查询、首次注册和重新注册沿用同一组请求与响应主题。注册请求可以省略 type 或使用 type=register;恢复查询必须使用 type=recovery。产品必须启用,并允许通过 MQTT 和 JSON 协议接入;产品注册密钥必须与平台当前配置一致。
注册失败响应示例:
{
"status": "FAILURE",
"code": "DEVICE_ALREADY_REGISTERED",
"message": "设备序列号已经注册,禁止重复领取访问令牌",
"retryable": false,
"nextAction": "WAIT_ADMIN",
"errorMsg": "设备序列号已经注册,禁止重复领取访问令牌"
}
注册与恢复查询的失败响应均使用以上结构;errorMsg 保留原注册错误文本,内容与 message 一致。按原因码和指引处理失败,不把消息质量一级的投递确认当作注册成功,不记录完整令牌或产品注册密钥。
注册响应超时不代表注册失败。 平台可能已创建设备,但设备未收到成功响应。应先重新查询;若设备已存在但本机没有有效令牌,平台返回 CREDENTIAL_INVALID,由管理员签发新凭据并安全配置到设备端。恢复查询不会回传此前签发的令牌,不能通过不断重试领取已签发凭据。