单片机与物联网 / 系统课时

保障消息可靠性

保障消息可靠性

本节把 MQTT 控制链路补成可长期运行的版本:ESP32 断线后按退避策略重连,Broker 用遗嘱消息标记设备离线,控制消息使用 QoS 1 并按 id 去重,异常载荷被拒绝,未能发出的回执在重连后补发。目标是把“偶尔能控制”变成“故障行为可预期”。

学习目标

  • 用稳定客户端 ID、持久会话和退避重连降低短暂断网带来的消息丢失。
  • 正确理解 QoS 1 的“至少一次”语义,并用命令 ID 避免重复执行。
  • 配置保留的在线状态与遗嘱消息,同时拒绝异常数据并补发失败回执。

把可靠性拆成四个问题

断线重连解决“设备重新接入”,QoS 1 解决“Broker 需要再次投递”,命令去重解决“重发不能重复产生副作用”,遗嘱消息解决“控制端如何知道设备异常离线”。这四件事互相关联,但不能互相替代。

ESP32 MQTT 断线、遗嘱、QoS 1 重发与去重时序

需要特别记住: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 消息才能按其策略排队。

cpp
#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);
}

预期输出

text
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,用于主动模拟重复交付。

bash
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}'

预期结果

text
第一次消息执行 led.set;第二次消息输出 duplicate 并跳过 digitalWrite,只再次发送回执。

示例中的去重表只保存在 RAM,设备重启后会丢失。如果命令会触发扣费、开锁、一次性脉冲等不可重复副作用,应把已处理 ID 或业务状态持久化到 NVS,或者把操作本身设计成“设置到目标状态”,不要设计成“再执行一次”。

拒绝异常数据并补发回执

异常消息至少要检查长度、JSON 语法、必填字段、类型和动作白名单。对于无法解析、超长或未知动作,设备应保持当前硬件状态,只返回拒绝原因。示例还保存最后一个未成功提交的回执,在 MQTT 重连后调用 flushPendingAck() 再发一次。

这种单槽回执缓存适合教学与低频控制;高并发或必须跨重启保存时,应改成有容量上限的 outbox,并持久化到 NVS。无论采用哪种队列,都要定义过期策略,避免设备重连后补发已经失去业务意义的旧消息。

验证遗嘱与恢复行为

在观察端订阅状态主题,并保持窗口打开。

bash
mosquitto_sub -h <HOST> -p 1883 -t 'device/<ID>/status' -v

预期结果

text
device/<ID>/status online
device/<ID>/status offline
device/<ID>/status online

第一条 online 来自 ESP32 建连后的保留消息;中间的 offline 只会在 Broker 判断连接异常终止后由遗嘱发布,因此出现时间取决于网络和保活检测;设备重连后再次发布 online。如果程序主动调用正常的 MQTT 断开流程,Broker 不会把遗嘱当成普通下线通知。

可靠链路的验收标准不应只是“能重新连上”。更重要的是:断网期间状态可识别,恢复后不会因为重发把命令执行两次,异常消息不会改变设备状态,关键回执也有明确的补发或持久化策略。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

保障消息可靠性

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通