Installa ROS 2 su Raspberry Pi e crea uno spazio di lavoro

Introduzione

Nulla in ROS 2 è difficile finché non provi a installarlo su un robot; a quel punto tre problemi non correlati si presentano insieme: il sistema operativo è sbagliato, lo spazio di lavoro non viene compilato nella memoria del Pi e il laptop non vede i nodi del robot. Non sono esattamente problemi di ROS, ed è per questo che i tutorial ufficiali non ti avvisano.

Questa guida ti porta da una scheda SD vuota a ros2 topic list funzionante dal laptop, con nodi in esecuzione sul robot.

Scegli il sistema operativo, non soltanto la scheda

I binari ROS 2 sono compilati per Ubuntu, non per Raspberry Pi OS. Raspberry Pi OS è basato su Debian, quindi i pacchetti apt non ci sono e ogni soluzione alternativa — compilare dai sorgenti, usare Docker o conda — ti costa ore prima ancora di scrivere una riga di codice per il robot.

Installa quindi Ubuntu Server 24.04 LTS (64-bit) e abbinalo alla versione di ROS 2 compilata per questa versione. Al momento della stesura, la coppia è Jazzy Jalisco, supportata fino al 2029; consulta la pagina di installazione per la versione corrente quando leggi questa guida e sostituisci il nome ovunque.

Tre cose da impostare correttamente durante il flashing:

• 64 bit. I pacchetti ROS 2 arm64 esistono; quelli armhf no.
• Server, non Desktop. Un robot non ha un monitor e l’ambiente desktop consuma RAM che vuoi dedicare alla visione.
• Pi 4 con 4 GB, oppure Pi 5. Una scheda da 2 GB esegue ROS 2 senza problemi, ma non può compilarlo in modo confortevole.

Installa ROS 2 con apt

Aggiungi la sorgente apt di ROS 2, poi installa. La configurazione del repository cambia tra le versioni, quindi questa è la struttura da ricordare, non un frammento da memorizzare:

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

Usa ros-base, non desktop. Il metapacchetto desktop porta con sé RViz e le GUI dimostrative, che un robot senza interfaccia grafica non eseguirà mai e che occupano a lungo una scheda SD durante l’installazione. La visualizzazione appartiene al laptop, dove installi ros-jazzy-desktop completo.

ros-dev-tools fornisce colcon e rosdep. Inizializza rosdep una sola volta:

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

Carica il sottolivello, poi l’overlay

ROS 2 non fa nulla finché non carichi il suo ambiente, ed è qui che nasce gran parte della confusione iniziale.

source /opt/ros/jazzy/setup.bash

Questo è il sottolivello, ossia la distribuzione installata. Il tuo spazio di lavoro, una volta compilato, è un overlay che si appoggia su di esso. Caricare un overlay importa implicitamente il sottolivello rispetto al quale è stato compilato.

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

Mettere il sottolivello in .bashrc è una pratica standard e sicura. Metterci anche il tuo overlay è una trappola da evitare fin dall’inizio: il giorno in cui avrai due spazi di lavoro, o ricompilerai rispetto a un’altra distribuzione, ogni nuova shell partirà silenziosamente con un ambiente obsoleto e perderai un pomeriggio a correggere un problema fantasma. Carica l’overlay esplicitamente in ogni shell, nel terminale che gli serve.

Crea uno spazio di lavoro e un pacchetto

Uno spazio di lavoro colcon è una directory che contiene src/. Questa è l’intera specifica.

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

Poi compilalo e caricalo come overlay:

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

Usa --symlink-install. Il comando collega i file Python nello spazio di installazione invece di copiarli, così la modifica di un nodo ha effetto alla successiva esecuzione anziché richiedere una nuova compilazione. Su un Pi, dove ricompilare è lento, è la differenza tra iterare e aspettare.

Dopo la compilazione, ~/ros2_ws contiene build/, install/ e log/ accanto a src/. Solo src/ deve andare nel controllo di versione.

Compila senza esaurire la memoria del Pi

colcon build compila i pacchetti in parallelo, un processo per core, e ogni compilazione C++ può occupare quasi un gigabyte. Su un Pi quadricore sono quattro compilatori pesanti contemporanei, e la build termina con un messaggio su un processo terminato — oppure l’intera scheda si blocca.

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

È più lento, ma finisce. I pacchetti scritti solo in Python non hanno questo problema; si manifesta appena compili qualcosa che contiene C++. Aggiungere qualche gigabyte di swap funziona, anche se su una scheda SD è lentissimo.

Comunica con il robot dal laptop

ROS 2 non ha un master. I nodi si trovano tramite DDS discovery sulla rete: laptop e Pi nella stessa LAN possono formare un unico grafo senza alcuna configurazione, quando funziona.

Imposta lo stesso dominio su entrambe le macchine:

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

Il dominio suddivide la rete. Due robot nella stessa stanza sul dominio predefinito sentiranno i reciproci topic e si contenderanno i messaggi: è un modo memorabile per capire a cosa serve questa impostazione.

Verifica dal laptop mentre sul Pi è in esecuzione un nodo che pubblica messaggi:

ros2 topic list
ros2 node list
ros2 topic echo /chatter

Fai sopravvivere il rilevamento al Wi-Fi

È il guasto di rete ROS 2 più comune vedere ros2 topic list vuoto mentre il Pi sta chiaramente pubblicando; quasi mai la colpa è di ROS.

Il rilevamento usa il multicast e molti punti di accesso non lo inoltrano. I router Wi-Fi domestici limitano o scartano spesso il multicast, mentre le modalità «isolamento client» o rete ospite bloccano del tutto il traffico tra client. I nodi sono in esecuzione; i pacchetti che dovrebbero presentarli non arrivano mai.

Procedi in quest’ordine:

1. Stessa sottorete? Un laptop a 5 GHz e un Pi su un SSID ospite non sono sulla stessa rete, per quanto simili sembrino gli indirizzi.
2. Stesso ROS_DOMAIN_ID, nella shell che sta davvero eseguendo il nodo? Un export in un terminale non raggiunge un altro terminale, né un servizio systemd.
3. Prova via cavo. Se Ethernet funziona e il Wi-Fi no, hai dimostrato che il problema è il multicast, non ROS.
4. Controlla il firewall. Esegui sudo ufw allow in proto udp from <subnet> su entrambi i lati, oppure disattivalo durante i test.
5. Ripiega su un server di rilevamento. Fast DDS può usare un endpoint noto invece del multicast: imposta ROS_DISCOVERY_SERVER all’indirizzo del robot su entrambe le macchine. È la soluzione affidabile su una rete che non controlli.

C’è anche un altro problema, meno evidente: mantieni sincronizzati gli orologi. TF2 confronta le marche temporali tra macchine diverse e un Pi senza RTC si avvia con un’ora sbagliata. Installa chrony su entrambi i lati, altrimenti ogni ricerca di trasformazione fallisce con un errore di estrapolazione che sembra un bug di ROS.

Avvia i nodi del robot all’accensione

Un robot in cui devi entrare via SSH per avviarlo è un robot spento. Lo risolve un’unità systemd:

# /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

La riga Environment= conta più di quanto sembri. systemd non legge .bashrc, quindi un servizio non eredita nessuna delle variabili ROS presenti nella shell interattiva: è esattamente il motivo per cui un robot che funziona via SSH resta silenzioso quando si avvia da solo.

Quando qualcosa va storto

Una volta sistemato l’ambiente, la domanda successiva è cosa inserirci: è un problema di progettazione, non di installazione. Nodi, topic, servizi e azioni spiega come scegliere tra gli schemi di comunicazione, mentre Sistemi di riferimento TF2 affronta la parte che mette in difficoltà dopo quella scelta.