系列四 03|橋接 MQTT:在 LINE 查詢裝置狀態
本篇重點
- 理解為什麼橋接器要「記住」每台裝置的最新狀態
- 把程式拆成設定、狀態倉庫、MQTT 連線、Webhook 四個檔案
- 用 paho-mqtt 2.x 連上 HiveMQ Cloud,訂閱
iot/# - 處理上線/過期/離線三種狀態,與系列三儀表板的判斷一致
- 在 LINE 輸入「狀態」或「esp32-01」查詢即時數據
為什麼要「記住」,而不是「去問」?
直覺的做法是:使用者在 LINE 輸入「狀態」時,橋接器再去問 ESP32 現在幾度。但 MQTT 是「發布/訂閱」模式,沒有「問一下就回答」的機制;而且回覆 LINE 要越快越好,不適合現場等待。
所以橋接器的做法跟系列三的網頁儀表板一樣:平時就一直訂閱,每收到一則訊息就更新記憶體裡的資料。使用者查詢時,直接把記住的最新值拿出來回覆,幾乎零延遲。
這裡也用到了系列二學過的保留訊息(retained):橋接器每次啟動或重新連線,HiveMQ 都會立刻送來每個主題最後一則保留訊息,所以不必等裝置下一次回報,馬上就能查到資料。
程式架構:從一個檔案拆成四個
上一篇的 app.py 只有幾十行,接下來功能會越來越多,現在就先拆好結構:
| 檔案 | 負責的事 | 需要網路套件嗎 |
|---|---|---|
config.py | 讀取 .env、集中所有設定與主題名稱 | 否 |
device_store.py | 記住每台裝置的最新狀態、判斷三態、組文字 | 否(可單獨測試) |
mqtt_client.py | 連線 HiveMQ、訂閱、自動重連 | paho-mqtt |
app.py | Flask Webhook、處理 LINE 事件 | flask、line-bot-sdk |
這和系列三把 ESP32 程式拆出 config.h 是同一個道理:會變的東西放設定檔,邏輯放程式,而且邏輯和網路分開後,不用連線也能測試。
實作一:config.py
# config.py:橋接器的所有設定集中在這裡
# 金鑰從 .env 讀取;主題名稱請對照系列三第 01 篇的規劃
import os
from dotenv import load_dotenv
load_dotenv()
def _need(name):
value = os.getenv(name, "").strip()
if not value:
raise SystemExit(f"[設定錯誤] .env 缺少 {name}")
return value
# ---------- LINE ----------
LINE_CHANNEL_SECRET = _need("LINE_CHANNEL_SECRET")
LINE_CHANNEL_ACCESS_TOKEN = _need("LINE_CHANNEL_ACCESS_TOKEN")
LINE_ADMIN_USER_ID = _need("LINE_ADMIN_USER_ID")
# ---------- MQTT(HiveMQ Cloud)----------
MQTT_HOST = _need("MQTT_HOST")
MQTT_PORT = int(os.getenv("MQTT_PORT", "8883"))
MQTT_USER = _need("MQTT_USER")
MQTT_PASS = _need("MQTT_PASS")
MQTT_CLIENT_ID = os.getenv("MQTT_CLIENT_ID", "linebot-bridge")
# ---------- 主題結構(iot/<裝置>/<子主題>)----------
TOPIC_ROOT = "iot"
SUB_DATA = "data" # 感測數據(JSON)
SUB_STATUS = "status" # 上線狀態(online / offline,LWT)
SUB_INFO = "info" # 裝置資訊(JSON)
SUB_CMD = "cmd" # 控制指令(橋接器發布、ESP32 訂閱)
# 超過幾秒沒有新數據就視為「過期」(與系列三儀表板一致)
STALE_SECONDS = int(os.getenv("STALE_SECONDS", "120"))
# ---------- 控制 ----------
DEFAULT_LED_DEVICE = os.getenv("DEFAULT_LED_DEVICE", "esp32-01")
OLED_DEVICE = os.getenv("OLED_DEVICE", "esp32-02")
# ---------- 警報(分支 B 啟用)----------
ALERT_ENABLED = os.getenv("ALERT_ENABLED", "false").lower() == "true"
ALERT_COOLDOWN_MINUTES = int(os.getenv("ALERT_COOLDOWN_MINUTES", "30"))
# 欄位名稱: (下限, 上限),None 代表不檢查
ALERT_RULES = {
"temperature": (None, 30.0),
"humidity": (None, 80.0),
}
# ---------- 網頁伺服器 ----------
PORT = int(os.getenv("PORT", "5000"))
請先對照系列三的主題命名
本系列假設主題結構是 iot/<裝置名稱>/data、/status、/info,控制指令用 /cmd。如果你在系列三用的子主題名稱不同(例如 sensor、state),只要改 config.py 中 SUB_DATA 等四行,其他程式都不用動。
後半段的控制與警報設定(DEFAULT_LED_DEVICE、ALERT_*)第 05 篇和分支 B 才會用到,現在先放著。.env 的內容沿用第 01 篇的範本即可。
實作二:device_store.py(狀態倉庫)
# device_store.py:記住每台裝置的最新狀態(不依賴 LINE 或 MQTT 套件,可單獨測試)
import json
import threading
import time
# 欄位名稱 → (中文名稱, 單位);沒列到的欄位會用原名顯示
LABELS = {
"temperature": ("溫度", "°C"),
"temp": ("溫度", "°C"),
"humidity": ("濕度", "%"),
"hum": ("濕度", "%"),
"pressure": ("氣壓", "hPa"),
"lux": ("照度", "lx"),
"light": ("照度", "lx"),
"led": ("LED", ""),
}
# 這些欄位不顯示在數據清單中
HIDDEN_KEYS = {"device", "id", "ts", "time", "timestamp", "uptime", "rssi"}
STATE_TEXT = {
"online": "🟢 上線",
"stale": "🟡 過期",
"offline": "🔴 離線",
"unknown": "⚪ 未知",
}
def format_value(key, value):
name, unit = LABELS.get(key, (key, ""))
if isinstance(value, bool):
value = "開" if value else "關"
elif isinstance(value, float):
value = f"{value:.1f}"
return f"{name}:{value}{unit}"
class DeviceStore:
def __init__(self, root="iot", sub_data="data", sub_status="status",
sub_info="info", stale_seconds=120):
self.root = root
self.sub_data = sub_data
self.sub_status = sub_status
self.sub_info = sub_info
self.stale_seconds = stale_seconds
self._lock = threading.Lock()
self._devices = {}
def _entry(self, name):
return self._devices.setdefault(
name, {"data": {}, "status": None, "info": {}, "last_seen": None})
def handle(self, topic, payload):
"""處理一則 MQTT 訊息;認得的話回傳 (裝置名稱, 子主題),否則回傳 None"""
parts = topic.split("/")
if len(parts) != 3 or parts[0] != self.root:
return None
name, sub = parts[1], parts[2]
text = payload.decode("utf-8", errors="replace").strip()
if not text: # 空的保留訊息:代表這台裝置已被清除
with self._lock:
self._devices.pop(name, None)
return None
with self._lock:
if sub == self.sub_data:
obj = _loads(text)
if not isinstance(obj, dict):
return None
entry = self._entry(name)
entry["data"] = obj
entry["last_seen"] = time.time()
elif sub == self.sub_status:
obj = _loads(text)
if isinstance(obj, dict):
text = str(obj.get("state") or obj.get("status") or "")
self._entry(name)["status"] = text.lower()
elif sub == self.sub_info:
obj = _loads(text)
if isinstance(obj, dict):
self._entry(name)["info"] = obj
else:
return None
return name, sub
def names(self):
with self._lock:
return sorted(self._devices)
def snapshot(self, name):
with self._lock:
entry = self._devices.get(name)
if entry is None:
return None
return {"data": dict(entry["data"]), "status": entry["status"],
"info": dict(entry["info"]), "last_seen": entry["last_seen"]}
def state_of(self, name, now=None):
snap = self.snapshot(name)
if snap is None:
return "unknown"
if snap["status"] == "offline":
return "offline"
if snap["last_seen"] is None:
return "unknown"
now = time.time() if now is None else now
if now - snap["last_seen"] > self.stale_seconds:
return "stale"
return "online"
def _loads(text):
try:
return json.loads(text)
except ValueError:
return None
def ago_text(last_seen, now=None):
if last_seen is None:
return "尚無數據"
now = time.time() if now is None else now
sec = int(now - last_seen)
if sec < 60:
return f"{sec} 秒前"
if sec < 3600:
return f"{sec // 60} 分鐘前"
return f"{sec // 3600} 小時前"
def format_device(store, name, now=None):
snap = store.snapshot(name)
if snap is None:
return f"找不到裝置 {name}"
lines = [f"【{name}】{STATE_TEXT[store.state_of(name, now)]}"]
for key, value in snap["data"].items():
if key not in HIDDEN_KEYS:
lines.append(" " + format_value(key, value))
lines.append(f" 更新:{ago_text(snap['last_seen'], now)}")
return "\n".join(lines)
def format_summary(store, now=None):
names = store.names()
if not names:
return "目前還沒有收到任何裝置的資料。"
return "\n\n".join(format_device(store, n, now) for n in names)
幾個值得注意的設計:
- 主題拆解:
iot/esp32-01/data用/切成三段,中間就是裝置名稱。新增第三台裝置時完全不用改程式,這就是系列三第 01 篇主題規劃的回報。 - 空的保留訊息代表裝置已清除:系列三第 06 篇清除幽靈裝置時,是發布一則空的保留訊息;這裡收到空內容就把該裝置從清單移除,兩邊行為一致。
- 三種狀態:收到 LWT 的
offline為離線;超過STALE_SECONDS沒有新數據為過期;其餘為上線。判斷規則與系列三第 05 篇的儀表板相同。 - 欄位名稱轉中文:
LABELS把temperature顯示成「溫度」並加上單位。如果你的 JSON 用了其他欄位名,在這裡加一行即可。 - 執行緒鎖(Lock):MQTT 在背景執行緒寫入、Flask 在另一個執行緒讀取,用鎖避免同時存取出錯。
實作三:mqtt_client.py(連線 HiveMQ)
# mqtt_client.py:連線 HiveMQ、訂閱 iot/#,斷線時自動重連
import paho.mqtt.client as mqtt
import config
def start_mqtt(on_message):
"""建立 MQTT 連線並在背景執行;on_message(topic, payload) 會在收到訊息時被呼叫"""
client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
client_id=config.MQTT_CLIENT_ID)
client.username_pw_set(config.MQTT_USER, config.MQTT_PASS)
client.tls_set() # HiveMQ Cloud 使用 TLS(8883)
client.reconnect_delay_set(min_delay=1, max_delay=60)
def handle_connect(client, userdata, flags, reason_code, properties):
if reason_code.is_failure:
print("[MQTT] 連線失敗:", reason_code)
return
print("[MQTT] 已連線,訂閱", f"{config.TOPIC_ROOT}/#")
# 每次(重新)連線都要重新訂閱
client.subscribe(f"{config.TOPIC_ROOT}/#", qos=1)
def handle_disconnect(client, userdata, flags, reason_code, properties):
print("[MQTT] 連線中斷,稍後自動重連:", reason_code)
def handle_message(client, userdata, msg):
try:
on_message(msg.topic, msg.payload)
except Exception as e: # 單則訊息出錯不影響整體
print("[MQTT] 處理訊息失敗:", msg.topic, e)
client.on_connect = handle_connect
client.on_disconnect = handle_disconnect
client.on_message = handle_message
client.connect_async(config.MQTT_HOST, config.MQTT_PORT, keepalive=60)
client.loop_start() # 在背景執行緒處理收發與重連
return client
| 重點 | 說明 |
|---|---|
CallbackAPIVersion.VERSION2 | paho-mqtt 2.x 的新寫法,網路上很多舊教學沒有這個參數,照抄會出錯 |
在 on_connect 裡訂閱 | 斷線重連後會自動重新訂閱,不會「重連成功卻收不到訊息」 |
connect_async+loop_start | 在背景連線與收訊息,不會卡住 Flask;斷線會自動重試 |
client_id | 每個連線的 Client ID 必須唯一,否則會互相把對方踢下線 |
實作四:app.py(查詢版)
用下面的內容取代上一篇的 app.py:
# app.py(第 03 篇):橋接 MQTT,輸入「狀態」或裝置名稱查詢數據
from flask import Flask, abort, request
from linebot.v3 import WebhookHandler
from linebot.v3.exceptions import InvalidSignatureError
from linebot.v3.messaging import (ApiClient, Configuration, MessagingApi,
ReplyMessageRequest, TextMessage)
from linebot.v3.webhooks import MessageEvent, TextMessageContent
import config
from device_store import DeviceStore, format_device, format_summary
from mqtt_client import start_mqtt
app = Flask(__name__)
handler = WebhookHandler(config.LINE_CHANNEL_SECRET)
line_config = Configuration(access_token=config.LINE_CHANNEL_ACCESS_TOKEN)
# 裝置狀態倉庫+MQTT 連線(程式一啟動就開始訂閱)
store = DeviceStore(config.TOPIC_ROOT, config.SUB_DATA, config.SUB_STATUS,
config.SUB_INFO, config.STALE_SECONDS)
mqtt = start_mqtt(store.handle)
@app.route("/", methods=["GET"])
def home():
return f"Bridge OK, devices: {', '.join(store.names()) or 'none'}"
@app.route("/callback", methods=["POST"])
def callback():
signature = request.headers.get("X-Line-Signature", "")
body = request.get_data(as_text=True)
try:
handler.handle(body, signature)
except InvalidSignatureError:
abort(400)
return "OK"
def reply_text(event, text):
with ApiClient(line_config) as api_client:
MessagingApi(api_client).reply_message(ReplyMessageRequest(
reply_token=event.reply_token,
messages=[TextMessage(text=text)],
))
@handler.add(MessageEvent, message=TextMessageContent)
def handle_text(event):
text = event.message.text.strip()
if text == "狀態":
reply_text(event, format_summary(store))
elif text.lower() in store.names():
reply_text(event, format_device(store, text.lower()))
else:
reply_text(event, "請輸入「狀態」,或輸入裝置名稱,例如 esp32-01")
if __name__ == "__main__":
# use_reloader=False:避免開發模式重複啟動,建立兩條 MQTT 連線
app.run(host="0.0.0.0", port=config.PORT, use_reloader=False)
注意最後一行的 use_reloader=False:Flask 開發模式預設會啟動兩次程式來偵測檔案變更,這會建立兩條相同 Client ID 的 MQTT 連線,互相踢來踢去。
實作五:執行與測試
- 執行
python app.py,終端機應出現[MQTT] 已連線,訂閱 iot/#。 - 瀏覽器開
http://localhost:5000,應顯示Bridge OK, devices: esp32-01, esp32-02。 - 另一個視窗執行
cloudflared tunnel --url http://localhost:5000;如果網址變了,記得更新 LINE 後台的 Webhook URL。 - 在 LINE 輸入「狀態」,應收到類似:
【esp32-01】🟢 上線 溫度:25.3°C 濕度:60% 氣壓:1012.5hPa 更新:12 秒前 【esp32-02】🟢 上線 照度:320.0lx 更新:8 秒前
再輸入「esp32-02」,則只會回覆那一台的資料。試著拔掉 esp32-02 的電源,等 LWT 生效後再查一次,狀態會變成「🔴 離線」。
常見問題
Q1:一直顯示「目前還沒有收到任何裝置的資料」?
先看終端機有沒有「已連線」。沒有的話,檢查 .env 的 MQTT 帳密與主機名稱;有連線但沒資料,通常是主題名稱與系列三不一致(見上方的提醒),或 linebot-bridge 帳號沒有 iot/# 的訂閱權限。
Q2:終端機一直重複「連線中斷,稍後自動重連」?
最常見的原因是 Client ID 撞名:同時開了兩個橋接器,或別的程式也用 linebot-bridge 這個 ID。
Q3:數據顯示英文欄位名,例如 t: 25.3?
你的 JSON 欄位名稱不在 LABELS 裡,在 device_store.py 加一行 "t": ("溫度", "°C"), 即可。
Q4:裝置明明在線,卻顯示「過期」?
ESP32 回報間隔大於 STALE_SECONDS(預設 120 秒)。在 .env 加上 STALE_SECONDS=300 之類的值調整。
Q5:查詢的數據跟網頁儀表板不一樣?
兩者都讀同一個 HiveMQ,數據來源相同。差異通常只是更新時間點不同,等下一次回報就會一致。
延伸挑戰
- 單獨測試狀態倉庫:在 Python 互動模式建立
DeviceStore(),手動呼叫handle("iot/test/data", b'{"temperature": 28}'),再印出format_summary(store)。 - 讓「esp32-01」的查詢結果也顯示
info主題中的 IP 位址或韌體版本。 - 新增指令「清單」,只回覆目前所有裝置名稱與狀態圖示,不顯示數據。
下一篇預告
純文字的狀態查詢能用,但不夠好看。下一篇改用 Flex Message 做成一張張的裝置卡片,用顏色區分上線、過期、離線,再加上 Quick Reply 按鈕與圖文選單,讓使用者不用打字也能操作。
系列四:LINE Bot 與裝置互動
📚 系列總整理 |
🗺️ 系列四學習地圖
← 上一篇:02|第一個 Webhook |
下一篇:04|Flex 卡片與圖文選單 →
留言
張貼留言