2026年11月17日 星期二

從 Three.js 網頁動畫到 MQTT 物聯網控制:手機、網頁與 ESP32 的虛實整合實作

網際網路應用Three.jsMQTTESP32

從 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 ClientWebSocket、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/lightON、OFF網頁燈光與 ESP32 LED 同步切換
nfu/demo/animationPLAY、PAUSE網頁動畫播放或暫停
nfu/demo/speed0~10調整網頁旋轉速度
nfu/demo/statusON、OFFESP32 回報 LED 設定狀態
課堂使用請修改 Topic:公開 Broker 上的 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/animationPLAY
Button:暫停nfu/demo/animationPAUSE
Slider:速度nfu/demo/speed0~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 斷線重連及錯誤處理。

七、如何驗證虛實同步?

  1. 先啟動網頁,確認看到立方體與「MQTT 已連線」。
  2. 啟動 ESP32,確認 Thonny 顯示 Wi-Fi IP 與「MQTT 訂閱成功」。
  3. 手機 IoT MQTT Panel 連接同一 Broker。
  4. 手機發送 ON:網頁方向光開啟,ESP32 LED 點亮。
  5. 手機發送 OFF:網頁方向光關閉,ESP32 LED 熄滅。
  6. 發送 PAUSE、PLAY 與速度數值,觀察網頁旋轉變化。
  7. 打開瀏覽器開發者工具 Console,檢查收到的 Topic 與 Payload。
重要觀察:網頁與 ESP32 各自接收同一則命令,這是「共同接收命令」,不保證兩者在毫秒等級完全同步。若需要確認實體裝置已完成動作,應再設計狀態回報與確認機制。

八、進階知識:QoS、Retain、LWT

MQTT 功能意義本專題的用途
QoS 0最多傳送一次適合入門測試與頻繁速度更新
QoS 1至少傳送一次,可能重複需處理重複命令的控制情境
QoS 2MQTT 協定層級恰好一次較嚴格的訊息傳遞需求
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-FiSSID、密碼、頻段或訊號問題先確認 IP 與網際網路連線
ESP32 找不到 umqtt套件未安裝確認 MicroPython 套件
網頁有反應,LED 沒反應GPIO 腳位、接線、電位或 ESP32 MQTT 問題先用簡單 LED 閃爍程式測試硬體

十、從網頁動畫延伸到智慧生活 Capstone

專題 A|智慧養殖數位分身

ESP32 發布水溫或溶氧感測值,Three.js 以水色、警示與魚群動畫顯示水質變化。進一步加入 Django 儲存歷史資料。

專題 B|水井三寶智慧互動展覽

將白馬、烏龜、姻緣花轉譯為 3D 或 2D 互動場景,手機發布命令,ESP32 同步控制 WS2812B 燈光與語音模組,連結地方文化與網路技術。

專題 C|兒童機器人虛實互動

網頁模擬機器人前進、左轉、右轉,透過 MQTT 發送控制命令到實體機器人;學生需自行設計安全停止與狀態回報機制。

十一、六小時教學安排

階段時間操作任務成果證據
1. 網頁動畫2 小時建立 Three.js 場景、燈光、旋轉動畫可操作的 3D 網頁
2. MQTT 通訊2 小時手機發布、網頁訂閱與 Console 診斷手機控制網頁影片或截圖
3. 虛實整合2 小時ESP32 訂閱、LED 控制、狀態回報虛實同步展示及系統架構圖

學生挑戰題

  1. 為什麼瀏覽器使用 WSS,而 ESP32 可以使用 MQTT TCP?
  2. 如果兩個學生使用相同 Topic,可能發生什麼事?
  3. 如何設計狀態回報,分辨「命令已發布」與「LED 已設定」?
  4. 如何把立方體換成 3D 人物,讓 Walking 與 Dance 對應不同動畫片段?
  5. 如果 Broker 暫時斷線,網頁與 ESP32 應該如何恢復?

十二、結語:看得懂、連得上、做得出來

從 Three.js 的虛擬動畫,到手機 IoT MQTT Panel 發布命令,再到 ESP32 控制實體 LED,學生實際經歷了一則訊息如何穿越不同裝置與軟體環境。這正是網際網路應用的核心:不只是會寫網頁,更能說明訊息如何傳遞、如何驗證、如何安全且可靠地讓系統運作。

未來加入 Django、資料庫、感測器與 AI 模型,就可以將這個小型實驗擴充為智慧養殖、地方文化互動展示或智慧教育系統。

延伸閱讀與技術參考

教學說明:本文的 Topic、程式及系統架構為重新設計的入門教材;公開測試 Broker 僅適合非敏感資料實驗。正式場域部署需加入 TLS、帳號驗證、Topic ACL、重連與設備安全機制。

沒有留言:

張貼留言