AmazingHand PWM — Mão hábil: tutorial completo de utilização
Pacote de entrega: delivery_package.zip
Do comando de gesto no computador host ao rastreamento de gestos: um tutorial completo. Hardware aplicável: ESP32-S3 + 8 canais de servomotores PWM (acionamento diferencial).
Versão: 2026-08-20 · Firmware correspondente: versão componentizada ESP-IDF (
AmazingHand_Serial)
Capítulo 0: Navegação do tutorial
Este tutorial está organizado em ordem sequencial. Primeiro identifique qual a rota que vai seguir e depois salte para o capítulo correspondente.
| Rota | Finalidade | Pré-requisitos | Capítulos |
|---|---|---|---|
| A. Comandos de gesto do computador host | Clicar em botões/introduzir comandos para a mão mecânica fazer gestos (pedra/tesoura/papel/joia…) | Python + firmware gravado | Capítulos 1-4 |
| B. Rastreamento de gestos integrado na GUI | A câmara acompanha os movimentos da mão e a mão mecânica reproduz-os em tempo real (versão simplificada, sem IK) | A + Python de 64 bits + mediapipe | Capítulos 1-4 + 5.1 |
| C. Rastreamento IK oficial com dora | Cadeia completa oficial: câmara → IK → 8 ângulos de junta → servomotores (versão completa) | A + Rust + uv + dora | Capítulos 1-4 + 5.2 |
Rotas recomendadas:
- Primeira utilização → siga a A e confirme primeiro que o firmware e a cablagem estão corretos.
- Para ver rapidamente a câmara a seguir a mão → siga a B (leve, instala em poucos minutos).
- Para um rastreamento formal e completo → siga a C (cadeia oficial, maior precisão).
As três rotas partilham o mesmo hardware; apenas a rota C exige a instalação adicional de Rust/uv/dora no ambiente.
Capítulo 1: Preparação do ambiente
Instale pela ordem indicada. As rotas A/B precisam apenas da secção 1.1; a rota C também precisa da secção 1.2.
1.1 Ambiente do computador host (necessário para as rotas A/B)
① Python 3.12 de 64 bits
É obrigatório usar 64 bits. O mediapipe 0.10.14 só disponibiliza wheel de 64 bits para Windows; não é possível instalá-lo em 32 bits; esta é também uma causa comum de a GUI fechar sozinha ao clicar duas vezes.
- Recomenda-se instalar em
D:\Python312-64bit(este caminho já existe neste computador). - Durante a instalação, marque Add to PATH.
- Verificação (64 bits):
py -3.12-64 -c "import sys; print('64bit' if sys.maxsize > 2**32 else '32bit')"
# 输出: 64bit② Instalar as dependências do computador host
Diretório raiz do projeto (o diretório que contém hand_gui.py):
pip install -r requirements.txt # 只需 pyserial③ Dependências adicionais de rastreamento (para a rota B)
Execute no diretório raiz do projeto:
setup_tracking.batEle faz automaticamente: localiza o Python de 64 bits → cria o ambiente virtual tracking_env → instala o requirements-tracking.txt (mediapipe==0.10.14, numpy<2, scipy, opencv, Pillow, pyserial) → valida o mediapipe.
Ou instale manualmente:
bashD:\Python312-64bit\python.exe -m pip install -r requirements-tracking.txt
1.2 Ambiente IK oficial do dora (necessário para a rota C)
Instalação pelo cliente: clique duas vezes em ..\02_hand_tracking\Demo\Windows_Scripts_CN\1-安装环境.bat (a versão em inglês é ..\02_hand_tracking\Demo\Windows_Deploy_Scripts\1-Install_Env.bat); instala automaticamente todas as dependências: cadeia de ferramentas Rust, uv (gestor de pacotes Python) e dora-cli.
Depois da instalação, feche o terminal e abra-o novamente uma vez para que o PATH tenha efeito. As dependências detalhadas (versões, modo de instalação manual) estão no documento de manutenção; o cliente não precisa de tratar disso.
Capítulo 2: Ligação do hardware
2.1 Lista de hardware
| Hardware | Descrição |
|---|---|
| Placa de desenvolvimento ESP32-S3 | YX-ESP32-S3 ou equivalente |
| 8 canais de servomotores PWM | Servomotores analógicos, acionamento diferencial |
| Placa adaptadora de servomotores | Servomotores → 8 saídas PWM |
| Fonte de alimentação 5V independente | Pelo menos 5V 3A; os servomotores têm correntes transitórias elevadas |
| Cabo USB de dados | ESP32-S3 Type-C → PC |
| Câmara | Câmara integrada ou USB (para rastreamento) |
2.2 Mapeamento de GPIO
PWM1-8 da placa adaptadora → GPIO do ESP32-S3:
| Placa adaptadora | GPIO | Dedo |
|---|---|---|
| PWM1 | 4 | Junta 1 do indicador |
| PWM2 | 5 | Junta 2 do indicador |
| PWM3 | 6 | Junta 1 do médio |
| PWM4 | 7 | Junta 2 do médio |
| PWM5 | 15 | Junta 1 do anelar |
| PWM6 | 16 | Junta 2 do anelar |
| PWM7 | 17 | Junta 1 do polegar |
| PWM8 | 18 | Junta 2 do polegar |
As mãos esquerda e direita partilham o mesmo conjunto de GPIO. A troca entre esquerda/direita é feita por software (Capítulo 4), sem alterar a cablagem.
2.3 Requisitos de alimentação
- Alimente os servomotores com uma fonte de 5V independente (pelo menos 3A); não dependa apenas da alimentação USB.
- Os picos de corrente momentâneos dos servomotores podem reiniciar o ESP32 (sintoma: o ESP32 reinicia repetidamente). Nesse caso, desligue e volte a ligar o ESP32.
2.4 Passos de ligação
- 8 servomotores → PWM1-8 da placa adaptadora
- Placa adaptadora → GPIO correspondente do ESP32-S3 (tabela acima)
- ESP32-S3 Type-C → PC
- Câmara ligada ao PC (para rastreamento)
Para a cablagem/diagrama de circuito detalhado, consulte o diretório
ESP32开发板电路图/.
Capítulo 3: Pré-requisito: gravação do firmware
Para que os servomotores respondam, o firmware tem de ser gravado primeiro. O firmware está em
esp-idf\AmazingHand_Serial\.
3.1 Compilação da versão ESP-IDF (recomendada)
Abra o projeto AmazingHand_Serial no Espressif IDE:
- Definir o chip de destino (na primeira vez):
idf.py set-target esp32s3 - Compilar:
idf.py build - Gravar (no Windows, use a porta COM, por exemplo COM3):
idf.py -p COM3 flash
3.2 Verificação após a gravação
Monitorização série (débito 115200):
idf.py -p COM3 monitorDeve ver o registo de arranque:
AmazingHand Serial Control Ready (ESP-IDF)
Protocol: 115200-8N1 [0xAA CMD LEN DATA CKSUM]O débito da porta série já é configurado de forma unificada pelo firmware/scripts (115200); o cliente não precisa de o configurar manualmente.
Nota: normalmente o firmware já está gravado aquando da entrega do dispositivo; esta etapa só é necessária para firmware novo/nova gravação.
Capítulo 4: Primeira execução: comandos de gesto do computador host
Pré-requisitos: firmware gravado (Capítulo 3), ESP32 ligado à corrente e cabo série ligado. Verifique primeiro no Gestor de dispositivos qual é a porta COM.
4.1 GUI visual (recomendada)
Modo A: executar o exe empacotado
Clique duas vezes em dist/AmazingHand控制台.exe (sem rastreamento; o rastreamento exige o modo a partir do código-fonte).
Modo B: executar a partir do código-fonte
# 项目根目录,先激活追踪环境(装了 mediapipe)或任意带 pyserial 的 Python
tracking_env\Scripts\python hand_gui.pyPassos de utilização da GUI
- Selecione a porta série: no menu pendente superior, escolha a porta COM do ESP32.
- Clique em «Ligar»: a luz de estado fica verde, o registo mostra "ligado" e é enviado automaticamente um teste de ligação NOP.
- Comandos de gesto: clique em «pedra», «tesoura», «papel», «joia», «OK», «pinça», «apontar», etc.; a mão mecânica executa o gesto.
- Mão esquerda/direita: marque «direita»/«esquerda» para alternar a direção espelhada do polegar.
- Acionamento direto dos servomotores: arraste os 8 controlos deslizantes para controlar em tempo real o ângulo de cada servomotor (0-180°).
- Controlo diferencial dos dedos (recomendado): duas barras de progresso por dedo — «Curvar◀▶Esticar» em diferencial inverso, «Oscilar à direita◀▶Oscilar à esquerda» no mesmo sentido. Os dois graus de liberdade são independentes e acionados em sincronia.
- Repetir/Parar: repete o último gesto / interrompe imediatamente.
- Registo de comunicação: a parte inferior mostra em tempo real os quadros enviados e recebidos e as respostas.
4.2 Teste por linha de comandos (serial_test.py)
Diretório raiz do projeto:
# 链路测试(先确认能通)
python serial_test.py COM3 nop
# 手势
python serial_test.py COM3 rock # 石头
python serial_test.py COM3 thumbs_up # 真棒
python serial_test.py COM3 index # 指向
python serial_test.py COM3 open # 张开
python serial_test.py COM3 close # 握拳
# 单舵机直驱
python serial_test.py COM3 servo 1 90 # 舵机1 → 90°
# 全部归中
python serial_test.py COM3 mid
# 设左右手
python serial_test.py COM3 hand L
python serial_test.py COM3 hand R
# 扫频/自检
python serial_test.py COM3 sweep 1 # 舵机1 扫频
python serial_test.py COM3 test # 全部舵机逐个测试4.3 Verificação
- Após clicar num gesto, os servomotores devem executar a ação correspondente; o registo série devolve
ACKeDONE. - Códigos de resposta:
0x00=OK,0x01=comando inválido,0x02=erro de parâmetro,0x03=ocupado,0x10=concluído. - Se os servomotores não se moverem de forma alguma: consulte as perguntas frequentes no Capítulo 6 (verifique primeiro a alimentação/porta série).
A referência rápida completa dos comandos de gesto e do protocolo série está no Capítulo 7.
Capítulo 5: Tutorial avançado: rastreamento de gestos
Pré-requisitos: Capítulos 1-4 concluídos (firmware gravado, controlo pela porta série a funcionar, câmara posicionada). Este capítulo tem dois caminhos; escolha um deles.
5.1 Rastreamento integrado na GUI (versão leve)
Indicado para: demonstrações rápidas, sem precisar de instalar o dora. Câmara → mapeamento direto para os servomotores diferenciais, sem IK.
Pré-requisitos
- Python de 64 bits +
setup_tracking.bat(secção 1.1). - Câmara disponível.
Execução
# 项目根目录,用追踪环境启动 GUI
tracking_env\Scripts\python hand_gui.py- Selecione a porta série → «Ligar».
- Desloque-se até ao painel «Rastreamento de gestos (câmara MediaPipe)».
- Selecione o número da câmara (predefinição 0) → clique em «Iniciar rastreamento».
- Coloque a mão no enquadramento; a mão mecânica acompanha a flexão/extensão da mão.
Princípio
- O mediapipe 0.10.14 extrai vetores 3D das pontas dos 4 dedos (no sistema de coordenadas da mão).
- A função
tips_to_angles()dehand_tracking.pymapeia cada dedo para um ângulo diferencial:- flex (curvar/esticar): os três dedos usam a componente z; o polegar usa a componente y;
- base (oscilação lateral): fixo em 90 (a oscilação lateral ainda não foi implementada).
- A GUI tem suavização EMA integrada (alpha=0.4) + limitação a 60ms, para evitar tremores.
Limitações
- Sem IK: as pontas dos dedos são mapeadas diretamente para ângulos; a precisão não é tão boa como a da cadeia oficial.
- Oscilação lateral adiada: base fixo em 90, sem oscilação lateral.
- Indicado para demonstração/prototipagem; para uso formal, recomenda-se a secção 5.2.
5.2 Rastreamento IK oficial com dora (versão completa)
Indicado para: uso formal. Cadeia oficial: câmara → mediapipe → IK MuJoCo+mink → 8 ângulos de junta → AHControl (Rust) → ESP32 → servomotores PWM.
Pré-requisitos
- Ambiente completo (Rust + uv + dora, secção 1.2).
- Firmware gravado (Capítulo 3).
- O yml do fluxo de dados já define o débito PWM (115200); não é preciso alterá-lo manualmente.
Primeiro passo: implementação (script tudo-em-um recomendado)
Clique duas vezes em ..\02_hand_tracking\Demo\Windows_Scripts_CN\3-部署代码.bat (a versão em inglês é ..\02_hand_tracking\Demo\Windows_Deploy_Scripts\3-Deploy_Demo.bat); realiza automaticamente: cria o ambiente Python, compila o AHControl (Rust) e instala o AHSimulation/HandTracking (mediapipe).
A primeira implementação demora alguns minutos. O script já trata das variáveis de ambiente; não é preciso configurá-las manualmente.
Segundo passo: execução
Clique duas vezes em ..\02_hand_tracking\Demo\Windows_Scripts_CN\4-运行代码.bat (a versão em inglês é ..\02_hand_tracking\Demo\Windows_Deploy_Scripts\4-Run_Demo.bat) e escolha no menu:
1 - 模拟仿真(摄像头手势追踪)
2 - 真实硬件(SCS0009 总线舵机)
3 - PWM 舵机(ESP32 直驱) ← 选 3Em seguida, escolha o tipo de mão: 1 右手 / 2 左手. O script executa automaticamente dora build + dora run.
- A janela da câmara abre; coloque a mão no enquadramento → os dedos da simulação 3D acompanham → a mão mecânica acompanha.
- Parar: Ctrl+C (ou fechar a janela).
Alternância entre mão esquerda e direita
Basta escolher o tipo de mão no menu de execução (segundo passo da secção 5.2): selecione 1 右手 ou 2 左手.
Após a troca, o script reconstrói automaticamente o fluxo de dados correspondente; aguarde a conclusão da compilação antes de fazer qualquer operação em frente à câmara.
Como ler os registos de execução
Na janela de execução, o nó AHControl emite registos continuamente. Preste atenção a esta linha:
[ACK-STATS] sent N frames, ESP32 acked M framesM ≈ N(por exemplo,sent 300 frames, ESP32 acked 300 frames) → normal, o ESP32 recebeu todos os quadros.M = 0→ o ESP32 não recebeu dados; verifique a porta série/alimentação (ver Capítulo 6).
Enquanto esta linha estiver a crescer normalmente, a cadeia dos servomotores está a funcionar; o que resta é saber se a câmara consegue acompanhar.
Capítulo 6: Perguntas frequentes (durante a execução)
Esta secção lista apenas os problemas mais comuns e que consegue resolver sozinho durante a utilização. Localize rapidamente pelo sintoma.
6.1 Os servomotores não se movem de forma alguma
Verifique pela ordem:
- Alimentação: os servomotores estão ligados a uma fonte independente (5V 3A ou mais)? Se dependerem apenas do USB, os servomotores podem não se mover ou o ESP32 pode reiniciar repetidamente. → Desligue e volte a ligar o ESP32.
- Porta série: a porta COM está correta? No Gestor de dispositivos → Portas (COM e LPT), veja a porta correspondente ao ESP32. Há outro programa (como um assistente série) a ocupar a porta? → Feche o programa que a estiver a ocupar.
- Cablagem: os PWM1-8 da placa adaptadora estão ligados aos GPIO corretos? Os fios de sinal dos servomotores estão bem ligados?
6.2 A câmara não mostra imagem
- Na primeira execução no Windows, aparece um pedido de permissão da câmara → clique em «Permitir».
- Se escolheu "Não" anteriormente: Definições → Privacidade e segurança → Câmara → Permitir que as aplicações de ambiente de trabalho acedam à câmara, e execute novamente.
6.3 A câmara mostra imagem, mas a mão não acompanha / acompanha com atraso
- Confirme que a câmara está de frente para a mão, com iluminação suficiente e a mão totalmente visível no enquadramento.
- Mova-se mais devagar e com maior amplitude. Movimentos demasiado rápidos ou de amplitude demasiado pequena podem fazer com que o rastreamento não acompanhe.
- Os dedos movem-se na janela da simulação 3D?
- Sim: a cadeia de rastreamento está normal; o problema está nos servomotores/porta série; ver 6.1.
- Não: o nó de rastreamento não reconheceu a mão; ajuste a pose/iluminação e tente novamente.
6.4 Tipo de mão invertido / direção do polegar invertida
- Selecionou a mão esquerda/direita errada? Selecione o tipo de mão correto no menu de execução.
- Na GUI do computador host, marque «direita»/«esquerda» para alternar.
6.5 A troca de mão esquerda/direita não produz efeito
- Após trocar o tipo de mão, o
doratem de reconstruir o fluxo de dados: depois de escolher o tipo de mão no menu de execução, odora buildé executado automaticamente; basta aguardar a conclusão.
6.6 A imagem congela / o registo para durante a execução
- É possível que a câmara esteja a ser utilizada por outra aplicação (videoconferência, outro script); feche-a e tente novamente.
- Ou prima
Ctrl+Cpara parar e execute novamente.
6.7 Após trocar a porta USB / reiniciar o computador, a porta série não é encontrada
- O número da porta COM pode ter mudado. Confirme o novo número COM no Gestor de dispositivos, execute novamente
2-配置串口.bat(ou2-Setup_Serial.bat) e selecione a porta uma vez, e depois execute.
6.8 Continua a não funcionar?
- Envie ao responsável pela manutenção uma captura de ecrã dos registos do terminal de execução, explicando: em que etapa, que operação e que fenómeno foi observado.
- Registos principais: a linha
[CONFIG]no arranque e a linha[ACK-STATS]durante a execução (se o M emESP32 acked M framesestá próximo de N).
Capítulo 7: Referência rápida de comandos (apêndice)
A descrição completa do protocolo está em
用户手册.md, no mesmo diretório. Aqui fica a tabela de referência rápida.
7.1 Comandos de gesto
| Gesto | HEX | ACK | DONE |
|---|---|---|---|
| NOP | AA 00 00 00 | BB 00 00 00 | — |
| Pedra | AA 01 00 01 | BB 01 00 01 | BB 01 10 11 |
| Tesoura | AA 02 00 02 | BB 02 00 02 | BB 02 10 12 |
| Papel | AA 03 00 03 | BB 03 00 03 | BB 03 10 13 |
| Joia | AA 04 00 04 | BB 04 00 04 | BB 04 10 14 |
| Provocação 1 (agitar o indicador) | AA 05 00 05 | BB 05 00 05 | BB 05 10 15 |
| Provocação 2 (anelar) | AA 06 00 06 | BB 06 00 06 | BB 06 10 16 |
| Abrir | AA 07 00 07 | BB 07 00 07 | BB 07 10 17 |
| Punho fechado | AA 08 00 08 | BB 08 00 08 | BB 08 10 18 |
| OK | AA 09 00 09 | BB 09 00 09 | BB 09 10 19 |
| Pinça | AA 0A 00 0A | BB 0A 00 0A | BB 0A 10 1A |
| Apontar | AA 0C 00 0C | BB 0C 00 0C | BB 0C 10 1C |
7.2 Comandos de controlo
| Comando | HEX | Descrição |
|---|---|---|
| Repetir | AA FE 00 FE | Repete o último gesto |
| Parar | AA FF 00 FF | Interrompe imediatamente |
| Definir mão direita | AA F1 01 01 F1 | — |
| Definir mão esquerda | AA F1 01 02 F2 | — |
| Acionamento direto | AA F0 08 [8×角度] CKSUM | 8 bytes de ângulo |
7.3 Formato do quadro
帧头(0xAA) + 命令(CMD) + 长度(LEN) + 数据(DATA) + 校验和(CKSUM)
CKSUM = CMD ^ LEN ^ DATA[0] ^ ... ^ DATA[N-1]
响应: 帧头(0xBB) + CMD + STATUS + (CMD^STATUS)7.4 Ferramentas do computador host
| Ferramenta | Comando | Utilização |
|---|---|---|
| GUI | tracking_env\Scripts\python hand_gui.py | Gestos visuais + acionamento direto + diferencial + rastreamento |
| exe empacotado | dist/AmazingHand控制台.exe | Visualização sem instalar Python (sem rastreamento) |
| Linha de comandos | python serial_test.py COMx <cmd> | Testes automatizados |
7.5 Ficheiros de fluxo de dados de rastreamento (versão PWM)
| Utilização | Ficheiro |
|---|---|
| Rastreamento PWM da mão esquerda | dataflow_tracking_real_left_pwm.yml |
| Rastreamento PWM da mão direita | dataflow_tracking_real_right_pwm.yml |
| Configuração PWM da mão esquerda | AHControl/config/l_hand_pwm.toml |
| Configuração PWM da mão direita | AHControl/config/r_hand_pwm.toml |

