MQTT接入

设备注册

通过临时 MQTT 连接申请设备访问令牌,完成机器码登记和租户认领,并处理设备删除或令牌失效后的接入恢复。

首次注册

按需配置:仅使用设备自动注册的产品需要实现。 已获得平台发放的访问令牌时,可以直接进入连接认证流程。

未注册设备使用临时用户名 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_ALLOWEDREGISTER否设备不存在且产品允许创建,或预注册设备尚未领取凭据;使用新的请求编号提交首次注册格式的申请。
CREDENTIAL_VALIDRECONNECT否原令牌仍有效,继续使用原令牌重连,不申请新令牌;若仍被拒绝,应检查代理服务及认证配置。
DEVICE_IN_RECYCLE_BINWAIT_ADMIN否等待管理员恢复原设备,或彻底删除后重新查询。
DEVICE_DISABLEDWAIT_ADMIN否等待管理员解除设备禁用。
CREDENTIAL_INVALIDWAIT_ADMIN否设备存在但令牌缺失、不匹配或无效;由管理员签发凭据并安全配置到设备。
CREDENTIAL_REVOKEDWAIT_ADMIN否令牌已吊销或轮换,由管理员配置新凭据。
CREDENTIAL_EXPIREDWAIT_ADMIN否令牌过期,由管理员配置新凭据。
DEVICE_ALREADY_REGISTEREDWAIT_ADMIN否已有记录不满足领取条件,停止重复注册。
DEVICE_PRODUCT_MISMATCHWAIT_ADMIN否序列号属于其他产品,管理员核对设备产品归属。
PRE_PROVISION_REQUIREDWAIT_ADMIN否管理员先准备预注册设备。
REGISTRATION_DISABLEDWAIT_ADMIN否产品不允许自注册,管理员处理。
PRODUCT_NOT_FOUND、INVALID_PROVISION_SECRET、PRODUCT_NOT_READY、INVALID_PROVISION_STRATEGYWAIT_ADMIN否核对产品标识、注册密钥、产品启用状态、通信协议和注册策略。
INVALID_REQUESTWAIT_ADMIN否修正固件请求格式后再查询,不重复发送原错误报文。
SERVICE_UNAVAILABLERETRY是平台或安全保护存储暂时不可用,保留旧令牌并退避重试查询。
RATE_LIMITEDRETRY是等待频率窗口恢复后,使用新的请求编号重试。
REQUEST_REPLAYEDRETRY是使用新的请求编号,退避重试。

只有合法查询响应明确返回 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,由管理员签发新凭据并安全配置到设备端。恢复查询不会回传此前签发的令牌,不能通过不断重试领取已签发凭据。

相关文档

© 2026 飞鸟智联