MQTT 即時儀表板 05:用 HTML 與 JavaScript 做即時網頁儀表板
這是「MQTT 即時儀表板」系列的第 5 篇,也是系列的重頭戲。前幾篇我們在 Web Client 看資料、發指令,這一篇要自己做一個真正的儀表板:用單一 HTML 檔,顯示 ESP32 即時的溫度與濕度、趨勢圖、資料是否過期,並提供按鈕遠端控制 LED。不需要後端伺服器,也不需要安裝任何東西。
・讓瀏覽器透過 WebSocket 直接連上 HiveMQ Cloud
・Broker 的帳號密碼不寫死在網頁裡,由使用者開啟時輸入
・用第 2 篇的時間戳記判斷資料是否過期
・按鈕送出指令,LED 狀態則顯示 ESP32 實際回報的結果
難度:中等 預估時間:60 分鐘
一、整體架構
瀏覽器沒辦法直接使用 MQTT 的 TCP 連線,所以要走 WebSocket。HiveMQ Cloud 提供加密的 WebSocket 連接埠 8884,網頁上的 MQTT.js 函式庫連上它,訂閱 ESP32 的主題,就能即時收到資料。
二、為什麼密碼不寫在網頁裡?
網頁的原始碼,任何打開它的人都看得到。如果把 Broker 的帳號密碼寫死在 JavaScript 裡,再把網頁放到網路上,等於把鑰匙公開給所有人,他們可以用你的帳號收發訊息,包含控制你的 LED。
所以這個儀表板的做法是:網頁本身不含任何機密,開啟時由你自己輸入叢集網址、帳號與密碼。密碼只存在這次瀏覽的記憶體中,不會寫進任何地方。「記住設定」只會儲存叢集網址、帳號與裝置 ID,不會儲存密碼。
輸入的帳號依然有權限發布指令,只是不會被公開。更完整的做法是為儀表板建立專用的帳號,只給它需要的權限(訂閱資料與狀態、發布 LED 指令),這會在第 6 篇處理。
三、準備
- ESP32 已執行第 4 篇的程式,並持續發布
telemetry與state/led - HiveMQ Cloud 的叢集網址(不含協定與埠號)、帳號與密碼
- 一個瀏覽器,以及網路(程式會從 CDN 載入 MQTT.js)
- 一個文字編輯器,用來儲存 HTML 檔
四、完整程式碼
把下面的程式碼全部複製,貼到文字編輯器,存成 dashboard.html(編碼選 UTF-8),再用瀏覽器開啟檔案即可。不需要架設網站。
<!DOCTYPE html>
<html lang="zh-Hant">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ESP32 即時儀表板</title>
<style>
:root {
--bg: #f6f8fa; --card: #ffffff; --text: #222222; --muted: #666666;
--border: #d0d7de; --accent: #2b7bd6; --ok: #2e7d32; --bad: #d32f2f;
--warn: #b27a00; --temp: #d32f2f; --hum: #2b7bd6; --btn-text: #ffffff;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #12161b; --card: #1b2129; --text: #e6e6e6; --muted: #9aa4af;
--border: #2f3843; --accent: #5aa2f0; --ok: #5fc16a; --bad: #ef6a6a;
--warn: #f0b73c; --temp: #ef6a6a; --hum: #5aa2f0; --btn-text: #0d1117;
}
}
* { box-sizing: border-box; }
body {
margin: 0; padding: 16px; background: var(--bg); color: var(--text);
font-family: system-ui, -apple-system, "Segoe UI", "Noto Sans TC", "Microsoft JhengHei", sans-serif;
line-height: 1.6;
}
main { max-width: 760px; margin: 0 auto; }
h1 { font-size: 1.4rem; margin: 0 0 12px; }
h2 { font-size: 1rem; margin: 0 0 6px; color: var(--muted); font-weight: 600; }
.card { background: var(--card); border: 1px solid var(--border); border-radius: 10px; padding: 14px 16px; margin-bottom: 14px; }
.grid { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; }
@media (max-width: 560px) { .grid { grid-template-columns: 1fr; } }
.row { display: flex; gap: 12px; flex-wrap: wrap; margin-bottom: 10px; align-items: flex-end; }
label { display: flex; flex-direction: column; font-size: 0.85rem; color: var(--muted); flex: 1 1 200px; }
label.chk { flex-direction: row; gap: 6px; align-items: center; margin-bottom: 10px; }
input[type=text], input[type=password], input:not([type]) {
margin-top: 4px; padding: 8px 10px; font-size: 1rem; color: var(--text); background: var(--bg);
border: 1px solid var(--border); border-radius: 6px;
}
button {
padding: 8px 16px; font-size: 1rem; border: 0; border-radius: 6px; cursor: pointer;
background: var(--accent); color: var(--btn-text); font-weight: 600;
}
button:disabled { opacity: 0.45; cursor: not-allowed; }
button.sec { background: transparent; color: var(--text); border: 1px solid var(--border); }
.badge { padding: 4px 10px; border-radius: 999px; font-size: 0.85rem; border: 1px solid var(--border); color: var(--muted); }
.badge[data-state=ok] { color: var(--ok); border-color: var(--ok); }
.badge[data-state=bad] { color: var(--bad); border-color: var(--bad); }
.badge[data-state=warn] { color: var(--warn); border-color: var(--warn); }
.big { font-size: 2.6rem; font-weight: 700; line-height: 1.2; }
.big small { font-size: 1.1rem; font-weight: 500; color: var(--muted); }
#temp { color: var(--temp); }
#hum { color: var(--hum); }
canvas { width: 100%; height: 90px; display: block; margin-top: 6px; }
.stale { color: var(--bad); font-weight: 700; }
.led { display: inline-block; width: 14px; height: 14px; border-radius: 50%; background: var(--border); vertical-align: middle; margin-right: 6px; }
.led[data-on=on] { background: #f5c518; box-shadow: 0 0 8px #f5c518; }
.led[data-on=off] { background: var(--muted); }
ul#log { list-style: none; margin: 0; padding: 0; font-size: 0.85rem; color: var(--muted); font-family: ui-monospace, Menlo, Consolas, monospace; }
ul#log li { padding: 2px 0; border-bottom: 1px dashed var(--border); word-break: break-all; }
.note { font-size: 0.8rem; color: var(--muted); }
</style>
</head>
<body>
<main>
<h1>ESP32 即時儀表板</h1>
<section class="card">
<div class="row">
<label>叢集網址
<input id="host" type="text" placeholder="xxxxxxxx.s1.eu.hivemq.cloud" autocomplete="off">
</label>
<label>裝置 ID
<input id="device" type="text" value="esp32-01" autocomplete="off">
</label>
</div>
<div class="row">
<label>MQTT 帳號
<input id="user" type="text" autocomplete="username">
</label>
<label>MQTT 密碼
<input id="pass" type="password" autocomplete="current-password">
</label>
</div>
<label class="chk"><input type="checkbox" id="remember"> 記住叢集網址、帳號與裝置 ID(不會儲存密碼)</label>
<div class="row">
<button id="btnConnect">連線</button>
<button id="btnDisconnect" class="sec" disabled>中斷連線</button>
<span id="status" class="badge" data-state="idle">未連線</span>
</div>
</section>
<section class="grid">
<div class="card">
<h2>溫度</h2>
<div class="big" id="temp">--<small> °C</small></div>
<canvas id="chartTemp"></canvas>
</div>
<div class="card">
<h2>濕度</h2>
<div class="big" id="hum">--<small> %</small></div>
<canvas id="chartHum"></canvas>
</div>
</section>
<section class="card">
<div class="row">
<div>資料時間:<span id="age">尚未收到資料</span></div>
<div>LED 狀態:<span class="led" id="ledDot" data-on="unknown"></span><span id="ledText">未知</span></div>
</div>
<div class="row">
<button id="btnOn" disabled>開燈</button>
<button id="btnOff" class="sec" disabled>關燈</button>
<button id="btnToggle" class="sec" disabled>切換</button>
</div>
<div class="note">按鈕送出的是指令;上方的 LED 狀態是 ESP32 實際回報的結果。</div>
</section>
<section class="card">
<h2>最近訊息</h2>
<ul id="log"></ul>
</section>
</main>
<script src="https://cdn.jsdelivr.net/npm/mqtt@5.10.4/dist/mqtt.min.js"></script>
<script>
(function () {
'use strict';
var STALE_SEC = 30; // 超過幾秒沒有新資料,視為過期
var MAX_POINTS = 120; // 圖表最多保留幾筆
var MAX_LOG = 12; // 最近訊息最多顯示幾行
var client = null;
var topics = null;
var lastTs = null; // 最新一筆資料的時間(毫秒)
var temps = [];
var hums = [];
function $(id) { return document.getElementById(id); }
function cssVar(name) {
return getComputedStyle(document.documentElement).getPropertyValue(name).trim();
}
function setStatus(text, state) {
var s = $('status');
s.textContent = text;
s.setAttribute('data-state', state || 'idle');
}
function addLog(text) {
var li = document.createElement('li');
var t = new Date().toLocaleTimeString('zh-TW', { hour12: false });
li.textContent = t + ' ' + text;
var list = $('log');
list.insertBefore(li, list.firstChild);
while (list.children.length > MAX_LOG) {
list.removeChild(list.lastChild);
}
}
// ===== 記住設定(不含密碼)=====
function loadSaved() {
try {
if (localStorage.getItem('dash.remember') === '1') {
$('remember').checked = true;
$('host').value = localStorage.getItem('dash.host') || '';
$('user').value = localStorage.getItem('dash.user') || '';
$('device').value = localStorage.getItem('dash.device') || 'esp32-01';
}
} catch (e) { /* 瀏覽器不允許儲存時略過 */ }
}
function saveInputs() {
try {
if ($('remember').checked) {
localStorage.setItem('dash.remember', '1');
localStorage.setItem('dash.host', $('host').value.trim());
localStorage.setItem('dash.user', $('user').value.trim());
localStorage.setItem('dash.device', $('device').value.trim());
} else {
localStorage.removeItem('dash.remember');
localStorage.removeItem('dash.host');
localStorage.removeItem('dash.user');
localStorage.removeItem('dash.device');
}
} catch (e) { /* 略過 */ }
}
// ===== 畫面更新 =====
function setConnectedUi(connected) {
$('btnConnect').disabled = connected;
$('btnDisconnect').disabled = !connected;
$('btnOn').disabled = !connected;
$('btnOff').disabled = !connected;
$('btnToggle').disabled = !connected;
}
function setLedUi(value) {
var dot = $('ledDot');
if (value === 'on') {
dot.setAttribute('data-on', 'on');
$('ledText').textContent = '亮';
} else if (value === 'off') {
dot.setAttribute('data-on', 'off');
$('ledText').textContent = '滅';
} else {
dot.setAttribute('data-on', 'unknown');
$('ledText').textContent = '未知';
}
}
function ageText(sec) {
if (sec < 60) return sec + ' 秒前';
if (sec < 3600) return Math.floor(sec / 60) + ' 分鐘前';
return Math.floor(sec / 3600) + ' 小時前';
}
function updateAge() {
var el = $('age');
if (lastTs === null) {
el.textContent = '尚未收到資料';
el.className = '';
return;
}
var sec = Math.max(0, Math.round((Date.now() - lastTs) / 1000));
if (sec > STALE_SEC) {
el.textContent = ageText(sec) + '(資料已過期,裝置可能離線)';
el.className = 'stale';
} else {
el.textContent = ageText(sec);
el.className = '';
}
return sec;
}
function drawSpark(canvas, data, color) {
var dpr = window.devicePixelRatio || 1;
var w = canvas.clientWidth;
var h = canvas.clientHeight;
if (w === 0 || h === 0) return;
canvas.width = w * dpr;
canvas.height = h * dpr;
var ctx = canvas.getContext('2d');
ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
ctx.clearRect(0, 0, w, h);
ctx.font = '11px sans-serif';
ctx.fillStyle = cssVar('--muted');
if (data.length < 2) {
ctx.fillText('資料不足', 4, h / 2);
return;
}
var min = Math.min.apply(null, data);
var max = Math.max.apply(null, data);
if (max - min < 1) { min -= 0.5; max += 0.5; }
var padTop = 14, padBottom = 4;
ctx.strokeStyle = color;
ctx.lineWidth = 2;
ctx.beginPath();
for (var i = 0; i < data.length; i++) {
var x = (i / (data.length - 1)) * (w - 8) + 4;
var y = padTop + (1 - (data[i] - min) / (max - min)) * (h - padTop - padBottom);
if (i === 0) ctx.moveTo(x, y); else ctx.lineTo(x, y);
}
ctx.stroke();
ctx.fillText('最高 ' + max.toFixed(1) + ' 最低 ' + min.toFixed(1), 4, 10);
}
function redrawCharts() {
drawSpark($('chartTemp'), temps, cssVar('--temp'));
drawSpark($('chartHum'), hums, cssVar('--hum'));
}
// ===== 處理收到的訊息 =====
function handleTelemetry(text) {
var d;
try { d = JSON.parse(text); } catch (e) { addLog('JSON 格式錯誤:' + text); return; }
if (!d || typeof d.temp !== 'number' || typeof d.hum !== 'number') {
addLog('缺少 temp 或 hum 欄位');
return;
}
$('temp').innerHTML = d.temp.toFixed(1) + '<small> °C</small>';
$('hum').innerHTML = d.hum.toFixed(1) + '<small> %</small>';
// 優先使用裝置端的時間戳記(Epoch 秒),沒有就用收到的時間
lastTs = (typeof d.ts === 'number') ? d.ts * 1000 : Date.now();
// 過期的資料(例如剛連線時收到的舊保留訊息)不畫進圖表
var sec = updateAge();
if (sec <= STALE_SEC) {
temps.push(d.temp);
hums.push(d.hum);
if (temps.length > MAX_POINTS) temps.shift();
if (hums.length > MAX_POINTS) hums.shift();
redrawCharts();
}
}
function onMessage(topic, payload, packet) {
var text = payload.toString();
addLog(topic + ' = ' + text + (packet && packet.retain ? '(保留訊息)' : ''));
if (topic === topics.telemetry) {
handleTelemetry(text);
} else if (topic === topics.stateLed) {
setLedUi(text.trim().toLowerCase());
}
}
// ===== 連線 =====
function connect() {
if (typeof mqtt === 'undefined') {
setStatus('無法載入 MQTT 函式庫', 'bad');
return;
}
var host = $('host').value.trim().replace(/^[a-z]+:\/\//i, '').replace(/[\/:].*$/, '');
var user = $('user').value.trim();
var pass = $('pass').value;
var device = $('device').value.trim();
if (!host || !user || !pass || !device) {
setStatus('請填寫所有欄位', 'warn');
return;
}
saveInputs();
if (client) disconnect(true); // 避免重複點擊造成多個連線
$('btnConnect').disabled = true;
topics = {
telemetry: 'iot/' + device + '/telemetry',
stateLed: 'iot/' + device + '/state/led',
cmdLed: 'iot/' + device + '/cmd/led'
};
setStatus('連線中…', 'warn');
client = mqtt.connect('wss://' + host + ':8884/mqtt', {
username: user,
password: pass,
clientId: 'dashboard-' + Math.random().toString(16).slice(2, 10),
keepalive: 30,
reconnectPeriod: 3000,
connectTimeout: 10000,
clean: true
});
client.on('connect', function () {
setStatus('已連線', 'ok');
setConnectedUi(true);
addLog('已連線,訂閱 ' + topics.telemetry + ' 與 ' + topics.stateLed);
client.subscribe([topics.telemetry, topics.stateLed], { qos: 0 }, function (err) {
if (err) addLog('訂閱失敗:' + err.message);
});
});
client.on('message', onMessage);
client.on('reconnect', function () { setStatus('重新連線中…', 'warn'); });
client.on('close', function () {
if (client) { setStatus('連線中斷', 'bad'); }
setConnectedUi(false);
});
client.on('error', function (err) {
addLog('錯誤:' + err.message);
// 帳密錯誤時重試也沒用,直接停止
if (/not authorized|bad user/i.test(err.message)) {
setStatus('帳號或密碼錯誤', 'bad');
disconnect(true);
}
});
}
function disconnect(keepStatus) {
if (client) {
var c = client;
client = null;
c.end(true);
}
setConnectedUi(false);
if (!keepStatus) setStatus('未連線', 'idle');
}
function sendCmd(cmd) {
if (!client || !client.connected) return;
// 指令不使用 retain,避免裝置重新連線時重複執行
client.publish(topics.cmdLed, cmd, { qos: 1, retain: false });
addLog('送出指令 ' + topics.cmdLed + ' = ' + cmd);
}
// ===== 事件綁定 =====
$('btnConnect').addEventListener('click', connect);
$('btnDisconnect').addEventListener('click', function () { disconnect(false); });
$('btnOn').addEventListener('click', function () { sendCmd('on'); });
$('btnOff').addEventListener('click', function () { sendCmd('off'); });
$('btnToggle').addEventListener('click', function () { sendCmd('toggle'); });
$('pass').addEventListener('keydown', function (e) { if (e.key === 'Enter') connect(); });
window.addEventListener('resize', redrawCharts);
loadSaved();
redrawCharts();
setInterval(updateAge, 1000);
})();
</script>
</body>
</html>
五、使用方式
- 用瀏覽器開啟
dashboard.html。 - 填入叢集網址(例如
xxxx.s1.eu.hivemq.cloud,不要加wss://或埠號;程式會自動處理,就算誤貼了也會去掉)、裝置 ID(預設esp32-01)、MQTT 帳號與密碼。 - 按「連線」。狀態變成綠色的「已連線」後,幾秒內就會看到溫度與濕度。
- 按「開燈」「關燈」「切換」,ESP32 的 LED 會亮或滅,上方的 LED 狀態也會跟著變化。
六、程式重點說明
1. 載入 MQTT.js
程式用 jsDelivr 載入 MQTT.js 的瀏覽器版本,並固定在 5.10.4 版:
<script src="https://cdn.jsdelivr.net/npm/mqtt@5.10.4/dist/mqtt.min.js"></script>
固定版本號是為了避免函式庫日後改版,讓你的儀表板突然壞掉。載入後,瀏覽器裡會多一個全域的 mqtt 物件。
2. 連線網址
mqtt.connect('wss://' + host + ':8884/mqtt', { username, password, ... })
三個地方缺一不可:wss://(加密的 WebSocket)、埠號 8884、結尾的路徑 /mqtt。用成 8883 埠,或漏掉路徑,是瀏覽器端最常見的連線失敗原因。
3. Client ID 隨機產生
每次連線都用 dashboard- 加隨機字串當 Client ID,避免和 ESP32 或其他分頁重複,造成互相踢下線。
4. 訂閱與收訊息
連線成功(connect 事件)後訂閱 telemetry 與 state/led,收到訊息會觸發 message 事件。資料是 JSON,程式用 JSON.parse 解析,並檢查 temp、hum 是不是數字,格式不對就記錄在「最近訊息」裡,不會讓畫面壞掉。
5. 資料過期判斷
這是第 3 篇預告過的功能。程式優先用 ESP32 送來的時間戳記 ts,換算出「這筆資料是幾秒前的」,超過 30 秒就用紅字顯示「資料已過期,裝置可能離線」。因此,就算 Broker 傳來的是舊的保留訊息,畫面也不會被騙。過期的資料也不會被畫進趨勢圖。
這個判斷拿的是 ESP32 的時間與你電腦的時間相比,兩邊的時鐘如果差距很大(例如電腦的時間設定錯誤),會誤判。ESP32 有用 NTP 對時,通常只要你的電腦時間正確就沒問題。
6. 控制按鈕:指令與狀態分開
client.publish(topics.cmdLed, cmd, { qos: 1, retain: false });
按鈕只負責送出指令,並且明確指定不保留(retain: false),避免 ESP32 重新連線時重複執行。畫面上的 LED 燈號顯示的則是 state/led 的內容,也就是 ESP32 實際回報的狀態。如果 ESP32 離線,按了按鈕,燈號也不會變,這樣畫面才不會騙人。
7. 趨勢圖
圖表是用 Canvas 自己畫的,沒有引入額外的函式庫,只保留最近 120 筆資料,並自動調整範圍。這是為了讓整個儀表板維持單一檔案。
8. 自動重連
MQTT.js 預設會在斷線後自動重連,程式設定每 3 秒重試。例外是帳號或密碼錯誤:重試也沒用,所以偵測到之後會直接停止,並顯示「帳號或密碼錯誤」。
七、測試清單
- 資料更新:連線後,溫濕度應每 5 秒更新,趨勢圖逐漸延伸。
- 呵氣測試:對 DHT11 呵氣,濕度數值與圖表明顯上升。
- 控制 LED:按「開燈」,ESP32 的 LED 亮起,畫面上的 LED 狀態也變成「亮」。
- 過期警示:把 ESP32 拔掉電源,約 30 秒後「資料時間」會變成紅字的「資料已過期」。接回電源後會恢復。
- 保留訊息:重新整理頁面並再次連線,應該立刻看到最近的資料與 LED 狀態,不用等下一次更新。
- 錯誤密碼:故意輸入錯誤的密碼,應顯示「帳號或密碼錯誤」,不會一直重試。
八、放到網路上(選用)
最簡單的用法是把檔案存在自己的電腦,需要時打開。如果你想從手機或其他電腦也能用,可以把它放到網路上。因為網頁本身不含任何機密,公開並不會洩漏你的 MQTT 帳密,但別人也無法使用它來連你的 Broker,除非他們有你的帳號密碼。
- GitHub Pages 或其他靜態網站空間:上傳
dashboard.html即可。 - 放進 Blogger 的「頁面」:新增一個頁面,切到「HTML 檢視」貼入完整程式碼。要小心:貼上後不要切換回「撰寫」模式,否則編輯器可能會改動程式碼中的符號。Blogger 的版型樣式也可能影響畫面外觀。如果發現畫面或功能異常,改用上面的靜態網站方式。
九、常見問題
- 一直停在「連線中」或顯示「連線中斷」:確認叢集網址正確、埠號是 8884,而且你的網路沒有擋掉 WebSocket。可以換手機熱點測試。
- 顯示「帳號或密碼錯誤」:檢查帳號密碼有沒有多餘的空白,並確認該憑證有訂閱與發布權限。
- 顯示「無法載入 MQTT 函式庫」:CDN 沒有載入,檢查網路,或廣告攔截、公司網路是否擋掉了 jsDelivr。
- 連線成功,但沒有資料:確認 ESP32 在線上、裝置 ID 與 ESP32 程式的
DEVICE_ID一致。可以先在 HiveMQ 的 Web Client 訂閱iot/esp32-01/#確認有資料。 - 一直顯示「資料已過期」:通常是 ESP32 沒有對時成功(沒有
ts,或時間不對),或電腦的時間不準確。 - 按了按鈕,ESP32 沒反應:先看「最近訊息」是否有「送出指令」,再回到第 4 篇的常見問題檢查 ESP32 是否有訂閱成功。
- 手機版畫面太擠:程式已做基本的響應式設計,如果還是不理想,可以調整 CSS 中的
.grid設定。
十、延伸挑戰
- 新增「狀態」主題的顯示:訂閱
iot/esp32-01/status,在畫面上顯示裝置上線或離線(第 6 篇會把 ESP32 這一端做好)。 - 用
localStorage儲存最近的資料點,重新整理頁面後,趨勢圖不會從零開始。 - 修改
STALE_SEC,讓過期判斷更嚴格或更寬鬆,觀察效果。 - 支援多台裝置:在畫面上加上裝置選單,切換訂閱的主題。
下一篇預告
儀表板已經能用了,但安全上還有幾個缺口:所有裝置共用同一個帳號、ESP32 沒有驗證伺服器的身分、而且 ESP32 意外斷線時,儀表板只能靠「資料過期」來猜。下一篇是系列的最後一篇,我們要做權限分離、改用憑證驗證,並加入 LWT 遺囑訊息,讓斷線偵測更可靠。
系列:MQTT 即時儀表板
目錄:系列總整理 | 學習地圖 | 上一篇:讓 ESP32 接收指令 | 下一篇:連線安全與斷線偵測
留言
張貼留言