MQTT接入
接入概览
通过 MQTT 接入飞鸟智联云平台,按功能查阅连接、注册、数据、属性、控制、联动和升级文档。
概述
第三方设备可通过 MQTT 接入飞鸟智联云平台。接入前需要在平台中创建产品并配置物模型,设备按照接入文档完成注册、连接、主题订阅和数据交互。
本文中的 {token} 表示平台颁发的设备访问令牌,不是设备编号、机器码或数据库编号。连接用户名和主题中的访问令牌必须完全一致。
接入前准备
- 在“IOT物联网 → 产品中心 → 产品管理”中创建产品。
- 获取产品标识和产品注册密钥。
- 在产品物模型中定义设备需要使用的遥测、属性和服务。
- 确认设备支持通过安全连接访问 MQTT 服务。
- 为每台设备准备稳定且全局唯一的设备序列号和机器码。
产品注册密钥、设备访问令牌和节点连接密钥均属于敏感凭据,不得写入公开日志、截图或工单正文。
产品物模型
接入前需要在产品物模型中定义以下三类能力,设备使用的数据键、类型和取值范围应与物模型一致:
- 遥测:由设备上报的时序数据,例如温度、湿度、运行状态和机器码,报文格式见数据上报。
- 属性:包含客户端属性、共享属性和服务端属性。客户端属性由设备上报,共享属性由平台维护并下发,交互方式见共享属性。
- 服务:需要立即执行的一次性动作,通过控制指令完成,例如重启设备或切换继电器。
采用自动注册和租户认领的产品,必须在遥测中定义字符串类型的 machineCode,名称为“机器码”。机器码必须由设备保持稳定且全局唯一,不能使用访问令牌代替,也不能在每次上报时随机生成。
文档导航
接入基础与设备交互分篇说明,请先阅读连接认证和主题总览,再按产品能力查阅对应流程。首次自动注册见设备注册;已经持有访问令牌的设备可直接建立正式连接。认证被拒绝时,保留旧令牌并按接入恢复查询获取平台处理指引,再决定重连、注册或等待管理员处理。
| 文档 | 内容 |
|---|---|
| 连接认证 | 服务地址、安全连接、令牌认证和连接排查。 |
| 主题总览 | 按功能查看主题、交互方向和必需或按需配置标签。 |
| 设备注册 | 临时注册连接、令牌获取、设备认领与接入恢复查询。 |
| 设备交互 | 数据上报、共享属性、配置读取、控制指令、设备联动和固件升级,按功能分节说明。 |
禁止事项
- 不在综合数据报文中加入共享属性区块。
- 不在上报报文中传递设备访问令牌、设备编号、产品元数据或物模型中未声明的字段。
- 不使用秒级时间戳,也不由平台自动换算时间单位。
- 不将重启、开关等一次性动作定义为共享属性,此类动作必须通过物模型服务和控制指令执行。
- 不使用新的消息编号重复发送已经提交成功的同一批数据。
- 不把平台保存的共享属性值冒充为设备当前配置读取结果。
- 不在设备联动请求中传入目标访问令牌、目标设备编号、控制方法或临时参数。
- 不把联动的排队、已下发或发送确认状态当作目标设备执行成功,也不在结果未知时无条件重复动作。
- 不在日志中输出完整的产品注册密钥或设备访问令牌。
- 不因普通断线、连接超时或多次重连失败而清空令牌、重新注册。
- 不仅凭认证被拒绝就判断设备已删除,也不通过修改序列号绕过重复注册限制。
接入验收清单
- 系统时间准确,系统根证书已经安装并更新。
- 客户端已启用服务证书和服务域名校验。
- 连接用户名和所有主题使用同一个设备访问令牌。
- 客户端标识在所有设备中保持唯一。
- 按实际启用的能力配置主题,设备重连后恢复这些能力对应的下行订阅。
- 数据上报:每次综合数据携带唯一消息编号和固定机器码,上报前完成数据确认订阅,超时后保留原消息编号重试。
- 使用的遥测、客户端属性和共享属性按照物模型定义的数据类型传输。
- 自动注册(按需):先订阅具体响应主题并等待确认,再发布注册请求;新令牌持久化成功后才切换正式设备连接,保存失败时重试本地保存。
- 接入恢复(按需):认证明确被拒绝后保留原令牌,复用临时注册主题发送
type=recovery;按code和nextAction判断处理方式,只有明确允许注册才申请新令牌。等待管理员时停止注册,服务异常或响应超时则退避重试查询。 - 共享配置下发(按需):收到属性后校验、保存并应用,启动或重连后主动读取平台最新配置。
- 平台读取设备配置(按需):读取本机实际值,按原请求编号和属性键返回标准成功或失败报文,不执行写入动作。
- 远程控制或联动目标(按需):按物模型执行指令,使用收到的目标指令编号响应,对重复投递只执行一次。
- 联动来源(按需):只发送已配置的联动标识,区分来源请求编号与目标指令编号;结果丢失时查询原请求,正确处理超时和发送不确定状态。
- 固件升级(按需):按检查请求或升级任务的原请求编号交互,正确上报进度与失败原因。