從 Three.js 網頁動畫到 MQTT 物聯網控制:手機、網頁與 ESP32 的虛實整合實作
手機按下一個按鈕,網頁中的 3D 立方體改變光線,同時 ESP32 的 LED 也跟著亮起。這不是手機直接連到網頁或開發板,而是三個不同的程式透過 MQTT Broker 交換訊息。本篇從可操作的最小範例出發,帶你完成虛擬與實體同步控制。
學習成果:理解 Three.js 3D 渲染、MQTT Publish/Subscribe、Topic、Payload、WebSocket、Wi-Fi 與 MicroPython,並能逐層診斷連線問題。
一、從原有的動畫與燈光控制案例出發
台灣工藝創客青創基地曾展示「物聯網燈光控制」與「物聯網動作控制」;相關教學則示範以 IoT MQTT Panel APP 發送 MQTT 命令,控制 Three.js 場景中的燈光與人物動畫。原有動畫案例的命令 Topic 為 AnimationCommand,例如 Idle、Walking、Running、Dance、Jump;燈光案例的發布 Topic 為 LightControlinHTML,命令包含 toggleHemisphereLight 與 toggleDirectionalLight。
為了讓初學者可以從零實作,本文另外設計一組更簡單的教學 Topic,並以旋轉立方體取代需載入模型的角色動畫。本文程式是重新編寫的教學範例,並非原展示網站的原始碼。
原案例:MQTT 動作控制展示、IoT MQTT Panel 控制 Three.js。
二、系統架構:誰發布?誰訂閱?
手機 IoT MQTT Panel ── Publish ──┐
▼
MQTT Broker
│
┌──────────────┴─────────────┐
▼ ▼
網頁 MQTT.js ESP32 MicroPython
│ │
▼ ▼
Three.js 動畫 實體 LED
網頁與 ESP32 都訂閱相同的燈光 Topic手機是 Publisher;Broker 是訊息轉送站;網頁與 ESP32 都是 Subscriber。網頁使用 MQTT over WebSocket,ESP32 使用 MQTT over TCP。兩種連線方式可以接到同一個 Broker,並交換相同 Topic 的訊息。
| 技術 | 角色 | 要理解的觀念 |
|---|---|---|
| Three.js | 建立 3D 場景 | Scene、Camera、Renderer、Mesh、Light |
| JavaScript | 處理動畫與命令 | 事件、狀態、條件判斷 |
| MQTT.js | 網頁 MQTT Client | WebSocket、Subscribe、Message |
| IoT MQTT Panel | 手機控制端 | Publish、Topic、Payload |
| ESP32 + MicroPython | 實體控制端 | Wi-Fi、GPIO、MQTT TCP |
三、MQTT Topic 與 Payload 設計
Topic 是訊息分類的名稱,Payload 是真正傳送的內容。Broker 只負責依照 Topic 轉送,並不知道 ON 代表要點亮 LED。
| Topic(本文示範) | Payload | 接收端動作 |
|---|---|---|
nfu/demo/light | ON、OFF | 網頁燈光與 ESP32 LED 同步切換 |
nfu/demo/animation | PLAY、PAUSE | 網頁動畫播放或暫停 |
nfu/demo/speed | 0~10 | 調整網頁旋轉速度 |
nfu/demo/status | ON、OFF | ESP32 回報 LED 設定狀態 |
nfu/demo/... 可能與其他使用者衝突,建議改成 nfu/class01/group03/light 等各組獨立名稱,且手機、網頁、ESP32 三端都要同步修改。四、實作一:完成可控制的 Three.js 網頁
先在電腦建立 index.html。以下使用 CDN 載入 Three.js 與 MQTT.js,方便學生不安裝建置工具就能入門。請將程式存成檔案,再用 VS Code Live Server 或 python -m http.server 8000 啟動本地 HTTP 伺服器,以 http://localhost:8000 開啟;避免直接以 file:// 測試。
<!DOCTYPE html>
<html lang="zh-Hant">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Three.js MQTT 虛實控制</title>
<style>
body { margin:0; background:#101b2c; color:white;
font-family:Arial,sans-serif; }
#info { padding:12px; }
#scene { width:100%; height:70vh; }
button { padding:10px; margin:4px; }
</style>
</head>
<body>
<div id="info">
<strong>Three.js × MQTT</strong>
<span id="status">MQTT 連線中...</span>
<button onclick="send('nfu/demo/light','ON')">開燈</button>
<button onclick="send('nfu/demo/light','OFF')">關燈</button>
<button onclick="send('nfu/demo/animation','PLAY')">播放</button>
<button onclick="send('nfu/demo/animation','PAUSE')">暫停</button>
</div>
<div id="scene"></div>
<script src="https://unpkg.com/mqtt@5.10.4/dist/mqtt.min.js"></script>
<script type="module">
import * as THREE from 'https://cdn.jsdelivr.net/npm/three@0.160.1/build/three.module.js';
const host = document.getElementById('scene');
const scene = new THREE.Scene();
scene.background = new THREE.Color(0x15273b);
const camera = new THREE.PerspectiveCamera(
65, host.clientWidth / host.clientHeight, 0.1, 100);
camera.position.set(3, 2.5, 5);
camera.lookAt(0, 0, 0);
const renderer = new THREE.WebGLRenderer({antialias:true});
renderer.setSize(host.clientWidth, host.clientHeight);
host.appendChild(renderer.domElement);
const cube = new THREE.Mesh(
new THREE.BoxGeometry(2, 2, 2),
new THREE.MeshStandardMaterial({color:0x39a8ed})
);
scene.add(cube);
const ambient = new THREE.HemisphereLight(0xffffff,0x334455,0.5);
scene.add(ambient);
const light = new THREE.DirectionalLight(0xffffff,2);
light.position.set(3,5,4);
scene.add(light);
let playing = true;
let speed = 0.7; // 每秒旋轉弧度
let previous = performance.now();
function animate(now) {
requestAnimationFrame(animate);
const dt = Math.min((now - previous)/1000,0.05);
previous = now;
if (playing) cube.rotation.y += speed * dt;
renderer.render(scene,camera);
}
requestAnimationFrame(animate);
window.addEventListener('resize', () => {
camera.aspect = host.clientWidth / host.clientHeight;
camera.updateProjectionMatrix();
renderer.setSize(host.clientWidth,host.clientHeight);
});
// 瀏覽器使用 MQTT over WebSocket
const client = mqtt.connect(
'wss://test.mosquitto.org:8081/mqtt',
{clientId:'nfu_web_'+Math.random().toString(16).slice(2)}
);
const status = document.getElementById('status');
client.on('connect', () => {
status.textContent = 'MQTT 已連線';
client.subscribe([
'nfu/demo/light',
'nfu/demo/animation',
'nfu/demo/speed',
'nfu/demo/status'
]);
});
client.on('reconnect',() => status.textContent='重新連線中');
client.on('offline',() => status.textContent='MQTT 離線');
client.on('error',err => console.error('MQTT:',err));
client.on('message',(topic,bytes) => {
const value = bytes.toString();
console.log('收到:',topic,value);
if (topic === 'nfu/demo/light') {
if (value === 'ON') light.visible = true;
if (value === 'OFF') light.visible = false;
}
if (topic === 'nfu/demo/animation') {
if (value === 'PLAY') playing = true;
if (value === 'PAUSE') playing = false;
}
if (topic === 'nfu/demo/speed') {
const n = Number(value);
if (value.trim() !== '' && Number.isFinite(n)
&& n >= 0 && n <= 10) speed = n * 0.2;
}
if (topic === 'nfu/demo/status') {
console.log('ESP32 LED 狀態:',value);
}
});
function send(topic,value) {
if (!client.connected) {
alert('MQTT 尚未連線'); return;
}
client.publish(topic,value,{qos:0,retain:false});
}
window.send = send;
</script>
</body>
</html>
完成後,網頁應該能看到藍色立方體旋轉;即使手機還沒有加入,也可以先用網頁按鈕發送 MQTT 命令,並由同一個網頁訂閱後執行。
五、實作二:IoT MQTT Panel 手機控制
在手機安裝 IoT MQTT Panel,新增一組 MQTT 連線,Host 填 test.mosquitto.org,Port 填 1883,連線方式為 MQTT TCP(依 APP 版本選擇)。網頁使用 WSS 8081,兩者連接的是同一個 Broker。
| 面板 | Topic | 值 |
|---|---|---|
| Switch:燈光 | nfu/demo/light | 開 ON/關 OFF |
| Button:播放 | nfu/demo/animation | PLAY |
| Button:暫停 | nfu/demo/animation | PAUSE |
| Slider:速度 | nfu/demo/speed | 0~10 |
手機按下「關燈」時,Broker 將 OFF 轉送到網頁;網頁執行 light.visible = false。這個過程不需要知道網頁的 IP 位址,也不需要手機直接連到電腦。
六、實作三:ESP32 MicroPython 控制實體 LED
準備 ESP32 開發板、LED、約 220~330Ω 限流電阻、麵包板及 USB 傳輸線。以外接 LED 為例,GPIO 2 經電阻接 LED 正極,LED 負極接 GND。若板子已有內建 LED,請依板型確認腳位與高低電位邏輯。
在 Thonny 建立 main.py,修改 Wi-Fi 帳號與密碼後上傳。此例使用 umqtt.simple,部分 MicroPython 韌體需要另外安裝 micropython-umqtt.simple。
import network
import time
from machine import Pin
from umqtt.simple import MQTTClient
SSID = "YOUR_WIFI"
PASSWORD = "YOUR_PASSWORD"
BROKER = "test.mosquitto.org"
TOPIC_LIGHT = b"nfu/demo/light"
TOPIC_STATUS = b"nfu/demo/status"
led = Pin(2, Pin.OUT)
led.value(0)
wifi = network.WLAN(network.STA_IF)
wifi.active(True)
wifi.connect(SSID, PASSWORD)
start = time.ticks_ms()
while not wifi.isconnected():
if time.ticks_diff(time.ticks_ms(),start) > 15000:
raise RuntimeError("Wi-Fi 連線逾時")
time.sleep(0.2)
print("Wi-Fi IP:",wifi.ifconfig()[0])
client = MQTTClient(
b"nfu_esp32_" + str(time.ticks_ms()).encode(),
BROKER,
port=1883,
keepalive=60
)
def on_message(topic,msg):
if topic != TOPIC_LIGHT:
return
if msg == b"ON":
led.value(1)
elif msg == b"OFF":
led.value(0)
else:
return
state = b"ON" if led.value() else b"OFF"
print("LED:",state)
client.publish(TOPIC_STATUS,state)
client.set_callback(on_message)
client.connect()
client.subscribe(TOPIC_LIGHT)
print("MQTT 訂閱成功")
try:
while True:
client.check_msg()
time.sleep(0.1)
finally:
client.disconnect()ESP32 收到 ON 後點亮 LED,並向 nfu/demo/status 回報狀態。這裡的狀態是程式對輸出腳位的設定結果,並非透過光感測器確認 LED 真的發光。這份程式適合課堂短時間實驗;長時間運作仍需增加 Wi-Fi/MQTT 斷線重連及錯誤處理。
七、如何驗證虛實同步?
- 先啟動網頁,確認看到立方體與「MQTT 已連線」。
- 啟動 ESP32,確認 Thonny 顯示 Wi-Fi IP 與「MQTT 訂閱成功」。
- 手機 IoT MQTT Panel 連接同一 Broker。
- 手機發送
ON:網頁方向光開啟,ESP32 LED 點亮。 - 手機發送
OFF:網頁方向光關閉,ESP32 LED 熄滅。 - 發送
PAUSE、PLAY與速度數值,觀察網頁旋轉變化。 - 打開瀏覽器開發者工具 Console,檢查收到的 Topic 與 Payload。
八、進階知識:QoS、Retain、LWT
| MQTT 功能 | 意義 | 本專題的用途 |
|---|---|---|
| QoS 0 | 最多傳送一次 | 適合入門測試與頻繁速度更新 |
| QoS 1 | 至少傳送一次,可能重複 | 需處理重複命令的控制情境 |
| QoS 2 | MQTT 協定層級恰好一次 | 較嚴格的訊息傳遞需求 |
| Retain | 保留 Topic 最新一則保留訊息 | 新連線網頁取得最新設定 |
| LWT | 異常斷線時 Broker 代發訊息 | 監測 ESP32 是否意外離線 |
特別注意:TOGGLE 命令若重複執行,可能讓燈光開了又關;ON 與 OFF 是明確設定狀態,通常較容易設計成可重複執行的命令。QoS 保證的是 MQTT 訊息傳遞語意,不保證實體硬體已完成動作。
九、常見問題與分層除錯
| 現象 | 可能原因 | 檢查方式 |
|---|---|---|
| 網頁空白 | Three.js 載入失敗、JavaScript 錯誤 | 按 F12 看 Console,確認使用 ES module |
| 網頁顯示 MQTT 離線 | WebSocket、TLS、網路或 Broker 問題 | 檢查 WSS URL 與瀏覽器 Network |
| 手機有發布但網頁不動 | Topic 或 Payload 不一致 | 檢查大小寫、空白與訂閱名稱 |
| ESP32 無法連 Wi-Fi | SSID、密碼、頻段或訊號問題 | 先確認 IP 與網際網路連線 |
| ESP32 找不到 umqtt | 套件未安裝 | 確認 MicroPython 套件 |
| 網頁有反應,LED 沒反應 | GPIO 腳位、接線、電位或 ESP32 MQTT 問題 | 先用簡單 LED 閃爍程式測試硬體 |
十、從網頁動畫延伸到智慧生活 Capstone
ESP32 發布水溫或溶氧感測值,Three.js 以水色、警示與魚群動畫顯示水質變化。進一步加入 Django 儲存歷史資料。
將白馬、烏龜、姻緣花轉譯為 3D 或 2D 互動場景,手機發布命令,ESP32 同步控制 WS2812B 燈光與語音模組,連結地方文化與網路技術。
網頁模擬機器人前進、左轉、右轉,透過 MQTT 發送控制命令到實體機器人;學生需自行設計安全停止與狀態回報機制。
十一、六小時教學安排
| 階段 | 時間 | 操作任務 | 成果證據 |
|---|---|---|---|
| 1. 網頁動畫 | 2 小時 | 建立 Three.js 場景、燈光、旋轉動畫 | 可操作的 3D 網頁 |
| 2. MQTT 通訊 | 2 小時 | 手機發布、網頁訂閱與 Console 診斷 | 手機控制網頁影片或截圖 |
| 3. 虛實整合 | 2 小時 | ESP32 訂閱、LED 控制、狀態回報 | 虛實同步展示及系統架構圖 |
學生挑戰題
- 為什麼瀏覽器使用 WSS,而 ESP32 可以使用 MQTT TCP?
- 如果兩個學生使用相同 Topic,可能發生什麼事?
- 如何設計狀態回報,分辨「命令已發布」與「LED 已設定」?
- 如何把立方體換成 3D 人物,讓
Walking與Dance對應不同動畫片段? - 如果 Broker 暫時斷線,網頁與 ESP32 應該如何恢復?
十二、結語:看得懂、連得上、做得出來
從 Three.js 的虛擬動畫,到手機 IoT MQTT Panel 發布命令,再到 ESP32 控制實體 LED,學生實際經歷了一則訊息如何穿越不同裝置與軟體環境。這正是網際網路應用的核心:不只是會寫網頁,更能說明訊息如何傳遞、如何驗證、如何安全且可靠地讓系統運作。
未來加入 Django、資料庫、感測器與 AI 模型,就可以將這個小型實驗擴充為智慧養殖、地方文化互動展示或智慧教育系統。
延伸閱讀與技術參考
- 台灣工藝創客青創基地:MQTT 動作控制展示
- 用 IoT MQTT Panel APP 控制 Three.js 網頁的燈光和動作
- Using MQTT commands to control the action of animation in Three.js
- Using MQTT commands to control lights in Three.js
- MQTT 不只是能傳:QoS、Retain、LWT 與斷線重連
- Three.js 官方文件
- MQTT.js 官方專案
教學說明:本文的 Topic、程式及系統架構為重新設計的入門教材;公開測試 Broker 僅適合非敏感資料實驗。正式場域部署需加入 TLS、帳號驗證、Topic ACL、重連與設備安全機制。
沒有留言:
張貼留言