Seguimiento de manos SCS0009 (Demo oficial dora)

Esta página describe la cadena oficial de seguimiento de manos de la versión con servos de bus SCS0009: cámara → MediaPipe → MuJoCo IK → AHControl (Rust) → SCS0009. Para el seguimiento de la versión PWM, consulta Seguimiento de manos PWM.

Los scripts 1 → 4 siguientes se presentan con los scripts de un clic para Windows, situados en AmazingHand-main/Demo/Windows_Deploy_Scripts/; para la ubicación y las diferencias de los scripts de Linux y macOS, consulta el final del documento. Ejecútalos en orden numérico.

---

Preparación del hardware

Hardware	Requisitos
Cuerpo de la mano diestra	Derecha / Izquierda / Ambas
Placa controladora de servos	Externa, USB al PC
Alimentación	Fuente externa, al menos 5 V 4 A (o entrada de 7–12 V según lo requiera la placa controladora); la alimentación USB es insuficiente
Cámara	Integrada en el PC o webcam USB

Los archivos del modelo se pueden ver o descargar en Onshape (incluye URDF).

Modelo MuJoCo de la mano diestra

---

Instalación del entorno (script 1)

Haz doble clic en 1-Install_Env.bat; automáticamente:

1. Comprueba las herramientas de compilación de MSVC (cl.exe), necesarias para compilar Rust. Si faltan, te pedirá instalar Visual Studio 2022 Build Tools, marcar «Desarrollo para el escritorio con C++» y volver a abrir el terminal tras la instalación.

2. Instala Rust (rustup + toolchain stable-msvc)

3. Configura el espejo de Tsinghua para cargo (C:\Users\<tu-usuario>\.cargo\config.toml) para acelerar la descarga de crates

4. Instala uv (gestor de paquetes de Python)

5. Instala dora-cli 0.5.0 (cargo install; la primera compilación tarda unos 10~20 minutos, ten paciencia)

6. Instala el paquete pip dora-rs (opcional; se instalará en el entorno virtual)

Importante: al terminar el script, cierra y vuelve a abrir el terminal para que las variables de entorno surtan efecto. El proceso de instalación puede tardar por la red; ten paciencia y no lo cierres a mitad.

Alternativa a la instalación del entorno (si el script no está disponible)

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

  • En Windows usa rustup-init.exe y elige la toolchain MSVC por defecto

  • Variable de entorno: añade %USERPROFILE%\.cargo\bin al PATH

• uv: en PowerShell ejecuta irm https://astral.sh/uv/install.ps1 | iex.

  • Variable de entorno: añade %USERPROFILE%\.local\bin al PATH

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

Configuración del espejo de Tsinghua para 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 el índice disperso (sparse) (como arriba), no un espejo de repositorio git: el método git descarga primero unos 1 GB de índice y es fácil que se quede colgado en Updating 'tuna' index.

---

Cableado

• La placa controladora de servos se conecta al PC por USB y usa una fuente de alimentación externa (al menos 5 V 4 A, o entrada de 7–12 V según lo requiera la placa)

• En el PC, localiza el número de puerto: Administrador de dispositivos → Puertos (COM y LPT), por ejemplo COM11

---

Configurar el puerto serie (script 2)

Haz doble clic en 2-Setup_Serial.bat (la lógica real está en 2-Setup_Serial.ps1):

1. Muestra «Conecta la placa controladora de servos al PC» → pulsa Enter para iniciar la detección

2. Lista automáticamente los puertos COM detectados (con el nombre del dispositivo)

3. Si hay un solo puerto, pulsa Enter para confirmar; si hay varios, escribe el número

4. Escribe automáticamente --serialport en los 3 archivos yml de dataflow y el puerto por defecto en AHControl\src\main.rs

5. Los archivos originales se guardan automáticamente como .bak

Si vuelves a conectar o desconectar el USB, el número de puerto puede cambiar y tendrás que volver a ejecutar este script.

---

Despliegue del código (script 3)

Haz doble clic en 3-Deploy_Demo.bat; automáticamente:

1. Inicia el daemon de dora (dora up)

2. Crea un entorno virtual de Python 3.12 (uv venv --python 3.12)

3. Activa el entorno virtual

4. Compila el nodo Rust AHControl (cargo build --release; la primera vez tarda unos 10 minutos)

5. Sincroniza las dependencias de AHSimulation y HandTracking (uv sync)

6. Instala a la fuerza mediapipe==0.10.14

El despliegue solo hay que hacerlo una vez. Si lo vuelves a ejecutar, preguntará si quieres reconstruir el entorno virtual.

---

Ejecutar el código (script 4)

Haz doble clic en 4-Run_Demo.bat; aparece un menú interactivo:

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

• Elige 1: entorno de simulación; los gestos de la cámara accionan las dos manos simuladas

• Elige 2: entra en un submenú para elegir mano derecha / izquierda / ambas

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

Tras elegir, se ejecuta automáticamente dora build + dora run. Se abre la ventana de la cámara; haz gestos frente a la cámara y la mano seguirá en tiempo real. Ctrl+C para detener; cuando termine el flujo de datos, pulsa Enter para volver al menú principal y elegir otro modo o q para salir.

En la primera ejecución, Windows puede bloquear el permiso de cámara; haz clic en «Permitir».

---

Limpieza del proyecto (script 0)

Haz doble clic en 0-Cleanup_Project.bat, escribe Y para confirmar y se limpiará automáticamente:

1. Detiene el daemon de dora

2. Elimina los 3 entornos virtuales (.venv)

3. Elimina los artefactos de compilación de Rust (AmazingHand-main/Demo/target)

4. Elimina pycache, las copias .bak, los registros y AmazingHand-main/Demo/out (directorio de registros de dora)

5. Restaura el puerto por defecto (--serialport /dev/ttyACM0) y elimina los restos de puerto serie de esta máquina

Tras la limpieza puedes copiar toda la carpeta AmazingHand-main a otra persona, limpia y sin restos. En una máquina nueva, ejecuta los scripts en orden 1 → 2 → 3 → 4.

---

Diferencias entre Linux y macOS

Los scripts de un clic también están disponibles para Linux y macOS, en AmazingHand-main/Demo/Linux_Deploy_Scripts/ y AmazingHand-main/Demo/Mac_Deploy_Scripts/ respectivamente. El flujo de los pasos 1–4 es el mismo que en Windows; a continuación solo se indican las diferencias del sistema.

Permisos de ejecución de los scripts (Linux / macOS)

Si los copias desde Windows o desde un archivo comprimido, el bit de ejecución +x de los scripts se pierde; antes de la primera ejecución, ejecuta:

cd "AmazingHand-main/Demo/Linux_Deploy_Scripts"   # en macOS cambia a Mac_Deploy_Scripts
chmod +x *.sh

Después ejecútalos con ./nombre-del-script; no uses bash nombre-del-script, porque se saltarían las preguntas interactivas del script.

Linux (Ubuntu)

• Permisos del puerto serie: sudo usermod -aG dialout $USER, cierra sesión y vuelve a entrar; temporalmente puedes usar sudo chmod 666 /dev/ttyACM*.
• Nombre del dispositivo: /dev/ttyUSB* (CH340 / CP2102) o /dev/ttyACM* (puerto serie USB integrado).
• Cámara: Configuración → Privacidad → Cámara, permite el acceso a las aplicaciones; confirma que ningún otro programa esté usando la cámara.
• Máquina virtual: conecta primero la cámara USB a la máquina virtual; si OpenCV muestra can't open camera by index o select() timeout, cambia el controlador USB 2.0 / 3.1 en la configuración de la máquina virtual y reinicia; si es necesario, sudo usermod -aG video $USER.
• Rutas con caracteres chinos: usa rutas en inglés para el proyecto, para evitar que MuJoCo / MediaPipe fallen al cargar el modelo.

macOS

• Puerto serie: usa /dev/cu.*, no /dev/tty.*; consulta ls /dev/cu.* para ver el nombre del dispositivo.
• Permisos del puerto serie: sudo chmod 666 /dev/cu.usbmodem*, o permite el terminal en «Configuración del sistema → Privacidad y seguridad → Monitorización de entrada».
• Cámara: en la primera ejecución, permite que el terminal acceda a la cámara; también puedes cambiarlo en «Configuración del sistema → Privacidad y seguridad → Cámara».
• Apple Silicon: la primera compilación de las dependencias de dora con cargo build tarda más de lo normal; si aparece «no se puede verificar al desarrollador», ve a «Privacidad y seguridad» y pulsa «Abrir igualmente».

Instalación manual (sin los scripts de un clic)

Si los scripts no están disponibles, puedes desplegar manualmente siguiendo el Demo oficial:

1. Obtener el código: clona el repositorio o descarga AmazingHand.zip y entra en AmazingHand-main/Demo/.

   

2. Instalar el entorno: Rust (rustup), uv, dora-cli; vuelve a abrir PowerShell/Bash para que el PATH surta efecto. Los detalles de instalación están en Instalación del entorno (script 1).

3. Crear el entorno e instalar las dependencias:

   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. Configurar el puerto serie: edita --serialport en dataflow_tracking_real_right.yml / _left.yml / _2hands.yml y cámbialo por el COM real o /dev/ttyUSB0, /dev/cu.usbserial-*.

   

   

5. Compilar y ejecutar:

   # simulación
   dora build dataflow_tracking_simu.yml --uv
   dora run dataflow_tracking_simu.yml --uv
   
   # hardware real (mano derecha; sustituye el nombre de archivo para izquierda/ambas)
   dora build dataflow_tracking_real_right.yml --uv
   dora run dataflow_tracking_real_right.yml --uv
   
   # ejemplo de ángulos simple
   dora build dataflow_angle_simu.yml --uv
   dora run dataflow_angle_simu.yml --uv

   

   

6. Preguntas frecuentes: mediapipe necesita 0.10.14 (Python 3.12); si la versión de dora no es compatible, alinéala según pyproject.toml/los registros; si falta OpenCV, instala opencv-contrib-python; los permisos de cámara, el paso USB directo a la máquina virtual y las rutas con caracteres chinos pueden afectar a la carga del modelo. Para el diagnóstico detallado, consulta Preguntas frecuentes y notas.

La explicación más detallada del Demo oficial está en AmazingHand-main/Demo/README.md; los pasos de despliegue de un clic de cada sistema ya están integrados en esta página.

Descripción de la estructura del código

Directorio Demo

AmazingHand-main/Demo/
├── AHControl/                Nodo Rust: controla los servos por puerto serie; en config/ están los ID y desfases de servo
├── AHSimulation/             Nodo Python: simulación MuJoCo y cinemática inversa
├── HandTracking/             Nodo Python: reconocimiento de landmarks de mano con MediaPipe
├── dataflow_*.yml            Orquestación de flujos de datos de dora
├── Windows_Deploy_Scripts/   Scripts de despliegue de un clic para Windows
├── Linux_Deploy_Scripts/     Scripts de despliegue de un clic para Linux
├── Mac_Deploy_Scripts/       Scripts de despliegue de un clic para macOS
└── docs/                     Tutoriales oficiales de despliegue multilingües

Correspondencia de cada dataflow

Archivo de flujo de datos	Uso
dataflow_tracking_simu.yml	Seguimiento de gestos con cámara, solo acciona las manos simuladas de MuJoCo
dataflow_tracking_real_right.yml	Seguimiento de gestos con cámara, acciona la mano derecha real
dataflow_tracking_real_left.yml	Seguimiento de gestos con cámara, acciona la mano izquierda real
dataflow_tracking_real_2hands.yml	Seguimiento de gestos con cámara, acciona ambas manos a la vez
dataflow_angle_simu.yml	Da directamente los ángulos articulares para validar la simulación y la cinemática inversa

Principio del flujo de datos

摄像头 → HandTracking（MediaPipe 识别手势）
              ↓ 手部关键点坐标
         AHSimulation（MuJoCo 仿真 + 逆运动学）
              ↓ 关节目标角度
         AHControl（串口 → 舵机驱动板 → 灵巧手）

Ubicación de la configuración del puerto

• La línea args: de los tres archivos dataflow_tracking_real_*.yml: --serialport COMxx

• default_value = "COMxx" de AHControl\src\main.rs (valor por defecto del parámetro de puerto serie)

• AHControl\config\*.toml: modelo de servo, ID, desfases (normalmente no hace falta cambiarlos)

---

Preguntas frecuentes y notas

1. cargo se queda colgado en Updating 'tuna' index

• Causa: la configuración del espejo usa el modo repositorio git (.../git/crates.io-index.git); la primera vez descarga más de 1 GB de índice

• Solución: cambia C:\Users\<tu-usuario>\.cargo\config.toml al índice disperso (sparse) (ver «Configuración del espejo de Tsinghua para cargo» arriba), o vuelve a ejecutar 1-Install_Env.bat

2. mediapipe sin el submódulo solutions / instalación dañada

uv pip uninstall mediapipe

uv pip install mediapipe==0.10.14

• Debe ejecutarse con el entorno virtual activado (en el directorio Demo)

• 3-Deploy_Demo.bat ya hace este paso como mecanismo de reserva

3. Versión de dora incompatible (message v0.8.0 vs v0.7.0)

• Síntoma: version mismatch: message format v0.8.0 is not compatible with expected message format v0.7.0

• Causa: la versión de dora-cli no coincide con dora-node-api. Deben unificarse en 0.5.0

  • Comprobación: dora --version debe mostrar dora-cli 0.5.0, dora-message: 0.8.0

  • Solución: cargo install dora-cli --version 0.5.0 --force

  • Si hay varios dora en el PATH (por ejemplo, una versión antigua en C:\Users\<tu-usuario>\.dora\bin), asegúrate de que .cargo\bin esté delante o elimina la versión antigua

  

  

4. Fallo al cargar el modelo de MuJoCo / mediapipe (rutas con caracteres chinos)

• Síntoma: ParseXML: Error opening file '...\scene.xml' o Can't find file: ....tflite

• Causa: los cargadores C++ de MuJoCo 3.x / mediapipe en Windows no pueden abrir rutas absolutas con caracteres chinos (por ejemplo D:\中文目录...)

• Este proyecto ya incluye correcciones:

  • AHSimulation\AHSimulation\mj_mink_*.py cambia el directorio de trabajo antes de cargar el modelo

  • HandTracking\mediapipe_patch.py usa rutas cortas 8.3 + rutas relativas para evitarlo

• No elimines este código de corrección

5. Permisos de cámara

• En la primera ejecución, elige «Permitir» en el diálogo

• Configuración → Privacidad → Cámara → permitir el acceso a aplicaciones de escritorio

  

  

  

6. El número de puerto cambia cada vez

• Tras volver a conectar el USB, el número COM puede cambiar; vuelve a ejecutar 2-Setup_Serial.bat

7. Falta OpenCV

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

(En el directorio HandTracking, con el entorno virtual activado)

---

Páginas relacionadas

• Inicio rápido SCS0009
• Control web SCS0009
• Depuración y calibración de servos SCS0009
• Seguimiento de manos PWM