Guia do utilizador do robô móvel Lekiwi

Comprar na loja

O braço ativo preto usa um adaptador de energia de 5V 6A, enquanto o braço passivo branco usa um adaptador de energia de 12V 5A

[lerobot-Lekiwi.zip]

O código deste repositório de tutorial é mantido na versão estável do Lerobot testada antes de 1º de março de 2026. Atualmente, o Hugging Face fez uma atualização muito significativa do Lerobot, adicionando um grande número de novos recursos. Se você quiser acompanhar o tutorial mais recente, siga a documentação oficial.

LeKiwi é um projeto de carro-robô totalmente open source criado pela SIGRobotics-UIUC. Ele inclui ficheiros detalhados de impressão 3D e guias de operação, e foi projetado para ser compatível com o framework de aprendizagem por imitação LeRobot. Ele suporta o braço robótico SO101, possibilitando um processo completo de aprendizagem por imitação.

As posições precisas dos componentes podem ser visualizadas no CAD online Fusion360.

Ficheiro URDF

Visualização online do URDF https://urdf.d-robotics.cc/

Principais recursos

1. Open source e baixo custo: o LeKiwi oferece uma solução de carro-robô open source de baixo custo.

2. Integração com o LeRobot: projetado especificamente para integração com a plataforma LeRobot.

3. Recursos de aprendizagem abundantes: oferece recursos de aprendizagem open source abrangentes, incluindo guias de montagem e calibração, além de tutoriais sobre testes, recolha de dados, treino e implantação, para ajudar os utilizadores a começar rapidamente e desenvolver aplicações robóticas.

4. Compatível com Nvidia: pode ser usado em conjunto com o reComputer Mini J4012 Orin NX 16 GB.

5. Aplicação em múltiplos cenários: adequado para as áreas de educação, pesquisa científica, produção automatizada e robótica, ajudando os utilizadores a realizar operações robóticas eficientes e precisas em diversas tarefas complexas.

A JUXI é responsável apenas pela qualidade do hardware em si. Os tutoriais são atualizados estritamente de acordo com a documentação oficial. Se você encontrar problemas de software ou de dependências de ambiente que realmente não consiga resolver, reporte-os prontamente à plataforma LeRobot ou ao canal do LeRobot no Discord.

Atenção

• Todos os servos do chassis do Lekiwi precisam de alimentação de 12V. Para utilizadores que usam um braço robótico de 5V, fornecemos um módulo conversor redutor de 12V para 5V. Observe que você precisará modificar o circuito por conta própria.

• Fonte de alimentação de 12V — se necessário, você pode selecionar essa opção no checkout. Se você já tiver uma fonte de 12V, basta converter a interface de saída de energia para um ficha CC 5521.

• O controlador Raspberry Pi e a câmara precisam ser comprados separadamente pela interface de pedido.

Lista de materiais (BOM)

Ambiente inicial do sistema

**Para Ubuntu x86: **

• Ubuntu 22.04

• CUDA 12+

• Python 3.10

• Torch 2.6

Para Jetson Orin:

• Jetson JetPack 6.0

• Python 3.10

• Torch 2.3+

**Para Raspberry Pi: **

• Raspberry Pi 5 4G~16G

Configurar SSH

Depois de configurar o Raspberry Pi, você deve habilitar e configurar o SSH (Secure Shell Protocol), para poder entrar no Raspberry Pi a partir do seu notebook sem conectar monitor, teclado e mouse a ele. Você pode encontrar um ótimo tutorial aqui. É possível entrar no Raspberry Pi pelo prompt de comando (cmd) ou, se você usar VSCode, pode usar esta extensão.

Guia de impressão 3D

Componentes

Fornecemos ficheiros STL imprimíveis para as seguintes peças impressas em 3D. Essas peças podem ser impressas em impressoras FDM de nível doméstico a usar filamentos PLA genéricos. Nós as testamos na impressora Bambu Lab P1S. Para todos os componentes, basta carregá-los no bambuslicer, rotacioná-los e organizá-los automaticamente, habilitar os suportes recomendados e imprimir.

Parâmetros de impressão

Os ficheiros STL fornecidos podem ser impressos diretamente em muitas impressoras FDM. A seguir estão as configurações testadas e recomendadas; outras configurações também podem funcionar.

• Material: PLA+

• Diâmetro e precisão do bico: bico de 0,2 mm, altura da camada de 0,2 mm

• Densidade de preenchimento: 15%

• Velocidade de impressão: 150 mm/s

• Se necessário, envie o G-code (ficheiro fatiado) para a impressora e imprima

Instalar o LeRobot

No seu Raspberry Pi:

1. Instalar o Miniconda:

mkdir -p ~/miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh -O ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm ~/miniconda3/miniconda.sh

2. Reiniciar o Shell

Copie e cole o seguinte comando no seu Shell:source ~/.bashrc ou, para utilizadores de Mac:source ~/.bash_profile ou source ~/.zshrc (se você usar zshell)

3. Criar e ativar um novo ambiente Conda para o LeRobot

conda create -y -n lerobot python=3.10

Em seguida, ative seu ambiente Conda (você precisa fazer isso toda vez que abrir o Shell para usar o LeRobot!):

conda activate lerobot

4. Clonar o LeRobot:

git clone https://github.com/huggingface/lerobot.git ~/lerobot

5. Instale o ffmpeg no seu ambiente:

Ao usar miniconda, instale ffmpeg no seu ambiente:

conda install ffmpeg -c conda-forge

Normalmente isso instala o ffmpeg 7.X compilado com o codificador libsvtav1 para a sua plataforma. Se o libsvtav1 não for suportado (você pode verificar os codificadores suportados com ffmpeg -encoders), você pode:

【Para todas as plataformas】Instale explicitamente o ffmpeg 7.X:

conda install ffmpeg=7.1.1 -c conda-forge

[Somente Linux] Instale as dependências de compilação do ffmpeg e compile o ffmpeg com suporte a libsvtav1 a partir do código-fonte, garantindo que o executável ffmpeg usado seja o correto, o que pode ser confirmado com which ffmpeg.

Se você encontrar o seguinte erro, também pode usar o comando acima para resolvê-lo.

6. Instalar o LeRobot com as dependências de motores feetech:

cd ~/lerobot && pip install --no-binary=av -e ".[feetech]"
pip install -e ".[lekiwi]"

7. Definir o tempo de conexão

Encontre o config_lekiwi.py no diretório lerobot\src\lerobot\robots\lekiwi

connection_time_s: int = 7200 # 也就是2小时

C. Instalar o LeRobot em um notebook

Se você já instalou o LeRobot no seu notebook, pode pular esta etapa; caso contrário, siga os mesmos passos que fizemos no Raspberry Pi.

Usaremos com frequência o Prompt de Comando (cmd). Se você não estiver familiarizado com o uso do cmd ou quiser revisar o uso da linha de comando, pode consultar este: [Curso intensivo de linha de comando](https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Environment_setup/Command_line)

No seu computador:

1. Instalar o Miniconda:

2. Reiniciar o Shell

Copie e cole o seguinte comando no seu shell:source ~/.bashrc ou, para utilizadores de Mac:source ~/.bash_profile ou source ~/.zshrc (se você usar zshell)

3. Criar e ativar um novo ambiente Conda para o LeRobot

conda create -y -n lerobot python=3.10

Em seguida, ative seu ambiente Conda (você precisa fazer isso toda vez que abrir o Shell para usar o LeRobot!):

conda activate lerobot

4. Clonar o LeRobot:

git clone https://github.com/huggingface/lerobot.git ~/lerobot

5. Instale o ffmpeg no seu ambiente:

Ao usar miniconda, instale ffmpeg no seu ambiente:

conda install ffmpeg -c conda-forge

Normalmente isso instala o ffmpeg 7.X compilado com o codificador libsvtav1 para a sua plataforma. Se o libsvtav1 não for suportado (você pode verificar os codificadores suportados com ffmpeg -encoders), você pode:

【Para todas as plataformas】Instale explicitamente o ffmpeg 7.X:

conda install ffmpeg=7.1.1 -c conda-forge

[Somente Linux] Instale as dependências de compilação do ffmpeg e compile o ffmpeg com suporte a libsvtav1 a partir do código-fonte, garantindo que o executável ffmpeg usado seja o correto, o que pode ser confirmado com which ffmpeg.

Se você encontrar o seguinte erro, também pode usar o comando acima para resolvê-lo.

6. Instalar o LeRobot com as dependências de motores feetech:

cd ~/lerobot && pip install --no-binary=av -e ".[feetech]"
pip install -e ".[lekiwi]"

Configurar o motor

1. Encontre a porta USB associada ao braço robótico

Para encontrar a porta correta de um único motor, execute o script de utilitário a seguir duas vezes:

lerobot-find-port

Exemplo de saída (por exemplo, /dev/tty.usbmodem575E0031751 no Mac ou /dev/ttyACM0 no Linux):

Exemplo de saída (por exemplo, /dev/tty.usbmodem575E0032081 no Mac ou /dev/ttyACM1 no Linux):

Solução de problemas: no Linux, talvez seja necessário conceder acesso à porta USB com o seguinte comando:

sudo chmod 666 /dev/ttyACM0
sudo chmod 666 /dev/ttyACM1

2. Configure seu motor (produtos prontos podem pular esta etapa)

Conecte cada motor do chassis em sequência e execute o script a seguir. Ele primeiro inicializa os servos do braço robótico (IDs 6..1) e depois os servos do chassis, definindo seus IDs para (IDs 9..7). Se você já calibrou o braço robótico, pode pressionar Enter repetidamente para sobrescrever e pular:

lerobot-setup-motors \
    --robot.type=lekiwi \
    --robot.port=/dev/tty.usbmodem58760431551 # <- paste here the port found at previous step

3. Configurar o mirror nacional do Hugging Face

• Ubuntu

sudo nano ~/.bashrc

# 在文件末尾加入
export HF_ENDPOINT=https://hf-mirror.com

source ~/.bashrc
echo $HF_ENDPOINT

# 输出
# https://hf-mirror.com

• Mac

sudo nano ~/.zshrc

# 在文件末尾加入
export HF_ENDPOINT=https://hf-mirror.com

source ~/.zshrc

# 输出
# https://hf-mirror.com

① Criar token

https://huggingface.co/settings/tokens

② Registrar o token

Por exemplo, o meu é:

hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

③ Vincular o token

hf auth login

hf auth whoami

④ Criar repositório de dataset

Registe o Owner e o nome do Dataset, que são o <hf_username> e o <dataset_repo_id> necessários adiante

4. Atualize a configuração!!!

Os ficheiros de configuração no LeKiwi LeRobot e no notebook devem ser consistentes. Primeiro, precisamos encontrar o endereço IP do Raspberry Pi do carro-robô móvel. É o mesmo endereço IP usado para o SSH. Também precisamos encontrar a porta USB da placa de acionamento de servos do braço ativo no notebook e a porta da placa de acionamento de servos no LeKiwi. Essas portas podem ser encontradas com o script a seguir.

No Linux, talvez seja necessário conceder acesso à porta USB a executar o seguinte comando:

sudo chmod 666 /dev/ttyACM0
sudo chmod 666 /dev/ttyACM1

Observação importante: agora que você obteve o número da porta do braço ativo e o endereço IP do carro-robô LeKiwi, atualize ip na configuração de rede, atualize port na configuração do braço ativo e atualize port, remote_ip na configuração do LeKiwi.

Altere esses quatro ficheiros no diretório example\lekiwi

① Modificar teleoperate.py

remote_ip: endereço IP do Raspberry Pi

port: número da porta quando o braço ativo está conectado a um computador ou ao Linux

② Modificar record.py

HF_REPO_ID: nome de utilizador e nome do dataset no Hugging Face

remote_ip: endereço IP do Raspberry Pi

port: número da porta quando o braço ativo está conectado a um computador ou ao Linux

③ Modificar replay.py

remote_ip: endereço IP do Raspberry Pi

<hf_username>/<dataset_repo_id>, ou seja, o nome de utilizador do Hugging Face e o nome do dataset

Calibração

Agora precisamos calibrar o braço ativo e o braço passivo. O servo de direção da roda omnidirecional não precisa de calibração.

Calibrar o braço seguidor (montado na base do LeKiwi)

Execute o seguinte comando no seu computador para calibrar o braço ativo. Observação: a imagem mostrada aqui é um exemplo do modelo SO101.

lerobot-calibrate \
    --teleop.type=so100_leader \
    --teleop.port=/dev/tty.usbmodem58760431551 \ #修改为找到的端口号
    --teleop.id=my_awesome_leader_arm

Agora execute o seguinte comando no seu Raspberry Pi para calibrar o braço escravo no LeKiwi. Ignore a posição atual dele na mesa — a calibração normal deve ser feita quando instalado no chassis do LeKiwi.

lerobot-calibrate \
    --robot.type=lekiwi \
    --robot.id=my_awesome_kiwi

Unificamos os métodos de calibração para a maioria dos robôs. Primeiro, precisamos mover o robô para uma posição em que cada articulação esteja no ponto médio da faixa de movimento e, em seguida, pressionar o botão. Depois, movemos todas as articulações por toda a faixa de movimento. Você pode encontrar aquiEnter um vídeo do mesmo processo de calibração do SO101 como referência.

F. Operação remota

Abra um novo Prompt do Anaconda

Se você estiver a usar um Mac, talvez seja necessário conceder ao "Terminal" a permissão de acesso ao teclado para as operações remotas. Vá em "Ajustes do Sistema" > "Privacidade e Segurança" > "Monitoramento de Entrada" e marque a opção "Terminal".

Para realizar as operações remotas, entre no seu Raspberry Pi via SSH e execute o comando a seguir para ativar o ambienteconda activate lerobot; em seguida, execute o script:

python -m lerobot.robots.lekiwi.lekiwi_host --robot.id=my_awesome_kiwi

Em seguida, no seu notebook, execute também o comando a seguir para ativar o ambiente conda activate lerobot e então rode o script:

python examples/lekiwi/teleoperate.py

O ecrã do seu notebook deve exibir uma interface semelhante a esta:[INFO] Connected to remote robot at tcp://172.17.133.91:5555 and video stream at tcp://172.17.133.91:5556.Agora você pode mover o braço de controle e usar as teclas (W, A, S, D) do teclado para controlar o robô: avançar, virar à esquerda, recuar e virar à direita. Use as teclas (Z, X) para controlar o robô virando à esquerda ou à direita. Use as teclas (R, F) para aumentar ou diminuir a velocidade do robô móvel. Há três modos de velocidade no total; consulte a tabela a seguir:

Se você usar um teclado diferente, pode alterar as configurações de teclas de cada comando em LeKiwiClientConfig .

Solução de problemas de falha de comunicação

Se você encontrar problemas ao conectar ao robô móvel SO101, siga os passos abaixo para diagnosticar e resolver o problema.

1. Verifique a configuração do endereço IP

Certifique-se de que o endereço IP correto do Raspberry Pi esteja definido no ficheiro de configuração. Para verificar o endereço IP do Raspberry Pi, execute o seguinte comando (na linha de comando do Pi):

hostname -I

2. Verifique se o notebook/PC consegue aceder o Pi

Tente dar ping no Raspberry Pi a partir do notebook:

ping <your_pi_ip_address>

Se o ping falhar:

• Certifique-se de que o Pi esteja ligado e conectado à mesma rede.

• Verifique se o SSH está habilitado no Pi.

3. Tente a conexão SSH

Se você não conseguir entrar no Pi via SSH, pode ser uma conexão incorreta. Use o seguinte comando:

ssh <your_pi_user_name>@<your_pi_ip_address>

Por exemplo, ssh pi@192.168.0.106

Se ocorrer um erro de conexão:

• Para garantir que o SSH esteja habilitado no Pi, você pode executar o seguinte comando:

sudo raspi-config

• Em seguida, navegue até:Interfacing Options -> SSH e habilite-o.

4. Consistência dos ficheiros de configuração!!!

Certifique-se de que os ficheiros de configuração no notebook/PC e no Raspberry Pi sejam exatamente iguais.

G. Registrar dataset

Depois de se familiarizar com a operação remota, você pode usar o LeKiwi para registar seu primeiro dataset.

Para iniciar o programa no LeKiwi, conecte-se ao seu Raspberry Pi via SSH e execute os comandos a seguir para ativar o ambiente e iniciar o script:

conda activate lerobot

python -m lerobot.robots.lekiwi.lekiwi_host --robot.id=my_awesome_kiwi

Se você quiser usar o recurso do Hub do Hugging Face para enviar um dataset e ainda não fez login, certifique-se de entrar com um token que tenha permissão de escrita, o qual pode ser gerado nas configurações do Hugging Face:

hf auth login

Guarde o nome do seu repositório do Hugging Face em uma variável para executar o comando a seguir:

hf auth whoami

Em seguida, execute o seguinte comando no seu notebook para registar 2 rodadas e enviar o dataset ao Hub:

python examples/lekiwi/record.py

H. Visualizar o dataset

Se você enviou um dataset, pode visualizar seu dataset online e copiar e colar o ID do repositório gerado pelo seguinte comando:

echo *${HF_USER}*/my_lekiwi_dataset

Se você não enviou um dataset, também pode fazer a visualização localmente (a janela do navegador pode abrir a ferramenta de visualização em http://127.0.0.1:9090):

python lerobot/scripts/visualize_dataset_html.py \
  --repo-id *${HF_USER}*/lekiwi_test \
  --local-files-only 1

Visualizar um dataset (opcional, pode ser tentado)

echo ${HF_USER}/my_lekiwi_dataset

Se você enviou um dataset, também pode visualizá-lo localmente com o seguinte comando:

lerobot-dataset-viz \
  --repo-id ${HF_USER}/my_lekiwi_dataset \

Se você não enviou um dataset, também pode visualizá-lo localmente com o seguinte comando:

lerobot-dataset-viz \
  --repo-id juxi/my_lekiwi_dataset \

Aqui, juxi é o nome personalizado do repo_id durante a recolha de dados.

Técnicas de recolha de dados

Depois que você se familiarizar com o registo de dados, poderá criar datasets maiores para o treino. Uma boa tarefa inicial é agarrar objetos de posições diferentes e colocá-los em recipientes. Recomendamos registar pelo menos 50 segmentos, com 10 segmentos para cada posição. Mantenha a posição da câmara fixa e mantenha ações de preensão consistentes durante todo o registo. Além disso, garanta que os objetos manipulados estejam claramente visíveis no quadro da câmara. Um critério simples é que você consiga concluir a tarefa apenas observando o feed da câmara.

Nos capítulos a seguir, você treinará sua rede neural. Depois de obter um desempenho confiável de preensão, você pode começar a introduzir mais variações durante o processo de recolha de dados, como aumentar as posições de preensão, adotar técnicas diferentes de preensão e alterar as posições da câmara.

Evite adicionar muitas mudanças de uma vez, pois isso pode afetar seus resultados.

Se você quiser se aprofundar nesse tópico importante, confira nossa postagem no blog sobre o que torna um dataset excelente .

Solução de problemas:

Em sistemas Linux, se as teclas de seta esquerda e direita e a tecla Esc não funcionarem durante a recolha de dados, certifique-se de que a variável de ambiente $DISPLAY esteja definida. Consulte as limitações do pynput

I. Reproduzir uma rodada

Agora tente reproduzir a primeira rodada no seu robô:

python examples/lekiwi/replay.py

Parabéns 🎉, seu robô está pronto para tarefas de aprendizagem autônomo. Siga a seção de treino deste tutorial para começar a treiná-lo: Introdução a robôs do mundo real

K. Avalie sua política

Certifique-se de alterar remote_ip, port e HF_MODEL_ID

Modificar evaluate.py

HF_MODEL_ID="<hf_username>/<model_repo_id>" deve ser alterado para o nome do dataset enviado ao Hugging Face após o treino (se tiver sido enviado ao Hugging Face) ou para o diretório onde o modelo foi exportado localmente após o treino

HF_DATASET_ID = "<hf_username>/<eval_dataset_id>" Altere para o nome de utilizador e o nome do dataset eval_ que você criou

remote_ip: endereço IP do Raspberry Pi

Em seguida, execute o seguinte comando:

python examples/lekiwi/evaluate.py

1. O nome do dataset começa com eval para refletir que você está a executar inferência (por exemplo, ${HF_USER}/eval_act_lekiwi_test).

2. Se na fase de avaliação aparecer File exists: 'home/xxxx/.cache/huggingface/lerobot/xxxxx/juxi/eval_xxxx', exclua primeiro a pasta que começa com eval_ e execute o programa novamente.

O treino em simulação pode consultar

https://github.com/Ekumen-OS/lekiwi/tree/main

https://github.com/SIGRobotics-UIUC/LeKiwi-sim

Ajuda 🙋

Para problemas de hardware, entre em contato com o atendimento ao cliente. Para problemas de uso, participe do Discord.

LeRobot Platform

LeRobot Discord Channel

Produtos relacionados

Robô móvel Lekiwi→Kit desenvolvedor SO-ARM101→Placa driver de servo de barramento→