Single board computer projects

ROS2 on the JPL NASA Open Source Robot (OSR)

last updated: 2024-09-02

Quick links

Intro

Here I gather infos on the update of our JPL NASA OSR. On github we find two repos. One for the hardware and one for the software. Our Rover was build in 2018/2019 and 2019/2020 by students. The software did not work (ROS1). In 2021 we changed the PCB because of many broken wires in the old OSR.

The robot had many changes in the last 3 years. In the hardware git we find an older revF branch, but it is easier to look at the Tags. Our updated rover model is v3.0.0. In the software an older branch melodic-devel an a branch in between called v2-humble.

We will use a Raspberry 3B+ or a Raspberry 4 with Ubuntu 22.04 and ROS2 humble.

For more information about ROS2: https://www.weigu.lu/sb-computer/ros2/index.html

Hardware

Motors

We have 5 RoboClaw 2x7A Dual Channel Brushed DC Motor Controller to control the 10 motors.

All RoboClaw controller are connected directly to the RxD/TxD serial pins of the Raspi RxD is pulled high to 5V!

Datasheet:

Simple Serial

In simple serial mode RoboClaw expects TTL level RS-232 serial data to control direction and speed of each motor.Simple serial is typically used to control RoboClaw from a microcontroller or PC. If using a PC, a MAX232 or an equivalent level converter circuit must be used since RoboClaw only works with TTL level inputs. Simple serial includes a slave select mode which allows multiple RoboClaws to be controlled from a signal RS-232 port (PC or microcontroller). Simple serial is a one way format, RoboClaw can only receive data. Encoders are not supported in Simple Serial mode.

Packet Serial

In packet serial mode RoboClaw expects TTL level RS-232 serial data to control direction and speed of each motor. Packet serial is typically used to control RoboClaw from a microcontroller or PC. If using a PC a MAX232 or an equivalent level converter circuit must be used since RoboClaw only works with TTL level input. In packet serial mode each RoboClaw is assigned a unique address. There are 8 addresses available. This means up to 8 RoboClaws can be on the same serial port. Encoders are supported in Packet Serial mode, refer to the RoboClaw user manual for setup instructions.

Control board

We use the version V1.0 in the revF, For assembly and schematic: (Interesting links).

Power and data signal distribution for the rover is done by the Control board PCB (our first version required you to run each of these wires by hand). The board takes in battery power and distributes it to to each of the voltage regulators and motor controllers. It also takes in encoders from the motors and distributes them to the motor controllers. It also provides serial UART communication between the RPi and the Motor controllers and with the LED matrix.

In the schematic we see, that the serial communication is done by connecting all the RX/TX lines from the RoboClaws together

Serial communication

Ubuntu 22.04, Raspi 3B+ and Raspi 4

The NASA robot communicates through the native serial port (ttyS0) with the Raspberry Pi (3B+ or 4). When Bluetooth was added to these newer Raspis, the hardware serial port (ttyAMA0) was taken away from the GPIO header and replaced by a “miniUART” (partly software and a bit flaky).

device connected to UART maps to
/dev/ttyAMA0 Bluetooth PL011 hardware UART (UART0) /dev/serial1
/dev/ttyS0 GPIO serial port BCM14 and BCM15 miniUART (UART1) /dev/serial0

To enable the serial port on Ubuntu 22.04 we have to do the following:

First we enable the UART by adding the following line to /boot/firmware/config.txt

    enable_uart=1

Then we add the user to the tty and dialout groups:

    sudo adduser $USER tty
    sudo adduser $USER dialout

Next we make symlinks serial0 and serial1, pointing to the default device names and grant read/write permissions for the devices. This is done in an udev rule. Create a file with nano (Shift+F4), add the following text and save it with the following name 51-ubuntu_serial.rules (Ctrl+o, Ctrl+x).

    KERNEL=="ttyS0", SYMLINK+="serial0" GROUP="tty" MODE="0660"
    KERNEL=="ttyAMA0", SYMLINK+="serial1" GROUP="tty" MODE="0660"

I'm not sure if the two following steps are necessary, but surely they don't hurt:

We remove the serial console from the system by deleting the following text from the line in /boot/firmware/cmdline.txt

    console = tty1

We disable serial-getty@ttyS0.service because it has some level of control over serial devices and it can create weird errors:

    sudo systemctl stop serial-getty@ttyS0.service
    sudo systemctl disable serial-getty@ttyS0.service
    sudo systemctl mask serial-getty@ttyS0.service

Finally, we reboot:

    sudo reboot

To test we connect the Raspi with a computer (USB-Serial adapter, 3V!, don't connect the red wire, cross RxD, TxD)

Raspi Serial

Than we can use minicom on the Raspi (and PC) to test the serial connection with the miniUART.

    sudo apt install minicom
    minicom -b 115200 -D /dev/serial0

Switching to hardware serial

As stated if miniUART (serial0) is not stable enough you can switch to hardware UART serial1, but you loose bluetooth.

To switch the hardware UART back to the GPIO pins we disable bluetooth by adding the following line to /boot/firmware/config.txt and reboot:

    dtoverlay=disable-bt
    sudo reboot
    minicom -b 115200 -D /dev/serial1

Setting up ROS2

The info can be found in the rpi.md file!

Setting up ROS environment and building the rover code

Setup ROS build environment

Creating the colcon workspace and sourcing the new environment:

    mkdir -p ~/osr_ws/src && cd ~/myros2_ws
    source /opt/ros/${ROS_DISTRO}/setup.bash
Clone and build the rover code
    sudo apt install git
    cd ~/osr_ws/src
    git clone https://github.com/nasa-jpl/osr-rover-code.git
    cd osr-rover-code
    git fetch origin
    git checkout v2-humble

Now we will install the dependencies using rosdep

    sudo apt install python3-rosdep
    cd ~/osr_ws
    sudo rosdep init
    rosdep update
    rosdep install --from-paths src --ignore-src --rosdistro=humble
    sudo apt install python3-pip
    pip3 install adafruit-circuitpython-servokit 

If we try now to build the package we get the following errors: Usage of dash-separated 'script-dir' will not be supported in future versions. Please use the underscore name 'script_dir' instead. So we correct this with nano:

    cd ~/osr_ws/src/osr-rover-code/ROS/osr_control
    nano setup.cfg

Replace the two dashes with underscores.

The next error: easy_install command is deprecated. Use build and pip and other standards-based tools We need to downgrade our package setuptools to the last version last version that works with ROS2 python packages without any warnings:

pip install setuptools==58.2.0

    pip install setuptools==58.2.0 
    cd ~/osr_ws
    colcon build --symlink-install # build the ROS packages
    source install/setup.bash # add the generated files to the path

We have to manually create the two following YAML-files:

    cd ~/osr_ws/src/osr-rover-code/ROS/osr_bringup/config
    touch osr_params_mod.yaml roboclaw_params_mod.yaml

These files will contain changes to the default values. More info in rover_bringup.md.

Automate sourcing:

The following lines add the source lines to ~/.bashrc which is executed every time a new terminal is opened (also ssh).

    cd ~
    echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc 
    echo "source ~/osr_ws/install/setup.bash" >> ~/.bashrc
    source ~/.bashrc

This adds the source lines to ~/.bashrc, which runs whenever a new shell is opened on the RPi - by logging in via ssh, for example. So, from now on, when you log into the RPi your new command line environment will have the appropriate configuration for ROS and the rover code.

First let's check the bash scripts to understand what's going on:

launch_osr.sh

    #!/bin/bash
    # exit on error, and output executed commands to stdout
    set -ex

    source osr_paths.sh
    launch_dir=$OSR_CODE_DIR/ROS/osr_bringup/launch

    bash -c ". /opt/ros/humble/setup.bash"
    bash -c ". /home/$USER/osr_ws/install/setup.sh"

    # execute the custom mod launch file if it's available
    if [ -e "$launch_dir/osr_mod_launch.py" ]; then
        echo "Launching osr_mod_launch.py"
        bash -i -c "ros2 launch osr_bringup osr_mod_launch.py"
    # otherwise go with the default
    else
        echo "Launching osr.launch"
        bash -i -c "ros2 launch osr_bringup osr_launch.py"
    fi

osr_paths.sh

    export OSR_CODE_DIR=$HOME/osr_ws/src/osr-rover-code

Interesting links