4. MQTT协议基础
MQTT（Message Queuing Telemetry Transport，消息队列遥测传输）是物联网领域最主流的轻量级发布/订阅消息协议。它由IBM于1999年开发，2014年成为OASIS标准，专为低带宽、高延迟、不可靠网络环境下的设备通信而设计。在ThingsBoard平台中，MQTT是设备接入和数据采集的核心协议。
4.1 MQTT协议简介
MQTT基于TCP/IP协议栈，采用客户端-服务器架构，其中服务器称为Broker（代理/消息代理）。协议设计目标包括：最小化网络带宽消耗、降低代码占用空间、提供可靠的消息传递保障。
| 特性 | 描述 | 物联网场景价值 |
|---|---|---|
| 轻量级 | 最小报文头仅2字节 | 适合NB-IoT、2G/3G等窄带网络 |
| 双向通信 | 支持设备到云端、云端到设备 | 遥测上报与远程控制 |
| 异步模式 | 发布者与订阅者解耦 | 设备无需等待响应，节省功耗 |
| 会话感知 | 支持持久会话与离线消息 | 设备断线重连后数据不丢失 |
| QoS保障 | 三种服务质量等级 | 按需选择可靠性级别 |
4.2 发布/订阅模型
MQTT采用发布/订阅（Pub/Sub）模型，替代传统的客户端-服务器点对点通信。核心角色包括：
- 发布者（Publisher）： 发送消息到指定主题的设备或应用。
- 订阅者（Subscriber）： 订阅感兴趣的主题，接收该主题下的所有消息。
- 代理（Broker）： 接收发布者消息，过滤并分发给所有匹配的订阅者。
主题（Topic）是消息分类的层级结构，使用正斜杠（/）分隔，支持通配符：
+：单级通配符，匹配一个层级。例如sensor/+/temperature匹配sensor/room1/temperature。#：多级通配符，匹配剩余所有层级。例如sensor/#匹配sensor/temperature、sensor/humidity/outdoor等。
v1/devices/me/telemetry；设备属性上报到 v1/devices/me/attributes；RPC控制指令订阅 v1/devices/me/rpc/request/+。这些主题由ThingsBoard平台预定义，设备端需严格遵循。
4.3 QoS等级
服务质量（Quality of Service，QoS）定义了消息传递的可靠性级别。MQTT提供三个等级，适用于不同场景：
| QoS等级 | 名称 | 发送次数 | 确认机制 | 可靠性 | 适用场景 |
|---|---|---|---|---|---|
| 0 | 至多一次 | 1次 | 无确认 | 最低 | 高频传感器数据（温度、湿度），允许少量丢失 |
| 1 | 至少一次 | ≥1次 | PUBACK确认 | 中等 | 设备状态上报、告警事件，确保送达但可能重复 |
| 2 | 恰好一次 | 2次握手 | PUBREC/PUBREL/PUBCOMP | 最高 | 计费指令、关键控制命令，不允许重复或丢失 |
4.4 保留消息
保留消息（Retained Message）是MQTT的一项特殊机制：发布者发送消息时设置保留标志（RETAIN=1），Broker会存储该主题的最后一条保留消息。当新订阅者订阅该主题时，Broker立即将保留消息推送给订阅者，无需等待下一次发布。
保留消息的核心用途：
- 设备状态快照： 新接入的设备或应用立即获取最新状态，无需等待设备下次上报。
- 配置同步： 设备上线后立即获取云端下发的配置参数。
- 系统初始化： 仪表盘或监控系统启动时自动获取所有设备的当前值。
清除保留消息： 向同一主题发布一条空载荷（payload长度为0）且RETAIN=1的消息，即可清除该主题的保留消息。
v1/devices/me/attributes 主题上报属性时，ThingsBoard会自动存储最新值，设备重连后可通过 v1/devices/me/attributes/request/+ 获取。对于自定义MQTT主题，可在发布时设置RETAIN标志实现类似效果。
4.5 遗嘱消息
遗嘱消息（Will Message，简称遗嘱）是MQTT为处理设备异常离线而设计的机制。设备在连接Broker时，可以在CONNECT报文中指定遗嘱主题和遗嘱消息。当Broker检测到设备非正常断开连接时（如网络中断、设备掉电），会自动向遗嘱主题发布该遗嘱消息。
遗嘱消息的触发条件：
- 网络连接断开（TCP/IP超时）
- 设备异常掉电，未发送DISCONNECT报文
- Broker端Keep Alive超时
遗嘱消息的配置参数：
| 参数 | 说明 | 示例值 |
|---|---|---|
| Will Topic | 遗嘱消息发布的主题 | v1/devices/me/telemetry |
| Will Payload | 遗嘱消息的内容 | {"online": false} |
| Will QoS | 遗嘱消息的服务质量等级 | 1 |
| Will Retain | 是否保留遗嘱消息 | true |
server-side attributes功能，可实现设备在线状态自动管理。设备正常上线时主动上报 {"online": true}，异常离线时Broker自动发布 {"online": false}，无需设备端额外心跳逻辑。
4.6 MQTT报文结构速览
MQTT控制报文由固定头、可变头、有效载荷三部分组成。固定头最小仅2字节：
| 字段 | 长度 | 说明 |
|---|---|---|
| 报文类型 | 4 bit | CONNECT(1)、PUBLISH(3)、SUBSCRIBE(8) 等14种类型 |
| 标志位 | 4 bit | DUP、QoS、RETAIN等标志 |
| 剩余长度 | 1-4字节 | 可变头+有效载荷的总字节数，使用变长编码 |
常用报文类型：
- CONNECT： 客户端请求连接Broker，包含Client ID、用户名密码、遗嘱消息、Keep Alive等。
- CONNACK： Broker确认连接结果，返回连接状态码（0=成功，1-5=各类失败原因）。
- PUBLISH： 发布消息，包含主题名、载荷、QoS、RETAIN标志。
- SUBSCRIBE： 订阅主题，包含主题过滤器列表及对应的QoS等级。
- SUBACK： Broker确认订阅结果，返回每个主题的最大QoS等级。
- PINGREQ/PINGRESP： 心跳保活，用于维持连接。
- DISCONNECT： 客户端正常断开连接。