last updated: 2024-09-02
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
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.
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
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)
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
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
The info can be found in the rpi.md file!
Creating the colcon workspace and sourcing the new environment:
mkdir -p ~/osr_ws/src && cd ~/myros2_ws
source /opt/ros/${ROS_DISTRO}/setup.bash
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
.
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
Control Board PCB schematic: https://github.com/nasa-jpl/open-source-rover/blob/revF/electrical/schematics/Control%20Board.pdf
RoboClaw data sheet: https://downloads.basicmicro.com/docs/roboclaw_datasheet_2x7A.pdf
https://spellfoundry.com/2016/05/29/configuring-gpio-serial-port-raspbian-jessie-including-pi-3-4/