MQTT 即時儀表板 04:讓 ESP32 接收指令,遠端控制 LED

這是「MQTT 即時儀表板」系列的第 4 篇。前三篇的資料都是 ESP32 往外送,這一篇要讓方向反過來:ESP32 訂閱一個指令主題,收到網頁客戶端發來的 on 或 off,就開關板子上的 LED,並把目前的狀態回報出去。這是 MQTT 雙向通訊的基本款,也是之後儀表板上控制按鈕的基礎。

本篇重點
・讓 ESP32 訂閱主題,並在回呼函式中處理收到的指令
・把「指令」與「狀態」分成兩個主題
・斷線重連後要重新訂閱,並同步狀態
・了解為什麼指令不應該加 Retained
難度:中等 預估時間:50 分鐘

一、設計:指令與狀態分開

控制裝置時,有個很重要的觀念:「我要它做什麼」與「它現在是什麼狀態」是兩件事,應該放在不同的主題:

MQTT 指令與狀態回報流程 網頁客戶端 按下開關 Broker ESP32 控制 LED ① 指令 cmd/led:on ② 狀態回報 state/led:on 前綴皆為 iot/esp32-01/
主題 誰發布 誰訂閱 內容
iot/esp32-01/cmd/led 網頁客戶端 ESP32 on、off、toggle
iot/esp32-01/state/led ESP32 網頁客戶端、儀表板 on 或 off

分開的好處是:儀表板上的開關要顯示的是裝置真實的狀態,而不是「我剛剛送出的指令」。如果 ESP32 沒有收到或沒做到,狀態主題不會變,畫面就不會騙人。(這是對第 1 篇主題規劃的補充,多了一個 state/led。)

二、材料準備

  • 已完成第 2、3 篇的 ESP32 與 DHT11
  • 板子上的內建 LED(多數開發板接在 GPIO 2,與系列一第 1 篇相同)。如果你的板子 LED 不在 GPIO 2,請修改程式中的 LED_PIN。
  • HiveMQ Cloud 的帳號憑證需有訂閱權限(第 1 篇建立的是「Publish and Subscribe」)

三、程式碼

這份程式是第 2 篇的完整版加上指令功能,保留了第 3 篇的 Retained 設定。請替換最上方的設定。

#include <WiFi.h>
#include <WiFiClientSecure.h>
#include <PubSubClient.h>
#include <time.h>
#include "DHT.h"

// ===== 需要修改的設定 =====
const char* WIFI_SSID = "你的WiFi名稱";
const char* WIFI_PASSWORD = "你的WiFi密碼";

const char* MQTT_HOST = "你的叢集網址.hivemq.cloud";
const int   MQTT_PORT = 8883;
const char* MQTT_USER = "你的MQTT帳號";
const char* MQTT_PASS = "你的MQTT密碼";

const char* DEVICE_ID = "esp32-01";
const int   LED_PIN = 2;               // 內建 LED 腳位
// ==========================

#define DHTPIN 4
#define DHTTYPE DHT11
DHT dht(DHTPIN, DHTTYPE);

WiFiClientSecure secureClient;
PubSubClient mqtt(secureClient);

String topicTelemetry;
String topicCmdLed;
String topicStateLed;

const unsigned long PUBLISH_INTERVAL = 5000;
const unsigned long RECONNECT_INTERVAL = 5000;
unsigned long lastPublish = 0;
unsigned long lastReconnect = 0;

bool ledState = false;

bool connectWiFi() {
  WiFi.mode(WIFI_STA);
  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
  unsigned long start = millis();
  while (WiFi.status() != WL_CONNECTED && millis() - start < 15000) {
    delay(500);
    Serial.print(".");
  }
  Serial.println();
  if (WiFi.status() == WL_CONNECTED) {
    Serial.print("WiFi 已連線,IP:");
    Serial.println(WiFi.localIP());
    return true;
  }
  Serial.println("WiFi 連線失敗");
  return false;
}

// 回報 LED 目前狀態(retained:新連線的儀表板能立刻知道現況)
void publishLedState() {
  if (!mqtt.connected()) return;
  mqtt.publish(topicStateLed.c_str(), ledState ? "on" : "off", true);
}

void setLed(bool on) {
  ledState = on;
  digitalWrite(LED_PIN, on ? HIGH : LOW);
  Serial.print("LED:");
  Serial.println(on ? "ON" : "OFF");
  publishLedState();
}

// 收到訂閱的訊息時,PubSubClient 會呼叫這個函式
void onMessage(char* topic, byte* payload, unsigned int length) {
  // 先把內容複製到自己的緩衝區,再處理
  char msg[16];
  unsigned int n = (length < sizeof(msg) - 1) ? length : sizeof(msg) - 1;
  memcpy(msg, payload, n);
  msg[n] = '\0';

  Serial.print("收到 [");
  Serial.print(topic);
  Serial.print("]:");
  Serial.println(msg);

  if (strcmp(topic, topicCmdLed.c_str()) == 0) {
    if (strcasecmp(msg, "on") == 0) {
      setLed(true);
    } else if (strcasecmp(msg, "off") == 0) {
      setLed(false);
    } else if (strcasecmp(msg, "toggle") == 0) {
      setLed(!ledState);
    } else {
      Serial.println("無法辨識的指令,已忽略");
    }
  }
}

bool connectMqtt() {
  Serial.print("連線 MQTT...");
  if (mqtt.connect(DEVICE_ID, MQTT_USER, MQTT_PASS)) {
    Serial.println("成功");
    // 重要:每次(重新)連線後都要重新訂閱
    if (mqtt.subscribe(topicCmdLed.c_str(), 1)) {
      Serial.print("已訂閱:");
      Serial.println(topicCmdLed);
    }
    publishLedState();   // 連線後同步一次狀態
    return true;
  }
  Serial.print("失敗,狀態碼:");
  Serial.println(mqtt.state());
  return false;
}

void publishTelemetry() {
  float hum = dht.readHumidity();
  float temp = dht.readTemperature();

  if (isnan(hum) || isnan(temp)) {
    Serial.println("DHT11 讀取失敗,這次不發布");
    return;
  }

  char payload[96];
  time_t now = time(nullptr);
  if (now > 1600000000) {
    snprintf(payload, sizeof(payload),
             "{\"temp\":%.1f,\"hum\":%.1f,\"ts\":%lu}",
             temp, hum, (unsigned long)now);
  } else {
    snprintf(payload, sizeof(payload),
             "{\"temp\":%.1f,\"hum\":%.1f}", temp, hum);
  }

  bool ok = mqtt.publish(topicTelemetry.c_str(), payload, true);
  Serial.print(ok ? "已發布:" : "發布失敗:");
  Serial.println(payload);
}

void setup() {
  Serial.begin(115200);
  delay(1000);

  pinMode(LED_PIN, OUTPUT);
  digitalWrite(LED_PIN, LOW);
  dht.begin();

  topicTelemetry = String("iot/") + DEVICE_ID + "/telemetry";
  topicCmdLed    = String("iot/") + DEVICE_ID + "/cmd/led";
  topicStateLed  = String("iot/") + DEVICE_ID + "/state/led";

  connectWiFi();
  configTime(8 * 3600, 0, "time.stdtime.gov.tw", "pool.ntp.org");

  secureClient.setInsecure();
  mqtt.setServer(MQTT_HOST, MQTT_PORT);
  mqtt.setBufferSize(256);
  mqtt.setCallback(onMessage);   // 註冊收到訊息時的處理函式
}

void loop() {
  if (WiFi.status() != WL_CONNECTED) {
    Serial.println("WiFi 已中斷,重新連線");
    connectWiFi();
    return;
  }

  if (!mqtt.connected()) {
    if (millis() - lastReconnect >= RECONNECT_INTERVAL) {
      lastReconnect = millis();
      connectMqtt();
    }
  } else {
    mqtt.loop();   // 處理收到的訊息,會觸發 onMessage

    if (millis() - lastPublish >= PUBLISH_INTERVAL) {
      lastPublish = millis();
      publishTelemetry();
    }
  }
}

新增的部分,逐項說明

  • mqtt.setCallback(onMessage):告訴 PubSubClient,收到訂閱的訊息時要呼叫哪個函式。實際觸發的時機是 mqtt.loop() 處理封包時,所以 loop() 必須經常被呼叫。
  • mqtt.subscribe(主題, 1):訂閱指令主題,第二個參數是 QoS,PubSubClient 可選 0 或 1。每次重新連線後都要重新訂閱,因為斷線後 Broker 不會替這個連線記住訂閱,只訂閱一次的話,斷線重連後就再也收不到指令了。
  • onMessage 的參數:依序是主題、內容、內容長度。內容是原始的位元組,結尾沒有字串結束符號,所以要自己複製到緩衝區再補上 '\0'。
  • 為什麼先複製再處理:PubSubClient 收到的內容放在它自己的內部緩衝區,而在回呼中呼叫 publish 會重複使用同一塊緩衝區,可能把原本的內容蓋掉。先複製到自己的變數,就不怕這個問題。
  • strcasecmp:不分大小寫比較,所以 ON、On、on 都能辨識。
  • publishLedState():每次 LED 改變,以及每次重新連線後,都回報一次狀態,並使用 Retained,讓之後才連上的儀表板立刻知道 LED 現在是亮是滅。
  • 回呼函式要快:不要在 onMessage 裡放 delay() 或耗時的工作,否則會卡住 MQTT 的連線維護。

四、上傳與測試

  1. 替換設定後上傳,序列埠應該顯示連線成功,以及「已訂閱:iot/esp32-01/cmd/led」。
  2. 開啟 HiveMQ Cloud 的 Web Client,連線後訂閱 iot/esp32-01/#,這樣可以同時看到資料、指令與狀態。
  3. 發布指令:主題 iot/esp32-01/cmd/led,內容 on。不要勾選 Retain。
  4. 你應該會看到:
    • ESP32 的 LED 亮起。
    • 序列埠顯示「收到 [iot/esp32-01/cmd/led]:on」與「LED:ON」。
    • Web Client 收到 state/led 的內容 on。
  5. 再發布 off、toggle,確認 LED 與狀態都正確變化。
  6. 發布一個奇怪的內容,例如 hello,確認 ESP32 顯示「無法辨識的指令,已忽略」,LED 不變。

測試斷線重連

  1. 暫時關閉路由器或手機熱點,等序列埠顯示斷線,再重新開啟。
  2. 連線恢復後,序列埠應再次出現「已訂閱」。
  3. 再發布一次 on 或 off,確認 ESP32 仍然會回應。這證明重連後重新訂閱有生效。

五、為什麼指令不要加 Retained?

第 3 篇我們為了讓儀表板立刻看到資料,把狀態與資料都加了 Retained。但指令千萬不要加。做個實驗就知道為什麼:

  1. 在 Web Client 發布 on 到 cmd/led,這次勾選 Retain(如果你使用的工具有這個選項)。
  2. 讓 ESP32 斷電後重新啟動,或讓它斷線重連。
  3. 它一連上並重新訂閱,Broker 就會把那則保留的 on 再送一次,LED 又被打開了,即使你早就不想開了。

也就是說,被保留的指令會在每次重新連線時被重複執行。如果是控制馬達、閥門、加熱器之類的設備,這樣很危險。原則是:

  • 指令:不保留,是一次性的動作。
  • 狀態、資料:可以保留,代表「最新的情況」。

如果真的不小心留下了保留的指令,用第 3 篇的方法對 cmd/led 發布一則空內容、帶 retain 的訊息,把它清除。

六、常見問題

  • 發布指令後 ESP32 沒反應:先看序列埠有沒有「已訂閱」。沒有的話,檢查帳號是否有訂閱權限。有的話,核對指令主題的拼寫與大小寫,包含 DEVICE_ID。
  • 序列埠有收到,但 LED 沒亮:你的板子 LED 可能不是 GPIO 2,或是低電位點亮(有些板子是 LOW 亮、HIGH 滅)。修改 LED_PIN,或把 HIGH 與 LOW 互換。
  • 只有第一次有效,斷線重連後就沒反應:重新訂閱的程式被漏掉了,確認 subscribe 在 connectMqtt() 裡面。
  • 收到的內容有多餘的字元或判斷失敗:檢查發布端有沒有多送空白或換行。程式只會比對 on、off、toggle,前後有多餘空白就會辨識失敗。
  • ESP32 不停斷線又連線:Client ID 重複,確認 Web Client 或其他工具沒有使用 esp32-01。
  • 發布很長的內容會被忽略:程式只取前 15 個字元,且 MQTT 緩衝區有大小限制,本篇的指令都很短。

七、延伸挑戰

  • 讓指令改用 JSON,例如 {"led":"on"},並在 ESP32 解析。(可以先用字串比對,之後再學 ArduinoJson 函式庫)
  • 再新增一個指令 blink,讓 LED 閃爍三次。注意不能在回呼函式中用 delay() 卡住,要想辦法用 millis() 在 loop() 裡完成。
  • 再加一顆外接 LED,用另一個腳位與另一組主題控制。
  • 如果日後想控制繼電器去開關家電,涉及市電,請務必確認元件規格與絕緣安全,不熟悉的話建議先尋求有經驗的人協助。
目前的安全狀況
現在任何拿到你 MQTT 帳號密碼的人,都能對 cmd/led 發布指令。因為我們還在學習階段,只控制一顆 LED 沒問題,但用來控制實際設備之前,必須把權限收緊,這會在第 6 篇處理。

下一篇預告

現在資料與指令都能透過 MQTT 流動了。下一篇我們要把它們做成一個即時網頁儀表板:用 HTML 與 JavaScript 透過 WebSocket 連上 Broker,顯示溫濕度,並提供按鈕控制 LED。


系列:MQTT 即時儀表板
目錄:系列總整理 | 上一篇:訂閱、除錯與保留訊息 | 下一篇:即時網頁儀表板

留言

熱門文章