Robot Arm — Controle de Mão Robótica via Hand Tracking e Arduino

Descrição

Este projeto controla uma mão robótica impressa em 3D (estilo InMoov) imitando os movimentos da mão do usuário capturados por uma webcam USB.
Uma aplicação em Python realiza rastreamento de mão em tempo real com MediaPipe, calcula ângulos dos dedos e envia comandos para um Arduino Uno (rodando StandardFirmata) via comunicação serial para acionar 5 servomotores.

Estrutura do Projeto

Visão geral dos módulos

• core/: configurações e logging
• models/: tipos e estruturas de dados compartilhadas
• services/: visão computacional (MediaPipe) e hardware (Firmata/Arduino)
• ui/: interface PyQt (janela, controller/loop)
• tests/: testes unitários (mapeamento, visão, robustez)

Repo Tree

robot-arm/
├─ pyproject.toml
├─ poetry.lock
├─ README.md
├─ .gitignore
├─ .env.example
├─ requirements.txt          # opcional (referência); Poetry é o principal
├─ src/
│  └─ robot_arm/
│     ├─ __init__.py
│     ├─ cli.py      
│     ├─ core/
│     │  ├─ config.py
│     │  └─ logging.py
│     ├─ models/
│     │  └─ types.py
│     ├─ services/
│     │  ├─ hardware.py
│     │  ├─ mapping.py
│     │  └─ vision.py
│     └─ ui/
│        ├─ __init__.py
│        ├─ controllers.py
│        └─ main_window.py
└─ tests/

Instalação

Pré-requisitos

• Python 3.10+
• Poetry
• Arduino IDE (para gravar o StandardFirmata)
• Arduino Uno + 5 servos + fonte externa para os servos (recomendado)
• Webcam USB

1) Clonar o repositório

git clone <url-do-seu-repo>
cd robot-arm

2) Instalar dependências com Poetry

poetry install

3) Gravar o StandardFirmata no Arduino

1. Abra a Arduino IDE
2. Vá em: File > Examples > Firmata > StandardFirmata
3. Selecione a placa e a porta corretas e faça o upload

4) Configurar porta serial e parâmetros (via .env)

Ajuste as configurações do projeto no arquivo .env (porta do Arduino, câmera e logging).

• Arquivo recomendado: .env (baseado no .env.example)
• Variáveis utilizadas:

# ====== Camera ======
CAMERA_INDEX=0
CAM_WIDTH=360
CAM_HEIGHT=320
TIMER_MS=10

# ====== Arduino ======
ARDUINO_PORT=COM17

# ====== Logging ======
LOG_LEVEL=INFO

Exemplos de porta serial (ARDUINO_PORT):

• Windows: COM17
• Linux: /dev/ttyACM0
• macOS: /dev/tty.usbmodemXXXX

Uso

Rodar o aplicativo desktop (PyQt)

poetry run python -m robot_arm.cli

O que você deve ver

• Uma janela desktop com:
  • Feed da webcam com landmarks/traços desenhados
  • Um gráfico em tempo real (por padrão, do dedo indicador)

Funcionalidades

• ✅ Hand tracking em tempo real com MediaPipe Hands
• ✅ Overlay dos landmarks desenhado diretamente no frame (OpenCV)
• ✅ Cálculo de ângulos dos dedos (matemática vetorial + thresholds)
• ✅ Controle do Arduino via Firmata com pyfirmata2 (5 servos)
• ✅ Modo robusto: se o Arduino não estiver conectado, o app continua rodando (apenas loga aviso)
• ✅ Estrutura modular preparada para evolução futura para versão Web (FastAPI + MJPEG + WebSockets)

Tech Stack / Construído com

• Python 3.10+
• PyQt5 — interface desktop
• pyqtgraph — gráfico em tempo real
• OpenCV — captura da webcam + renderização do frame
• MediaPipe — detecção de landmarks da mão
• NumPy — matemática vetorial / cálculo de ângulos
• Arduino Uno / StandardFirmata
• pyfirmata2 — comunicação serial via Firmata
• Poetry — gerenciamento de dependências e ambiente

Links e Referências

• Arquivos para impressão 3D (InMoov STL Parts Viewer — Right Hand):
  https://inmoov.fr/inmoov-stl-parts-viewer/?bodyparts=Right-Hand

• Tutorial original de montagem (InMoov — Hand and Forearm):
  https://inmoov.fr/hand-and-forarm/

• Exemplo adicional (Thingiverse):
  https://www.thingiverse.com/thing:17773 https://www.instructables.com/3D-Printed-EMG-Prosthetic-Hand/