Seguimento de mãos SCS0009 (Demo oficial dora)

Esta página descreve a cadeia oficial de seguimento de mãos da versão de servos de barramento SCS0009: câmara → MediaPipe → IK em MuJoCo → AHControl (Rust) → SCS0009. Para o seguimento da versão PWM, ver Seguimento de mãos PWM.

Os scripts 1 → 4 abaixo usam como exemplo os scripts de um clique para Windows, localizados em AmazingHand-main/Demo/Windows_Deploy_Scripts/; para a localização e diferenças dos scripts em Linux e macOS, ver no final da página. Execute pela ordem numérica.

---

Preparação do hardware

Hardware	Requisitos
Corpo da mão robótica	Mão direita / mão esquerda / ambas as mãos
Placa controladora dos servos	Externa, ligada por USB ao PC
Alimentação	Fonte externa, pelo menos 5V 4A (ou entrada de 7–12V conforme os requisitos da placa controladora); a alimentação USB é insuficiente
Câmara	Integrada no PC ou câmara USB

O ficheiro do modelo pode ser consultado ou descarregado em Onshape (inclui URDF).

Modelo MuJoCo da mão robótica

---

Instalação do ambiente (script 1)

Faça duplo clique em 1-Install_Env.bat; executa automaticamente:

1. Verificar as ferramentas de compilação MSVC (cl.exe) —— necessárias para compilar Rust. Se faltarem, indica a instalação do Visual Studio 2022 Build Tools, com a opção "Desenvolvimento para desktop com C++"; após instalar, reabra o terminal.

2. Instalar o Rust (rustup + toolchain stable-msvc)

3. Configurar o espelho TUNA do cargo (C:\Users\<o seu nome de utilizador>\.cargo\config.toml) para acelerar o download de crates

4. Instalar o uv (gestor de pacotes Python)

5. Instalar o dora-cli 0.5.0 (cargo install; a primeira compilação demora cerca de 10~20 minutos, aguarde com paciência)

6. Instalar o pacote pip dora-rs (opcional; é instalado no ambiente virtual)

Importante: após o fim do script, feche e reabra o terminal para aplicar as variáveis de ambiente. O processo de instalação pode ser lento devido à rede; aguarde com paciência e não o feche a meio.

Instalação alternativa do ambiente (quando os scripts não estão disponíveis)

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

  • No Windows, use rustup-init.exe e escolha a toolchain MSVC predefinida

  • Variáveis de ambiente: adicione %USERPROFILE%\.cargo\bin ao PATH

• uv: no PowerShell, execute irm https://astral.sh/uv/install.ps1 | iex.

  • Variáveis de ambiente: adicione %USERPROFILE%\.local\bin ao PATH

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

Configuração do espelho TUNA do 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

Use o índice esparso (sparse) (como acima), não o espelho do repositório git —— o modo git tem de descarregar cerca de 1 GB de índice na primeira vez e facilmente fica bloqueado em Updating 'tuna' index.

---

Modo de cablagem

• A placa controladora dos servos liga-se por USB ao PC, com fonte externa (pelo menos 5V 4A, ou entrada de 7–12V conforme os requisitos da placa controladora)

• No PC, identifique o número da porta: Gestor de Dispositivos → Portas (COM e LPT), por exemplo COM11

---

Configurar a porta série (script 2)

Faça duplo clique em 2-Setup_Serial.bat (a lógica real está em 2-Setup_Serial.ps1):

1. Pede "ligue a placa controladora dos servos ao computador" → Enter para iniciar a deteção

2. Lista automaticamente as portas COM detetadas (com o nome do dispositivo)

3. Com uma única porta, Enter para confirmar; com várias portas, introduza o número

4. Escreve automaticamente --serialport nos 3 dataflow yml e a porta predefinida em AHControl\src\main.rs

5. Os ficheiros originais são copiados automaticamente para backup como .bak

Se voltar a ligar/desligar o USB, o número da porta pode mudar e é necessário voltar a executar este script.

---

Instalação do código (script 3)

Faça duplo clique em 3-Deploy_Demo.bat; executa automaticamente:

1. Inicia o daemon do dora (dora up)

2. Cria um ambiente virtual Python 3.12 (uv venv --python 3.12)

3. Ativa o ambiente virtual

4. Compila o nó Rust AHControl (cargo build --release; cerca de 10 minutos na primeira vez)

5. Sincroniza as dependências do AHSimulation e do HandTracking (uv sync)

6. Força a instalação de mediapipe==0.10.14

A instalação só precisa de ser executada uma vez. Execuções seguintes perguntam se quer recriar o ambiente virtual.

---

Executar o código (script 4)

Faça duplo clique em 4-Run_Demo.bat; aparece um menu interativo:

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

• Escolha 1: ambiente de simulação; os gestos da câmara acionam as duas mãos simuladas

• Escolha 2: entra num submenu para escolher mão direita / mão esquerda / ambas as mãos

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

Após escolher, executa automaticamente dora build + dora run. A janela da câmara abre; faça gestos para a câmara e a mão robótica acompanha em tempo real. Ctrl+C para parar; após o fim do fluxo de dados, prima Enter para voltar ao menu principal e escolher outro modo, ou q para sair.

Na primeira execução, o Windows pode bloquear o acesso à câmara; basta clicar em "Permitir".

---

Limpeza do projeto (script 0)

Faça duplo clique em 0-Cleanup_Project.bat, introduza Y para confirmar e executa automaticamente:

1. Para o daemon do dora

2. Elimina os 3 ambientes virtuais (.venv)

3. Elimina os artefactos de compilação Rust (AmazingHand-main/Demo/target)

4. Elimina pycache, backups .bak, registos e AmazingHand-main/Demo/out (diretório de registos do dora)

5. Restaura a porta predefinida (--serialport /dev/ttyACM0), removendo resíduos da porta série desta máquina

Após a limpeza, pode copiar a pasta AmazingHand-main completa para outra pessoa, limpa e sem resíduos. Numa máquina nova, basta executar pela ordem 1 → 2 → 3 → 4.

---

Diferenças entre Linux e macOS

Os scripts de um clique também têm versões para Linux e macOS, nos diretórios AmazingHand-main/Demo/Linux_Deploy_Scripts/ e AmazingHand-main/Demo/Mac_Deploy_Scripts/. O fluxo dos passos 1–4 é igual ao do Windows; abaixo listam-se apenas as diferenças de sistema.

Permissões de execução dos scripts (Linux / macOS)

Depois de copiar do Windows ou de um arquivo comprimido, o bit de execução +x dos scripts perde-se; antes da primeira execução, execute:

cd "AmazingHand-main/Demo/Linux_Deploy_Scripts"   # em macOS, altere para Mac_Deploy_Scripts
chmod +x *.sh

De seguida, execute com ./nome-do-script; não use bash nome-do-script, caso contrário os pedidos interativos internos do script são ignorados.

Linux (Ubuntu)

• Permissões da porta série: sudo usermod -aG dialout $USER, termine e reinicie a sessão; temporariamente pode usar sudo chmod 666 /dev/ttyACM*.
• Nome do dispositivo: /dev/ttyUSB* (CH340 / CP2102) ou /dev/ttyACM* (porta série USB integrada).
• Câmara: Definições → Privacidade → Câmara, permitir o acesso à aplicação; confirme que nenhum outro programa está a usar a câmara.
• Máquina virtual: ligue primeiro a câmara USB à máquina virtual; se o OpenCV reportar can't open camera by index ou select() timeout, altere o controlador USB para 2.0 / 3.1 nas definições da máquina virtual e reinicie; se necessário, sudo usermod -aG video $USER.
• Caminhos com caracteres chineses: use, se possível, caminhos em inglês para o projeto, para evitar falhas de carregamento de modelos no MuJoCo / MediaPipe.

macOS

• Porta série: use /dev/cu.*, não /dev/tty.*; ls /dev/cu.* para ver o nome do dispositivo.
• Permissões da porta série: sudo chmod 666 /dev/cu.usbmodem*, ou permita o terminal em "Definições do Sistema → Privacidade e Segurança → Monitorização de entrada".
• Câmara: na primeira execução, permita que o terminal aceda à câmara; também pode alterar em "Definições do Sistema → Privacidade e Segurança → Câmara".
• Apple Silicon: é normal que a primeira compilação das dependências do dora com cargo build seja lenta; se aparecer "não é possível verificar o programador", vá a "Privacidade e Segurança" e clique em "Abrir mesmo assim".

Instalação manual (sem os scripts de um clique)

Se os scripts não estiverem disponíveis, pode instalar manualmente segundo a Demo oficial:

1. Obter o código: clone o repositório ou descarregue o AmazingHand.zip e entre em AmazingHand-main/Demo/.

   

2. Instalar o ambiente: Rust (rustup), uv, dora-cli; reabra o PowerShell/Bash para aplicar o PATH. Detalhes em Instalação do ambiente (script 1).

3. Criar o ambiente e instalar as dependências:

   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 a porta série: edite --serialport em dataflow_tracking_real_right.yml / _left.yml / _2hands.yml, alterando para a porta COM real ou /dev/ttyUSB0, /dev/cu.usbserial-*.

   

   

5. Compilar e executar:

   # Simulação
   dora build dataflow_tracking_simu.yml --uv
   dora run dataflow_tracking_simu.yml --uv
   
   # Hardware real (mão direita; para esquerda/ambas, substituir o nome do ficheiro)
   dora build dataflow_tracking_real_right.yml --uv
   dora run dataflow_tracking_real_right.yml --uv
   
   # Exemplo simples de ângulos
   dora build dataflow_angle_simu.yml --uv
   dora run dataflow_angle_simu.yml --uv

   

   

6. Perguntas frequentes: o mediapipe requer 0.10.14 (Python 3.12); se a versão do dora for incompatível, alinhe segundo o pyproject.toml/registos; se faltar o OpenCV, instale opencv-contrib-python; as permissões da câmara, a passagem USB da máquina virtual e os caminhos com caracteres chineses afetam o carregamento dos modelos. Para resolução detalhada, ver Perguntas frequentes e notas.

Para uma descrição mais detalhada da Demo oficial, ver AmazingHand-main/Demo/README.md; os passos de instalação com um clique de cada sistema foram integrados nesta página.

Descrição da estrutura do código

Diretório da Demo

AmazingHand-main/Demo/
├── AHControl/                Nó Rust: controla os servos pela porta série; em config/ estão os IDs e desvios dos servos
├── AHSimulation/             Nó Python: simulação MuJoCo e cinemática inversa
├── HandTracking/             Nó Python: reconhecimento dos pontos-chave da mão com MediaPipe
├── dataflow_*.yml            Orquestração dos fluxos de dados dora
├── Windows_Deploy_Scripts/   Scripts de instalação com um clique para Windows
├── Linux_Deploy_Scripts/     Scripts de instalação com um clique para Linux
├── Mac_Deploy_Scripts/       Scripts de instalação com um clique para macOS
└── docs/                     Tutoriais oficiais de instalação multilingues

Correspondência de cada dataflow

Ficheiro de fluxo de dados	Finalidade
dataflow_tracking_simu.yml	Seguimento de gestos por câmara; aciona apenas a mão simulada no MuJoCo
dataflow_tracking_real_right.yml	Seguimento de gestos por câmara; aciona a mão direita real
dataflow_tracking_real_left.yml	Seguimento de gestos por câmara; aciona a mão esquerda real
dataflow_tracking_real_2hands.yml	Seguimento de gestos por câmara; aciona ambas as mãos
dataflow_angle_simu.yml	Envia diretamente ângulos articulares; verifica a simulação e a cinemática inversa

Princípio do fluxo de dados

Câmara → HandTracking (reconhecimento de gestos com MediaPipe)
              ↓ coordenadas dos pontos-chave da mão
         AHSimulation (simulação MuJoCo + cinemática inversa)
              ↓ ângulos alvo das articulações
         AHControl (porta série → placa controladora dos servos → mão robótica)

Localização da configuração da porta

• Linha args: dos três dataflow_tracking_real_*.yml: --serialport COMxx

• default_value = "COMxx" em AHControl\src\main.rs (valor predefinido do parâmetro da porta série)

• AHControl\config\*.toml: modelo de servo, ID, desvio (normalmente não é necessário alterar)

---

Perguntas frequentes e notas

1. O cargo fica bloqueado em Updating 'tuna' index

• Causa: a configuração do espelho usou o modo de repositório git (.../git/crates.io-index.git), que na primeira vez tem de descarregar mais de 1 GB de índice

• Solução: altere C:\Users\<o seu nome de utilizador>\.cargo\config.toml para o índice esparso (sparse) (ver acima "Configuração do espelho TUNA do cargo"), ou volte a executar 1-Install_Env.bat

2. O mediapipe não tem o submódulo solutions / instalação corrompida

uv pip uninstall mediapipe

uv pip install mediapipe==0.10.14

• Tem de ser executado com o ambiente virtual ativo (no diretório Demo)

• O 3-Deploy_Demo.bat já executa automaticamente este passo de recurso

3. Versão do dora incompatível (message v0.8.0 vs v0.7.0)

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

• Causa: a versão do dora-cli não corresponde ao dora-node-api. É obrigatório uniformizar em 0.5.0

  • Verificação: dora --version deve mostrar dora-cli 0.5.0 e dora-message: 0.8.0

  • Correção: cargo install dora-cli --version 0.5.0 --force

  • Se houver várias versões de dora no PATH (por exemplo, uma antiga em C:\Users\<nome>\.dora\bin), garanta que .cargo\bin vem primeiro ou elimine a versão antiga

  

  

4. Falha de carregamento de modelos no MuJoCo / mediapipe (caminhos com caracteres chineses)

• Sintoma: ParseXML: Error opening file '...\scene.xml' ou Can't find file: ....tflite

• Causa: o carregador C++ do MuJoCo 3.x / mediapipe não consegue abrir caminhos absolutos com caracteres chineses no Windows (por exemplo, D:\中文目录...)

• Este projeto já inclui a correção:

  • AHSimulation\AHSimulation\mj_mink_*.py muda o diretório de trabalho antes de carregar o modelo

  • HandTracking\mediapipe_patch.py contorna com o caminho curto 8.3 + caminho relativo

• Não elimine este código de correção

5. Permissões da câmara

• Na primeira execução, escolha "Permitir" na caixa de diálogo

• Definições → Privacidade → Câmara → Permitir o acesso de aplicações de ambiente de trabalho

  

  

  

6. O número da porta muda de cada vez

• Após ligar/desligar o USB, o número COM pode mudar; volte a executar 2-Setup_Serial.bat

7. Falta o OpenCV

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

(executar no diretório HandTracking, com o ambiente virtual ativo)

---

Páginas relacionadas

• Início rápido SCS0009
• Controlo web SCS0009
• Depuração e calibração dos servos SCS0009
• Seguimento de mãos PWM