单片机与物联网 / 系统课时
保障消息可靠性
保障消息可靠性
本节把 MQTT 控制链路补成可长期运行的版本:ESP32 断线后按退避策略重连,Broker 用遗嘱消息标记设备离线,控制消息使用 QoS 1 并按 id 去重,异常载荷被拒绝,未能发出的回执在重连后补发。目标是把“偶尔能控制”变成“故障行为可预期”。
学习目标
- 用稳定客户端 ID、持久会话和退避重连降低短暂断网带来的消息丢失。
- 正确理解 QoS 1 的“至少一次”语义,并用命令 ID 避免重复执行。
- 配置保留的在线状态与遗嘱消息,同时拒绝异常数据并补发失败回执。
把可靠性拆成四个问题
断线重连解决“设备重新接入”,QoS 1 解决“Broker 需要再次投递”,命令去重解决“重发不能重复产生副作用”,遗嘱消息解决“控制端如何知道设备异常离线”。这四件事互相关联,但不能互相替代。

需要特别记住:QoS 1 允许重复交付。因此“收到两次”不是异常,而是协议为了避免丢失做出的取舍。真正会控制继电器、电机或门锁的命令必须设计成可去重或幂等。
建立断线重连与遗嘱状态
下面完整示例使用 Arduino ESP32、PubSubClient 和 ArduinoJson。控制消息格式为 {"id":"req-101","action":"led.set","value":true};请替换 <SSID>、<PASSWORD>、<HOST>、<USER>、<MQTT_PASSWORD> 和 <ID>。它使用稳定的 CLIENT_ID、cleanSession=false、QoS 1 订阅和保留遗嘱,重连失败时采用 1~30 秒退避。Broker 还需要允许持久会话,离线期间的 QoS 1 消息才能按其策略排队。
#include <WiFi.h>
#include <PubSubClient.h>
#include <ArduinoJson.h>
const char* WIFI_SSID = "<SSID>";
const char* WIFI_PASS = "<PASSWORD>";
const char* MQTT_HOST = "<HOST>";
const char* MQTT_USER = "<USER>";
const char* MQTT_PASS = "<MQTT_PASSWORD>";
constexpr uint16_t MQTT_PORT = 1883;
const char* CLIENT_ID = "esp32-<ID>";
const char* CONTROL_TOPIC = "device/<ID>/control";
const char* ACK_TOPIC = "device/<ID>/control/ack";
const char* STATUS_TOPIC = "device/<ID>/status";
constexpr int LED_PIN = 2;
WiFiClient network;
PubSubClient mqtt(network);
uint32_t nextReconnectAt = 0;
uint32_t reconnectDelayMs = 1000;
String recentIds[8];
size_t recentPos = 0;
char pendingAck[256] = "";
bool wasSeen(const char* id) {
for (const String& item : recentIds) {
if (item == id) {
return true;
}
}
return false;
}
void rememberId(const char* id) {
recentIds[recentPos] = id;
recentPos = (recentPos + 1) % 8;
}
void sendOrQueueAck(const char* id, const char* status, const char* detail) {
StaticJsonDocument<192> doc;
doc["id"] = id;
doc["status"] = status;
doc["detail"] = detail;
char payload[256];
serializeJson(doc, payload, sizeof(payload));
if (mqtt.connected() && mqtt.publish(ACK_TOPIC, payload, false)) {
pendingAck[0] = '\0';
Serial.printf("ack published id=%s status=%s\n", id, status);
return;
}
// 连接瞬间丢失时先保留最后一个回执,重连成功后再尝试发送。
snprintf(pendingAck, sizeof(pendingAck), "%s", payload);
Serial.printf("ack queued id=%s status=%s\n", id, status);
}
void flushPendingAck() {
if (pendingAck[0] == '\0') {
return;
}
if (mqtt.publish(ACK_TOPIC, pendingAck, false)) {
Serial.println("pending ack flushed");
pendingAck[0] = '\0';
}
}
void onMessage(char* topic, byte* payload, unsigned int length) {
if (strcmp(topic, CONTROL_TOPIC) != 0) {
return;
}
if (length == 0 || length > 256) {
sendOrQueueAck("unknown", "rejected", "invalid_length");
return;
}
StaticJsonDocument<384> doc;
if (deserializeJson(doc, payload, length)) {
sendOrQueueAck("unknown", "rejected", "invalid_json");
return;
}
if (!doc["id"].is<const char*>() ||
!doc["action"].is<const char*>() ||
!doc["value"].is<bool>()) {
sendOrQueueAck("unknown", "rejected", "invalid_schema");
return;
}
const char* id = doc["id"];
const char* action = doc["action"];
if (strcmp(action, "led.set") != 0) {
sendOrQueueAck(id, "rejected", "unsupported_action");
return;
}
// QoS 1 可能重复交付;重复 id 只回执,不再次操作硬件。
if (wasSeen(id)) {
Serial.printf("duplicate id=%s ignored\n", id);
sendOrQueueAck(id, "duplicate", "already_applied");
return;
}
bool on = doc["value"].as<bool>();
digitalWrite(LED_PIN, on ? HIGH : LOW);
rememberId(id);
Serial.printf("applied id=%s value=%s\n", id, on ? "true" : "false");
sendOrQueueAck(id, "ok", on ? "led_on" : "led_off");
}
void attemptMqttReconnect() {
if (mqtt.connected() || WiFi.status() != WL_CONNECTED) {
return;
}
uint32_t now = millis();
if ((int32_t)(now - nextReconnectAt) < 0) {
return;
}
bool ok = mqtt.connect(
CLIENT_ID,
MQTT_USER,
MQTT_PASS,
STATUS_TOPIC,
1,
true,
"offline",
false);
if (ok) {
reconnectDelayMs = 1000;
mqtt.publish(STATUS_TOPIC, "online", true);
mqtt.subscribe(CONTROL_TOPIC, 1);
flushPendingAck();
Serial.println("MQTT connected, status=online");
return;
}
Serial.printf("MQTT reconnect failed, retry in %lu ms\n",
(unsigned long)reconnectDelayMs);
nextReconnectAt = now + reconnectDelayMs;
reconnectDelayMs =
reconnectDelayMs < 15000 ? reconnectDelayMs * 2 : 30000;
}
void setup() {
Serial.begin(115200);
pinMode(LED_PIN, OUTPUT);
WiFi.persistent(false);
WiFi.setAutoReconnect(true);
WiFi.begin(WIFI_SSID, WIFI_PASS);
while (WiFi.status() != WL_CONNECTED) {
delay(500);
}
mqtt.setServer(MQTT_HOST, MQTT_PORT);
mqtt.setCallback(onMessage);
mqtt.setBufferSize(512);
mqtt.setKeepAlive(15);
}
void loop() {
attemptMqttReconnect();
if (mqtt.connected()) {
mqtt.loop();
}
delay(10);
}预期输出
MQTT connected, status=online
applied id=req-101 value=true
ack published id=req-101 status=ok
duplicate id=req-101 ignored
ack published id=req-101 status=duplicate退避间隔和实际日志顺序会受网络状态影响;若连接失败,会额外看到 MQTT reconnect failed, retry in <VALUE> ms。
处理重发与重复命令
控制端发布命令时使用 QoS 1,ESP32 也以 QoS 1 订阅。若 Broker 因确认丢失而再次投递同一命令,设备通过 id 判断它是否已执行。下面连续发送两次相同 id,用于主动模拟重复交付。
mosquitto_pub -h <HOST> -p 1883 -t 'device/<ID>/control' -q 1 -m '{"id":"req-101","action":"led.set","value":true}'
mosquitto_pub -h <HOST> -p 1883 -t 'device/<ID>/control' -q 1 -m '{"id":"req-101","action":"led.set","value":true}'预期结果
第一次消息执行 led.set;第二次消息输出 duplicate 并跳过 digitalWrite,只再次发送回执。示例中的去重表只保存在 RAM,设备重启后会丢失。如果命令会触发扣费、开锁、一次性脉冲等不可重复副作用,应把已处理 ID 或业务状态持久化到 NVS,或者把操作本身设计成“设置到目标状态”,不要设计成“再执行一次”。
拒绝异常数据并补发回执
异常消息至少要检查长度、JSON 语法、必填字段、类型和动作白名单。对于无法解析、超长或未知动作,设备应保持当前硬件状态,只返回拒绝原因。示例还保存最后一个未成功提交的回执,在 MQTT 重连后调用 flushPendingAck() 再发一次。
这种单槽回执缓存适合教学与低频控制;高并发或必须跨重启保存时,应改成有容量上限的 outbox,并持久化到 NVS。无论采用哪种队列,都要定义过期策略,避免设备重连后补发已经失去业务意义的旧消息。
验证遗嘱与恢复行为
在观察端订阅状态主题,并保持窗口打开。
mosquitto_sub -h <HOST> -p 1883 -t 'device/<ID>/status' -v预期结果
device/<ID>/status online
device/<ID>/status offline
device/<ID>/status online第一条 online 来自 ESP32 建连后的保留消息;中间的 offline 只会在 Broker 判断连接异常终止后由遗嘱发布,因此出现时间取决于网络和保活检测;设备重连后再次发布 online。如果程序主动调用正常的 MQTT 断开流程,Broker 不会把遗嘱当成普通下线通知。
可靠链路的验收标准不应只是“能重新连上”。更重要的是:断网期间状态可识别,恢复后不会因为重发把命令执行两次,异常消息不会改变设备状态,关键回执也有明确的补发或持久化策略。