Video of Workshop 1

The video of the first workshop 1 presentation is here. Warning: it is 3 hours of mostly working with participant's connectivity problems, but the last hour goes into docker theory.

apt quick reference

You'll use apt for installing apps on Linux systems (RPis, VMs and wsl)

• sudo apt update # update the list of known packages and versions

• sudo apt upgrade # upgrade any packages that are behind the current version

• sudo apt-cache search <package-name> # search for a package

• sudo apt install <package-name> # install a package

• sudo apt remove <package-name> # remove a package

• sudo apt list --installed | grep <package-name> # check if a package is already installed

Editors: vi or nano

TODO: add ssh & sftp/scp instructions

HW required:

• Laptop capable of displaying GUIs and terminal windows from the RPi (minimum). Capable of running ROS2 in docker (desirable). The minimum level would be a laptop running VNC to the RPI. A better level would be an Ubuntu native machine or VM capable of running a docker with ROS2 in it.

• RPi with minimum 16GB SD card. Any RPI that can run Raspberry Pi OS (not Raspbian) should work. It must run the 64-bit OS. Examples are: Raspberry Pi 4 or 5, RPi 3 (less desirable), RPi zero 2W (slow).

• Adapter to connect SD card to laptop

• Serial console socket and connectors to RPi 40-pin header (desirable)

• USB-Serial cable (3.3V) (desirable). 

• Mini or micro-HDMI adapter to adapt RPi to monitor. A USB hub may be required to connect keyboard and mouse to RPi

Prerequisites:

• You have a github account and can connect a browser to github and view packages. Note: you will need to configure 2-factor authentication (e.g. authy on your phone)

Content outline

• Configure laptop. Install docker & test

• Update RPi FW

• Install the right OS (Bullseye or Bookworm)

• Configure serial console

• Configure the RPi with all the settings needed for remote use, minus docker installation

• Install ROS2 on laptop for local use

Where we will run and view apps of different kinds

The laptop displays all terminals and GUIs, whether their I/O be generated by the RPi or by the PC.

Laptop:

• Run rpi-imager

• Run terminal logged into RPi over ssh

• Run vnc window connected to vnc server on RPi, displaying RPi desktop and any GUIs running on RPi

• Run terminal or app using serial comms to talk to RPi (emergency recovery)

• Run Ubuntu locally on PC either under wsl (on Windows) or natively on Ubuntu or in Virtualbox (optional, but may be beneficial, e.g. for doing tutorials)

• Run vs-code (possibly using remote-login to rpi for editing)

• Run meetup, and other laptop apps and web pages

RPi from ssh login:

• Launch vncserver if GUI is desired (for whatever purpose)

• Launch docker container for running ROS2. Run any number of terminal sessions connected to running container.

  •  Inside container, run ROS2 robot apps (e.g. telemetry collection) and ROS2 CLI commands.

  • Inside container, launch terminator, which starts x-windows running in container and displayed on vnc

RPi from VNC client window

• Launch terminator inside vnc window in terminal running in container, and can run ROS or other programs from terminator windows

• ROS2 GUI apps launched from a docker-terminal connected to RPi are viewed and operated from vnc window

Hands-on

Laptop Configuration

This section describes how to configure your laptop to work with ROS2 software running on an rpi.

It is possible to use only vnc, and to run all exercises on an rpi.  In that case, no laptop configuration is needed. You can delay the decision to install ROS on a laptop - it will not affect the exercises.

Configure Laptop to monitor RPi boot over serial

Install a comms program to the base Linux or Windows PC in order to use the RPi serial port for monitoring boot and configuring networking. miniterm is a lightweight choice for linux, but minicom is also suitable, or any other standard comms program). If you're running Windows you'll also need a driver for the USB-serial cable.

• On linux, the miniterm command uses .bash.aliases or .bashrc: alias miniterm='python -m serial.tools.miniterm --eol LF

• On Windows, there are many comms programs. PuTTy is one.

Add RPi to etc/hosts on laptop

Edit your laptop's hosts file and add the IP address of the RPi

• On linux, sudo vi /etc/hosts

• On Windoze: run Notepad as administrator and edit C:\Windows\system32\drivers\etc\hosts. (Click all file types on the dialog)

  • # Example

  • 192.168.15.102 rpi4 # RPi 4

Install ssh client on laptop

Install an ssh client on the Windows or Linux PC to enable launching ROS programs from the command line. openssh is a good choice. (It looks like Windows 10 might come with an ssh command-line client, so a GUI client may not be necessary.) ssh clients also provide sftp - an ssh-based implementation of ftp, useful for file transfers between laptop and rpi.

• Linux: sudo apt install openssh-client

• Windows (Recommended: alternative 1 - terminal and vscode ssh support): Install openssh from an administrative power shell as described here: https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=powershell and set up key-based login as described here: https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_keymanagement

• Windows (alternative 2 - ssh terminal support - no vscode): Install an ssh client such as PuTTY. Follow these instructions to allow PuTTY to ssh into the RPi without needing to enter a password each time: https://www.techtarget.com/searchsecurity/tutorial/How-to-use-PuTTY-for-SSH-key-based-authentication

Install the remote-ssh extension into vs-code (optional)

If you want to use vs-code to edit files on the RPi, launch vs-code and install the Remote - SSH extension. It will use the openssh keys you installed in the preceding step.

Install a VNC client on laptop

In this segment we install tigervnc-viewer or equivalent on the base Windows or Linux PC in order to perform graphical operations on the RPI. Oddly, configuring networking using the Network Manager seems to be one of the most useful cases, but also ROS utilities can be run directly on the RPi

• Linux: sudo apt install tigervnc-viewer

• Windows, install tigervnc (suggested) from https://sourceforge.net/projects/tigervnc/

Install rpi-imager

In this segment we install rpi-imager to the base Linux or Windows PC in order to load Raspberry Pi OS onto an SD card or SSD. Be sure to get version 1.8.4 or later.

• Linux: sudo apt install rpi-imager. 

• Windows: search for rpi-imager and download & run the .exe

RPi Configuration

In this segment we install the latest Raspberry Pi OS onto an SD card on a Raspberry Pi and configure it for developing ROS software.

The overall approach taken is to run Raspberry Pi OS on the RPi, because it is the latest and best suited to RPi hardware, but ROS programs are run inside a docker container, because ROS isn't supported on Raspberry Pi OS. The ROS docker container uses the host's networking stack, and mounts /dev for hardware access. 

My configuration: user bouchier is the main user account on both linux laptop and the RPi and inside the ROS docker container, and has ability to commit to github from either laptop or rpi4, and to ssh from laptop to rpi4 without needing to enter a password.  Consider doing something similar with your config.

ROS source code is saved in the recommended places on RPi OS and is edited (generally) on the RPi OS filesystem then built and tested and run in the docker container. Build products are stored on the RPi OS filesystem, so as to persist across container instances. 

Containers are (generally) removed after each use, and re-instantiated from the image each time they're started. See the ROS docker page for more details.

The ROS docker containers are configured with the ROS GUI apps, which can be run either on the rpi or on the laptop. Generally, running on the laptop will perform better and may be more convenient because they won't be bound inside a vnc window.

rpi-imager configuration

In this step we connect the boot media (typically SD-card, but could be SSD) to the laptop, run rpi-imager to install a firmware update image or a Raspberry Pi OS image, then reconnect the boot media to the rpi and boot the rpi from it.

1. Get rpi-imager: Load the latest rpi-imager on to your laptop. At least 1.8.4 is needed.

2. Update firmware: Run rpi-imagerInstall the firmware updater onto the SD card, then boot the RPi from the card. It will update the rpi board firmware

3. Select an appropriate Raspberry Pi OS 64-bit: In rpi-imager "Select OS", select 64-bit Raspberry Pi OS. I installed the Bookworm release of Raspberry Pi OS onto an RPi 4. (As of this writing, rpi-imager didn't offer Rpi OS Bookworm for the rpi zero 2 W. The latest 64-bit OS for the hardware is preferred. I installed Bullseye on rpi zero 2W legacy - not Full, not Lite - to the boot media. Selecting the proper OS may require going into "Other images"). 

VERY IMPORTANT: DON'T SKIP THIS STEP

You want your initial user on RPi to be the same as on your Ubuntu-PC. If you don't do this step you'll end up having to configure networking manually, add your username to sudoers, get it synced to github, or you'll forever be user pi and your identity will feel quite mixed up.

4. Configure and install Raspberry Pi OS 64-bit: In the "Use OS customization" pop-up, choose "Edit Settings". Use the new window that opens to configure hostname, initial username, password, and wifi parameters (General tab). In the Services tab, enable ssh and select password or public key authentication. If you use public key authentication, paste the openssh public key from your laptop (e.g. .ssh/id_rsa.pub) into the key field. Save the configuration to get back to the "Use OS customization popup. Select "Yes" to apply OS customization settings.  Press Next to write the SD card.

5. Insert the SD card into the RPi and apply power to boot the RPi.

6. Connect a monitor and keyboard and verify that the RPi booted. 

7. Note the IP address that the RPi was given on the wired and/or wireless network

8. Check that networking is connected. Verify that you can ssh to the RPi from your laptop.

9. Open a terminal to the RPi and run "df -h" and inspect available space in the '/' filesystem. Verify that remaining space on the SD card is sufficient. 

Note: I found RPi didn't seem to boot the first time until I connected a monitor (but I may not have waited long enough).

RPi firmware configuration

The purpose of these steps is to provide a serial console interface which can be used to configure RPi networking when the robot is placed in a new wifi environment.

This section describes settings in the boot config files. The only change required is to modify config.txt and cmdline.txt.

1. Precondition: Booted the RPi with an external monitor and Keyboard/Mouse

2. Open a terminal in the GUI or use the command line and edit /boot/config.txt using vi or nano.  Add the following lines which causes the OS to present a login on the serial console, and to print boot messages to the serial console.

1. Add the following lines to file /boot/config.txt to enable serial (and potentially console) on UART 2, 3, 4 and 5 (/dev/ttyAMA2-5):

dtoverlay=uart2

dtoverlay=uart3

dtoverlay=uart4

dtoverlay=uart5

3. Edit /boot/cmdline.txt and remove the boot options "quiet" and "plymouth.ignore-serial-consoles". This causes the OS to output boot messages to the serial console

Test serial console and networking

1. Connect a USB serial cable to the RPi Serial console connection on the header per the diagram below. Connect ground to pin 14. Connect RXD on the serial cable to pin 8 on the header. Connect TXD of the serial cable to pin 10 of the header. 

2. On linux, add your username to the dialout group (so you can use the serial port) with sudo usermod –a –G dialout <your_username>

3. On the laptop, run a serial comms program such as PuTTY (on windows) or miniterm or minicom on Linux and connect to /dev/ttyUSB0 (linux) or a COM port (Windows) at 115200 baud to connect from PC to rpi via USB serial. Reboot from the monitor/keyboard and verify you see boot messages come out on the miniterm terminal. Verify you can log in. The USB-serial connection is your back-door into the system in case you're in the field and can't access the rpi through the network.

Raspberry Pi Header showing TXD and RXD and Ground pins

1. The miniterm command uses .bash.aliases: alias miniterm='python -m serial.tools.miniterm --eol LF'. But cursor movement commands don't work: backspace, vi is crap.

2. Use the monitor/keyboard to connect to Wifi. Check you know the IP the rpi was given (use ifconfig), and ssh to it from your laptop to verify the ability to connecto over the network.

3. Use the keyboard/monitor to shut down the board, or use the poweroff command. Disconnect keyboard/monitor, and reapply power. Verify you can ssh to the board after it boots.

Raspberry Pi OS Configuration

These are the steps to configure Raspberry Pi OS on the RPi once it has been installed and is bootable. 

1. If needed, change /etc/hostname to set your hostname. (Would be needed if you didn't configure the image correctly in rpi-imager boot configuration)

2. If needed, edit /etc/hosts to make your hostname a name for 127.0.1.1. (Would be needed if you didn't configure the image correctly in rpi-imager boot configuration)

3. On your laptop: add the hostname of the rpi and it's IP to the laptop's /etc/hosts file

4. Ensure ping www.google.com works from the RPi

5. Ensure you can ping your laptop from the RPi

6. Update and upgrade list of packages. sudo apt update; sudo apt upgrade

7. On laptop, create the .ssh/config file that causes ssh rpi4 to connect to host rpi4 as  your username (bouchier in the example). Put the following lines in .ssh/config:

1. Linux: From laptop, install your user's ssh public key to allow laptop to log into RPi without a password: ssh-copy-id username@<rpi-name>. You will be asked for your RPi password. Then ssh-copy-id will install your public key into ~/.ssh, which removes the need for a password to log into the RPi

2. Windows: PuTTY: create a key per web instructions

3. Optional (important for rpi zero 2W): Increase swap size using these instructions: https://pimylifeup.com/raspberry-pi-swap-file/

Package Installation

This section describes installation of packages needed to make ROS on RPi work as desired. Note: some of these steps are no longer necessary if using the 1.8 version of rpi-imager; it does a lot more to pre-configure the system.

Install VNC on RPi

VNC was chosen for graphical use because generally the robot's RPi would run headless, but remote desktop capability is sometimes valuable. 

Observations: the current version of RPi OS doesn't support the RealVNC server which ships with it, owing to Raspberry Pi OS using Wayland and RealVNC using X11. Tigervnc is the recommended alternative

1. On the RPi install tigervnc-standalone-server: sudo apt install tigervnc-standalone-server

2. Edit /etc/tigervnc/vncserver-config-mandatory and search for localhost. In the localhost section, uncomment $localhost="no" so as to allow remote connections. 

3. Run tigervncpasswd and set a password. Do not enter a view-only password.

Test vnc

4. On RPi, run tigervncserver: tigervncserver

5. On laptop, if you run Windows, install and run the tigervnc app and verify you can get the RPi virtual desktop

6. On laptop, if your run Linux, install tigervnc-viewer then run it with: xtigervncviewer -SecurityTypes VncAuth,TLSVnc <hostname>:1 

7. Close the vnc window on the laptop. Kill the vnc session on the rpi with (Note: space betweek -kill and :1) tigervncserver -kill :1 

miniterm for linux (optional)

Miniterm is a lightweight python serial comms app. It is useful for talking to the robot microcontroller. Installing it can be delayed. Configure python for miniterm, (serial port access from python, etc). sudo apt install python-is-python3; sudo apt install python3-pip; Add the following to .bash_aliases: alias miniterm='python -m serial.tools.miniterm --eol LF'

Make ROS source directory in the RPi home

mkdir -p ros2_ws/src

Configure Laptop to run ROS2 locally

It is (in Paul's opinion) beneficial to run ROS in a docker on the laptop, because you have so much more power there, and because ROS2 windows can be intermixed with your other desktop windows, rather than being locked into a VNC or a VM desktop. For example, exploring data in interactive GUIs should be much snappier, and you can run simulations. But this is a "soft benefit", not a hard requirement. In this segment we either use wsl or we configure a virtual machine on the laptop or we install Ubuntu 22.04 on a PC, in order to run ROS2 in a docker container.

• If you're a Windows user, Option 1 below is your easiest path to getting Ubuntu 22.04 with ROS2 installed. Warning: as of this writing: Option 1 cannot connect to ROS2 on RPi

• If you're on a Mac, or for some other reason you can't use option 1, you can run Ubuntu 22.04 in a Virtualbox VM and install ROS2 and other programs manually

• If you have a dual-boot or other PC that you installed Ubuntu 22.04 on, you can install ROS2 and other programs manually.

Option 1 (More Preferred for Windows Users: Enable WSL2 on Windows and download a preconfigured VM

1. You must have Admin rights on Windows to do these steps. The instructions for enabling wsl below require running a command shell or power shell as Administrator.

2. Install the Windows terminal from the microsoft store

3. Enable wsl using these instructions: https://learn.microsoft.com/en-us/windows/wsl/install. Note: this will install Ubuntu, but we won't use what it installed. You may need to use the manual install process if it fails.

4. Download the Ubuntu.22.04.ros2.tar file from here: https://drive.google.com/file/d/10LHJ2-Pnl8rTC7RdhYBfWae3hyPfsBo7/view?usp=drive_link

5. Import the image you just downloaded which has ros2 installed by cd to the download directory and running the wsl --import command of the form:

wsl --import <distro_name> <install_location> <tar_file_name> [Options]

For example:

wsl --import Ubuntu-ROS2 C:\Users\dprg\Downloads\Pauls_ros2_distro Ubuntu22.04.ros2.tar

Test the ros2 VM

1.  Start wsl running the image you just imported. (My powershell terminal has a dropdown next to the + (add tab) that lets me select Ubuntu 22.04 and it launches into the WSL VM shell.

2. Verify your linux prompt in wsl is: ros2_x86_linux:~$

3. Start the ros2 talker program: ros2 run demo_nodes_cpp talker

4. Open a new wsl terminal, start the ros2 listener program: ros2 run demo_nodes_py listener

5. Open a new wsl terminal, run: rqt

6. In the rqt window, under Plugins, select topics -> topic monitor. You should get a listing of ros2 topics, and if you check the chatter topic and expand it, you should see the messages going by.

Option 2: Install VirtualBox and Install Ubuntu 22.04 on laptop

This step is recommended if you're not running Linux on your laptop - it enables you to run ROS2 with laptop performance.

If you have some other way of getting Ubuntu 22.04 to run on your laptop (e.g. a different VM) you can use that. Or you can run the tutorials on your RPi.

• Download VirtualBox from here: https://www.virtualbox.org/wiki/Downloads and install VirtualBox

• Download the iso for Ubuntu 22.04 from here: https://ubuntu.com/download/desktop

• Make a new VM and install Ubuntu 22.04 into it

If you need to install VirtualBox on Ubuntu, this page gives instructions: https://ubuntu.com/tutorials/how-to-run-ubuntu-desktop-on-a-virtual-machine-using-virtualbox#1-overview

Configure Ubuntu 22.04 in the VM

• Start the VM to boot Ubuntu 22.04

• Login as the user you configured in VirtualBox, with the configured password

• When you have the desktop, launch a terminal from the "dots" icon

• Right click the terminal on the taskbar and add it to favorites

• Add yourself to the sudo group. If you used VirtualBox7 unattended install, run "su -" and give your password and you will become root. As root, run "usermod -a -G sudo <your username>". Log out of Ubuntu and log back in. Run "sudo ls" to check you have sudo. It will ask you for a password. 

• Configure to use sudo without password: run sudo <your_editor> /etc/sudoers. Edit the sudo group line as follows:

%sudo ALL=(ALL:ALL) NOPASSWD:ALL

• Remove the Ubuntu screen lock timeout: press the activities button, start typing screen lock, select the screen lock settings app, and turn off screen lock

• Be sure to enable bidirectional copy/paste in the shared clipboard between VM and host under "Devices->Shared clipboard"

• Add RPi to /etc/hosts in the VM's Ubuntu using the instructions above

• Install git: "sudo apt install git"

Install ros2 and the extras in the Ubuntu install