一、协议核心设计原则极致精简主题仅保留 3 个核心主题网关仅需订阅 2 个、发布 1 个大幅降低开发与维护成本全字段缩写关键字段采用 1-3 位缩写压缩 JSON 报文体积 30%适配网关低带宽、低存储场景物模型兼容保留产品标识、设备 ID、功能点三大物模型核心覆盖注册、状态上报全流程标准化通信基于 MQTT 3.1.1/5.0 协议QoS1 保证消息送达retain0 避免无效消息堆积。二、基础规范核心定义2.1 通信载体规范表格配置项取值说明传输协议MQTT 3.1.1/5.0主流物联网通用协议兼容性强消息质量QoS1至少一次送达避免核心消息丢失保留消息retain0不保留历史消息减少无效数据占用数据格式UTF-8 JSON轻量易解析适配嵌入式网关消息标识mid全局唯一消息 IDUUID用于链路追踪2.2 关键字段缩写映射为降低报文体积与开发记忆成本核心字段统一缩写映射关系如下表格原字段名缩写字段字段含义适用场景msgIdmid全局唯一消息 ID所有报文必含timestampts13 位时间戳所有报文必含versionver协议版本所有报文必含固定值v1typetyp功能类型标识区分报文功能核心缩写字段productKeypk子设备产品唯一标识子设备注册 / 状态上报deviceNamedn子设备唯一 ID子设备注册 / 状态上报gatewaySngs网关唯一序列号网关身份唯一标识propertiesprop设备功能点 / 状态数据物模型核心字段subDevicessds子设备数组批量注册场景hardwareVersionhw网关硬件版本网关注册softwareVersionsw网关软件版本网关注册ipAddressip网关本地 IP网关注册connectTypect联网方式网关注册取值wifi/eth/4g2.3 客户端 ID 命名规则网关作为唯一通信节点子设备无需独立连接 MQTT由网关透传所有消息网关客户端 IDgw_{gs}例gw_GW20260001gs为网关序列号子设备无独立客户端 ID通过报文字段pkdn标识。三、极致精简主题设计仅 3 个以网关唯一序列号 gs为核心隔离维度所有功能复用主题通过typ字段区分报文类型主题格式如下表格主题缩写格式发布端订阅端覆盖功能备注gw/{gs}/req网关平台网关注册、子设备注册、状态上报网关仅需发布此主题gw/{gs}/resp平台网关所有请求的统一响应网关核心订阅主题gw/{gs}/ntf平台网关平台主动通知可选注册过期、设备异常等按需启用 替换说明{gs}需替换为网关实际序列号例gw/GW20260001/req四、通用报文规范必含字段所有请求 / 响应报文必须包含通用头字段保证通信统一性通用头结构如下json{ mid: UUID唯一标识, // 全局唯一用于匹配请求与响应 ts: 1743456789012, // 13位时间戳避免消息时序混乱 ver: v1, // 协议版本固定值便于版本兼容 typ: 字符串 // 功能类型缩写核心区分报文用途 }五、核心功能报文全缩写5.1 网关注册typrg功能说明网关上电后向平台注册身份上报硬件、软件、联网方式等基础信息是网关与平台建立通信关系的第一步。报文示例网关→平台发布至gw/{gs}/req{ mid: a1b2c3d4-5678-90ef-ghij, ts: 1743456789012, ver: v1, typ: rg, data: { gs: GW20260001, // 网关唯一序列号 hw: v1.0, // 硬件版本 sw: v2.1, // 软件版本 ip: 192.168.1.100, // 网关本地IP ct: eth // 联网方式eth以太网、wifi无线、4g移动网络 } }平台响应报文平台→网关发布至gw/{gs}/resp{ mid: a1b2c3d4-5678-90ef-ghij, ts: 1743456789567, ver: v1, typ: rg, code: 200, // 状态码200成功 msg: 网关注册成功, // 响应描述 data: { et: 86400, // 注册有效期秒 pt: 1743456789567 // 平台标准时间戳 } }5.2 子设备注册typrs功能说明网关扫描并挂载子设备后批量向平台上报子设备物模型信息产品标识、设备 ID、功能点等支持单次注册多个子设备。报文示例网关→平台发布至gw/{gs}/req{ mid: b2c3d4e5-6789-01fg-hijk, ts: 1743456790123, ver: v1, typ: rs, data: { gs: GW20260001, sds: [ // 子设备数组支持批量注册 { pk: TEMP_SENSOR_001, // 子设备产品标识对应物模型 dn: TS_0001, // 子设备唯一ID dt: sensor, // 设备类型sensor传感器、switch开关 mv: v1.0, // 物模型版本 prop: [ // 子设备物模型功能点核心 {id: temp, n: 温度, t: float, u: ℃, ro: true}, {id: bat, n: 电量, t: int, u: %, ro: true} ] } ] } }平台响应报文平台→网关发布至gw/{gs}/resp{ mid: b2c3d4e5-6789-01fg-hijk, ts: 1743456790789, ver: v1, typ: rs, code: 200, msg: 子设备注册完成, data: { sc: 1, // 成功注册的子设备数 fc: 0, // 失败注册的子设备数 sl: [TEMP_SENSOR_001_TS_0001] // 成功注册的子设备ID列表 } }5.3 子设备状态上报typpr功能说明子设备状态变化如温度更新、电量变化或定时上报时网关透传数据至平台支持单 / 多属性同时上报适配实时监控场景。报文示例网关→平台发布至gw/{gs}/req{ mid: c3d4e5f6-7890-12hi-jklm, ts: 1743456791234, ver: v1, typ: pr, data: { gs: GW20260001, pk: TEMP_SENSOR_001, // 待上报状态的子设备产品标识 dn: TS_0001, // 待上报状态的子设备唯一ID prop: { // 状态数据键为功能点id值为对应数值 temp: 25.6, bat: 85 } } }平台响应报文可选平台→网关发布至gw/{gs}/resp{ mid: c3d4e5f6-7890-12hi-jklm, ts: 1743456791890, ver: v1, typ: pr, code: 200, msg: 状态上报接收成功 }六、通用状态码定义统一状态码便于网关与平台排查通信问题所有响应报文包含code字段含义如下表格状态码含义适用场景200操作成功注册、状态上报等所有正常流程400参数错误报文缺失必填字段、字段格式错误401鉴权 / 未注册失败网关未注册、身份验证失败404设备不存在上报状态时子设备未在平台注册500平台服务异常平台内部错误无法处理请求七、网关端实现流程技术落地指引7.1 上电通信流程初始化网关启动后初始化 MQTT 客户端配置连接参数服务器地址、端口、客户端 ID订阅主题连接 MQTT 后订阅gw/{gs}/resp与gw/{gs}/ntf2 个主题完成响应与通知接收网关注册发布rg类型报文至gw/{gs}/req等待平台注册响应子设备注册注册成功后扫描本地子设备列表发布rs类型报文完成子设备物模型注册状态上报子设备状态变化时网关采集数据并发布pr类型报文实现实时同步。7.2 异常处理机制MQTT 重连连接断开后自动触发重连重连成功后重新订阅主题并重发未收到响应的请求离线缓存网关本地缓存离线状态数据重连后批量补发避免数据丢失超时重试请求发送后若超过设定时间如 5 秒未收到响应自动重试最多 3 次避免单次通信失败。八、协议核心优势主题极致精简仅 3 个主题网关订阅 / 发布逻辑极简大幅降低嵌入式网关开发复杂度报文体积最小全字段缩写JSON 体积压缩 30%适配低带宽、低存储的网关硬件物模型完整兼容保留物模型核心定义支持自定义功能点可适配传感器、开关、控制器等各类子设备扩展灵活新增功能如指令下发、设备离线通知仅需扩展typ字段值无需新增主题无缝升级标准化强基于 MQTTJSON 通用协议兼容阿里云、华为云、腾讯云等主流物联网平台降低对接成本。九、扩展建议可选功能指令下发扩展新增gw/{gs}/cmd主题平台向网关下发子设备控制指令typ扩展为ctrl控制、cfg配置离线消息扩展网关本地增加离线消息队列缓存网络异常期间的注册、状态数据重连后自动补发心跳机制网关定时发布typhb心跳报文至req主题平台接收后判定网关在线状态提升通信可靠性。文末说明本文协议专为物联网网关场景设计兼顾精简性与功能性可直接作为网关端开发的技术文档也可根据实际业务需求扩展指令下发、远程配置等功能。若需对接具体物联网平台可在响应报文中增加平台专属标识字段实现快速兼容。MQTT协议学习笔记深入解析版基于 MQTTJSON 的物联网网关物模型通讯协议极致精简・缩写版如果本文对你有帮助欢迎点赞、收藏、评论如有疑问或补充欢迎在评论区交流探讨日常深耕嵌入式、物联网、协议开发相关技术有技术答疑、项目合作、毕设指导需求均可私信私聊