Instalar o ROS 2 em um Raspberry Pi e criar um espaço de trabalho

Introdução

Nada no ROS 2 é difícil até você tentar instalá-lo em um robô. Nesse momento, três coisas sem relação falham ao mesmo tempo: o sistema operacional está errado, o espaço de trabalho não compila por falta de memória do Pi e o computador portátil não enxerga os nós do robô. Nenhum desses problemas é exatamente do ROS, e é por isso que os tutoriais oficiais não avisam sobre eles.

Este guia leva você de um cartão SD vazio até ros2 topic list funcionando no computador portátil, com nós executando no robô.

Escolha o sistema operacional, não apenas a placa

Os binários do ROS 2 são compilados para Ubuntu, não para Raspberry Pi OS. Como o Raspberry Pi OS é baseado no Debian, os pacotes apt simplesmente não existem, e todas as soluções alternativas — compilar a partir do código-fonte, Docker, conda — custam horas antes de você escrever qualquer código de robô.

Portanto, instale o Ubuntu Server 24.04 LTS (64 bits) e use a versão do ROS 2 compilada para ele. No momento em que este texto foi escrito, essa combinação é Jazzy Jalisco, com suporte até 2029; consulte a página de instalação para verificar a versão atual quando você ler e substitua o nome em todo o texto.

Três pontos devem estar corretos ao gravar o sistema:

• 64 bits. Os pacotes arm64 do ROS 2 existem; os armhf, não.
• Server, não Desktop. Um robô não tem monitor, e o ambiente gráfico consome RAM que você quer usar para visão computacional.
• Pi 4 com 4 GB, ou um Pi 5. Uma placa de 2 GB executa o ROS 2 normalmente, mas não consegue compilá-lo sem problemas.

Instale o ROS 2 pelo apt

Adicione a fonte apt do ROS 2 e faça a instalação. A configuração do repositório é a parte que muda entre as versões, portanto este é um modelo geral, não um trecho para memorizar:

sudo apt update && sudo apt install -y software-properties-common curl
sudo add-apt-repository universe

# Fetch and install the package that registers the ROS 2 apt repository and key.
export ROS_APT_SOURCE_VERSION=$(curl -s \
  https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest \
  | grep -F "tag_name" | awk -F\" '{print $4}')
curl -L -o /tmp/ros2-apt-source.deb \
  "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo $VERSION_CODENAME)_all.deb"
sudo apt install -y /tmp/ros2-apt-source.deb

sudo apt update
sudo apt install -y ros-jazzy-ros-base ros-dev-tools

Use ros-base, não desktop. O metapacote desktop inclui o RViz e as interfaces gráficas de demonstração, que um robô sem tela nunca executará e que levam muito tempo para instalar em um cartão SD. A visualização pertence ao seu computador portátil, onde você instala o ros-jazzy-desktop completo.

ros-dev-tools fornece colcon e rosdep. Inicialize o rosdep uma vez:

sudo rosdep init      # skip if it says the file already exists
rosdep update

Execute o source no underlay e depois no overlay

O ROS 2 não faz nada até que você execute o comando source no ambiente, e é aqui que está a maior parte da confusão inicial.

source /opt/ros/jazzy/setup.bash

Este é o underlay — a distribuição instalada. Seu próprio workspace, depois de compilado, é um overlay sobre ele. Executar o source no overlay também carrega o underlay usado para compilá-lo.

echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc

Colocar o underlay no .bashrc é padrão e seguro. Colocar o overlay ali é uma armadilha que vale evitar desde o início: no dia em que você tiver dois workspaces, ou recompilar contra outra distribuição, cada novo terminal começará silenciosamente com um ambiente obsoleto, e você perderá uma tarde depurando um problema fantasma. Execute o source no overlay explicitamente em cada terminal que precisar dele.

Crie um espaço de trabalho e um pacote

Um workspace do colcon é um diretório com um src/ dentro. Essa é toda a especificação.

mkdir -p ~/ros2_ws/src && cd ~/ros2_ws
ros2 pkg create --build-type ament_python --license Apache-2.0 my_robot

Depois, compile e carregue o overlay:

cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -y
colcon build --symlink-install
source install/setup.bash

Use --symlink-install. Ele cria vínculos dos arquivos Python no diretório de instalação em vez de copiá-los, portanto uma alteração em um nó passa a valer na próxima execução, sem exigir uma recompilação. Em um Pi, em que a recompilação é lenta, essa é a diferença entre iterar e esperar.

Após a compilação, ~/ros2_ws contém build/, install/ e log/ ao lado de src/. Apenas src/ deve entrar no controle de versão.

Compile sem esgotar a memória do Pi

colcon build compila pacotes em paralelo, um processo por núcleo, e cada compilação C++ pode consumir quase um gigabyte. Em um Pi de quatro núcleos, isso significa quatro processos de compilação pesados ao mesmo tempo, e a compilação termina com uma mensagem sobre um processo encerrado — ou a placa inteira trava.

MAKEFLAGS="-j1" colcon build --parallel-workers 1 --symlink-install

É mais lento, mas termina. Pacotes puramente em Python não têm esse problema; ele surge assim que você compila algo que contenha C++. Adicionar alguns gigabytes de swap também resolve, mas em um cartão SD a compilação fica extremamente lenta.

Fale com o robô a partir do computador portátil

O ROS 2 não tem um mestre. Os nós se encontram por descoberta DDS na rede, o que significa que um computador portátil e um Pi na mesma LAN podem formar um grafo sem nenhuma configuração — quando funciona.

Defina o mesmo ROS_DOMAIN_ID nas duas máquinas:

export ROS_DOMAIN_ID=42        # any value 0–101; the same on every machine

O domínio particiona a rede. Dois robôs na mesma sala usando o mesmo ROS_DOMAIN_ID ouvirão os tópicos um do outro e disputarão o acesso a eles, uma forma memorável de aprender o que essa configuração faz.

Verifique no computador portátil, com um talker em execução no Pi:

ros2 topic list
ros2 node list
ros2 topic echo /chatter

Faça a descoberta funcionar pelo Wi-Fi

ros2 topic list sem resultados enquanto o Pi claramente está publicando é a falha de rede do ROS 2 mais comum, e quase nunca a culpa é do ROS.

A descoberta usa multicast, e muitos pontos de acesso não o encaminham. Roteadores Wi-Fi domésticos normalmente limitam a taxa ou descartam pacotes multicast, e os modos de “isolamento de clientes” ou rede de visitantes bloqueiam totalmente o tráfego entre clientes. Os nós estão em execução; os pacotes que permitiriam que se descobrissem nunca chegam.

Resolva nesta ordem:

1. Mesma sub-rede? Um computador portátil em 5 GHz e um Pi em um SSID de visitantes não estão na mesma rede, por mais parecidos que os endereços pareçam.
2. Mesmo ROS_DOMAIN_ID, no terminal que realmente está executando o nó? Um export em um terminal não chega a outro, nem a um serviço systemd.
3. Tente uma conexão com fio. Se a Ethernet funcionar e o Wi-Fi não, você comprovou que o problema é multicast, não o ROS.
4. Verifique o firewall. Use sudo ufw allow in proto udp from <subnet> nas duas extremidades ou desative-o durante os testes.
5. Use um servidor de descoberta como alternativa. O Fast DDS pode usar um endpoint conhecido em vez de multicast — defina ROS_DISCOVERY_SERVER com o endereço do servidor de descoberta do robô nas duas máquinas. Essa é a solução confiável em uma rede que você não controla.

Mais uma, e ela é discreta: mantenha os relógios sincronizados. O TF2 compara carimbos de tempo entre máquinas, e um Pi sem RTC inicia com a hora errada. Instale o chrony nas duas extremidades, ou cada consulta de transformação falhará com um erro de extrapolação que parece um defeito do ROS.

Inicie os nós do robô na inicialização

Um robô que exige entrada via SSH para ser iniciado está, na prática, desligado. Uma unidade systemd resolve:

# /etc/systemd/system/my-robot.service
[Unit]
Description=Robot bringup
After=network-online.target

[Service]
User=ubuntu
Environment=ROS_DOMAIN_ID=42
ExecStart=/bin/bash -lc 'source /opt/ros/jazzy/setup.bash && \
  source /home/ubuntu/ros2_ws/install/setup.bash && \
  ros2 launch my_robot bringup.launch.py'
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now my-robot
journalctl -u my-robot -f

A linha Environment= importa mais do que parece. O systemd não lê seu .bashrc, portanto um serviço não herda nenhuma das variáveis ROS do seu terminal interativo — exatamente por isso que um robô que funciona via SSH fica em silêncio quando se inicia sozinho.

Quando algo dá errado

Com o ambiente corretamente configurado, a próxima questão é o que executar nele — um problema de design, não de instalação. Nós, tópicos, serviços e ações aborda a escolha entre os padrões de comunicação, e frames de coordenadas no TF2 aborda a parte que causa problemas depois disso.