Install ROS on Your Raspberry Pi 5 With ROCKO!

This instructable will walk you through how to

1. Configure Ubuntu on a Rasperry Pi 5
2. Set up ROS2 (Robot Operating System) on a Raspberry Pi 5
3. Create a virtual environment to write Python code to ROS
4. Configure your software environment for ROCKO, a self-balancing robot

These steps are meant to setup the ROCKO robotics platform. To learn more and build a ROCKO of your own, visit the ROCKO wiki or the full ROCKO instructable for more information.

Materials you'll need:

1. Computer, preferrably one running Windows
2. UART Interface
3. USB-C cable
4. Rasberry Pi 5

Begin by inserting your microSD card into your device. When the microSD card has been properly inserted, it will appear in the File Explorer.

Double-click the microSD card. If the microSD card opens, you can move on to step 2.

If a notification appears instead that the disk needs to be formatted, select ‘format disc’.

A 'Format' window will appear. All settings can be left as-is.

Beware! Formatting an SD card will remove all of its data. If you have used the SD card in the past, save your files before formatting.

When you’re ready to reformat the microSD card, press ‘Start’.

Launch the Raspberry Pi Imager. Select ‘Raspberry Pi 5' as the device.

Select ‘Choose OS’. Within the dialogue menu, select ‘Other general-purpose OS’, then ‘Ubuntu’.

Select ‘Ubuntu Server 24.04.1 LTS (64-bit)’. Then, for ‘Storage’, select your microSD card.

Once all three options are correctly set, press ‘NEXT’. The application will ask you if you would “like to apply OS customization settings”. Select ‘Edit Settings’.

The ‘OS Customization’ window will appear and prompt you for input. In General, change the settings to those in the following:

Set hostname

rockopi

Set username and password

Username: rocko

Password: zoom

Configure wireless LAN

SSID: [The name of your WiFi network]

Password: [The password to your WiFi network]

Wireless LAN country: [Your region]

Set locale settings

Time zone: [Your timezone]

Keyboard layout: [Your keyboard layout]

Under Services, make sure “Enable SSH” and “Use password authentication” are selected.

Press ‘SAVE’. The “Would you like to apply OS customization settings?” will reappear. Select ‘YES’.

Raspberry Pi Imager will begin writing Ubuntu to your microSD card. When the process is finished, you can eject the microSD card from your device and insert it in the Raspberry Pi. The microSD card slot is located on the underside of the Raspberry Pi, near the reset button.

To communicate directly with the Raspberry Pi, we’ll now use our UART interface (debug probe). Connect the included cable to the port labelled UART on the Raspberry Pi.

The other side of the cable should be connected to the UART port within of the debugging probe. Then, the probe’s USB cable should be connected to your computer.

After we connect the UART interface, let’s check its port. Open the Device Manager in Windows. The UART interface will appear as a “USB Serial Device” in the “Ports (COM & LPT)” section.

Take note of the COM port displayed in the device manager, then launch PuTTY. (If you don't have it installed yet, the link will take you to the download page.) At this point, the Raspberry Pi should be powered. When it’s ready to go, you’ll see a green, (sometimes blinking) light.

Switch the connection type to “serial”. The serial mode will allow us to send our commands directly over the debug interface to the ROCKO Pi.

Set the ‘Serial line’ to the COM port identified previously. Here, we’ve identified it as COM13. Set the ‘Speed’ to 115200.

When all is ready to go, hit ‘Open’. If your Raspberry Pi is in the process of booting, you will see it initialize. If it has already booted, press “enter” on your keyboard to log in. When Ubuntu prompts you for your username and password, enter the username and password you chose in the Raspberry Pi Imager.

If you can’t log in, you may need to repeat the process of preparing the microSD card and check again within Raspberry Pi Imager that the username and password settings have been saved.

From here, we’ll start issuing commands to Ubuntu to install the ROCKO software. We won’t explain every command as we go, but here are the most important things to know:

1. apt: Ubuntu’s “package manager”. Used for installing and updating programs.
2. cd: Short for ‘change directory'. Moves you from one folder to another. If you are used to using the File Explorer on Windows, this is a little bit different. The folder you are currently using will be displayed to the right of your username (ROCKO or otherwise).
3. git: “Version control” software. Allows you to download and interact with software projects.
4. sudo: Allows you to execute a command as an administrator. Requires you to enter your password.

Execute the following commands in order, as described.

First, let’s check that the correct version of Ubuntu is installed. Run: lsb_release -a

The correct version of Ubuntu is 24.04. If a different version is displayed, you will need to restart the process of preparing the microSD card and select Ubuntu Server 24.04.

Check that the Pi is connected to WiFi. Run: ping 8.8.8.8

If there is no response, your WiFi network hasn’t been connected or your settings are incorrect. Refer to the final step on this page if you need help debugging these issues.

If a response is received, you are ready to move on to the next step. To stop the process, press CTRL+C.

Update your system with sudo apt-get update, then sudo apt-get upgrade. This might take some time.

Follow the instructions on the ROS 2 Documentation: Jazzy Jalisco page to install ROS 2. ROS 2 is ROCKO’s backbone, handling sensors, balancing, and motor control.

Follow the instructions in “System setup” and “Install ROS 2”. Stop when you reach the “Install additional RMW implementations” section. You should install the development tools in the optional section,

Next, we’ll install the packages for ros2_control. ros2_control is a ROS 2 component that allows us to use controls algorithms for ROCKO’s balancing loop. Run:

sudo apt-get install ros-jazzy-ros2-control

sudo apt-get install ros-jazzy-ros2-controllers

Install the foxglove_bridge package. This allows us to send data to a laptop for visualizing the sensor data and controllers.

sudo apt install ros-jazzy-foxglove-bridge

Now we’ll install two ROS tools: colcon and rosdep. These will allow us to build ROS packages. Run:

sudo apt install python3-colcon-common-extensions

sudo apt install python3-rosdep

Initialize rosdep. Run:

sudo rosdep init

sudo rosdep update

Now we need to install the dependencies for ros2_control. We’ll do this by leveraging an example from a ROS2 workshop. Dependencies are packages and programs needed for another program to run.

On the ROS2 workshop instructions page, run the commands in the first codeblock labelled “Build from debian packages”. This is the codeblock beginning with mkdir -p ~/ros2_ws/src and ending with sudo rosdep install --from-paths ./ -i -y --rosdistro ${ROS_DISTRO} . Once you’ve completed running all of the commands in the codeblock, move on to the next step. You do not need to build the repository or follow the rest of the steps on the page.

If the rosdep update or rosdep install command fails, Run:

export ROS_DISTRO=jazzy

Then try running rosdep update --rosdistro=$ROS_DISTRO and the following commands again.

Run cd ~ to move back to your home directory.

In order to connect ROS 2 to sensors and hardware, we use the library WiringPi. To install WiringPi on your system, open its page on GitHub and follow the instructions in the ‘From Source’ section of ‘Installing’.

However, please note: the instructions reference wiringpi-3.0-1.deb, an out-of-date version of WiringPi. This will not be the name of the file you will be installing. At the time of writing, the correct filename was wiringpi_3.12_arm64.deb, but the software is updated frequently. To check what the name of the file should be, reference the ‘Releases’ tab on the GitHub page, where the latest version number will be listed.

For example-- if the latest release is 3.14, substitute wiringpi-3.0-1.deb with wiringpi_3.14_arm64.deb.

If a permissions error occurs after installation (“download is performed unsandboxed as root”), it can be ignored.

Now, we’ll create a Python ‘virtual environment’. A virtual environment is a container for Python packages. If you ever decide to use the ROCKO Raspberry Pi for something else, or create your own projects on top of ROCKO’s code, you can create a new virtual environment to prevent conflicts between packages. This is a safety measure to ensure all of the Python components of ROCKO’s code work properly.

First, move back to the home directory: cd ~

Then run:

sudo apt install python3.12-venv

python3 -m venv .venv

source .venv/bin/activate

Once the virtual environment has been created and activated, we can install the Python packages ROCKO needs. Run:

git clone https://github.com/BiPed-Capstone/ROCKO-tools.git

cd ROCKO-tools

pip3 install -r requirements.txt

Once the Python packages have completed installing, navigate back to the home directory with cd ~

We’re almost to the finish line. It’s time to download ROCKO’s source code. Run:

git clone https://github.com/BiPed-Capstone/ROCKO-env.git

We’ll add some commands to our .bashrc file to make ROCKO easier to use in the future. The bashrc file is a file that runs automatically when you log into your rocko user account on Ubuntu. Run:

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

echo "source /home/rocko/ROCKO-env/install/setup.bash" >> ~/.bashrc

echo "source ~/.venv/bin/activate" >> ~/.bashrc

echo "cd ~/ROCKO-env" >> ~/.bashrc

echo "export ROS_DOMAIN_ID=17" >> ~/.bashrc

Once you run everything here, reboot with sudo reboot.

Your Pi should reboot directly into the ROCKO-env folder. If you didn’t make it there, ensure the commands in the last step have been run. (If you ever need to manually, you can navigate into the ROCKO-env folder from the home directory with cd ROCKO-env.)

Build ROCKO’s ROS environment. Run:

colcon build

Once the build has completed, update the dependencies of ROCKO-env. Run:

rosdep install --from-paths rocko_env --ignore-src -r -y

Your Pi is ready to ROCKO!

Visual Studio Code (VS Code) is a convenient text editor that will allow you to connect directly to WSL2 (“Windows Subsystem for Linux”). You will need to download WSL by searching ‘PowerShell’ in the Start menu of your computer. Right-click it and ‘Run as Administrator.’ Next, run: wsl --install in the PowerShell window. You will also need to download VS Code if you don't already have it.

Preparing Ubuntu

If you do not already have an administrative PowerShell window open, search ‘PowerShell’ in the Start menu, right-click it, and select ‘Run as Administrator’.

Run: wsl --install -d Ubuntu

Ubuntu will now be installed. Search ‘Ubuntu’ in the Start menu and run it.

Once Ubuntu has been launched, it will prompt you for your desired username and password. Enter these details, and Ubuntu will start.

Update your system by running

sudo apt-get update

Installing ROS2 on WSL2

Follow the official instructions for installing Jazzy Jalisco on Ubuntu. Install the optional development tools. Installing either ros-jazzy-desktop or ros-jazzy-ros-base is fine, but there may be advantages to the GUI components included in ros-jazzy-desktop for desktop development.

Set the system environment variable, which tells Ubuntu which version of ROS2 is installed and where it is installed.

source /opt/ros/jazzy/setup.bash

Finally, follow the ros2_control section in the primary Raspberry Pi configuration document.

Preparing ROCKO Environment

Now, we will install the ROCKO software repositories on our WSL2 Ubuntu installation.

**Note that this installation procedure is not 1:1 with the installation for the robot’s host computer. We will not install the software components that directly interact with ROCKO’s hardware, as the Ubuntu installation lacks the physical hardware addresses for this code to run properly.**

Download the ROCKO-tools helper repository. Run:

git clone https://github.com/BiPed-Capstone/ROCKO-tools

Set up the Python environment for ROCKO. Run:

sudo apt-get install python3-pip

[When the system asks you whether or not you would like to install, enter Y.]

sudo apt install python3.12-venv

python3 -m venv .venv

source .venv/bin/activate

Install ROCKO’s Python dependencies. Run:

cd ROCKO-tools

pip3 install -r requirements.txt

Download ROCKO’s primary repository, ROCKO-env. Run:

cd ~

git clone https://github.com/BiPed-Capstone/ROCKO-env.git

ROCKO’s environment has now been downloaded and can be built. Run:

cd /home/rocko/ROCKO-env

colcon build

For convenience, we can use VS Code to write and test our code. While WSL2 is running, select the “connect to” button in the bottom left corner of the screen.

Pressing this button will open the “Select an option to pen a Remote Window” input box. Select “Connect to WSL”.

VS Code will restart connected to Ubuntu. Folders in Ubuntu can now be opened, and files can be directly edited.

To configure the environment to run ROCKO’s environment and start the software, we can use the root_startup.sh script from ROCKO-tools. Press Ctrl+` to open the terminal. Then, run:

cd ~/ROCKO-tools

source root_startup.sh

To stop the program from running, press Ctrl+C.

Your computer is ready to ROCKO!

Raspberry Pi isn’t connecting to my WiFi network

If your Raspberry Pi cannot connect to WiFi, the most likely cause is incorrect credentials supplied to the installer. We can correct this by modifying our “netplan” file.

**If you are on a college campus providing eduroam, the Raspberry Pi Imager application will not be able to configure the Raspberry Pi to connect to that network. The process to connect a Raspberry Pi to eduroam frequently varies by campus. Check with your campus IT department.**

To access the file, run:

sudo nano /etc/netplan/50-cloud-init.yaml

Our file configured for a network with no password looks like the first image above. A typical configuration for a home WiFi network will probably look like the second image above.

Where YOUR_NETWORK and your_password are replaced with the name and password for your WiFi network.

Once you’re done editing your file, hit CTRL+S, then CTRL+X. Then, reboot. Run:

sudo reboot

If your credentials are correct, the Raspberry Pi will have connected. If not, repeat this process until you have everything right.

Raspberry Pi’s status light is red

If your Raspberry Pi’s status light is red, the most likely cause is a corrupt SD card. This frequently occurs if your Raspberry Pi is experiencing voltage drops on its USB cable. One possible cause is a USB cable that is too long.

We recommend using as short of a USB cable as possible. To reformat the microSD card, simply begin configuration process again from the beginning of this guide.

UART is displaying error/warning

If you are connected via UART, and your system encounters a warning or error state, UART will display it as it appears in your window.

Sometimes, these error messages are important and can tell you something about your system to fix (keep an eye out for voltage drops). Other times, this is just a warning or not a cause for immediate concern, such as the example above-- on our network, the brcmfmac error is an indication of an issue with the WiFi network rather than ROCKO itself.

Regardless, if you encounter an error like this, you can return to the command prompt by pressing CTRL+C.