SCS0009-Handtracking (offizielles dora-Demo)

Diese Seite beschreibt die offizielle Handtracking-Kette der SCS0009-Bus-Servo-Version: Kamera → MediaPipe → MuJoCo IK → AHControl (Rust) → SCS0009. Die Tracking-Version für PWM siehe PWM-Handtracking.

Die Skripte 1 → 4 unten beziehen sich auf das Windows-Ein-Klick-Skript; die Skripte liegen in AmazingHand-main/Demo/Windows_Deploy_Scripts/. Position und Unterschiede der Linux-/macOS-Skripte findest du am Ende. Führe sie in nummerierter Reihenfolge aus.

---

Hardware-Vorbereitung

Hardware	Anforderung
Dexterhand selbst	rechte Hand / linke Hand / beide Hände
Servo-Treiberplatine	extern, USB am PC
Stromversorgung	externes Netzteil, mindestens 5 V 4 A (oder 7–12 V Eingang gemäß Treiberplatinenanforderung); USB-Versorgung reicht nicht
Kamera	integriert oder USB-Kamera

Modelldateien können bei Onshape angesehen oder selbst heruntergeladen werden (inkl. URDF).

Das MuJoCo-Modell der Dexterhand

---

Umgebungsinstallation (Skript 1)

Doppelklick auf 1-Install_Env.bat — erledigt automatisch:

1. Prüft MSVC-Build-Tools (cl.exe) — für die Rust-Kompilierung erforderlich. Falls sie fehlen, wird die Installation von Visual Studio 2022 Build Tools vorgeschlagen; Workload "Desktop development with C++" auswählen, danach Terminal neu öffnen.

2. Installiert Rust (rustup + stable-msvc Toolchain)

3. Konfiguriert den cargo-Tsinghua-Mirror (C:\Users\<dein Benutzername>\.cargo\config.toml), um Crate-Downloads zu beschleunigen

4. Installiert uv (Python-Paketmanager)

5. Installiert dora-cli 0.5.0 (cargo install, erste Kompilierung ca. 10–20 Minuten, bitte Geduld)

6. Installiert das dora-rs-pip-Paket (optional, wird in die virtuelle Umgebung installiert)

Wichtig: Nach dem Skript das Terminal schließen und neu öffnen, damit die Umgebungsvariablen wirksam werden. Die Installation kann je nach Netzwerk langsam sein, bitte geduldig warten und nicht mittendrin abbrechen.

Alternative Umgebungsinstallation (wenn das Skript nicht verfügbar ist)

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

  • Windows: rustup-init.exe verwenden, standardmäßige MSVC-Toolchain wählen

  • Umgebungsvariable: %USERPROFILE%\.cargo\bin zum PATH hinzufügen

• uv: In PowerShell irm https://astral.sh/uv/install.ps1 | iex ausführen.

  • Umgebungsvariable: %USERPROFILE%\.local\bin zum PATH hinzufügen

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

cargo-Tsinghua-Mirror einrichten (~/.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

Den sparse-Index verwenden (wie oben), nicht den git-Repository-Mirror — die git-Variante lädt beim ersten Mal etwa 1 GB Index herunter und bleibt leicht bei Updating 'tuna' index hängen.

---

Verkabelung

• Servo-Treiberplatine per USB mit dem PC verbinden, externe Stromversorgung (mindestens 5 V 4 A oder 7–12 V gemäß Treiberplatinenanforderung)

• Portnummer am PC ermitteln: Geräte-Manager → Anschlüsse (COM und LPT), z. B. COM11

---

Serielle Schnittstelle konfigurieren (Skript 2)

Doppelklick auf 2-Setup_Serial.bat (die eigentliche Logik liegt in 2-Setup_Serial.ps1):

1. Aufforderung "Bitte die Servo-Treiberplatine an den PC anschließen" → Eingabetaste startet die Erkennung

2. Erkannte COM-Ports werden automatisch aufgelistet (mit Gerätenamen)

3. Bei einem Port mit Eingabetaste bestätigen, bei mehreren die Nummer eingeben

4. Schreibt automatisch --serialport in die 3 dataflow-yml-Dateien und den Standardport in AHControl\src\main.rs

5. Originaldateien werden automatisch als .bak gesichert

Nach erneutem Anstecken des USB kann sich die Portnummer ändern; dann dieses Skript erneut ausführen.

---

Code bereitstellen (Skript 3)

Doppelklick auf 3-Deploy_Demo.bat — erledigt automatisch:

1. Startet den dora-Daemon (dora up)

2. Erstellt eine Python-3.12-virtuelle-Umgebung (uv venv --python 3.12)

3. Aktiviert die virtuelle Umgebung

4. Kompiliert den AHControl-Rust-Node (cargo build --release, beim ersten Mal ca. 10 Minuten)

5. Synchronisiert die Abhängigkeiten von AHSimulation, HandTracking (uv sync)

6. Erzwingt die Installation von mediapipe==0.10.14

Deployment nur einmal ausführen. Bei erneuter Ausführung wird gefragt, ob die virtuelle Umgebung neu gebaut werden soll.

---

Code ausführen (Skript 4)

Doppelklick auf 4-Run_Demo.bat — interaktives Menü erscheint:

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

• 1: Simulationsumgebung, Kameragesten steuern zwei simulierte Hände

• 2: Untermenü für rechte Hand / linke Hand / beide Hände

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

Nach der Auswahl werden automatisch dora build + dora run ausgeführt. Ein Kamerafenster öffnet sich; mache Gesten vor der Kamera, die Dexterhand folgt in Echtzeit. Ctrl+C zum Beenden; nach Ende des Datenstroms Eingabetaste drücken, um zum Hauptmenü zurückzukehren, dann einen anderen Modus wählen oder mit q beenden.

Beim ersten Start kann Windows die Kameraberechtigung abfragen; auf "Zulassen" klicken.

---

Projekt bereinigen (Skript 0)

Doppelklick auf 0-Cleanup_Project.bat, Y zur Bestätigung eingeben, dann automatisch:

1. Stoppt den dora-Daemon

2. Löscht die 3 virtuellen Umgebungen (.venv)

3. Löscht die Rust-Build-Artefakte (AmazingHand-main/Demo/target)

4. Löscht pycache, .bak-Sicherungen, Logs, AmazingHand-main/Demo/out (dora-Logverzeichnis)

5. Stellt den Standardport wieder her (--serialport /dev/ttyACM0) und entfernt lokale Seriell-Rückstände

Nach der Bereinigung kann der gesamte Ordner AmazingHand-main sauber und ohne Rückstände an andere weitergegeben werden. Auf einem neuen Rechner einfach 1 → 2 → 3 → 4 in dieser Reihenfolge ausführen.

---

Linux- und macOS-Unterschiede

Die Ein-Klick-Skripte gibt es auch für Linux und macOS, in AmazingHand-main/Demo/Linux_Deploy_Scripts/ bzw. AmazingHand-main/Demo/Mac_Deploy_Scripts/. Der Ablauf der Schritte 1–4 ist wie unter Windows; unten nur die Systemunterschiede.

Skript-Ausführungsrechte (Linux / macOS)

Nach dem Kopieren von Windows oder aus einem Archiv geht das +x-Ausführungsbit verloren; vor dem ersten Start ausführen:

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

Danach mit ./Skriptname starten; nicht bash Skriptname verwenden, sonst werden die interaktiven Hinweise im Skript übersprungen.

Linux (Ubuntu)

• Serielle Berechtigungen: sudo usermod -aG dialout $USER, abmelden und neu anmelden; temporär sudo chmod 666 /dev/ttyACM*.
• Gerätenamen: /dev/ttyUSB* (CH340 / CP2102) oder /dev/ttyACM* (Onboard-USB-Seriell).
• Kamera: Einstellungen → Datenschutz → Kamera, Zugriff für Anwendungen erlauben; prüfen, dass kein anderes Programm die Kamera belegt.
• Virtuelle Maschine: zuerst die USB-Kamera mit der VM verbinden; wenn OpenCV can't open camera by index oder select() timeout meldet, in den VM-Einstellungen den USB-Controller zwischen 2.0/3.1 umschalten und neu starten; bei Bedarf sudo usermod -aG video $USER.
• Chinesische Pfade: Projektpfade möglichst englisch halten, sonst schlagen MuJoCo-/MediaPipe-Modellladungen fehl.

macOS

• Serielle Schnittstelle: /dev/cu.* verwenden, nicht /dev/tty.*; mit ls /dev/cu.* Gerätenamen anzeigen.
• Serielle Berechtigungen: sudo chmod 666 /dev/cu.usbmodem* oder in „Systemeinstellungen → Datenschutz & Sicherheit → Eingabeüberwachung" das Terminal zulassen.
• Kamera: beim ersten Start dem Terminal Kamerazugriff erlauben; auch unter „Systemeinstellungen → Datenschutz & Sicherheit → Kamera" änderbar.
• Apple Silicon: Der erste cargo build der dora-Abhängigkeiten ist normalerweise langsam; bei „Entwickler kann nicht verifiziert werden" unter „Datenschutz & Sicherheit" auf „Trotzdem öffnen" klicken.

Manuelle Installation (ohne Ein-Klick-Skripte)

Wenn die Skripte nicht verfügbar sind, nach dem offiziellen Demo manuell bereitstellen:

1. Code holen: Repository klonen oder AmazingHand.zip herunterladen, in AmazingHand-main/Demo/ wechseln.

   

2. Umgebung installieren: Rust (rustup), uv, dora-cli; PowerShell/Bash neu öffnen, damit PATH wirksam wird. Details siehe oben Umgebungsinstallation (Skript 1).

3. Umgebung erstellen und Abhängigkeiten installieren:

   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. Serielle Schnittstelle konfigurieren: --serialport in dataflow_tracking_real_right.yml / _left.yml / _2hands.yml auf den tatsächlichen COM-Port bzw. /dev/ttyUSB0, /dev/cu.usbserial-* ändern.

   

   

5. Bauen und ausführen:

   # Simulation
   dora build dataflow_tracking_simu.yml --uv
   dora run dataflow_tracking_simu.yml --uv
   
   # echte Hardware (rechte Hand; für linke/beide den Dateinamen ersetzen)
   dora build dataflow_tracking_real_right.yml --uv
   dora run dataflow_tracking_real_right.yml --uv
   
   # einfaches Winkelbeispiel
   dora build dataflow_angle_simu.yml --uv
   dora run dataflow_angle_simu.yml --uv

   

   

6. Häufige Probleme: mediapipe erfordert 0.10.14 (Python 3.12); bei inkompatibler dora-Version gemäß pyproject.toml/Logs angleichen; bei fehlendem OpenCV opencv-contrib-python installieren; Kameraberechtigungen, VM-USB-Durchreichung und chinesische Pfade beeinflussen das Modellladen. Genaueres siehe Häufige Probleme und Hinweise.

Ausführlichere Beschreibung des offiziellen Demos siehe AmazingHand-main/Demo/README.md; die Ein-Klick-Deploy-Schritte der einzelnen Systeme sind auf dieser Seite zusammengeführt.

Code-Struktur

Demo-Verzeichnis

AmazingHand-main/Demo/
├── AHControl/                Rust-Node: serielle Servo-Steuerung, unter config/ Servo-IDs und Offsets
├── AHSimulation/             Python-Node: MuJoCo-Simulation und inverse Kinematik
├── HandTracking/             Python-Node: MediaPipe-Hand-Landmark-Erkennung
├── dataflow_*.yml            dora-Dataflow-Orchestrierung
├── Windows_Deploy_Scripts/   Windows-Ein-Klick-Deploy-Skripte
├── Linux_Deploy_Scripts/     Linux-Ein-Klick-Deploy-Skripte
├── Mac_Deploy_Scripts/       macOS-Ein-Klick-Deploy-Skripte
└── docs/                     offizielle mehrsprachige Deployment-Tutorials

Zuordnung der dataflows

Dataflow-Datei	Zweck
dataflow_tracking_simu.yml	Kamera-Handtracking, treibt nur die MuJoCo-Simulationshand
dataflow_tracking_real_right.yml	Kamera-Handtracking, treibt die echte rechte Hand
dataflow_tracking_real_left.yml	Kamera-Handtracking, treibt die echte linke Hand
dataflow_tracking_real_2hands.yml	Kamera-Handtracking, treibt gleichzeitig linke und rechte Hand
dataflow_angle_simu.yml	gibt Gelenkwinkel direkt vor, validiert Simulation und inverse Kinematik

Dataflow-Prinzip

Kamera → HandTracking (MediaPipe-Gestenerkennung)
              ↓ Koordinaten der Hand-Landmarks
         AHSimulation (MuJoCo-Simulation + inverse Kinematik)
              ↓ Gelenkzielwinkel
         AHControl (seriell → Servo-Treiberplatine → Dexterhand)

Position der Portkonfiguration

• args:-Zeile der drei dataflow_tracking_real_*.yml: --serialport COMxx

• AHControl\src\main.rs: default_value = "COMxx" (Standardwert des seriellen Parameters)

• AHControl\config\*.toml: Servomodell, ID, Offset (normalerweise nicht zu ändern)

---

Häufige Probleme und Hinweise

1. cargo bleibt bei Updating 'tuna' index hängen

• Ursache: Mirror wurde als git-Repository konfiguriert (.../git/crates.io-index.git), der erste Lauf lädt einen Index von 1 GB+ herunter

• Lösung: C:\Users\<dein Benutzername>\.cargo\config.toml auf den sparse-Index umstellen (siehe oben „cargo-Tsinghua-Mirror einrichten") oder 1-Install_Env.bat erneut ausführen

2. mediapipe: fehlendes solutions-Submodul / beschädigte Installation

uv pip uninstall mediapipe

uv pip install mediapipe==0.10.14

• Muss bei aktivierter virtueller Umgebung ausgeführt werden (im Verzeichnis Demo)

• 3-Deploy_Demo.bat erledigt diesen Fallback automatisch

3. dora-Version inkompatibel (message v0.8.0 vs. v0.7.0)

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

• Ursache: dora-cli-Version passt nicht zu dora-node-api. Beide müssen 0.5.0 sein

  • Prüfen: dora --version sollte dora-cli 0.5.0, dora-message: 0.8.0 ausgeben

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

  • Wenn mehrere dora im PATH liegen (z. B. altes C:\Users\<Benutzername>\.dora\bin), sicherstellen, dass .cargo\bin vorn steht, oder die alte Version löschen

  

  

4. MuJoCo / mediapipe können Modelle nicht laden (chinesische Pfade)

• Symptom: ParseXML: Error opening file '...\scene.xml' oder Can't find file: ....tflite

• Ursache: Die C++-Lader von MuJoCo 3.x / mediapipe können unter Windows absolute Pfade mit chinesischen Zeichen nicht öffnen (z. B. D:\中文目录...)

• Dieses Projekt enthält bereits Korrekturen:

  • AHSimulation\AHSimulation\mj_mink_*.py wechselt vor dem Modellladen das Arbeitsverzeichnis

  • HandTracking\mediapipe_patch.py umgeht das mit 8.3-Kurznamen + relativen Pfaden

• Diese Korrekturdateien nicht löschen

5. Kameraberechtigung

• Beim ersten Start im Dialog "Zulassen" wählen

• Einstellungen → Datenschutz → Kamera → Desktop-Apps Zugriff erlauben

  

  

  

6. Portnummer ändert sich jedes Mal

• Nach erneutem Anstecken des USB kann sich die COM-Nummer ändern, 2-Setup_Serial.bat erneut ausführen

7. OpenCV fehlt

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

(im Verzeichnis HandTracking, bei aktivierter virtueller Umgebung ausführen)

---

Verwandte Seiten

• SCS0009-Schnellstart
• SCS0009-Websteuerung
• SCS0009-Servo-Debugging und Kalibrierung
• PWM-Handtracking