SCS0009 手勢追蹤（官方 dora Demo）

本頁介紹 SCS0009 匯流排伺服馬達版的官方手勢追蹤鏈路：攝影機 → MediaPipe → MuJoCo IK → AHControl（Rust）→ SCS0009。PWM 版追蹤見 PWM 手勢追蹤。

下面的腳本 1 → 4 以 Windows 一鍵腳本為例，腳本位於 AmazingHand-main/Demo/Windows_Deploy_Scripts/；Linux 與 macOS 的腳本位置和差異見文末。按編號順序執行即可。

硬體準備

硬體	要求
靈巧手本體	右手 / 左手 / 雙手
伺服馬達驅動板	外接，USB 連電腦
電源	外接電源，至少 5V 4A（或按驅動板要求使用 7–12V 輸入）；USB 供電不足
攝影機	電腦自帶或 USB 攝影機

模型檔案可在 Onshape 查看或自行下載（含 URDF）。

靈巧手的 MuJoCo 模型

環境安裝（腳本 1）

Windows 一鍵部署腳本目錄

雙擊 1-Install_Env.bat，自動完成：

檢查 MSVC 建置工具（cl.exe）——Rust 編譯必需。缺失時會提示安裝 Visual Studio 2022 Build Tools，勾選「使用 C++ 的桌面開發」，裝完重開終端機。
安裝 Rust（rustup + stable-msvc 工具鏈）
設定 cargo 清華鏡像源（C:\Users\<你的使用者名稱>\.cargo\config.toml），加速 crate 下載
安裝 uv（Python 套件管理器）
安裝 dora-cli 0.5.0（cargo install，首次編譯約 10~20 分鐘，耐心等待）
安裝 dora-rs pip 套件（可選，會裝進虛擬環境）

重要：腳本結束後關閉並重新開啟終端機，讓環境變數生效。安裝過程可能因網路較慢，請耐心等待，不要中途關閉。

環境安裝備選（腳本不可用時）

Rust：https://www.rust-lang.org/tools/install
- Windows 用 rustup-init.exe，選預設 MSVC 工具鏈
- 環境變數：%USERPROFILE%\.cargo\bin 加入 PATH
uv：PowerShell 執行 irm https://astral.sh/uv/install.ps1 | iex。
- 環境變數：%USERPROFILE%\.local\bin 加入 PATH
dora-cli：cargo install dora-cli --version 0.5.0

cargo 清華鏡像設定（~/.cargo/config.toml）

bash

[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

[registries.tuna]
index = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

[http]
check-revoke = false

用 sparse 稀疏索引（如上），不要用 git 儲存庫鏡像——git 方式首次要下載約 1GB 索引，容易卡死在 Updating 'tuna' index。

接線方式

伺服馬達驅動板 USB 連電腦，外接電源（至少 5V 4A，或按驅動板要求使用 7–12V）
電腦端找到埠號：裝置管理員 → 連接埠(COM 和 LPT)，如 COM11

設定序列埠（腳本 2）

雙擊 2-Setup_Serial.bat（實際邏輯在 2-Setup_Serial.ps1）：

提示「請將伺服馬達驅動板連接到電腦」→ Enter 開始偵測
自動列出偵測到的 COM 埠（帶裝置名稱）
單一埠時 Enter 確認，多個埠時輸入編號
自動寫入 3 個 dataflow yml 的 --serialport 和 AHControl\src\main.rs 的預設埠
原檔案自動備份為 .bak

如果重新插拔 USB，埠號可能變化，需重新執行本腳本。

程式碼部署（腳本 3）

雙擊 3-Deploy_Demo.bat，自動完成：

啟動 dora 守護程序（dora up）
建立 Python 3.12 虛擬環境（uv venv --python 3.12）
啟用虛擬環境
編譯 AHControl Rust 節點（cargo build --release，首次約 10 分鐘）
同步 AHSimulation、HandTracking 相依套件（uv sync）
強制安裝 mediapipe==0.10.14

部署只需執行一次。之後重複執行會提示是否重建虛擬環境。

執行程式碼（腳本 4）

雙擊 4-Run_Demo.bat，出現互動選單：

bash

============================================
   请选择运行模式：
============================================
    1 - 模拟仿真（摄像头手势追踪）
    2 - 真实硬件
    q - 退出
============================================
  请输入序号 [1/2/q]:

選 1：模擬環境，攝影機手勢驅動兩隻模擬手
選 2：進入子選單，選右手 / 左手 / 雙手

bash

============================================
   真实硬件 - 请选择灵巧手：
============================================
    1 - 右手
    2 - 左手
    3 - 左右双手
    b - 返回上级菜单
============================================

選好後自動執行 dora build + dora run。攝影機視窗彈出，對著攝影機做手勢，靈巧手即時跟隨。Ctrl+C 停止，資料流結束後按 Enter 返回主選單，可再選其它模式或 q 結束。

首次執行時 Windows 可能攔截攝影機權限，點擊「允許」即可。

專案清理（腳本 0）

雙擊 0-Cleanup_Project.bat，輸入 Y 確認後自動清理：

停止 dora 守護程序
刪除 3 個虛擬環境（.venv）
刪除 Rust 編譯產物（AmazingHand-main/Demo/target）
刪除 pycache、.bak 備份、日誌、AmazingHand-main/Demo/out（dora 日誌目錄）
恢復預設埠（--serialport /dev/ttyACM0），去掉本機序列埠殘留

清理後可把整個 AmazingHand-main 資料夾拷給他人，乾淨無殘留。新機器上按 1 → 2 → 3 → 4 順序執行即可。

Linux 與 macOS 差異

一鍵腳本同樣提供 Linux 和 macOS 版本，目錄分別為 AmazingHand-main/Demo/Linux_Deploy_Scripts/ 和 AmazingHand-main/Demo/Mac_Deploy_Scripts/。第 1–4 步的流程與 Windows 相同，下面只列系統差異。

腳本執行權限（Linux / macOS）

從 Windows 或壓縮包拷貝後，腳本的 +x 執行位會遺失，首次執行前先執行：

bash

cd "AmazingHand-main/Demo/Linux_Deploy_Scripts"   # macOS 改為 Mac_Deploy_Scripts
chmod +x *.sh

之後用 ./腳本名 執行；不要用 bash 腳本名，否則會跳過腳本內的互動提示。

Linux（Ubuntu）

序列埠權限：sudo usermod -aG dialout $USER，登出並重新登入；臨時可用 sudo chmod 666 /dev/ttyACM*。
裝置名稱：/dev/ttyUSB*（CH340 / CP2102）或 /dev/ttyACM*（板載 USB 序列埠）。
攝影機：設定 → 隱私 → 相機，允許應用程式存取；確認沒有其他程式佔用攝影機。
虛擬機：先把 USB 攝影機連接到虛擬機；若 OpenCV 報 can't open camera by index 或 select() timeout，在虛擬機設定中切換 USB 控制器 2.0 / 3.1 並重新啟動；必要時 sudo usermod -aG video $USER。
中文路徑：專案路徑盡量使用英文，避免 MuJoCo / MediaPipe 載入模型失敗。

Linux 一鍵部署

Linux 下 main.rs 的序列埠預設值範例

macOS

序列埠：使用 /dev/cu.*，不要用 /dev/tty.*；ls /dev/cu.* 查看裝置名稱。
序列埠權限：sudo chmod 666 /dev/cu.usbmodem*，或在「系統設定 → 隱私與安全性 → 輸入監控」中允許終端機。
攝影機：首次執行允許終端機存取相機；也可在「系統設定 → 隱私與安全性 → 相機」中修改。
Apple Silicon：首次 cargo build 編譯 dora 相依套件較慢屬正常；若提示「無法驗證開發者」，到「隱私與安全性」中點擊「仍要開啟」。

macOS 一鍵部署

手動安裝（不使用一鍵腳本）

如果腳本不可用，可按官方 Demo 手動部署：

取得程式碼：複製儲存庫或下載 AmazingHand.zip，進入 AmazingHand-main/Demo/。
安裝環境：Rust（rustup）、uv、dora-cli；PowerShell/Bash 重新開啟使 PATH 生效。安裝細節見上方環境安裝（腳本 1）。

建立環境並安裝相依套件：

bash

uv venv --python 3.12
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate

cd AHControl
cargo build --release
cd ..
cd AHSimulation
uv sync
cd ..
cd HandTracking
uv sync
cd ..

建置 Python 節點相依套件

設定序列埠：編輯 dataflow_tracking_real_right.yml / _left.yml / _2hands.yml 中的 --serialport，改成實際 COM 埠或 /dev/ttyUSB0、/dev/cu.usbserial-*。

建置並執行：

bash

# 模擬
dora build dataflow_tracking_simu.yml --uv
dora run dataflow_tracking_simu.yml --uv

# 真實硬體（右手；左手/雙手替換檔案名稱）
dora build dataflow_tracking_real_right.yml --uv
dora run dataflow_tracking_real_right.yml --uv

# 簡單角度範例
dora build dataflow_angle_simu.yml --uv
dora run dataflow_angle_simu.yml --uv

建置並啟動真實硬體資料流

MuJoCo 模擬與攝影機追蹤視窗

常見問題：mediapipe 需 0.10.14（Python 3.12）；dora 版本不相容時按 pyproject.toml/日誌對齊；缺 OpenCV 時安裝 opencv-contrib-python；攝影機權限、虛擬機 USB 直通、中文路徑都會影響模型載入。具體排查見常見問題與注意事項。

更詳細的官方 Demo 說明見 AmazingHand-main/Demo/README.md；各系統的一鍵部署步驟已合併到本頁。

程式碼結構說明

Demo 目錄

text

AmazingHand-main/Demo/
├── AHControl/                Rust 節點：序列埠控制伺服馬達，config/ 下為伺服馬達 ID 與偏移
├── AHSimulation/             Python 節點：MuJoCo 模擬與逆運動學
├── HandTracking/             Python 節點：MediaPipe 手部關鍵點辨識
├── dataflow_*.yml            dora 資料流編排
├── Windows_Deploy_Scripts/   Windows 一鍵部署腳本
├── Linux_Deploy_Scripts/     Linux 一鍵部署腳本
├── Mac_Deploy_Scripts/       macOS 一鍵部署腳本
└── docs/                     官方多語言部署教學

各 dataflow 對應關係

資料流檔案	用途
`dataflow_tracking_simu.yml`	攝影機手勢追蹤，僅驅動 MuJoCo 模擬手
`dataflow_tracking_real_right.yml`	攝影機手勢追蹤，驅動真實右手
`dataflow_tracking_real_left.yml`	攝影機手勢追蹤，驅動真實左手
`dataflow_tracking_real_2hands.yml`	攝影機手勢追蹤，同時驅動左右手
`dataflow_angle_simu.yml`	直接給關節角度，驗證模擬與逆運動學

資料流原理

bash

攝影機 → HandTracking（MediaPipe 辨識手勢）
              ↓ 手部關鍵點座標
         AHSimulation（MuJoCo 模擬 + 逆運動學）
              ↓ 關節目標角度
         AHControl（序列埠 → 伺服馬達驅動板 → 靈巧手）

埠設定位置

三個 dataflow_tracking_real_*.yml 的 args: 行：--serialport COMxx
AHControl\src\main.rs 的 default_value = "COMxx"（序列埠參數預設值）
AHControl\config\*.toml：伺服馬達型號、ID、偏移量（一般不用改）

常見問題與注意事項

1. cargo 卡在 `Updating 'tuna' index`

原因：鏡像設定用了 git 儲存庫方式（.../git/crates.io-index.git），首次要下載 1GB+ 索引
解決：C:\Users\<你的使用者名稱>\.cargo\config.toml 改為 sparse 稀疏索引（見上文「cargo 清華鏡像設定」），或直接重跑 1-Install_Env.bat

2. mediapipe 缺 solutions 子模組 / 安裝損壞

bash

uv pip uninstall mediapipe

bash

uv pip install mediapipe==0.10.14

必須在虛擬環境啟用狀態下執行（在 Demo 目錄）
3-Deploy_Demo.bat 已自動做這一步兜底

3. dora 版本不相容（message v0.8.0 vs v0.7.0）

dora 訊息格式版本不相符的錯誤日誌

症狀：version mismatch: message format v0.8.0 is not compatible with expected message format v0.7.0
原因：dora-cli 版本與 dora-node-api 不相符。必須統一為 0.5.0
- 檢查：dora --version 應輸出 dora-cli 0.5.0、dora-message: 0.8.0
- 修復：cargo install dora-cli --version 0.5.0 --force
- 若 PATH 裡有多個 dora（如 C:\Users\<你的使用者名稱>\.dora\bin 的舊版），確保 .cargo\bin 排在前面，或刪除舊版

4. MuJoCo / mediapipe 載入模型失敗（中文路徑）

症狀：ParseXML: Error opening file '...\scene.xml' 或 Can't find file: ....tflite
原因：MuJoCo 3.x / mediapipe 的 C++ 載入器在 Windows 上打不開含中文的絕對路徑（如 D:\中文目錄...）
本專案已內建修復：
- AHSimulation\AHSimulation\mj_mink_*.py 載入模型前切換工作目錄
- HandTracking\mediapipe_patch.py 用 8.3 短路徑 + 相對路徑繞過
不要刪除這些修復程式碼

5. 攝影機權限

首次執行彈窗選擇「允許」
設定 → 隱私 → 相機 → 允許桌面應用程式存取

6. 埠號每次變化

重新插拔 USB 後 COM 號可能變，重跑 2-Setup_Serial.bat

7. 缺少 openCV

缺少 cv2 模組的錯誤日誌

bash

python -m pip install opencv-contrib-python numpy mediapipe -i https://mirrors.aliyun.com/pypi/simple/

（在 HandTracking 目錄、啟用虛擬環境後執行）

1. 安裝 LeRobot 環境

2. 查看串列埠編號

3. 校準機械臂

4. 遙操作

5. 連接攝像頭的遙操作

6. 採集數據集(實機)

7. 訓練模型

8. 模型推論

基礎知識

其他與進階

1. 安裝 LeRobot 環境

3. 查看串列埠編號

4. 校準機械臂

5. 遙操作

6. 連接攝像頭的遙操作

7. 採集數據集(實機)

8. 訓練模型

9. 模型推論

Jetson AGX Orin 開發套件

Jetson Orin Nano 開發套件

PC 端

I2C 通信

串口通信

SCS0009 手勢追蹤（官方 dora Demo） ​

硬體準備 ​

環境安裝（腳本 1） ​

環境安裝備選（腳本不可用時） ​

cargo 清華鏡像設定（~/.cargo/config.toml） ​

接線方式 ​

設定序列埠（腳本 2） ​

程式碼部署（腳本 3） ​

執行程式碼（腳本 4） ​

專案清理（腳本 0） ​

Linux 與 macOS 差異 ​

腳本執行權限（Linux / macOS） ​

Linux（Ubuntu） ​

macOS ​

手動安裝（不使用一鍵腳本） ​

程式碼結構說明 ​

Demo 目錄 ​

各 dataflow 對應關係 ​

資料流原理 ​

埠設定位置 ​

常見問題與注意事項 ​

1. cargo 卡在 Updating 'tuna' index ​

2. mediapipe 缺 solutions 子模組 / 安裝損壞 ​

3. dora 版本不相容（message v0.8.0 vs v0.7.0） ​

4. MuJoCo / mediapipe 載入模型失敗（中文路徑） ​

5. 攝影機權限 ​

6. 埠號每次變化 ​

7. 缺少 openCV ​

相關頁面 ​

SCS0009 手勢追蹤（官方 dora Demo）

硬體準備

環境安裝（腳本 1）

環境安裝備選（腳本不可用時）

cargo 清華鏡像設定（~/.cargo/config.toml）

接線方式

設定序列埠（腳本 2）

程式碼部署（腳本 3）

執行程式碼（腳本 4）

專案清理（腳本 0）

Linux 與 macOS 差異

腳本執行權限（Linux / macOS）

Linux（Ubuntu）

macOS

手動安裝（不使用一鍵腳本）

程式碼結構說明

Demo 目錄

各 dataflow 對應關係

資料流原理

埠設定位置

常見問題與注意事項

1. cargo 卡在 `Updating 'tuna' index`

2. mediapipe 缺 solutions 子模組 / 安裝損壞

3. dora 版本不相容（message v0.8.0 vs v0.7.0）

4. MuJoCo / mediapipe 載入模型失敗（中文路徑）

5. 攝影機權限

6. 埠號每次變化

7. 缺少 openCV

相關頁面