常見問題（FAQ）
通用
應該選 SCS0009 還是 PWM？ 需要位置回饋、精度、LeRobot/SO-ARM101 資料採集選 SCS0009；獨立演示、手勢互動、網頁/桌面快速上手選 PWM。詳見 版本比較。
兩套伺服馬達能同時接嗎？ 不能。供電、協定和韌體都不同，同一時刻只接一套。
機械手能直接上電嗎？ 首次上電前把機械手擺到中位，按中位安裝伺服馬達臂；外部電源與驅動板/ESP32 必須共地。
伺服馬達型號能換嗎？ SCS0009 版使用匯流排伺服馬達；PWM 版韌體按 PTK 7452 MG-D（333 Hz 數位伺服馬達）標定。SG90 等 50 Hz 類比伺服馬達不能直接替換 PWM 版，需改 LEDC_FREQ 和脈寬標定。
SCS0009 序列匯流排版
動作方向反了 → 檢查是否按「奇數 ID 在前」接線；左手確認 angle_offset_deg = -35.16。
左手握拳幅度不夠 / 伺服馬達叫 → 檢查 config.json 限位是否已放到 ±120°（預設 ±90 會削掉左手握拳）。
手指不動 / 提示「需要 N 個馬達偵測到 M 個」 → 執行 tools/scan_servos.py；左手 ID 最容易接錯（11–18，不是 9–16）。
中位不對 → 中位值 -17.578125 對應官方 raw 451/571；按機械裝配標定就改 config.json 的 middle.positions。
伺服馬達 ID 怎麼設？ → 用 SCS0009 調校工具 掃描並修改 ID；右手 1–8，左手 11–18。
Linux 打不開序列埠 → 目前使用者加入 dialout 群組並重新登入。
能讀位置/溫度/電壓嗎？ → 可以，SCS0009 支援位置、速度、電壓、溫度回讀；協定記憶體表見 scs_servo_protocol.md。
PWM 伺服馬達版
連線失敗 / ESP32 無回應 → 確認 115200 鮑率、ESP32 的 COM 埠、5V/3A 供電和共地；開啟序列埠可能重置，頁面會自動重試 NOP。
伺服馬達不動或抖動 → 確認是 333 Hz 數位伺服馬達（PTK 7452 MG-D 或同類），電源足夠；SG90 需改韌體。
方向反了 → 在網頁 config.json 的 pwm.calibration 裡把對應手指 scale 改為 -1。
中位不對 → 調對應通道的 offset_deg；詳見 PWM 協定、命令與標定。
提示「忙碌（手勢執行中）」 → 韌體正在執行內建手勢，等待完成或發送停止（0xFF）。
PWM 版有回饋嗎？ → 沒有位置/溫度/電壓回讀，無法偵測堵轉或失步。
PWM 伺服馬達有鮑率嗎？ → 伺服馬達本身沒有；上位機↔ESP32 序列埠固定 115200 8N1。
只接了部分伺服馬達可以測試嗎？ → 可以。未接通道空著不影響其他通道；注意空插頭絕緣。
攝影機有畫面但手不跟隨 / 反應遲鈍 → 光線均勻、手掌距鏡頭約 40–80 cm 並正對鏡頭；關閉佔用攝影機的其他程式；確認序列埠已連線。GUI 追蹤參數見 PWM 手勢追蹤。
切換左右手不生效 → 韌體用 0xF1 切換左手/右手（網頁連線時會自動發送）；該設定主要影響韌體內建手勢的拇指方向，網頁姿態則按目前控制對象使用各自的映射。
追蹤畫面卡住 / 日誌停住 → 停止追蹤後重新開始；仍無回應時關閉 GUI 重開，並確認攝影機沒有被其他程式佔用。
換 USB 埠後找不到序列埠 → 到裝置管理員確認新的 COM 號，在 GUI 或網頁裡點「重新整理」後重新選擇。
網頁控制
模型失敗 / 攝影機追蹤載入失敗 → 確認頁面由本機服務提供（非 file:// 直接開啟），MediaPipe 資源路徑可存取；本機教學已修復伺服端 MediaPipe 路由。仍失敗時看瀏覽器 Console/Network 的 404 或權限錯誤。
攝影機辨識不準 → 光線均勻、手掌正對鏡頭；tracking.js 的 SMOOTH（預設 0.35）越大越平滑但越遲鈍。
某根手指不跟手 → 重新採集三個姿勢；方向反了重採對應姿勢；拇指只做屈伸，不參與側擺。
握拳到一半某伺服馬達反轉 → 側擺應隨彎曲衰減到 0（side *= (1 - curl)）；檢查側擺控制量的符號和大小是否異常。
網頁驅動怎麼切換？ → 頂部「驅動」下拉選 SCS0009 或 PWM；PWM 需選 115200 序列埠，詳見 網頁控制總覽。
桌面上位機
SCS0009 GUI 未列出序列埠 → 重新插拔 USB 適配器、安裝驅動或重新啟動 GUI；Linux 檢查 dialout。
Connect 按鈕變灰 → 已連線，先點 Disconnect。
序列未驅動所有手指 → 檢查每步速度，確保每個姿態包含全部 8 個伺服馬達值。
阻塞指示持續存在 → 檢查機械卡阻；目標與實際位置差異大且無運動會觸發阻塞。
PWM GUI 啟動報 mediapipe 缺失 → 用 tools/tracking_env 的 Python 啟動，或重跑 tools/setup_tracking.bat。
手勢追蹤
mediapipe 缺 solutions 子模組 → 安裝 mediapipe==0.10.14，並確認 Python 3.12 為 64 位。
dora 版本不相容 → 按 pyproject.toml 和日誌對齊 dora 版本；清理後重裝。
模型載入失敗（中文路徑） → 把專案/模型放到全英文路徑。
攝影機沒畫面 / 權限 → 允許系統攝影機權限；虛擬機需 USB 直通攝影機。
SCS0009 官方 Demo 與 PWM GUI 追蹤有什麼區別？ → SCS0009 使用 dora + MuJoCo IK 完整鏈路；PWM 版提供 GUI 內建 MediaPipe 輕量追蹤，dora Demo 不在模組內。詳見 SCS0009 手勢追蹤 / PWM 手勢追蹤。