Single board computer projects

ROS2 on the JPL NASA Open Source Robot (OSR)

last updated: 2024-10-01

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_basics/index.html

Hardware

Motors and RoboClaw

We have 5 RoboClaw 2x7A Dual Channel Brushed DC Motor Controller to control the 10 gearmotors. All the motors are from Pololu (25D metal gearmotors). The are brushed, need 12 V and are low power (LP). All the motors have a gear ratio of 172:1 that gives us 5600/172 = 33 rpm. With our

The 6 Pololu drive motors need 12V. Thehave

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

1/8 inch, 10 Bit Analog, Sleeve Bushing (N) 10-bit PWM output - 1,024 positions per revolution, 1 kHz Miniature Absolute Magnetic Shaft Encoder

Outer Diameter: 152mm (6")

old (12 V 31 RPM, 100 mA 13 kg⋅cm (180 oz⋅in), 1.1 A 172:1 Metal Gearmotor 25Dx68L mm LP 12V with 48 CPR Encoder (No End Cap))

https://www.pololu.com/product/4888 172:1 Metal Gearmotor 25Dx71L mm LP 12V with 48 CPR Encoder 12 V 33 RPM, 60 mA 13 kg⋅cm (180 oz⋅in), 0.9 A

https://www.pololu.com/product/3232 Corner 172:1 Metal Gearmotor 25Dx56L mm MP 12V 12 V 46 RPM, 80 mA 18 kg⋅cm (250 oz⋅in), 1.8 A

Connections drive motors to the RoboClaw:

Motor pin nr wire color RoboClaw pin
1 red motor power +
2 black motor power -
3 green encoder power GND
4 blue encoder power +5V
5 yellow encoder out A
6 white encoder out B

Serial connection RoboClaw to Raspberry Pi

Raspberry pin nr wire color RoboClaw pin direction
8, GPIO14, TxD green S1 RxD
10, GPIO15, RxD yellow S2 TxD

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

Enabling serial0 (ttyS0, header)

Raspi 4 with Pi OS (64 bit, release 2025-10-01)

The NASA robot communicates through the native serial port (ttyS0) with the Raspberry Pi 4. When Bluetooth was added to the 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

First we enable the UART. We can do this in the GUI, or with the command sudo raspi-config in the shell (3 Interface Options, I6 Serial Port). Let's do it in the shell.

The question "Would you like a login shell to be accessible over serial?" is answered with No, and the second question "Would you like the serial port hardware to be enabled?" is answered with Yes.

The first action removes the text console=serial0,115200 from the text line in /boot/firmware/cmdline.txt, and the second action adds the line enable_uart=1 to the file /boot/firmware/config.txt.

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

Then we add the user to the tty group and reboot:

    sudo adduser $USER tty
    sudo reboot

Test if everything is ok with:

    ls -l /dev/serial*

We should now see something like this:

    lrwxrwxrwx 1 root root 5 Oct  4 07:11 /dev/serial0 -> ttyS0

Switching to hardware serial

We would like to use hardware serial for the motors and miniUART for bluetoot. This can be done by adding a line to the config file:

    sudo nano /boot/firmware/config.txt

Add to the end:

    dtoverlay=miniuart-bt

Save (Ctrl+s) and exit the file (Ctrl+x).

    sudo reboot
    ls -l /dev/serial*

The output now shows that the hardware serial is connected to serial0!

   lrwxrwxrwx 1 root root 7 Oct  4 07:29 /dev/serial0 -> ttyAMA0

Testing serial0

If the Raspi is not already in the rover we can do this by connecting the header pins 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

If the Raspi is already connected with the roboclaws we can use this python test program: https://github.com/nasa-jpl/osr-rover-code/blob/v2-humble/scripts/roboclawtest.py.

Run the script with:

python roboclawtest.py 128

The result should be something like this:

Connected to /dev/serial0.
(1, 'USB Roboclaw 2x7a v4.2.8\n')
(1, 0, 128)

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