Guia de Configuração do OpenArm 101

Antes de Começar

• Certifique-se de ter um espaço de trabalho claro de 1m × 1m em uma superfície estável
• Tenha um laptop com Ubuntu 22.04 pronto (VM funciona, nativo preferido)
• Mantenha o braço energizado desligado durante a inspeção física abaixo

Na Caixa

Lista de Verificação de Inspeção

• Todas as 8 articulações giram livremente (sem atrito ou resistência)
• O roteamento de cabos está intacto ao longo do corpo do braço
• O conector de energia está intacto
• O botão de parada de emergência é acessível e funcional

Requisitos do Sistema

• Ubuntu 22.04 LTS (recomendado) ou 20.04
• Python 3.10+
• ROS2 Humble
• Adaptador USB-CAN (CANable ou compatível — deve suportar CAN FD para a taxa de dados completa de 5 Mbit/s)

Passo 2a — Configuração do ID do Motor

Antes de qualquer configuração de software, cada motor Damiao deve ter seu ID CAN atribuído. Este é um passo único realizado no Windows usando o Depurador USB CAN Damiao.

Use a tabela abaixo como a atribuição de ID canônica para cada junta (J1–J8):

Passo 2b — Instalar Pacotes OpenArm

No seu computador Ubuntu, instale todos os pacotes necessários do PPA oficial do OpenArm:

sudo apt install -y software-properties-common
sudo add-apt-repository -y ppa:openarm/main
sudo apt update
sudo apt install -y \
  can-utils \
  iproute2 \
  libeigen3-dev \
  libopenarm-can-dev \
  liborocos-kdl-dev \
  liburdfdom-dev \
  liburdfdom-headers-dev \
  libyaml-cpp-dev \
  openarm-can-utils

Passo 2c — Configurar Interface CAN (CAN FD)

Os motores OpenArm suportam tanto CAN 2.0 quanto CAN FD. O CAN FD é recomendado — ele executa a fase de dados a 5 Mbit/s e suporta cargas úteis de até 64 bytes, necessárias para a largura de banda total do motor Damiao.

Recomendado — use o helper OpenArm:

# CAN FD, 1M nominal / 5M data (recommended for single arm)
openarm-can-configure-socketcan can0 -fd -b 1000000 -d 5000000

# CAN 2.0 fallback (1M baud, no FD)
openarm-can-configure-socketcan can0

# 4-arm bimanual setup (can0–can3)
openarm-can-configure-socketcan-4-arms -fd

# Verify the interface is UP
ip link show can0

Comandos de link ip manuais (se não estiver usando o helper):

# CAN 2.0
sudo ip link set can0 down
sudo ip link set can0 type can bitrate 1000000
sudo ip link set can0 up

# CAN FD — 1M nominal / 5M data
sudo ip link set can0 down
sudo ip link set can0 type can bitrate 1000000 dbitrate 5000000 fd on
sudo ip link set can0 up

Passo 2d — Comandos de Controle do Motor e Depuração

Use estes cansend comandos para depuração de baixo nível. Monitore o barramento primeiro antes de enviar quaisquer comandos:

# Monitor all CAN frames
candump -x can0

# Change motor baudrate (replace 1 with target motor CAN ID)
openarm-can-change-baudrate --baudrate 5000000 --canid 1 --socketcan can0
# Persist across power cycles (max ~10,000 flash writes per motor — use sparingly)
openarm-can-change-baudrate --baudrate 5000000 --canid 1 --socketcan can0 --flash

controle de motor CAN 2.0 — substituir 001 pelo ID do Transmissor da junta alvo da tabela acima:

# Clear motor error
cansend can0 001#FFFFFFFFFFFFFFFB
# Enable motor
cansend can0 001#FFFFFFFFFFFFFFFC
# Disable motor
cansend can0 001#FFFFFFFFFFFFFFFD

controle de motor CAN FD — note o extra #1 após ## (bandeira BRS):

# Clear motor error
cansend can0 001##1FFFFFFFFFFFFFFFB
# Enable motor
cansend can0 001##1FFFFFFFFFFFFFFFC
# Disable motor
cansend can0 001##1FFFFFFFFFFFFFFFD

Status do LED do Motor

Cada motor Damiao possui um LED embutido que indica o estado atual. Use isso como um rápido verificador de saúde após ligar:

Passo 2e — Instalar Pacotes ROS2

sudo apt install ros-humble-ros2-control ros-humble-ros2-controllers
git clone https://github.com/enactic/openarm_ros2
cd openarm_ros2 && colcon build

Instale o SDK Python

pip install roboticscenter
python -c "import roboticscenter; print('SDK ready')"

Comece com Hardware Falso (Seguro — Sem Movimento Físico)

Sempre verifique na simulação antes de mover o braço real. Execute o arquivo de lançamento com use_fake_hardware:=true — sem conexão CAN necessária:

ros2 launch openarm_ros2 openarm.launch.py use_fake_hardware:=true
ros2 run openarm_ros2 test_trajectory

Abra o RViz para verificar se o braço simulado se move corretamente pela trajetória de teste. Todas as 8 articulações devem se animar suavemente.

Mude para Hardware Real

Uma vez que a simulação pareça correta, conecte o adaptador CAN e ligue o braço:

ros2 launch openarm_ros2 openarm.launch.py

Envie o Primeiro Comando de Movimento (Posição Inicial)

ros2 action send_goal /joint_trajectory_controller/follow_joint_trajectory \
  control_msgs/action/FollowJointTrajectory "{...}"

As posições zero das articulações devem corresponder à realidade física para um controle preciso. Articulações mal calibradas causam falhas de política a montante — não pule esta etapa.

Procedimento de Homing

1. Ligue com o braço em uma posição segura conhecida (aproximadamente estendido, longe de obstáculos)
2. Execute o script de homing:

   ros2 run openarm_ros2 homing

3. O script solicitará que você guie manualmente cada articulação até seu limite — mova-se lentamente
4. Confirme que a posição zero está salva para cada articulação quando solicitado

Verifique a Calibração

ros2 topic echo /joint_states  # check all positions read near zero

Escolha seu Dispositivo de Operador

Conectar dispositivo do operador

ros2 launch openarm_ros2 teleop.launch.py operator:=wuji_hand

Verificar Latência

A latência alvo de ponta a ponta é inferior a 50 ms. Execute o teste de latência e verifique:

ros2 run openarm_ros2 latency_check

Escolher Formato de Dados

• LeRobot (recomendado) — projetado para aprendizado por imitação e treinamento de modelos
• RLDS — compatível com Open-X-Embodiment e conjuntos de dados entre robôs

Começar a Gravar

ros2 launch openarm_ros2 record.launch.py \
  output_format:=lerobot \
  task_name:=pick_and_place \
  episode_id:=0

Cada episódio é salvo como um arquivo autônomo com estados de juntas, quadros de câmera e rótulos de ação. Execute vários episódios e, em seguida, use a plataforma SVRC para revisar e filtrar.

Lista de Verificação de Qualidade do Episódio

• Os feeds de câmera estão sincronizados (timestamps dentro de 5 ms)
• Estados conjuntos registrados em ≥ 50 Hz
• Rótulos de ação correspondem ao comportamento demonstrado
• Episódios falhados são marcados para exclusão, não deletados

Modelos Recomendados para OpenArm

• ACT (Transformador de Blocos de Ação) — melhor para pick-and-place. Prediz blocos de ação a partir de observações da câmera.
• Política de Difusão — melhor para tarefas ricas em contato. Gera trajetórias suaves através de desnoising.
• OpenVLA — melhor para tarefas condicionadas por linguagem. Combina compreensão de visão-linguagem com ações de robô.

Ajuste fino do ACT em seus dados

pip install lerobot
python train.py --config act_openarm --data-path ./recordings/

O treinamento em uma GPU de consumidor (RTX 3090 ou melhor) geralmente leva de 2 a 4 horas para 50 episódios. Use o --resume sinalizador para continuar a partir de um ponto de verificação.

Implantar na Edge

ros2 launch openarm_ros2 inference.launch.py \
  model_path:=./checkpoints/best.pt

O nó de inferência lê quadros da câmera, executa o modelo e publica comandos conjuntos na frequência de controle. A latência de inferência alvo é inferior a 20 ms para controle em tempo real.