ESP32 MQTT 實作：感測資料穩定送進系統，斷線重連與離線暫存怎麼做

ESP32 MQTT 的做法很直接：ESP32 用內建的 Wi-Fi 連上網路，再用 MQTT 用戶端把感測資料發布到 broker，後端系統訂閱同一個 topic，把資料收進資料庫。範例程式半小時就能跑起來，要在工廠裡穩定跑一整年，還得多做五件事：斷線自動重連、網路斷掉時先把資料暫存、每筆資料帶設備自己量到的時間、供電要夠穩、每台設備有唯一身分。這篇就照這五件事拆開講。

我們把 ESP32 Wi-Fi 模組和溫度感測器接進系統的經驗裡，程式寫不出來的情況很少見，麻煩幾乎都出現在上線後第二週：某台設備半夜斷線就再也沒回來、看板上一段時間的溫度整個空白、補傳回來的資料時間全部擠在同一秒。MQTT 協定本身很穩，問題出在設備端程式沒把「網路一定會斷」當成前提。

如果你還不熟 broker、topic、QoS 這些名詞，建議先看 MQTT 是什麼，那篇用工廠的例子把基本觀念講完了；帳號與加密的設定則在 MQTT 三層防禦架構。這篇專心講設備端：ESP32 這一頭的程式和硬體要怎麼做，資料才會穩穩進系統。

MQTT 在工業現場已經是主流選擇。Eclipse 基金會 2022 年的物聯網與邊緣開發者調查 裡，有 49% 的受訪者把 MQTT 列為工業物聯網最偏好的通訊協定。設備數量也還在長，IoT Analytics 的統計 估計 2025 年底全球連網的物聯網設備約 211 億台。設備越多，每一台「斷線後能不能自己回來」就越重要，因為沒有人能一台一台去按重開。

ESP32 MQTT 架構速覽：五個穩定關鍵一張表看完

先講結論：一個能上線的 ESP32 MQTT 節點，程式分成四層：讀感測器、排隊暫存、MQTT 連線管理、設備健康回報。下表是全文的濃縮版，每一列對應後面一個段落。

整條資料路線長這樣。左邊是 ESP32 裡面的流程，右邊是 broker 之後的系統端：

重點在中間那個佇列：量到的資料一律先進佇列，連線正常就送出去，斷線就留在裡面等。讀感測器的程式完全不用管網路狀態，兩邊互不卡住。

資料進了系統之後，才是工廠真正用得到的部分：看板、異常通知、產能分析。我們做的 生產力管理系統 就是這一段，為傳統製造業建立生產可見性與異常管理，現場資料穩不穩，直接決定看板上的數字能不能信。手上已經有一批 ESP32 想接進系統，可以直接 加 LINE 問我們，把設備型號和想看的資料丟過來。

ESP32 MQTT 感測節點的硬體清單

一個節點最少五樣東西：ESP32 開發板、感測器、電源、外殼，以及現場的無線網路。下表是我們規劃時的起手清單，「選擇重點」那一欄是最常被省略、事後最難補的地方。

板子怎麼選：經典 ESP32、S3、C3 差在哪

做感測節點，經典款 ESP32 或較新的 ESP32-C3 就夠用，兩者都有 Wi-Fi 和藍牙，價格也低。ESP32-S3 運算比較強，也內建 USB，適合同一塊板子還要接螢幕或做簡單的影像處理。要跑攝影機、做邊緣 AI 就是另一個等級的晶片了，可以參考 ESP32-P4 入門指南 和 ESP32 機械手臂視覺辨識 兩篇。

還有一件事常被忽略：ESP32 多數型號只支援 2.4GHz Wi-Fi，工廠如果把基地台設成只發 5GHz，設備會連不上。Espressif 的 ESP32-C5 才開始支援雙頻，採購前先確認現場網路的設定，比買回來再退貨省事得多。

ESP32 MQTT 程式重點：Arduino 用 PubSubClient，ESP-IDF 用 ESP-MQTT

一句話分工：做概念驗證、團隊熟 Arduino，用 PubSubClient；要上正式產線、需要 QoS 1 和 TLS 加密，用 Espressif 官方的 ESP-MQTT。兩套差在下面這幾點：

PubSubClient 的限制寫在它的 GitHub 說明頁：只能發布 QoS 0，訊息含標頭預設上限 256 bytes，keepalive 預設 15 秒。JSON 稍微長一點就會超過 256 bytes，這時 publish 會直接回傳 false，很多人卡在這裡好幾個小時找不到原因，記得在 setup 裡呼叫 setBufferSize 調大。

Arduino 版：不會卡住主程式的重連寫法

PubSubClient 官方範例的重連函式是 while 迴圈加 delay(5000)，連不上就整個卡在那裡，感測器也跟著停止讀值。正式用要改成非阻塞：每一輪 loop 檢查一次，時間到了才試，失敗就把等待時間拉長。

#include <WiFi.h>
#include <PubSubClient.h>

const char* WIFI_SSID = "factory-iot";
const char* WIFI_PASS = "********";
const char* MQTT_HOST = "192.168.10.20";
const uint16_t MQTT_PORT = 1883;

WiFiClient net;
PubSubClient mqtt(net);
String clientId;
String statusTopic = "factory1/line2/oven03/status";
unsigned long lastTry = 0;
unsigned long retryMs = 5000;

void connectMqtt() {
  // 遺囑訊息：設備沒說再見就斷線時，broker 代發 offline（retain）
  if (mqtt.connect(clientId.c_str(), "node-oven03", "********",
                   statusTopic.c_str(), 1, true, "offline")) {
    mqtt.publish(statusTopic.c_str(), "online", true);
    retryMs = 5000;
  } else {
    Serial.printf("MQTT 連線失敗 state=%d\n", mqtt.state());
    retryMs = min(retryMs * 2, 60000UL);   // 5、10、20、40、60 秒
  }
}

void setup() {
  Serial.begin(115200);
  WiFi.mode(WIFI_STA);
  WiFi.setAutoReconnect(true);
  WiFi.begin(WIFI_SSID, WIFI_PASS);
  clientId = "esp32-" + WiFi.macAddress();
  clientId.replace(":", "");
  mqtt.setServer(MQTT_HOST, MQTT_PORT);
  mqtt.setBufferSize(512);   // 預設 256 bytes，JSON 長一點就不夠
  mqtt.setKeepAlive(30);
}

void loop() {
  if (WiFi.status() == WL_CONNECTED && !mqtt.connected()) {
    if (millis() - lastTry > retryMs + random(0, 3000)) {
      lastTry = millis();
      connectMqtt();
    }
  }
  mqtt.loop();
  // 讀感測器、送出佇列另外用 millis() 排程，不要用 delay() 卡住 loop
}

幾個細節要注意。client ID 用 MAC 位址產生，保證每台不同：MQTT 3.1.1 規格 寫明，同一個 client ID 再連進來，broker 必須把舊的那條連線踢掉，兩台設備用同一個 ID 就會無限互踢。遺囑訊息（Last Will）設成 retain，設備不告而別時 broker 會代發 offline，後台一眼就看得到誰掉線。等待時間加一點隨機數，避免 broker 重開時幾百台設備同一秒擠進來。

ESP-IDF 版：讓官方元件幫你重連和重送

ESP-MQTT 把連線管理都包好了。從 ESP-IDF 6.0 開始，它搬出主程式庫成為獨立元件，用 idf.py add-dependency espressif/mqtt 加進專案，完整設定見 ESP-MQTT 官方文件。下面是加上 TLS、帳密與遺囑訊息的最小設定：

#include "mqtt_client.h"

extern const char ca_pem_start[] asm("_binary_ca_pem_start");

static void mqtt_event_handler(void *arg, esp_event_base_t base,
                               int32_t event_id, void *event_data)
{
    esp_mqtt_event_handle_t event = event_data;
    switch ((esp_mqtt_event_id_t)event_id) {
    case MQTT_EVENT_CONNECTED:
        esp_mqtt_client_publish(event->client, "factory1/line2/oven03/status",
                                "online", 0, 1, 1);
        break;
    case MQTT_EVENT_DISCONNECTED:
        // 不用自己寫重連，client 預設 10 秒後自動重試
        break;
    default:
        break;
    }
}

void mqtt_start(void)
{
    const esp_mqtt_client_config_t cfg = {
        .broker.address.uri = "mqtts://broker.factory.local:8883",
        .broker.verification.certificate = ca_pem_start,
        .credentials.client_id = "esp32-oven03",
        .credentials.username = "node-oven03",
        .credentials.authentication.password = "********",
        .session.keepalive = 30,
        .session.last_will.topic = "factory1/line2/oven03/status",
        .session.last_will.msg = "offline",
        .session.last_will.qos = 1,
        .session.last_will.retain = 1,
    };
    esp_mqtt_client_handle_t client = esp_mqtt_client_init(&cfg);
    esp_mqtt_client_register_event(client, ESP_EVENT_ANY_ID, mqtt_event_handler, NULL);
    esp_mqtt_client_start(client);
}

官方文件寫得很清楚：用 esp_mqtt_client_publish 發 QoS 0，斷線時會直接失敗；發 QoS 1 或 2，訊息會留在 outbox 直到收到確認，重連後依序重送。要注意 outbox 預設放在記憶體裡，設備斷電重開就沒了，所以下一段講的離線暫存還是要做。

ESP32 MQTT 斷線重連：從錯誤代碼找原因

先講結論：連不上的時候先印出 state()，多數問題看代碼就知道往哪查。下表是 PubSubClient 的回傳值和我們排查的順序。

主程式卡太久，broker 會先把你踢掉

MQTT 規格規定，broker 在 keepalive 時間的 1.5 倍內沒收到設備任何封包，就要把連線當成斷了。PubSubClient 預設 keepalive 15 秒，主程式只要有一段卡超過二十多秒（例如讀感測器逾時、一次寫一大段快閃記憶體），broker 就會把設備踢掉。所以 loop 裡不要放長時間的 delay，耗時的工作要拆小，每一小段之間都讓 mqtt.loop() 有機會跑。

連不上太久就重開機

現場最難查的是「連不上也不報錯」的情況。PubSubClient 的 GitHub 上有一則 ESP32 跑二十分鐘後就一直回 -2、只能重開機才恢復 的回報，討論到最後也沒有一個標準答案。我們的做法很務實：程式裡加一個計時器，Wi-Fi 或 MQTT 連續斷超過十分鐘，就呼叫 ESP.restart() 重開機，再搭配硬體看門狗，防止程式本身卡死。

重開機次數一定要記下來回報。某台設備一天重開十幾次，代表供電或訊號有問題，要派人去現場看，光靠程式是修不好的。

離線暫存：網路斷掉的那段時間，資料要放哪裡

一句話：短時間斷線靠記憶體佇列撐，長時間斷線或資料一筆都不能掉的，再寫進快閃記憶體。幾種放法比較如下：

記憶體佇列怎麼寫

下面是最簡單的環形佇列，量到的資料先 enqueue，連上線後在 loop 裡呼叫 flushQueue 慢慢補送：

struct Reading { uint32_t ts; uint32_t seq; float value; };

const int QSIZE = 600;          // 每 10 秒一筆，大約撐 100 分鐘
Reading q[QSIZE];
int head = 0, count = 0;

void enqueue(const Reading& r) {
  q[(head + count) % QSIZE] = r;
  if (count < QSIZE) count++;
  else head = (head + 1) % QSIZE; // 滿了就丟掉最舊的一筆
}

void flushQueue() {
  int sent = 0;
  while (count > 0 && mqtt.connected() && sent < 20) {   // 每輪最多補 20 筆
    char buf[96];
    const Reading& r = q[head];
    snprintf(buf, sizeof(buf), "{\"ts\":%lu,\"seq\":%lu,\"t\":%.1f}",
             (unsigned long)r.ts, (unsigned long)r.seq, r.value);
    if (!mqtt.publish("factory1/line2/oven03/temperature", buf)) break;
    head = (head + 1) % QSIZE;
    count--;
    sent++;
  }
}

滿了就丟最舊的一筆，這是刻意的選擇：現場斷線太久時，最新的資料比最舊的資料有用。補傳時每一輪限制筆數，避免一恢復連線就把幾百筆一次灌進 broker，後端和其他設備都會被拖慢。

publish 回傳 true 不代表送到了

這是最常見的誤解。PubSubClient 只能發 QoS 0，publish 回傳 true 只代表資料寫進了網路連線，broker 有沒有收到並不保證，斷線前最後那幾筆常常就是這樣不見的。資料一筆都不能少的場景（例如報工數量）有兩種做法：改用 ESP-MQTT 發 QoS 1；或維持 QoS 0，讓後端用流水號比對，發現跳號就請設備從快閃記憶體補傳那一段。

不管哪一種，後端都要用「設備代號加流水號」去重，因為 QoS 1 本身就可能送到兩次。快閃記憶體也有寫入壽命，每筆量測都直接寫進去，很快就會寫壞。比較好的做法是先在記憶體累積，斷線超過一段時間才整批寫入，恢復連線補傳完再清掉。

時間戳與供電：ESP32 MQTT 資料準不準的兩個暗坑

時間戳要用設備量到的時間

ESP32 沒有靠電池維持的時鐘，每次開機時間都從 1970 年起算，一定要先對網路時間。Arduino 環境用 configTzTime 一行就能設定時區與 NTP 伺服器，台灣可以用國家時間與頻率標準實驗室的 time.stdtime.gov.tw。

#include <time.h>

bool timeReady = false;

void syncClock() {
  configTzTime("CST-8", "time.stdtime.gov.tw", "pool.ntp.org");
  struct tm t;
  timeReady = getLocalTime(&t, 10000);   // 最多等 10 秒
}

uint32_t nowEpoch() {
  time_t now;
  time(&now);
  return timeReady ? (uint32_t)now : 0;  // 0 代表時間還沒對好
}

時間還沒對好之前量到的資料，ts 填 0，後端看到 0 就改用收到的時間並加上註記，不要讓它混進正常資料。每筆資料我們建議長這樣：

{"dev":"oven03","ts":1792459320,"seq":10482,"boot":17,"t":182.4,"rssi":-67,"fw":"1.3.0"}

seq 是流水號，後端靠它判斷重複和漏掉；boot 是開機次數，存在 NVS 裡每次開機加一，看得出設備有沒有反覆重開；rssi 是 Wi-Fi 訊號強度，經驗上長期低於 -75 dBm 就容易斷線，要考慮移動基地台或加外接天線；fw 是韌體版本，量產後才知道哪幾台還在舊版。時間戳和流水號一開始沒放，之後要補就得每台重燒一次，這是最不划算的返工。

供電不穩，設備就會自己重開

ESP32 的 Wi-Fi 發射瞬間電流可以到兩百多毫安，用電腦 USB 孔或品質差的變壓器供電，電壓一掉就會觸發晶片的低電壓保護，序列埠會印出 Brownout detector was triggered，接著重開、重連，循環不停。現場看起來像「網路很爛」，追到最後常常是電源。

電池節點的取捨，ESP-IDF 睡眠模式文件 寫得很明白：深度睡眠與淺睡眠都不會維持 Wi-Fi 連線，只有 RTC 記憶體裡用 RTC_DATA_ATTR 標記的變數能保留下來。每次醒來都要重新連 Wi-Fi、連 broker，連線花的時間往往比量測本身長，所以工廠裡有插座的地方，我們一律建議插電。

從 3 台到 300 台：ESP32 MQTT 量產前要想好的事

先講結論：桌上三台跑得好，跟產線三百台跑得好，中間差的是「不用到現場就能管」的能力。下表是我們在量產前會逐項確認的清單。

另一個常被問到的是 PLC。很多機台的資料在 PLC 裡，要用 Modbus 或 OPC UA 才讀得出來，這段通常由設備商或系統整合商處理，他們用閘道器把數值轉成 MQTT 送出來，我們負責 broker 之後的系統端。ESP32 適合補的是機台本身沒有的資料：環境溫濕度、加裝的電流感測、人員按鈕報工。用同一類晶片做人員端應用的例子，可以看 NFC 加 ESP32 打卡系統。

ESP32 MQTT 專案自己做還是找人做？

先講結論：幾台設備做概念驗證，有韌體背景的同事自己來就好；要接進 MES、讓主管每天看同一面看板、資料要拿來算稼動率和追溯，系統端就值得找人做好。分工可以參考這張表：

預算最容易漏的是佈線與現場安裝。我們估價時會把軟體、硬體、佈線三塊拆開，佈線以市場行情來說每點大約 1,000 到 2,500 元，拆法細節在 MES 系統價格怎麼算。要比較套裝、系統整合商、客製開發三種廠商，可以看 MES 廠商怎麼選；感測資料往上接工單與報工、整套製造執行系統怎麼規劃，則在 客製化 MES 開發完整指南 有完整說明。

我們不太贊成中小工廠一開始就買整套 IoT 平台。平台適合已經清楚要收哪些資料的工廠，多數中小工廠的第一步，是先搞清楚哪幾個數字真的有人在看。拿一條產線、十幾顆 ESP32 跑兩個月，先證明資料有用，再決定要擴大成 工廠管理系統 還是串進 生產履歷系統，比一次買到位省錢得多。整體導入的順序可以參考 台灣製造業智慧製造導入指南。

如果你手上已經有幾台 ESP32 在跑，想把它們變成穩定的系統，我們很樂意 聽你聊聊現場的情況，或直接 加 LINE 把設備清單和想看的數字丟過來。這個值不值得做、從哪一段開始最划算，我們會直接告訴你，真的要動手再談範圍跟費用。