Introdução ao Pinocchio e MeshCat para reBot Arm B601-DM

Adquira agora 🖱️

Braço robótico de 6 DOF · Suporte a múltiplos motores · Solucionador de cinemática · Planejamento de trajetória · Totalmente open source

dica

Este código de exemplo pode ser usado para controlar os motores ou poses do braço robótico, incluindo controle de motor único, controle e teste de cinemática direta/inversa, configuração da posição zero do braço e leitura do ângulo do motor, sistema de visualização MeshCat e muito mais.

Pinocchio é uma biblioteca open source para análise e otimização de dinâmica em robótica. Ela fornece cinemática direta/inversa eficiente, cálculos dinâmicos e recursos de planejamento de trajetória.

MeshCat é uma ferramenta de visualização 3D baseada na web que pode exibir o estado do robô e trajetórias de movimento em tempo real.

Este projeto combina as poderosas capacidades de computação do Pinocchio com a visualização intuitiva do MeshCat, fornecendo um conjunto completo de ferramentas de análise cinemática e depuração para o reBot Arm B601-DM.

---

Recursos do Projeto

1. Análise cinemática completa Suporta cálculos de Cinemática Direta (FK) e Cinemática Inversa (IK), sendo capaz de resolver em tempo real a pose do efetuador final do braço robótico.

2. Visualização 3D em tempo real Exibe o estado do braço robótico e as trajetórias de movimento em tempo real por meio do MeshCat no navegador, sem necessidade de software adicional.

3. Planejamento e rastreamento de trajetória Implementa planejamento de trajetória geodésica em SE(3), com suporte a controle de rastreamento CLIK (Cinemática Inversa em Malha Fechada).

4. Controle com compensação de gravidade Calcula o torque de gravidade das juntas com base no modelo dinâmico do Pinocchio, alcançando o efeito de “flutuação” do braço robótico.

5. Open source e extensível Todo o código é open source, permitindo que os usuários personalizem algoritmos de controle e efeitos de visualização conforme suas necessidades.

Especificações

O hardware para este tutorial é fornecido pela Seeed Studio

Parâmetro	Especificação
Modelo do braço robótico	reBot Arm B601-DM
Graus de liberdade	6-DOF + garra
Modelo do motor	Damiao DM4340 / DM4310
Método de comunicação	Barramento CAN via adaptador USB-CAN
Tensão de operação	24V DC
Método de controle	PC
Faixa de temperatura de operação recomendada	0°C ~ 40°C

Lista de Materiais (BOM)

Componente	Quantidade	Incluído
Braço robótico reBot Arm B601-DM	1	✅
Ponte serial USB2CAN	1	✅
Adaptador de energia (24V)	1	✅
Cabo USB-C	1	✅
Garra	1	✅

Requisitos de ambiente

Pré-requisito — Conclua primeiro o Guia de início rápido do braço

Antes de prosseguir com este tutorial, você deve concluir o documento reBot Arm B601-DM Quick Start de ponta a ponta, incluindo:

• Desembalagem do hardware, fiação e checklist de energização
• Permissão do dispositivo Serial / CAN (sudo chmod 666 /dev/ttyACM0 ou /dev/can0)
• Calibração de zero de todas as juntas (2_zero_and_read.py) e verificação de que o braço pode ser comandado nos modos MIT / POS_VEL

Este tutorial assume que o braço já responde no barramento, que as juntas estão zeradas e que o operador está familiarizado com os limites de segurança relevantes. Pular o Guia de início rápido pode levar a motores mal configurados, juntas travadas ou quedas do braço.

Item	Requisito
Python	3.10+
Sistema operacional	Ubuntu (Ubuntu 24.04 LTS recomendado)
Interface de comunicação	Ponte serial USB2CAN ou interface CAN

---

Etapas de instalação

1

Instalar uv (se ainda não estiver instalado)

Etapa 1

curl -LsSf https://astral.sh/uv/install.sh | sh

Após a instalação, execute o seguinte comando para verificar se uv está disponível:

uv --version

Se a instalação tiver sido bem-sucedida, você deverá ver uma saída semelhante à seguinte (a versão e a plataforma podem ser diferentes):

uv 0.11.31 (x86_64-unknown-linux-gnu)

2

Sincronizar ambiente (instalar todas as dependências)

Etapa 2

git clone https://github.com/Seeed-Projects/reBotArm_control_py.git
cd reBotArm_control_py
uv sync

dica

uv sync criará automaticamente um ambiente virtual (se ele não existir) e instalará todas as dependências de acordo com pyproject.toml e uv.lock.

Ajuste dos parâmetros do controlador MIT / POS_VEL

Esta seção explica como modificar os parâmetros do controlador para cada junta do braço nos modos MIT e POS_VEL, e como fazer com que as alterações entrem em vigor.

Esta seção aborda apenas “onde / como alterar”, não “qual valor usar”

Parâmetros adequados só podem ser obtidos por meio de ajuste direto no hardware. Esta seção aborda apenas: onde os parâmetros estão, o que cada campo controla e como fazer com que as alterações entrem em vigor e verificá-las. Para estratégias específicas de ajuste (por exemplo, tentativa e erro, Ziegler‑Nichols), consulte referências gerais de controle de motores.

Localização do arquivo de configuração

Versão de hardware	Arquivo de configuração do motor	Entrada de seleção
reBot Arm B601-DM (este documento)	config/rebotarm_dm.yaml	Defina hardware_yaml: "rebotarm_dm.yaml" em config/rebotarm.yaml
reBot Arm B601-RS	config/rebotarm_rs.yaml	Defina hardware_yaml: "rebotarm_rs.yaml" em config/rebotarm.yaml

Não edite rebotarm.yaml diretamente

Esse arquivo contém apenas uma única linha hardware_yaml: ...; todos os parâmetros dos motores estão em rebotarm_dm.yaml / rebotarm_rs.yaml.

Estrutura do arquivo de configuração

Cada junta tem sua própria entrada, agrupada por modo de controle:

joints:
  - name: joint1
    motor_id: 0x01
    feedback_id: 0x11
    model: "4340P"
    vendor: "damiao"
    MIT:
      kp: 120.0
      kd: 8.0
    POS_VEL:
      vel_kp: 0.0125
      vel_ki: 0.004
      pos_kp: 150.0
      pos_ki: 0.5
      vlim: 5.0
  # ... joint2 ~ joint6 follow the same structure ...

Como localizar:

• Pelo nome da junta: para modificar uma junta, encontre o bloco - name: jointX;
• Pelo modo: dentro dessa junta, MIT: contém os parâmetros do modo MIT, POS_VEL: contém os parâmetros do modo POS_VEL;
• O modo atual determina qual conjunto é enviado: o script alterna modos via mode mit / mode posvel; o motor na prática recebe os parâmetros sob o sub-bloco correspondente.

Significado dos campos no modo MIT

Campo	Função
kp	Ganho proporcional do loop de posição: a “rigidez” do rastreamento da posição alvo.
kd	Ganho de amortecimento do loop de velocidade: suprime oscilações causadas pelo erro de posição.

Significado dos campos no modo POS_VEL

Campo	Função
vel_kp	Ganho proporcional do loop de velocidade.
vel_ki	Ganho integral do loop de velocidade.
pos_kp	Ganho proporcional do loop de posição.
pos_ki	Ganho integral do loop de posição (presente apenas em algumas configurações de fornecedores).
vlim	Limite de velocidade, restringe a velocidade máxima de movimento.

As definições de campos variam entre fornecedores

Os motores Damiao (DM) e Robostride (RS) usam unidades diferentes na camada de protocolo, portanto o mesmo nome de campo não é comparável entre fornecedores. Modificar vel_kp de um RS e modificar vel_kp de um DM significam coisas diferentes. Interprete cada YAML de acordo com sua própria ordem de campos, não compare valores entre arquivos de configuração.

Limite o escopo de teste antes de ajustar

Grandes alterações de kp / kd em várias juntas podem causar oscilação imediata, sobrecorrente ou colisões em batentes mecânicos se qualquer direção ou sinal de junta estiver incorreto. Antes de ajustar, limpe o espaço de trabalho do braço e planeje testar uma junta e um modo por vez, em pequenos passos.

Procedimento de edição

1. Pare qualquer script em execução. O motor está habilitado enquanto você edita o YAML, as alterações não entram em vigor imediatamente e é fácil provocar comportamento inconsistente.
2. Edite o arquivo YAML correspondente:

   # Example for DM
   vim config/rebotarm_dm.yaml

   • Altere apenas a junta que você precisa ajustar (por exemplo, joint1); deixe as juntas não relacionadas como estão;
   • Dentro de uma junta, altere apenas o modo que você precisa ajustar (MIT ou POS_VEL); não modifique os campos do outro modo sem motivo.
3. Preserve a indentação YAML: 2 espaços por nível, chaves separadas dos valores por : . Indentação incorreta faz com que o yaml.safe_load falhe na análise e todos os parâmetros voltem aos padrões.
4. Reinicie o script após salvar. O YAML é lido uma vez na inicialização do script; edições em tempo de execução não entram em vigor imediatamente.
5. Verificação de uma única junta: use um script como 3_mit_control.py (MIT) / 4_pos_vel_control.py (POS_VEL) para verificar a alteração com um pequeno movimento de uma única junta antes de fazer um teste com o braço completo.

Verificando se a alteração entrou em vigor

• Observação em tempo de execução: habilite o motor em 3_mit_control.py / 4_pos_vel_control.py e verifique state; se os parâmetros parecerem inalterados ou o motor se comportar exatamente como antes, o YAML foi editado incorretamente ou foi sobrescrito pelos padrões.
• Auto-verificação do YAML: faça o parse diretamente com Python e imprima os campos de uma junta para confirmar que os valores correspondem ao que você acabou de escrever:

  uv run python -c "import yaml; print(yaml.safe_load(open('config/rebotarm_dm.yaml'))['joints'][0])"

• Rollback rápido: git checkout config/rebotarm_dm.yaml restaura os padrões do repositório.

---

Introdução às Ferramentas de Depuração

Configurações de Permissão

Antes de executar exemplos de controle de hardware, você precisa definir as permissões do dispositivo:

# Set serial device permissions (Damiao USB2CAN)
sudo chmod 666 /dev/ttyACM0

# Or set CAN device permissions (e.g., can0)
sudo chmod 666 /dev/can0

Ferramentas de Depuração (use apenas quando ocorrer uma exceção)

Console de Controle de Motor Único (0x01damiao_test.py)

Teste direto de um único motor usando o SDK do motorbridge.

Como Executar:

uv run python example/0x01damiao_test.py

Comandos Interativos:

Comando	Descrição
enable / disable	Habilitar/Desabilitar motor
set_zero	Definir posição zero
state	Ver status
ping	Enviar ping ao motor para obter resposta
clear_error	Limpar erros do motor
mode <mit/posvel/vel>	Alternar modo de controle
mit <pos> [vel] [kp] [kd]	Comando em modo MIT
posvel <pos> [vlim]	Comando em modo POS_VEL
vel <velocity>	Comando em modo de velocidade pura
read_param <id> [type]	Ler parâmetros do motor
write_param <id> <value> [type]	Gravar parâmetros do motor
loop	Entrar no modo de controle em loop
q / quit	Sair

---

Calibração de Zero e Monitoramento de Ângulo (2_zero_and_read.py)

Define automaticamente todos os zeros das juntas e exibe os ângulos das juntas em tempo real.

Como Executar:

uv run python example/2_zero_and_read.py

# Example Output
-0.12  +0.23  -6.42  +41.74  -0.45  -0.01  -0.01

---

3

Modo de Controle MIT (alternativo no reBot DM, visualizar sob demanda — POS_VEL é recomendado)

Demo 3 · 3_mit_control.py

Opcional — MIT é o modo alternativo no DM

Para o reBot Arm B601-DM, POS_VEL (Posição‑Velocidade) é geralmente o modo de controle de junta mais apropriado; o protocolo do motor Damiao oferece suporte nativo ao controle híbrido posição‑velocidade com limitação de velocidade integrada. O modo MIT geralmente requer um ajuste mais cuidadoso de kp / kd.

Este exemplo não é obrigatório para concluir o tutorial. A menos que você precise especificamente depurar o modo MIT, pule este exemplo e use o exemplo POS_VEL abaixo. Se o seu objetivo é um movimento suave do efetuador final ao longo de um caminho planejado, vá diretamente para Controle de IK com Trajetória Suave (8_arm_traj_control.py).

Insira ângulos alvo para todas as juntas para concluir o controle do motor no modo de controle MIT, normalmente usado para controle de força, controle de impedância ou cenários que exigem alta resposta dinâmica.

Antes de Executar — Este exemplo não possui planejamento de trajetória suave

Este exemplo envia ângulos alvo das juntas diretamente para os motores, sem planejamento de caminho ou velocidade. Uma grande mudança de alvo pode causar movimento repentino em alta velocidade e acionar a proteção contra sobrecorrente.

• Execute-o apenas quando precisar verificar o controle de junta MIT de baixo nível. Comece movendo uma junta em apenas 5–10 graus e, em seguida, aumente a mudança gradualmente após confirmar a resposta e a direção;
• Se você precisar de uma trajetória suave completa, pule este exemplo e vá para Controle de IK com Trajetória Suave (8_arm_traj_control.py);
• Limpe a área de trabalho do braço antes de executar e certifique-se de que você possa cortar a alimentação imediatamente.

Expandir Instruções de Execução (Opcional)

Como Executar:

uv run python example/3_mit_control.py
> 30 0 0 0 0 0 0 # Control motor 1 to rotate 30 degrees
> state
  pos (deg): ['+29.99', '+0.00', '-45.00', '+0.00', '+0.00', '+0.00']
> q # Exit system

4

Modo de Controle Posição-Velocidade

Demo 4 · 4_pos_vel_control.py

Insira ângulos alvo para todas as juntas para controlar os motores no modo híbrido POS_VEL (Posição-Velocidade). A limitação de velocidade integrada do Damiao pode reduzir o impacto das mudanças de alvo, mas este exemplo em si não fornece um planejamento completo de trajetória suave.

Opcional — Limitação de velocidade não é planejamento completo de trajetória

Embora POS_VEL seja o modo de controle de junta recomendado para DM, este exemplo ainda atualiza diretamente os alvos de posição das juntas e não planeja o caminho intermediário. Uma grande mudança de alvo ainda pode causar movimento repentino, colisão ou sobrecorrente.

• Este exemplo não é obrigatório para concluir o tutorial. Se você só precisa de movimento suave do efetuador final, pule este exemplo e vá diretamente para Controle de IK com Trajetória Suave (8_arm_traj_control.py);
• Ao verificar o controle de junta POS_VEL, comece movendo uma junta em apenas 5–10 graus e, em seguida, aumente gradualmente a mudança de alvo;
• Limpe a área de trabalho do braço antes de executar e certifique-se de que você possa cortar a alimentação imediatamente.

Expandir Instruções de Execução (Opcional)

Como Executar:

uv run python example/4_pos_vel_control.py
> 30 0 0 0 0 0 0 # Control motor 1 to rotate 30 degrees
> state
  pos (deg): ['+29.99', '+0.00', '-45.00', '+0.00', '+0.00', '+0.00']
> q # Exit system

---

Testes de Cinemática

5

Teste de Cinemática Direta

Demo 5 · 5_fk_test.py

Calcular a pose do efetuador final com base nos ângulos das juntas.

Entrada: 6 ângulos de junta (graus)

Saída:

• Posição do efetuador final (X, Y, Z) — Unidade: metros
• Matriz de rotação (3×3)
• Ângulos de Euler (rolagem/tangagem/giro) — Unidade: graus

Exemplo:

uv run python example/5_fk_test.py
> 0 0 0 0 0 0
====================================================
  Result / Result
====================================================
  Joint angles (deg): [0. 0. 0. 0. 0. 0.]
  End-effector position (m):
    X = +0.260306
    Y = +0.000000
    Z = +0.191701
  Rotation matrix (R_world^end):
    [+1.000000  +0.000000  -0.000007]
    [+0.000000  +1.000000  +0.000100]
    [+0.000007  -0.000100  +1.000000]
  Euler XYZ (roll, pitch, yaw) [deg]:
    roll   = -0.0057
    pitch  = -0.0004
    yaw    = +0.0000

6

Teste de Cinemática Inversa

Demo 6 · 6_ik_test.py

Resolver os ângulos das juntas com base na pose desejada do efetuador final.

Formato de Entrada:

• Apenas posição: <x> <y> <z> (metros)
• Posição + Orientação: <x> <y> <z> <roll> <pitch> <yaw> (graus)

Exemplo:

uv run python example/6_ik_test.py

# Usage A
> 0.28 0 0.3  # Position only
====================================================
  Result / Result
====================================================
  Target position : [+0.2800, +0.0000, +0.3000] m
  Converged : Yes
  Iterations: 2000
  Position error: 5.62e-17 m
  Joint angles (deg) [first 6 control joints]:
    joint1     =  -0.0003 deg  (-0.0000 rad)
    joint2     = -22.9687 deg  (-0.4009 rad)
    joint3     = -24.2191 deg  (-0.4227 rad)
    joint4     =  +1.2508 deg  (+0.0218 rad)
    joint5     =  -0.0003 deg  (-0.0000 rad)
    joint6     =  +0.0057 deg  (+0.0001 rad)

# Usage B
> 0.28 0 0.3 0 1 0       # Position + Orientation
====================================================
  Result / Result
====================================================
  Target position   : [+0.2800, +0.0000, +0.3000] m
  Target orientation : [+0.00, +1.00, +0.00] deg
  Converged  : Yes
  Iterations: 2000
  Position error: 6.28e-17 m
  Joint angles (deg) [first 6 control joints]:
    joint1     =  -0.0003 deg  (-0.0000 rad)
    joint2     = -23.3968 deg  (-0.4084 rad)
    joint3     = -25.3018 deg  (-0.4416 rad)
    joint4     =  +2.9054 deg  (+0.0507 rad)
    joint5     =  -0.0003 deg  (-0.0000 rad)
    joint6     =  +0.0057 deg  (+0.0001 rad)

7

Controle de Cinemática Inversa em Modo MIT

Demo 7 · 7_arm_ik_control.py

Use cinemática inversa (IK) em modo MIT para especificar as coordenadas 3D (X, Y, Z) e a orientação (ângulos de Euler) para onde o efetuador final do braço robótico deve se mover.

Formato de Entrada:

• Apenas posição: <x> <y> <z> (metros)
• Posição + Orientação: <x> <y> <z> <roll> <pitch> <yaw> (graus)
• Digite state: visualizar os valores atuais em radianos de cada junta.
• Digite end_state: visualizar as coordenadas atuais reais (m) e os ângulos de Euler (rad) do efetuador final no espaço.

Opcional — Este exemplo não possui planejamento de trajetória suave

Este exemplo envia a solução de IK diretamente como alvo das juntas, sem planejamento de trajetória ou velocidade. Uma grande mudança na pose alvo pode causar um movimento repentino em alta velocidade e acionar a proteção de sobrecorrente.

• Este exemplo não é necessário para concluir o tutorial. Na maioria dos casos, ignore este exemplo e use a próxima seção, Controle de IK com Trajetória Suave (8_arm_traj_control.py), que inclui planejamento de aceleração/desaceleração de mínimo tranco;
• Execute-o apenas quando precisar comparar ou depurar o controle de IK sem planejamento de trajetória. Mantenha o primeiro alvo dentro de 5–10 cm da posição atual do efetuador final;
• Antes de executar, confirme que a pose alvo é alcançável, limpe a área de trabalho de pessoas e obstáculos e certifique-se de que você pode cortar a alimentação imediatamente.

Expandir instruções de execução (opcional)

Como executar:

uv run python example/7_arm_ik_control.py

#Usage A
> 0.3 0.0 0.4 # Position only (orientation defaults to 0), move the arm end-effector to 0.3 meters forward and 0.4 meters above.

#Usage B
> 0.3 0.0 0.4 0.0 0.0 0.5 # Control both position and orientation: move to the specified position while rotating the wrist yaw angle by 0.5 radians.

> ctrl + c # Return to zero position and exit system

8

Controle de Cinemática Inversa com Trajetória Suave

Demo 8 · 8_arm_traj_control.py

Use cinemática inversa (IK) em modo MIT para planejar automaticamente uma trajetória de movimento com aceleração/desaceleração uniforme ou suave dentro do tempo alvo, evitando vibração severa nas juntas.

Formato de entrada:

• Somente posição: <x> <y> <z> (metros)
• Posição + orientação: <x> <y> <z> <roll> <pitch> <yaw> (graus)
• Posição + orientação + tempo (padrão 2.0): <x> <y> <z> <roll> <pitch> <yaw> <time> (graus)
• Entrada state: visualizar os valores atuais em radianos de cada junta.
• Entrada end_state: visualizar as coordenadas atuais do efetuador final (m) e ângulos de Euler (rad) no espaço.

Como executar:

uv run python example/8_arm_traj_control.py

#Usage A
> 0.3 0.0 0.4 # Position only, orientation defaults to 0, default movement time is 2.0 seconds

#Usage B
> 0.3 0.0 0.4 0.0 0.0 0.5 # Control both position and orientation: move to the specified position while rotating the wrist yaw angle by 0.5 radians, default movement time is 2.0 seconds

#Usage C
> 0.3 0.0 0.4 0.0 0.0 0.0 5.0 # Move the arm to the specific position and specify 5.0 seconds to slowly move there. (Note: If entering time, the preceding orientation parameters 0 0 0 cannot be omitted)

> ctrl + c # Return to zero position and exit system

E se eu observar desvio de pose?

Se você notar que a pose lida do efetuador final difere da pose alvo comandada, e a pose em si é alcançável (não está fora da área de trabalho, nem em uma singularidade), o problema provavelmente está nos parâmetros do seu controlador MIT / POS_VEL. Nesse caso, consulte a seção anterior Ajuste de Parâmetros do Controlador MIT / POS_VEL e ajuste manualmente kp / kd etc. usando a abordagem de "uma junta por vez, modo por modo, pequenos passos"; depois de ajustar, retorne a este exemplo para verificar.

---

Teste de Compensação de Gravidade

9

Controle de Compensação de Gravidade — Versão Básica

Demo 9 · 9_gravity_compensation.py

Use o modelo dinâmico Pinocchio para compensar a gravidade das juntas.

Lei de controle:

tau = g(q)          — Gravity feedforward
pos = current motor position   — Joint position follows current position
kp = 2,  kd = 1     — Unified stiffness/damping for all joints

Comportamento esperado:

• O braço pode "flutuar" em qualquer pose
• Não cai devido ao próprio peso quando solto
• Pode ser movido manualmente para qualquer posição

Saída normal executa um retorno seguro à posição inicial

Quando você interrompe o script normalmente com Ctrl+C, ele primeiro para o controle de compensação de gravidade e mantém a pose atual com ganhos rígidos e alimentação antecipada de gravidade. Em seguida, retorna o braço para zero por meio de uma trajetória de mínimo tranco; somente após a conclusão do retorno à origem ele desconecta e desabilita os motores.

O retorno automático à origem depende da execução normal do programa, da comunicação e da alimentação. Mantenha pessoas e obstáculos fora da área de trabalho do braço e esteja pronto para sustentar o braço durante o retorno. Uma falha de comunicação, perda inesperada de energia ou término forçado pode impedir a conclusão da sequência de proteção; corte a alimentação imediatamente se ocorrer movimento anormal.

Como executar:

uv run python example/9_gravity_compensation.py

Saída:

• Exibição em tempo real do torque desejado para cada junta (N·m)
• Pressione Ctrl+C para parar e desconectar

Ajustando a compensação de juntas individuais

Se algumas juntas estiverem subcompensadas ou supercompensadas devido a atrito estrutural ou diferenças de montagem, você pode aplicar uma escala adicional ao elemento correspondente do array tau_g no código:

tau_g[x] *= y  # x is the joint motor id, y is the compensation factor, usually starting from 1
# This compensation is generally only used for joints 2 and 3

Por exemplo, tau_g[2] *= 1.2 significa aumentar o torque de compensação de gravidade da junta 2 em 20%. Recomenda-se ajustar item por item com base no efeito real de flutuação para evitar fazer alterações excessivamente grandes de uma só vez.

10

Controle de Compensação de Gravidade — Versão com Travamento de Velocidade do Efetuador Final

Demo 10 · 10_gravity_compensation_lock.py

Com base na compensação de gravidade básica, adiciona detecção de velocidade do efetuador final e mecanismo de travamento de ângulo das juntas.

Lei de controle:

tau = g(q) + integral_term    — Gravity feedforward + integral term
pos = q_target                 — Target joint angle (locked or updated)
kp = 8.0,  kd = 1.0           — Enhanced stiffness/damping

Lógica de travamento:

• Quando a velocidade linear do efetuador final ||v_ee|| < 0.04 m/s e a velocidade angular ||w_ee|| < 0.08 rad/s:
  • O ângulo alvo da junta q_target permanece travado
  • O braço robótico trava na posição atual
• Quando a velocidade do efetuador final excede o limite:
  • q_target é atualizado para o ângulo atual da junta
  • Permite empurrar manualmente para mudar a posição

Comportamento esperado:

• O braço robótico trava na posição atual, exigindo força para mudar o ângulo alvo
• Mais estável que a versão básica, adequada para cenários que exigem manutenção de pose

Saída normal executa um retorno seguro à posição inicial

Quando você interrompe o script normalmente com Ctrl+C, ele primeiro para o controle de compensação de gravidade e mantém a pose atual com ganhos rígidos e alimentação antecipada de gravidade. Em seguida, retorna o braço para zero por meio de uma trajetória de mínimo tranco; somente após a conclusão do retorno à origem ele desconecta e desabilita os motores.

O retorno automático à origem depende da execução normal do programa, da comunicação e da alimentação. Mantenha pessoas e obstáculos fora da área de trabalho do braço e esteja pronto para sustentar o braço durante o retorno. Uma falha de comunicação, perda inesperada de energia ou término forçado pode impedir a conclusão da sequência de proteção; corte a alimentação imediatamente se ocorrer movimento anormal.

Como executar:

uv run python example/10_gravity_compensation_lock.py

Saída:

• Exibição em tempo real do status de travamento (LOCKED / UPDATE)
• Velocidade linear e velocidade angular do efetuador final
• Torque de compensação de gravidade para cada junta (N·m)
• Pressione Ctrl+C para parar e desconectar

Ajustando a compensação de juntas individuais

Se algumas juntas estiverem subcompensadas ou supercompensadas devido a atrito estrutural ou diferenças de montagem, você pode aplicar uma escala adicional ao elemento correspondente do array tau_g no código:

tau_g[x] *= y  # x is the joint motor id, y is the compensation factor, usually starting from 1
# This compensation is generally only used for joints 2 and 3

Por exemplo, tau_g[2] *= 1.2 significa aumentar o torque de compensação de gravidade da junta 2 em 20%. Recomenda-se ajustar item por item com base no efeito real de flutuação para evitar fazer alterações excessivamente grandes de uma só vez.

Configuração de teste de segurança: Você pode modificar a lista ENABLED_JOINTS no início do script para habilitar apenas juntas específicas para teste de segurança:

ENABLED_JOINTS = ["joint1"]  # Enable only joint1

---

Ambiente de Simulação

S1

Simulação de Cinemática Direta

Demo de Simulação 1 · sim/fk_sim.py

Simulação interativa de cinemática direta, visualize a pose do braço robótico inserindo ângulos de junta no MeshCat.

Como executar:

uv run python example/sim/fk_sim.py

Comandos interativos:

• Insira 6 ângulos de junta (graus), separados por espaço
• Exemplo: 0 0 0 0 0 0
• Exemplo: 45 -30 15 -60 90 -180
• q/quit/exit: sair

Recursos:

• Exibição em tempo real da posição e orientação do efetuador final
• Suporta entrada contínua para testar diferentes poses
• Saída formatada das informações de pose

S2

Simulação de Cinemática Inversa

Demonstração de Simulação 2 · sim/ik_sim.py

Simulação interativa de cinemática inversa, resolve automaticamente os ângulos das juntas a partir da pose alvo e visualiza o resultado.

Como executar:

uv run python example/sim/ik_sim.py

Formato de entrada:

• Somente posição: x y z (metros)
• Posição+Orientação: x y z roll pitch yaw (radianos)

Exemplo:

> 0.25 0.0 0.25              # Position only
> 0.25 0.0 0.25 0 0 0        # Position+Orientation

Recursos:

• Julgamento automático da convergência da IK
• Exibir contagem de iterações e erro
• Atualizações em tempo real da pose do robô

S3

Simulação de Planejamento de Trajetória

Demonstração de Simulação 3 · sim/traj_sim.py

Simulação de planejamento de trajetória baseada em geodésicas SE(3), incluindo rastreamento CLIK e reprodução de animação MeshCat.

Como executar:

uv run python example/sim/traj_sim.py

Comandos interativos:

• Entrada: x y z [roll pitch yaw] (metros/radianos)
• Pressione Enter para usar a configuração padrão
• q: Sair

Recursos:

• Planejar da posição atual até a posição alvo
• Usar perfil de trajetória de mínimo tranco (minimum jerk)
• Exibição em tempo real das estatísticas da trajetória
• Reprodução completa da animação da trajetória no MeshCat
• Exibir caminho de referência (cinza) e caminho real (verde)

S4

Ferramenta de Visualização

Demonstração de Simulação 4 · sim/visualizer.py

[LINE_63>Wrapper do visualizador MeshCat, fornecendo uma interface unificada de exibição do robô.

Principais recursos:

• Carregar modelo URDF e exibir o robô
• Desenhar caminhos polilinha 3D (referência/real)
• Exibir pose alvo da IK (eixos tricolores + esfera)
• Suportar reprodução de animação de trajetória das juntas

Exemplo de uso:

from example.sim.visualizer import Visualizer
viz = Visualizer()
viz.update(q)  # Update robot pose
viz.draw_path(points, "path_name", color)  # Draw path

---

FAQ

• Encontrando erro Permission denied Certifique-se de ter executado sudo chmod 666 /dev/ttyACM0 ou sudo chmod 666 /dev/can0 para definir as permissões do dispositivo.

• A solução de IK falha ou os resultados são anormais Verifique se a pose alvo está dentro da área de trabalho do braço robótico e certifique-se de que a configuração dos limites das juntas está correta.

• O efeito da compensação de gravidade não é bom Isso pode ser causado por erros estruturais e precisão de usinagem. A compensação de gravidade deste projeto depende de URDF e Pinocchio. Você pode tentar corrigir o URDF para os seus parâmetros medidos reais (você pode pedir ajuda à IA para esta etapa).

---

Contato

• Suporte técnico: Submit Issue
• Repositório do projeto: GitHub
• Fórum: Seeed Studio Forum

---

Documentos de referência

• Documentação oficial do Pinocchio
• Documentação oficial do MeshCat
• motorbridge SDK

---

Se este projeto ajudar você, por favor nos dê uma estrela!