Tracciamento delle mani SCS0009 (demo ufficiale dora)

Questa pagina descrive la catena ufficiale di tracciamento delle mani per la versione con servo bus SCS0009: telecamera → MediaPipe → MuJoCo IK → AHControl (Rust) → SCS0009. Per il tracciamento della versione PWM vedi Tracciamento delle mani PWM.

Gli script 1 → 4 riportati di seguito hanno come esempio lo script in un clic per Windows, che si trova in AmazingHand-main/Demo/Windows_Deploy_Scripts/; per posizione e differenze degli script su Linux e macOS vedi le differenze Linux e macOS. Eseguili nell'ordine numerico.

---

Preparazione hardware

Hardware	Requisiti
Mano robotica	Mano destra / mano sinistra / entrambe
Scheda driver servo	Esterna, collegata al PC via USB
Alimentazione	Alimentatore esterno, almeno 5V 4A (oppure ingresso 7–12V secondo i requisiti della scheda driver); l'alimentazione USB non è sufficiente
Telecamera	Integrata nel PC o telecamera USB

I file del modello sono visibili o scaricabili da Onshape (incluso URDF).

Modello MuJoCo della mano robotica

---

Installazione dell'ambiente (script 1)

Fai doppio clic su 1-Install_Env.bat; vengono eseguite automaticamente:

1. Verifica di MSVC Build Tools (cl.exe) — necessari per la compilazione Rust. Se mancano viene proposto di installare Visual Studio 2022 Build Tools, selezionando "Sviluppo desktop con C++"; al termine riapri il terminale.

2. Installazione di Rust (rustup + toolchain stable-msvc)

3. Configurazione dello specchio Tsinghua per cargo (C:\Users\<tuo nome utente>\.cargo\config.toml) per accelerare il download dei crate

4. Installazione di uv (gestore di pacchetti Python)

5. Installazione di dora-cli 0.5.0 (cargo install, la prima compilazione richiede circa 10~20 minuti, attendi con pazienza)

6. Installazione del pacchetto pip dora-rs (opzionale, viene installato nell'ambiente virtuale)

Importante: al termine dello script chiudi e riapri il terminale per rendere effettive le variabili d'ambiente. Il processo di installazione può essere lento per la rete; attendi con pazienza e non chiudere a metà.

Alternativa all'installazione dell'ambiente (se lo script non è disponibile)

• Rust: https://www.rust-lang.org/tools/install

  • Su Windows usa rustup-init.exe e scegli la toolchain MSVC predefinita

  • Variabili d'ambiente: aggiungi %USERPROFILE%\.cargo\bin al PATH

• uv: in PowerShell esegui irm https://astral.sh/uv/install.ps1 | iex.

  • Variabili d'ambiente: aggiungi %USERPROFILE%\.local\bin al PATH

• dora-cli: cargo install dora-cli --version 0.5.0

Configurazione dello specchio Tsinghua per cargo (~/.cargo/config.toml)

[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

Usa l'indice sparse (come sopra), non lo specchio di un repository git — con il metodo git la prima volta si scarica un indice di circa 1GB e si rischia di bloccarsi su Updating 'tuna' index.

---

Modalità di cablaggio

• Collegare la scheda driver servo al PC via USB, con alimentazione esterna (almeno 5V 4A, oppure ingresso 7–12V secondo i requisiti della scheda driver)

• Sul PC individua il numero di porta: Gestione dispositivi → Porte (COM e LPT), ad es. COM11

---

Configurazione della seriale (script 2)

Fai doppio clic su 2-Setup_Serial.bat (la logica effettiva è in 2-Setup_Serial.ps1):

1. Viene chiesto "collega la scheda driver servo al PC" → premi Invio per avviare il rilevamento

2. Vengono elencate automaticamente le porte COM rilevate (con il nome del dispositivo)

3. Con una sola porta conferma con Invio; con più porte inserisci il numero

4. Vengono scritti automaticamente --serialport nei 3 file yml dei dataflow e la porta predefinita in AHControl\src\main.rs

5. I file originali vengono salvati automaticamente come .bak

Se scolleghi e ricolleghi l'USB, il numero di porta può cambiare; in tal caso esegui di nuovo questo script.

---

Distribuzione del codice (script 3)

Fai doppio clic su 3-Deploy_Demo.bat; vengono eseguite automaticamente:

1. Avvio del demone dora (dora up)

2. Creazione dell'ambiente virtuale Python 3.12 (uv venv --python 3.12)

3. Attivazione dell'ambiente virtuale

4. Compilazione del nodo Rust AHControl (cargo build --release, la prima volta richiede circa 10 minuti)

5. Sincronizzazione delle dipendenze di AHSimulation e HandTracking (uv sync)

6. Installazione forzata di mediapipe==0.10.14

La distribuzione va eseguita una sola volta. Le esecuzioni successive chiedono se ricreare l'ambiente virtuale.

---

Esecuzione del codice (script 4)

Fai doppio clic su 4-Run_Demo.bat; compare un menu interattivo:

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

• Seleziona 1: ambiente di simulazione, i gesti della telecamera azionano le due mani simulate

• Seleziona 2: si entra in un sottomenu, scegli mano destra / sinistra / entrambe

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

Dopo la selezione vengono eseguiti automaticamente dora build + dora run. Compare la finestra della telecamera: esegui i gesti davanti alla telecamera e la mano robotica segue in tempo reale. Ctrl+C per fermare; al termine del flusso di dati premi Invio per tornare al menu principale, dove puoi scegliere un'altra modalità o q per uscire.

Alla prima esecuzione Windows può bloccare il permesso della telecamera; fai clic su "Consenti".

---

Pulizia del progetto (script 0)

Fai doppio clic su 0-Cleanup_Project.bat, inserisci Y per confermare e vengono eseguite automaticamente:

1. Arresto del demone dora

2. Eliminazione dei 3 ambienti virtuali (.venv)

3. Eliminazione degli artefatti di compilazione Rust (AmazingHand-main/Demo/target)

4. Eliminazione di pycache, backup .bak, log, AmazingHand-main/Demo/out (directory dei log dora)

5. Ripristino della porta predefinita (--serialport /dev/ttyACM0), rimozione dei residui della seriale locale

Dopo la pulizia puoi copiare l'intera cartella AmazingHand-main a qualcun altro, pulita e senza residui. Su una nuova macchina esegui nell'ordine 1 → 2 → 3 → 4.

---

Differenze Linux e macOS

Gli script in un clic sono disponibili anche per Linux e macOS, rispettivamente nelle directory AmazingHand-main/Demo/Linux_Deploy_Scripts/ e AmazingHand-main/Demo/Mac_Deploy_Scripts/. Il flusso dei passaggi 1–4 è identico a Windows; di seguito sono elencate solo le differenze di sistema.

Permessi di esecuzione degli script (Linux / macOS)

Dopo averli copiati da Windows o da un archivio compresso, il bit di esecuzione +x degli script va perso; prima della prima esecuzione esegui:

cd "AmazingHand-main/Demo/Linux_Deploy_Scripts"   # su macOS sostituisci con Mac_Deploy_Scripts
chmod +x *.sh

Poi esegui con ./nome_script; non usare bash nome_script, altrimenti vengono saltati i prompt interattivi all'interno dello script.

Linux (Ubuntu)

• Permessi della seriale: sudo usermod -aG dialout $USER, poi disconnetti e riconnetti; temporaneamente puoi usare sudo chmod 666 /dev/ttyACM*.
• Nome del dispositivo: /dev/ttyUSB* (CH340 / CP2102) oppure /dev/ttyACM* (seriale USB a bordo).
• Telecamera: Impostazioni → Privacy → Fotocamera, consenti l'accesso alle applicazioni; verifica che nessun altro programma stia usando la telecamera.
• Macchina virtuale: collega prima la telecamera USB alla macchina virtuale; se OpenCV segnala can't open camera by index o select() timeout, nella configurazione della VM passa il controller USB a 2.0 / 3.1 e riavvia; se necessario sudo usermod -aG video $USER.
• Percorsi con caratteri cinesi: usa il più possibile percorsi in inglese per il progetto, per evitare che MuJoCo / MediaPipe non riescano a caricare i modelli.

macOS

• Seriale: usa /dev/cu.*, non /dev/tty.*; ls /dev/cu.* per vedere i nomi dei dispositivi.
• Permessi della seriale: sudo chmod 666 /dev/cu.usbmodem*, oppure consenti il terminale in "Impostazioni di Sistema → Privacy e sicurezza → Monitoraggio input".
• Telecamera: alla prima esecuzione consenti al terminale l'accesso alla fotocamera; puoi modificarlo anche in "Impostazioni di Sistema → Privacy e sicurezza → Fotocamera".
• Apple Silicon: la prima compilazione cargo build delle dipendenze dora è lenta, è normale; se compare "impossibile verificare lo sviluppatore", vai in "Privacy e sicurezza" e fai clic su "Apri comunque".

Installazione manuale (senza script in un clic)

Se gli script non sono disponibili, puoi distribuire manualmente la demo ufficiale:

1. Ottenere il codice: clona il repository o scarica AmazingHand.zip, entra in AmazingHand-main/Demo/.

   

2. Installare l'ambiente: Rust (rustup), uv, dora-cli; riapri PowerShell/Bash per rendere effettivo il PATH. I dettagli dell'installazione sono nella sezione Installazione dell'ambiente (script 1).

3. Creare l'ambiente e installare le dipendenze:

   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 ..

   

4. Configurare la seriale: modifica --serialport in dataflow_tracking_real_right.yml / _left.yml / _2hands.yml con la porta COM reale oppure /dev/ttyUSB0, /dev/cu.usbserial-*.

   

   

5. Compilare ed eseguire:

   # simulazione
   dora build dataflow_tracking_simu.yml --uv
   dora run dataflow_tracking_simu.yml --uv
   
   # hardware reale (mano destra; per sinistra/entrambe sostituisci il nome del file)
   dora build dataflow_tracking_real_right.yml --uv
   dora run dataflow_tracking_real_right.yml --uv
   
   # semplice esempio di angoli
   dora build dataflow_angle_simu.yml --uv
   dora run dataflow_angle_simu.yml --uv

   

   

6. Domande frequenti: mediapipe richiede 0.10.14 (Python 3.12); se la versione di dora è incompatibile allineala secondo pyproject.toml/i log; se manca OpenCV installa opencv-contrib-python; permessi della telecamera, pass-through USB della macchina virtuale e percorsi con caratteri cinesi influiscono sul caricamento dei modelli. Per la risoluzione dettagliata vedi Domande frequenti e note.

Per una descrizione più dettagliata della demo ufficiale vedi AmazingHand-main/Demo/README.md; i passaggi della distribuzione in un clic per ciascun sistema sono già stati integrati in questa pagina.

Descrizione della struttura del codice

Directory Demo

AmazingHand-main/Demo/
├── AHControl/                Nodo Rust: controllo seriale dei servo; in config/ ID servo e offset
├── AHSimulation/             Nodo Python: simulazione MuJoCo e cinematica inversa
├── HandTracking/             Nodo Python: riconoscimento dei landmark della mano con MediaPipe
├── dataflow_*.yml            Orchestrazione dei dataflow dora
├── Windows_Deploy_Scripts/   Script di distribuzione in un clic per Windows
├── Linux_Deploy_Scripts/     Script di distribuzione in un clic per Linux
├── Mac_Deploy_Scripts/       Script di distribuzione in un clic per macOS
└── docs/                     Tutorial di distribuzione ufficiali multilingua

Corrispondenza dei dataflow

File dataflow	Scopo
dataflow_tracking_simu.yml	Tracciamento dei gesti con telecamera, aziona solo la mano simulata MuJoCo
dataflow_tracking_real_right.yml	Tracciamento dei gesti con telecamera, aziona la mano destra reale
dataflow_tracking_real_left.yml	Tracciamento dei gesti con telecamera, aziona la mano sinistra reale
dataflow_tracking_real_2hands.yml	Tracciamento dei gesti con telecamera, aziona entrambe le mani
dataflow_angle_simu.yml	Fornisce direttamente gli angoli delle articolazioni, per verificare simulazione e cinematica inversa

Principio del flusso di dati

Telecamera → HandTracking (riconoscimento dei gesti con MediaPipe)
              ↓ coordinate dei landmark della mano
         AHSimulation (simulazione MuJoCo + cinematica inversa)
              ↓ angoli target delle articolazioni
         AHControl (seriale → scheda driver servo → mano robotica)

Posizione della configurazione delle porte

• Riga args: dei tre dataflow_tracking_real_*.yml: --serialport COMxx

• default_value = "COMxx" in AHControl\src\main.rs (valore predefinito del parametro seriale)

• AHControl\config\*.toml: modello di servo, ID, offset (di solito non serve modificarli)

---

Domande frequenti e note

1. cargo bloccato su Updating 'tuna' index

• Causa: la configurazione dello specchio usa il metodo repository git (.../git/crates.io-index.git), la prima volta scarica un indice di 1GB+

• Soluzione: in C:\Users\<tuo nome utente>\.cargo\config.toml passa all'indice sparse (vedi sopra "Configurazione dello specchio Tsinghua per cargo"), oppure esegui di nuovo 1-Install_Env.bat

2. mediapipe manca del sottomodulo solutions / installazione danneggiata

uv pip uninstall mediapipe

uv pip install mediapipe==0.10.14

• Va eseguito con l'ambiente virtuale attivo (nella directory Demo)

• 3-Deploy_Demo.bat esegue già automaticamente questo passaggio di fallback

3. Versione di dora incompatibile (message v0.8.0 vs v0.7.0)

• Sintomo: version mismatch: message format v0.8.0 is not compatible with expected message format v0.7.0

• Causa: la versione di dora-cli non corrisponde a quella di dora-node-api. Devono essere entrambe 0.5.0

  • Verifica: dora --version deve restituire dora-cli 0.5.0, dora-message: 0.8.0

  • Correzione: cargo install dora-cli --version 0.5.0 --force

  • Se nel PATH ci sono più dora (ad es. una versione vecchia in C:\Users\<tuo nome utente>\.dora\bin), assicurati che .cargo\bin venga prima, oppure elimina la versione vecchia

  

  

4. MuJoCo / mediapipe non caricano i modelli (percorsi con caratteri cinesi)

• Sintomo: ParseXML: Error opening file '...\scene.xml' oppure Can't find file: ....tflite

• Causa: su Windows i loader C++ di MuJoCo 3.x / mediapipe non riescono ad aprire percorsi assoluti contenenti caratteri cinesi (ad es. D:\中文目录...)

• Questo progetto include già le correzioni:

  • AHSimulation\AHSimulation\mj_mink_*.py cambia la directory di lavoro prima di caricare il modello

  • HandTracking\mediapipe_patch.py aggira il problema con il percorso breve 8.3 + percorso relativo

• Non eliminare questo codice di correzione

5. Permessi della telecamera

• Al primo avvio seleziona "Consenti" nella finestra

• Impostazioni → Privacy → Fotocamera → consenti l'accesso alle app desktop

  

  

  

6. Il numero di porta cambia ogni volta

• Dopo aver scollegato e ricollegato l'USB il numero COM può cambiare; riesegui 2-Setup_Serial.bat

7. Manca OpenCV

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

(esegui nella directory HandTracking, dopo aver attivato l'ambiente virtuale)

---

Pagine correlate

• Avvio rapido SCS0009
• Controllo web SCS0009
• Messa a punto e calibrazione dei servo SCS0009
• Tracciamento delle mani PWM