顯示具有 Raspberry Pi Pico 2 W 標籤的文章。 顯示所有文章
顯示具有 Raspberry Pi Pico 2 W 標籤的文章。 顯示所有文章

2026年11月17日 星期二

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

網際網路應用Three.jsMQTTRaspberry Pi Pico 2 W

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

手機按下一個按鈕,網頁中的 3D 立方體改變光線,同時 Raspberry Pi Pico 2 W 的 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                  Raspberry Pi Pico 2 W MicroPython
                   │                            │
                   ▼                            ▼
             Three.js 動畫                   實體 LED

        網頁與 Raspberry Pi Pico 2 W 都訂閱相同的燈光 Topic

手機是 Publisher;Broker 是訊息轉送站;網頁與 Raspberry Pi Pico 2 W 都是 Subscriber。網頁使用 MQTT over WebSocket,Raspberry Pi Pico 2 W 使用 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
Raspberry Pi Pico 2 W + MicroPython實體控制端Wi-Fi、GPIO、MQTT TCP

三、MQTT Topic 與 Payload 設計

Topic 是訊息分類的名稱,Payload 是真正傳送的內容。Broker 只負責依照 Topic 轉送,並不知道 ON 代表要點亮 LED。

Topic(本文示範)Payload接收端動作
nfu/demo/lightON、OFF網頁燈光與 Raspberry Pi Pico 2 W LED 同步切換
nfu/demo/animationPLAY、PAUSE網頁動畫播放或暫停
nfu/demo/speed0~10調整網頁旋轉速度
nfu/demo/statusON、OFFRaspberry Pi Pico 2 W 回報 LED 設定狀態
課堂使用請修改 Topic:公開 Broker 上的 nfu/demo/... 可能與其他使用者衝突,建議改成 nfu/class01/group03/light 等各組獨立名稱,且手機、網頁、Raspberry Pi Pico 2 W 三端都要同步修改。

四、實作一:完成可控制的 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('Raspberry Pi Pico 2 W 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 位址,也不需要手機直接連到電腦。

六、實作三:Raspberry Pi Pico 2 W MicroPython 控制實體 LED

準備 Raspberry Pi Pico 2 W、Micro-USB 資料傳輸線,以及安裝 Thonny 的電腦。Pico 2 W 具備 Wi-Fi 功能,本實作直接使用板載 LED,因此不需要另外接線。Pico 2 W 的板載 LED 由無線晶片控制,MicroPython 可透過 Pin("LED", Pin.OUT) 存取;不要直接假設它位於 GPIO 2 或 GP25。

環境準備:先在 Thonny 選擇 MicroPython (Raspberry Pi Pico) 直譯器,安裝適用於 Pico 2 W 的 MicroPython 韌體。若出現 ImportError: no module named 'umqtt',可使用 Thonny 的「工具 → 管理套件」安裝 micropython-umqtt.simple,或將相容的 umqtt/simple.py 放入開發板。請確認使用 2.4 GHz Wi-Fi。

先在 Thonny 測試板載 LED 是否正常:

from machine import Pin
from time import sleep

led = Pin("LED", Pin.OUT)
for i in range(3):
    led.on()
    sleep(0.5)
    led.off()
    sleep(0.5)

確認燈號正常後,再建立 main.py,修改 Wi-Fi 帳號密碼並執行以下 MQTT 訂閱程式:

import network
import time
from machine import Pin, unique_id
from ubinascii import hexlify
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"

# Pico 2 W 板載 LED(由無線晶片控制)
led = Pin("LED", Pin.OUT)
led.off()

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) > 20000:
        raise RuntimeError("Wi-Fi 連線逾時")
    time.sleep(0.2)
print("Wi-Fi IP:", wifi.ifconfig()[0])

client_id = b"nfu_pico2w_" + hexlify(unique_id())
client = MQTTClient(client_id, BROKER, port=1883, keepalive=60)

def on_message(topic, msg):
    if topic != TOPIC_LIGHT:
        return
    if msg == b"ON":
        led.on()
    elif msg == b"OFF":
        led.off()
    else:
        return
    state = b"ON" if led.value() else b"OFF"
    print("Pico 2 W 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()

當手機發布 ON 到 nfu/demo/light 時,網頁的方向光與 Pico 2 W 的板載 LED 會各自接收同一 Topic 的命令。Pico 2 W 也會發布 nfu/demo/status 回報程式設定的 LED 狀態。這不等同以光感測器確認 LED 實際發光。

教學注意:公開 Broker 的 1883 埠為未加密 MQTT TCP,僅供非敏感資料的短時間測試。正式場域請改用具有身分驗證、TLS 及 Topic 權限控管的 Broker。此範例尚未包含 Wi-Fi 與 MQTT 自動重連,適合課堂入門實驗。

七、如何驗證虛實同步?

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

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

MQTT 功能意義本專題的用途
QoS 0最多傳送一次適合入門測試與頻繁速度更新
QoS 1至少傳送一次,可能重複需處理重複命令的控制情境
QoS 2MQTT 協定層級恰好一次較嚴格的訊息傳遞需求
Retain保留 Topic 最新一則保留訊息新連線網頁取得最新設定
LWT異常斷線時 Broker 代發訊息監測 Raspberry Pi Pico 2 W 是否意外離線

特別注意:TOGGLE 命令若重複執行,可能讓燈光開了又關;ON 與 OFF 是明確設定狀態,通常較容易設計成可重複執行的命令。QoS 保證的是 MQTT 訊息傳遞語意,不保證實體硬體已完成動作。

九、常見問題與分層除錯

現象可能原因檢查方式
網頁空白Three.js 載入失敗、JavaScript 錯誤按 F12 看 Console,確認使用 ES module
網頁顯示 MQTT 離線WebSocket、TLS、網路或 Broker 問題檢查 WSS URL 與瀏覽器 Network
手機有發布但網頁不動Topic 或 Payload 不一致檢查大小寫、空白與訂閱名稱
Raspberry Pi Pico 2 W 無法連 Wi-FiSSID、密碼、頻段或訊號問題先確認 IP 與網際網路連線
Raspberry Pi Pico 2 W 找不到 umqtt套件未安裝確認 MicroPython 套件
網頁有反應,LED 沒反應GPIO 腳位、接線、電位或 Raspberry Pi Pico 2 W MQTT 問題先用簡單 LED 閃爍程式測試硬體

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

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

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

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

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

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

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

十一、六小時教學安排

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

學生挑戰題

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

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

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

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

延伸閱讀與技術參考

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