From c392ff6c3a2820394c8d17fdf87af2ef2e183380 Mon Sep 17 00:00:00 2001 From: Kevin Nickels Date: Fri, 7 Nov 2025 10:47:14 -0600 Subject: [PATCH 1/7] pi5 serial details added --- setup/rpi.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/setup/rpi.md b/setup/rpi.md index fa8e604..4e331e6 100644 --- a/setup/rpi.md +++ b/setup/rpi.md @@ -143,6 +143,14 @@ Next, we'll add udev rules to add a symbolic link (symlink) to the serial and i2 sudo cp ~/osr_ws/src/osr-rover-code/config/* /etc/udev/rules.d/ sudo udevadm control --reload-rules && sudo udevadm trigger ``` +### If using Pi 5, disable the bluetooth serial +If you are using a Raspberry Pi 5, add the following lines to `/boot/firmware/config.txt`: +``` + enable_uart=1 + dtoverlay=disable-bt + dtoverlay=uart0 +``` +This will connect /dev/ttyS0 (and /dev/serial0) to the debug UART, and more importantly, connect /dev/ttyAMA0 (and /dev/serial1) to the hardware UART on GPIO 14/15 that the roboclaws are using. ### Add user to system groups From e24b8921511d94ed179e9d3e6867d20533c9304a Mon Sep 17 00:00:00 2001 From: Kevin Nickels Date: Fri, 7 Nov 2025 10:48:10 -0600 Subject: [PATCH 2/7] Update pi5 introduction --- setup/rpi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup/rpi.md b/setup/rpi.md index 4e331e6..991989e 100644 --- a/setup/rpi.md +++ b/setup/rpi.md @@ -2,7 +2,7 @@ In this section, we’ll go over setting up the Raspberry Pi (RPi) and setting up all the code that will run the rover. Our rover uses ROS (Robotic Operating System); we will set these up below. -These instructions should work for both the RPi 3 and 4. You are free to use other versions of RPi, ROS, or OS, but setting these up is not covered here and it is not guaranteed that those will work. +These instructions should work for RPi 3, 4, and 5. You are free to use other versions of RPi, ROS, or OS, but setting these up is not covered here and it is not guaranteed that those will work. ## Installing an Operating System From 1d0c0116aecf30dd8a229335b3800e0e2cceb4bc Mon Sep 17 00:00:00 2001 From: Kevin Nickels Date: Fri, 7 Nov 2025 10:58:25 -0600 Subject: [PATCH 3/7] Update serial port discussion --- setup/rpi.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/setup/rpi.md b/setup/rpi.md index 991989e..e1a76ed 100644 --- a/setup/rpi.md +++ b/setup/rpi.md @@ -150,7 +150,7 @@ If you are using a Raspberry Pi 5, add the following lines to `/boot/firmware/co dtoverlay=disable-bt dtoverlay=uart0 ``` -This will connect /dev/ttyS0 (and /dev/serial0) to the debug UART, and more importantly, connect /dev/ttyAMA0 (and /dev/serial1) to the hardware UART on GPIO 14/15 that the roboclaws are using. +This will connect `/dev/ttyS0` (and `/dev/serial0`) to the debug UART, and more importantly, connect `/dev/ttyAMA0` (and `/dev/serial1`) to the hardware UART on GPIO 14/15 that the roboclaws are using. ### Add user to system groups @@ -173,7 +173,7 @@ Log back in and in a terminal, verify that the serial devices are present: ls -l /dev/serial* ``` -Should at least show a line that contains `/dev/serial0 -> ttyS0`. This is the main serial device used to send information to the Roboclaws over UART / GPIO pins. If you see `/dev/serial1 -> ttyAMA0`, that is a less powerful software-defined serial device typically used for bluetooth. This varies between Raspberry Pi versions. +should at least show a line that contains `/dev/serial0 -> ttyS0` on a Pi3 or Pi4, and a line that contains `/dev/serial1 -> ttyAMA0` ona Pi5. This is the main serial device used to send information to the Roboclaws over UART / GPIO pins. The opposite (`ttyAMA0` on Pi3/4, and `ttyS0` on Pi5 is dedicated for bluetooth. ## Testing serial comm with the Roboclaw motors controllers From a46aa0da88fedbab76d7342b8ef7ae5fe4b16807 Mon Sep 17 00:00:00 2001 From: Kevin Nickels Date: Fri, 7 Nov 2025 10:59:10 -0600 Subject: [PATCH 4/7] update stale URL for calibration --- setup/rpi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup/rpi.md b/setup/rpi.md index e1a76ed..ce193b6 100644 --- a/setup/rpi.md +++ b/setup/rpi.md @@ -201,6 +201,6 @@ The version number may be a later version. If all three work, congratulations! Y If the script seems to hang, or returns only zeros inside the parantheses (0,0), then you have a problem communicating with the given roboclaw for that address. Some troubleshooting steps in this cases: - Make sure you followed the instructions in the [#Setting up serial communication] section above, and the serial devices are configured correctly on the RPi. -- Also make sure you went through the calibration instructions from the [main repo](https://github.com/nasa-jpl/open-source-rover/blob/master/Electrical/Calibration.pdf) and set the proper address, serial comm baud rate, and "Enable Multi-Unit Mode" option for every roboclaw controller (if multi-unit mode isn't enabled on every controller, there will be serial bus contention.). If you update anything on a controller, you'll need to fully power cycle it by turning the rover off. +- Also make sure you went through the calibration instructions from the [main repo](https://github.com/nasa-jpl/open-source-rover/tree/master/electrical/pcb#61-roboclaw-testing-and-verification) and set the proper address, serial comm baud rate, and "Enable Multi-Unit Mode" option for every roboclaw controller (if multi-unit mode isn't enabled on every controller, there will be serial bus contention.). If you update anything on a controller, you'll need to fully power cycle it by turning the rover off. - If you're still having trouble after the above steps, try unplugging every motor controller except for one, and debug exclusively with that one. Reboot the Raspberry Pi if you haven't already. - If that still doesn't work, please ask on the troubleshooting channel on our Slack group. Include as much relevant information as possible so we can help you find the issue as fast as possible. From 409eda20b9c5e8213f33681ac4557dbebcfbc53e Mon Sep 17 00:00:00 2001 From: Kevin Nickels Date: Fri, 7 Nov 2025 16:40:20 -0600 Subject: [PATCH 5/7] cleanup pi3/4/5 serial port info, add back in pointer to serial_config_info.md --- setup/rpi.md | 13 +++++++------ setup/serial_config_info.md | 37 ++++++++++++++++++++++++++++--------- 2 files changed, 35 insertions(+), 15 deletions(-) diff --git a/setup/rpi.md b/setup/rpi.md index ce193b6..4ea9262 100644 --- a/setup/rpi.md +++ b/setup/rpi.md @@ -143,14 +143,15 @@ Next, we'll add udev rules to add a symbolic link (symlink) to the serial and i2 sudo cp ~/osr_ws/src/osr-rover-code/config/* /etc/udev/rules.d/ sudo udevadm control --reload-rules && sudo udevadm trigger ``` -### If using Pi 5, disable the bluetooth serial -If you are using a Raspberry Pi 5, add the following lines to `/boot/firmware/config.txt`: + +### Disable the bluetooth serial +Add the following lines to `/boot/firmware/config.txt`: ``` enable_uart=1 dtoverlay=disable-bt - dtoverlay=uart0 + dtoverlay=uart0 # (only on RPi5) ``` -This will connect `/dev/ttyS0` (and `/dev/serial0`) to the debug UART, and more importantly, connect `/dev/ttyAMA0` (and `/dev/serial1`) to the hardware UART on GPIO 14/15 that the roboclaws are using. +This will connect `/dev/ttyAMA0` (and `/dev/serial1`) to the hardware UART on GPIO 14/15 that the roboclaws are using. ### Add user to system groups @@ -170,10 +171,10 @@ You might have to create the dialout group if it doesn't already exist with `gro Log back in and in a terminal, verify that the serial devices are present: ```bash -ls -l /dev/serial* +ls -l /dev/ttyAMA0 ``` -should at least show a line that contains `/dev/serial0 -> ttyS0` on a Pi3 or Pi4, and a line that contains `/dev/serial1 -> ttyAMA0` ona Pi5. This is the main serial device used to send information to the Roboclaws over UART / GPIO pins. The opposite (`ttyAMA0` on Pi3/4, and `ttyS0` on Pi5 is dedicated for bluetooth. +should at least show a line that contains `/dev/ttyAMA0`. This is the main serial device used to send information to the Roboclaws over UART / GPIO pins. More detail on serial setup can be found in [serial_config_info.md](serial_config_info.md) ## Testing serial comm with the Roboclaw motors controllers diff --git a/setup/serial_config_info.md b/setup/serial_config_info.md index 1d5bee6..7b37b49 100644 --- a/setup/serial_config_info.md +++ b/setup/serial_config_info.md @@ -1,19 +1,38 @@ -Configuration can be a bit of a pain for using the serial port on the raspberry pi with ubuntu. You can use either for communications, but if you've followed -the instructions, you most likely will be using `/dev/serial1`. +Configuration can be a bit of a pain for using the serial port on the raspberry pi with ubuntu. You can use either for communications, but if you've followed the instructions, you most likely will be using `/dev/serial1`. + +# On the Pi3/Pi4 Difference between `/dev/serial0` and `/dev/serial1`: -- `/dev/serial0` maps to `/dev/ttyS0`, which handles serial communication through a software "mini-UART" implementation. -- `/dev/serial1` maps to `/dev/ttyAMA0`, which handles serial communication through a hardware PL011 UART implementation. +- `/dev/serial0` maps to `/dev/ttyS0`, which handles serial communication through a software "mini-UART" implementation. Connected to GPIO 14/15 by default. If `dtoverlay=disable-bt` is set, this is not connected. +- The mini-UART (UART1) has a reduced set of features +- `/dev/serial1` maps to `/dev/ttyAMA0`, which handles serial communication through a hardware PL011 UART implementation. Connected to Bluetooth by default. If `dtoverlay=disable-bt` is set, connected to GPIO 14/15. - The PL011 UART (UART0) is a full-featured universal asynchronous receiver/transmitter for serial communication -- the mini-UART (UART1) has a reduced set of features -- On the RPi4, the PL011 UART is also connected to the bluetooth controller. - + +If you are using a Raspberry Pi 3/4, add the following lines to `/boot/firmware/config.txt`: +``` + enable_uart=1 + dtoverlay=disable-bt +``` +This will disconnect `/dev/ttyS0` (and `/dev/serial0`) to the debug UART, and more importantly, connect `/dev/ttyAMA0` (and `/dev/serial1`) to the hardware UART on GPIO 14/15 that the roboclaws are using. + See [this discussion](https://www.engineersgarage.com/microcontroller-projects/articles-raspberry-pi-serial-communication-uart-protocol-serial-linux-devices/) and [this discussion](https://spellfoundry.com/2016/05/29/configuring-gpio-serial-port-raspbian-jessie-including-pi-3-4/) for more information. -- when using `/dev/serial0` for serial communications instead of `/dev/serial1`, you're using a less capable communications device. For whatever reason, this worked under ubuntu 18.04, but but seems to have a lot of trouble under ubuntu 20.04. So it's best to use `/dev/serial1`. -- However, `/dev/serial1` is also connected to the bluetooth controller, so we need to disable bluetooth. This is why we use the `dtoverlay=disable-bt` overlay in config.txt (see [rpi.md](rpi.md)) - We also need to remove `console=serial0,115200` from cmdline.txt, because it also seems to prevent the operation of `serial1` for serial comms. To find out which one you should be using, run [the test script](../scripts/roboclawtest.py). If you want to use `serial0` instead of `serial1`, you must change the default in the [config yaml](../osr_bringup/config/roboclaw_params.yaml). + +# On the Pi5 + +Difference between `/dev/serial0` and `/dev/serial1`: +- `/dev/serial0` maps to `/dev/ttyS0`, which handles serial communication through a hardware PL011 UART implementation. Connected to GPIO 14/15 by default. If `dtoverlay=disable-bt` is set, this is routed to the debug UART between HDMI0 and HDMI1. +- `/dev/serial1` maps to `/dev/ttyAMA0`, which handles serial communication through a hardware PL011 UART implementation. Connected to Bluetooth by default. If `dtoverlay=disable-bt` is set, connected to GPIO 14/15. + +If you are using a Raspberry Pi 5, add the following lines to `/boot/firmware/config.txt`: +``` + enable_uart=1 + dtoverlay=disable-bt + dtoverlay=uart0 +``` +This will connect `/dev/ttyS0` (and `/dev/serial0`) to the debug UART, and more importantly, connect `/dev/ttyAMA0` (and `/dev/serial1`) to the hardware UART on GPIO 14/15 that the roboclaws are using. From c7714f3b9b45c07c27ace5bf26a60744ffdc996d Mon Sep 17 00:00:00 2001 From: Kevin Nickels Date: Fri, 7 Nov 2025 16:48:25 -0600 Subject: [PATCH 6/7] checking wording --- setup/serial_config_info.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/setup/serial_config_info.md b/setup/serial_config_info.md index 7b37b49..b90f070 100644 --- a/setup/serial_config_info.md +++ b/setup/serial_config_info.md @@ -1,4 +1,4 @@ -Configuration can be a bit of a pain for using the serial port on the raspberry pi with ubuntu. You can use either for communications, but if you've followed the instructions, you most likely will be using `/dev/serial1`. +Configuration can be a bit of a pain for using the serial port on the raspberry pi with ubuntu. # On the Pi3/Pi4 @@ -13,8 +13,7 @@ If you are using a Raspberry Pi 3/4, add the following lines to `/boot/firmware/ enable_uart=1 dtoverlay=disable-bt ``` -This will disconnect `/dev/ttyS0` (and `/dev/serial0`) to the debug UART, and more importantly, connect `/dev/ttyAMA0` (and `/dev/serial1`) to the hardware UART on GPIO 14/15 that the roboclaws are using. - +This will disconnect `/dev/ttyS0` (and `/dev/serial0`) from the mini-UART, and more importantly, connect `/dev/ttyAMA0` (and `/dev/serial1`) to the hardware UART on GPIO 14/15 that the roboclaws are using. See [this discussion](https://www.engineersgarage.com/microcontroller-projects/articles-raspberry-pi-serial-communication-uart-protocol-serial-linux-devices/) and [this discussion](https://spellfoundry.com/2016/05/29/configuring-gpio-serial-port-raspbian-jessie-including-pi-3-4/) for more information. @@ -35,4 +34,4 @@ If you are using a Raspberry Pi 5, add the following lines to `/boot/firmware/co dtoverlay=disable-bt dtoverlay=uart0 ``` -This will connect `/dev/ttyS0` (and `/dev/serial0`) to the debug UART, and more importantly, connect `/dev/ttyAMA0` (and `/dev/serial1`) to the hardware UART on GPIO 14/15 that the roboclaws are using. +This will connect `/dev/ttyS0` (and `/dev/serial0`) to the debug UART port, and more importantly, connect `/dev/ttyAMA0` (and `/dev/serial1`) to the hardware UART on GPIO 14/15 that the roboclaws are using. From 2d4cb54ae95f77c0eda000e3654cb76604cc9069 Mon Sep 17 00:00:00 2001 From: Kevin Nickels Date: Fri, 7 Nov 2025 16:49:54 -0600 Subject: [PATCH 7/7] add back in some discussion on pi3/4 serial --- setup/serial_config_info.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/setup/serial_config_info.md b/setup/serial_config_info.md index b90f070..52760b6 100644 --- a/setup/serial_config_info.md +++ b/setup/serial_config_info.md @@ -17,6 +17,10 @@ This will disconnect `/dev/ttyS0` (and `/dev/serial0`) from the mini-UART, and m See [this discussion](https://www.engineersgarage.com/microcontroller-projects/articles-raspberry-pi-serial-communication-uart-protocol-serial-linux-devices/) and [this discussion](https://spellfoundry.com/2016/05/29/configuring-gpio-serial-port-raspbian-jessie-including-pi-3-4/) for more information. +- when using `/dev/serial0` for serial communications instead of `/dev/serial1`, you're using a less capable communications device. For whatever reason, this worked under ubuntu 18.04, but but seems to have a lot of trouble under ubuntu 20.04. So it's best to use `/dev/serial1`. + +- However, `/dev/serial1` is also connected to the bluetooth controller, so we need to disable bluetooth. + - We also need to remove `console=serial0,115200` from cmdline.txt, because it also seems to prevent the operation of `serial1` for serial comms. To find out which one you should be using, run [the test script](../scripts/roboclawtest.py). If you want to use `serial0` instead of `serial1`, you must change