MQTT 即時儀表板 04:讓 ESP32 接收指令,遠端控制 LED
這是「MQTT 即時儀表板」系列的第 4 篇。前三篇的資料都是 ESP32 往外送,這一篇要讓方向反過來:ESP32 訂閱一個指令主題,收到網頁客戶端發來的 on 或 off,就開關板子上的 LED,並把目前的狀態回報出去。這是 MQTT 雙向通訊的基本款,也是之後儀表板上控制按鈕的基礎。
本篇重點
・讓 ESP32 訂閱主題,並在回呼函式中處理收到的指令
・把「指令」與「狀態」分成兩個主題
・斷線重連後要重新訂閱,並同步狀態
・了解為什麼指令不應該加 Retained
難度:中等 預估時間:50 分鐘
・讓 ESP32 訂閱主題,並在回呼函式中處理收到的指令
・把「指令」與「狀態」分成兩個主題
・斷線重連後要重新訂閱,並同步狀態
・了解為什麼指令不應該加 Retained
難度:中等 預估時間:50 分鐘
一、設計:指令與狀態分開
控制裝置時,有個很重要的觀念:「我要它做什麼」與「它現在是什麼狀態」是兩件事,應該放在不同的主題:
| 主題 | 誰發布 | 誰訂閱 | 內容 |
|---|---|---|---|
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 的連線維護。
四、上傳與測試
- 替換設定後上傳,序列埠應該顯示連線成功,以及「已訂閱:iot/esp32-01/cmd/led」。
- 開啟 HiveMQ Cloud 的 Web Client,連線後訂閱
iot/esp32-01/#,這樣可以同時看到資料、指令與狀態。 - 發布指令:主題
iot/esp32-01/cmd/led,內容on。不要勾選 Retain。 - 你應該會看到:
- ESP32 的 LED 亮起。
- 序列埠顯示「收到 [iot/esp32-01/cmd/led]:on」與「LED:ON」。
- Web Client 收到
state/led的內容on。
- 再發布
off、toggle,確認 LED 與狀態都正確變化。 - 發布一個奇怪的內容,例如
hello,確認 ESP32 顯示「無法辨識的指令,已忽略」,LED 不變。
測試斷線重連
- 暫時關閉路由器或手機熱點,等序列埠顯示斷線,再重新開啟。
- 連線恢復後,序列埠應再次出現「已訂閱」。
- 再發布一次
on或off,確認 ESP32 仍然會回應。這證明重連後重新訂閱有生效。
五、為什麼指令不要加 Retained?
第 3 篇我們為了讓儀表板立刻看到資料,把狀態與資料都加了 Retained。但指令千萬不要加。做個實驗就知道為什麼:
- 在 Web Client 發布
on到cmd/led,這次勾選 Retain(如果你使用的工具有這個選項)。 - 讓 ESP32 斷電後重新啟動,或讓它斷線重連。
- 它一連上並重新訂閱,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 帳號密碼的人,都能對
現在任何拿到你 MQTT 帳號密碼的人,都能對
cmd/led 發布指令。因為我們還在學習階段,只控制一顆 LED 沒問題,但用來控制實際設備之前,必須把權限收緊,這會在第 6 篇處理。
下一篇預告
現在資料與指令都能透過 MQTT 流動了。下一篇我們要把它們做成一個即時網頁儀表板:用 HTML 與 JavaScript 透過 WebSocket 連上 Broker,顯示溫濕度,並提供按鈕控制 LED。
系列:MQTT 即時儀表板
目錄:系列總整理 | 上一篇:訂閱、除錯與保留訊息 | 下一篇:即時網頁儀表板
留言
張貼留言