From 2595422ec221ab444c047aae03cac26a61322d2f Mon Sep 17 00:00:00 2001 From: Joe Foley Date: Mon, 29 Jun 2026 00:09:46 +0000 Subject: [PATCH 01/13] dwc2 needs to match --- gadget.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/gadget.md b/gadget.md index 4468d04..7fcdf04 100644 --- a/gadget.md +++ b/gadget.md @@ -8,6 +8,37 @@ USB-OTG method (Works on Zero, Zero W, and Compute Module) Based upon Adafruit guide: https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget/serial-gadget: +# Raspberry Pi Connect +1. Make sure you have your USB cable plugged into the left port **USB** and not the right port marked **PWR**. +1. Open a connection to the device +1. Become root (the superuser) + `sudo su` +1. Enable the DWC USB peripheral device tree overlay by appending it to the end after the `[all]` category + `echo "dtoverlay=dwc2" >> /boot/firmware/config.txt` +1. We add the required module `dwc2` for loading at startup + `echo "dwc2" >> /etc/modules` +1. Check that we can load the libcomposite module + `modprobe libcomposite` +1. Put a copy of this repository in root's home directory using git + ``` + apt install -y git + git clone https://gitea.cs.ru.is/RU-V207/rover-pi.git + ``` +1. Go to Scripts and test if the `gadget.sh` runs without errors and hopefully a Serial port appers in Device Manager or equivalent + ``` + cd rover-pi/Scripts/ + ./gadget.sh + ``` +1. Install the systemd script + `cp serial-ether-gadget.service /lib/systemd/system/.` +1. Enable the getty (which connects a login terminal to the serial port) + ``` + systemctl enable serial-getty@ttyGS0.service + ``` +1. Reboot and see if the serial port appears + +## Additional hints + Look for the SD card reader on the VM under "Devices > USB" and click on it  Iff you get errors, you may have to shut down the VM and set the USB version to 2.0 or 3.0 The Boot and Root partition should mount in Linux under /media/$USER/boot and /media/$USER/rootfs Navigate to /media/$USER/boot and edit: From b7a327904e8011c1bf8b74fce47c3ddeea7a7739 Mon Sep 17 00:00:00 2001 From: Joe Foley Date: Mon, 29 Jun 2026 00:19:35 +0000 Subject: [PATCH 02/13] format and info on serial terminal --- gadget.md | 74 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 42 insertions(+), 32 deletions(-) diff --git a/gadget.md b/gadget.md index 7fcdf04..b5d3ef8 100644 --- a/gadget.md +++ b/gadget.md @@ -9,16 +9,24 @@ USB-OTG method (Works on Zero, Zero W, and Compute Module) Based upon Adafruit guide: https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget/serial-gadget: # Raspberry Pi Connect -1. Make sure you have your USB cable plugged into the left port **USB** and not the right port marked **PWR**. +Make sure you have your USB cable plugged into the left port **USB** and not the right port marked **PWR**. 1. Open a connection to the device 1. Become root (the superuser) - `sudo su` -1. Enable the DWC USB peripheral device tree overlay by appending it to the end after the `[all]` category - `echo "dtoverlay=dwc2" >> /boot/firmware/config.txt` + ``` + sudo su + ``` +1. Enable the DWC version 2 USB peripheral device tree overlay by appending it to the end after the `[all]` category (which is at the end) + ``` + echo "dtoverlay=dwc2" >> /boot/firmware/config.txt + ``` 1. We add the required module `dwc2` for loading at startup - `echo "dwc2" >> /etc/modules` + ``` + echo "dwc2" >> /etc/modules + ``` 1. Check that we can load the libcomposite module - `modprobe libcomposite` + ``` + modprobe libcomposite + ``` 1. Put a copy of this repository in root's home directory using git ``` apt install -y git @@ -37,31 +45,33 @@ Based upon Adafruit guide: https://learn.adafruit.com/turning-your-raspberry-pi- ``` 1. Reboot and see if the serial port appears -## Additional hints +# Connecting to the serial terminal +You will need a serial terminal program (which used to be very very common) in order to communicate over your serial port -Look for the SD card reader on the VM under "Devices > USB" and click on it  Iff you get errors, you may have to shut down the VM and set the USB version to 2.0 or 3.0 -The Boot and Root partition should mount in Linux under /media/$USER/boot and /media/$USER/rootfs -Navigate to /media/$USER/boot and edit: -config.txt: add "dtoverlay=dwc2" at the end -cmdline.txt:  remove "init=/usr/lib/raspi-config/init_resize.sh" and add "modules-load=dwc2,g_serial" to the end.  Make sure everything is on one line! -Eject the card -Boot the pi with a keyboard and monitor attached -Login -sudo systemctl enable serial-getty@ttyGS0.service -sudo systemctl start serial-getty@ttyGS0.service +## Windows +- Putty: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html +- MobaXterm: https://mobaxterm.mobatek.net/ - - -# connecting to the serial terminal -If using a Linux VM, you will need to pass the Pi USB connection there.  This is similar to the procedure for accessing an Arduino. -Start the Linux VM if you haven't already -Menu:  Devices > USB -Look for "Silicon Labs CP210x USB to UART Bridge" and click on it.   -Run "ls -l /dev/ttyU*" to check if port /dev/ttyUSB0 is found.  The Pi will most often be accessible over this port. -The user must be in the dialout group to access it.  Use the Linux command: id  -to check if you are in the group.  If not in the dialout group, use: - sudo usermod -a -G dialout -You will use the screen app in Linux to access the Pi.   You can install it with: - sudo apt install screen -You should now gain access to the Pi with: - sudo screen /dev/ttyUSB0 115200 -Press enter and you will be prompted to log in to the Pi with default credentials. User: pi - PW: raspberry +## Linux +If using a Linux VM, you will need to pass the Pi USB connection there. +This is similar to the procedure for accessing an Arduino. +1. Start the Linux VM if you haven't already +1. Menu: Devices > USB +1. Look for "Silicon Labs CP210x USB to UART Bridge" and click on it. +1. check if port /dev/ttyUSB0 is found. The Pi will most often be accessible over this port. + ``` + ls -l /dev/ttyU* + ``` +1. The user must be in the dialout group to access it. Use the Linux command: `uid` -to check if you are in the group. If not in the dialout group, use: + ``` + sudo usermod -a -G dialout + ``` +1. You will use the GNU `screen` application in Linux to access the Pi. You can install it with: + ``` + sudo apt install screen + ``` +1. You should now gain access to the Pi with: + ``` + ` sudo screen /dev/ttyUSB0 115200 + ``` +1. Press enter and you will be prompted to log in to the Pi with default credentials. User: pi - PW: raspberry From 6a70ef94d1f90e37a3e7167e800ee056dce882a8 Mon Sep 17 00:00:00 2001 From: Joe Foley Date: Mon, 29 Jun 2026 00:22:16 +0000 Subject: [PATCH 03/13] more cleaning up --- gadget.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/gadget.md b/gadget.md index b5d3ef8..ed4702d 100644 --- a/gadget.md +++ b/gadget.md @@ -1,16 +1,13 @@ # Gadget Mode to setup a serial connection over USB Prepare Raspberry Pi OS connection over a microUSB serial cable -Important:  choose either PiUART or OTG.  If you do both, it is possible that neither will work.  Also, you will want to disable the serial console if you are trying to use that serial port for communicating with other devices.  Important reading:  Raspberry PI UART configuration - - -USB-OTG method (Works on Zero, Zero W, and Compute Module) +Important: You will want to disable the serial console on RX/TX if you are trying to use that serial port for communicating with other devices. Based upon Adafruit guide: https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget/serial-gadget: +The author discovered errors in the guide and was able to correct them thanks to this blog https://www.isticktoit.net/?p=1383 -# Raspberry Pi Connect Make sure you have your USB cable plugged into the left port **USB** and not the right port marked **PWR**. -1. Open a connection to the device +1. Open a connection to the device via ssh or Raspberry Pi Connect 1. Become root (the superuser) ``` sudo su From 1eb4e238628c02aaa08cb2228697553e68b83dcf Mon Sep 17 00:00:00 2001 From: Joe Foley Date: Mon, 29 Jun 2026 00:38:48 +0000 Subject: [PATCH 04/13] Official Raspi OTG whitepaper --- gadget.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gadget.md b/gadget.md index ed4702d..76046ac 100644 --- a/gadget.md +++ b/gadget.md @@ -4,7 +4,7 @@ Prepare Raspberry Pi OS connection over a microUSB serial cable Important: You will want to disable the serial console on RX/TX if you are trying to use that serial port for communicating with other devices. Based upon Adafruit guide: https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget/serial-gadget: -The author discovered errors in the guide and was able to correct them thanks to this blog https://www.isticktoit.net/?p=1383 +The author discovered the guide was out of date, consulted the [2025 Raspberry Pi whitepaper on OTG](https://pip-assets.raspberrypi.com/categories/685-app-notes-guides-whitepapers/documents/RP-009276-WP/Using-OTG-mode-on-Raspberry-Pi-SBCs), found additional errors, and was finally able to correct them thanks to this blog https://www.isticktoit.net/?p=1383 Make sure you have your USB cable plugged into the left port **USB** and not the right port marked **PWR**. 1. Open a connection to the device via ssh or Raspberry Pi Connect From 60284fdbd70943f68fe683c354b4fe1eea9cc70d Mon Sep 17 00:00:00 2001 From: Joe Foley Date: Mon, 29 Jun 2026 16:59:58 +0000 Subject: [PATCH 05/13] uninstallation help --- gadget.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/gadget.md b/gadget.md index 76046ac..feb921b 100644 --- a/gadget.md +++ b/gadget.md @@ -36,6 +36,10 @@ Make sure you have your USB cable plugged into the left port **USB** and not the ``` 1. Install the systemd script `cp serial-ether-gadget.service /lib/systemd/system/.` +1. Enable the service + ``` + systemctl enable serial-ether-gadget.service + ``` 1. Enable the getty (which connects a login terminal to the serial port) ``` systemctl enable serial-getty@ttyGS0.service @@ -72,3 +76,30 @@ This is similar to the procedure for accessing an Arduino. ` sudo screen /dev/ttyUSB0 115200 ``` 1. Press enter and you will be prompted to log in to the Pi with default credentials. User: pi - PW: raspberry + +# Disabling the OTG mode to use a keyboard and mouse again + +**WARNING: Untested** +1. Comment out the dwg2 line in `/boot/firmware/config.txt` using a `#` in front of the line + ``` + [all] + #dtoverlay=dwg2 + ``` +1. Comment out the dwg2 line in `/etc/modules` using a `#` in front of the line + ``` + #dwg2 + ``` +1. Disable the gadget service + ``` + systemctl disable serial-ether-gadget.service + ``` +1. Disable the getty + ``` + systemctl disable serial-getty@ttyGS0.service + ``` + +# Connecting over the USB ethernet to ssh into your Pi + +I have not tested this procedure because the serial console and normal network connection is sufficient for me --foley + +https://www.raspberrypi.com/news/usb-gadget-mode-in-raspberry-pi-os-ssh-over-usb/ From 37f5100dac10b0e41a8e66c4d180b27ebc8b63ad Mon Sep 17 00:00:00 2001 From: Joe Foley Date: Tue, 30 Jun 2026 17:57:17 +0000 Subject: [PATCH 06/13] TODO: test Imager manifest modified for otg --- gadget.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/gadget.md b/gadget.md index feb921b..999c8dc 100644 --- a/gadget.md +++ b/gadget.md @@ -103,3 +103,10 @@ This is similar to the procedure for accessing an Arduino. I have not tested this procedure because the serial console and normal network connection is sufficient for me --foley https://www.raspberrypi.com/news/usb-gadget-mode-in-raspberry-pi-os-ssh-over-usb/ + + +# Untested + Here are items that bear investigating but haven't been tested yet + + - [Modify Imager manifest to install otg](https://github.com/raspberrypi/rpi-imager/tree/main/doc/local_json) + From c6f164220966e75691210b347b5e9d18cd9ca3a7 Mon Sep 17 00:00:00 2001 From: Joseph Timothy Foley Date: Thu, 2 Jul 2026 09:33:44 +0000 Subject: [PATCH 07/13] Ignore generated html files --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 25be4a4..3691aad 100644 --- a/.gitignore +++ b/.gitignore @@ -225,3 +225,4 @@ cython_debug/ # PyPI configuration file .pypirc +*.html From f8dac3c07f800b669db05eedcb938923d63d2796 Mon Sep 17 00:00:00 2001 From: Joseph Timothy Foley Date: Thu, 2 Jul 2026 09:33:56 +0000 Subject: [PATCH 08/13] Testing code formatting --- gadget.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/gadget.md b/gadget.md index 999c8dc..d9a893a 100644 --- a/gadget.md +++ b/gadget.md @@ -1,11 +1,16 @@ # Gadget Mode to setup a serial connection over USB Prepare Raspberry Pi OS connection over a microUSB serial cable -Important: You will want to disable the serial console on RX/TX if you are trying to use that serial port for communicating with other devices. - Based upon Adafruit guide: https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget/serial-gadget: The author discovered the guide was out of date, consulted the [2025 Raspberry Pi whitepaper on OTG](https://pip-assets.raspberrypi.com/categories/685-app-notes-guides-whitepapers/documents/RP-009276-WP/Using-OTG-mode-on-Raspberry-Pi-SBCs), found additional errors, and was finally able to correct them thanks to this blog https://www.isticktoit.net/?p=1383 +## Important : +- **Using the Gadget Mode will make the usb port unable to connect to a mouse or keyboard!!!** You will need to disable it make them work again. +- You will want to disable the serial console on RX/TX in `raspi-config` if you are trying to use that serial port for communicating with other devices. + + +## Procedure + Make sure you have your USB cable plugged into the left port **USB** and not the right port marked **PWR**. 1. Open a connection to the device via ssh or Raspberry Pi Connect 1. Become root (the superuser) @@ -13,9 +18,9 @@ Make sure you have your USB cable plugged into the left port **USB** and not the sudo su ``` 1. Enable the DWC version 2 USB peripheral device tree overlay by appending it to the end after the `[all]` category (which is at the end) - ``` - echo "dtoverlay=dwc2" >> /boot/firmware/config.txt - ``` +``` +echo "dtoverlay=dwc2" >> /boot/firmware/config.txt +``` 1. We add the required module `dwc2` for loading at startup ``` echo "dwc2" >> /etc/modules From aebf3aaab8886af2e8978e05610b8085ade0857d Mon Sep 17 00:00:00 2001 From: Joseph Timothy Foley Date: Thu, 2 Jul 2026 09:37:25 +0000 Subject: [PATCH 09/13] Formatted code indentation to match sequence --- gadget.md | 52 +++++++++++++++++++++++++++------------------------- 1 file changed, 27 insertions(+), 25 deletions(-) diff --git a/gadget.md b/gadget.md index d9a893a..3c75f9d 100644 --- a/gadget.md +++ b/gadget.md @@ -14,41 +14,43 @@ The author discovered the guide was out of date, consulted the [2025 Raspberry P Make sure you have your USB cable plugged into the left port **USB** and not the right port marked **PWR**. 1. Open a connection to the device via ssh or Raspberry Pi Connect 1. Become root (the superuser) - ``` - sudo su - ``` +``` +sudo su +``` 1. Enable the DWC version 2 USB peripheral device tree overlay by appending it to the end after the `[all]` category (which is at the end) ``` echo "dtoverlay=dwc2" >> /boot/firmware/config.txt ``` 1. We add the required module `dwc2` for loading at startup - ``` - echo "dwc2" >> /etc/modules - ``` +``` +echo "dwc2" >> /etc/modules +``` 1. Check that we can load the libcomposite module - ``` - modprobe libcomposite - ``` +``` +modprobe libcomposite +``` 1. Put a copy of this repository in root's home directory using git - ``` - apt install -y git - git clone https://gitea.cs.ru.is/RU-V207/rover-pi.git - ``` +``` +apt install -y git +git clone https://gitea.cs.ru.is/RU-V207/rover-pi.git +``` 1. Go to Scripts and test if the `gadget.sh` runs without errors and hopefully a Serial port appers in Device Manager or equivalent - ``` - cd rover-pi/Scripts/ - ./gadget.sh - ``` -1. Install the systemd script - `cp serial-ether-gadget.service /lib/systemd/system/.` + ``` +cd rover-pi/Scripts/ +./gadget.sh +``` +1. Install the systemd +``` +cp serial-ether-gadget.service /lib/systemd/system/. +``` 1. Enable the service - ``` - systemctl enable serial-ether-gadget.service - ``` +``` +systemctl enable serial-ether-gadget.service +``` 1. Enable the getty (which connects a login terminal to the serial port) - ``` - systemctl enable serial-getty@ttyGS0.service - ``` +``` +systemctl enable serial-getty@ttyGS0.service +``` 1. Reboot and see if the serial port appears # Connecting to the serial terminal From ca46da2501e39a06b4986f148a84876c3a5fa446 Mon Sep 17 00:00:00 2001 From: Joseph Timothy Foley Date: Thu, 2 Jul 2026 09:45:23 +0000 Subject: [PATCH 10/13] imager --- imager.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/imager.md b/imager.md index 7d02e84..939db9a 100644 --- a/imager.md +++ b/imager.md @@ -23,7 +23,7 @@ We don't have many monitors and keyboards in V207 for students to use, so we wil ![imager-ssh_nokey.png](Graphics/imager-ssh_nokey.png) 1. Once you have uploaded your `id_edcsa.pub` file it should look like this. ![imager-ssh_key.png](Graphics/imager-ssh_key.png) -1. Since we don't have enough monitors, we will need another way to setup the initial connection. The officially supported option is Raspberry Pi Connect. You will need to: +1. Since we don't have a monitor, keyboard, and mouse available, we will need another way to setup the initial connection. The officially supported option is Raspberry Pi Connect. You will need to enable it then: 1. Register for an account first at https://connect.raspberrypi.com 2. Confirm your account with email 2. Login with that account From 15222445611ad1d237b931a67a7332c6fc9b1cf8 Mon Sep 17 00:00:00 2001 From: Joseph Timothy Foley Date: Thu, 2 Jul 2026 09:47:30 +0000 Subject: [PATCH 11/13] Started file on making initial connection --- connect.md | 10 ++++++++++ imager.md | 9 +-------- 2 files changed, 11 insertions(+), 8 deletions(-) create mode 100644 connect.md diff --git a/connect.md b/connect.md new file mode 100644 index 0000000..98a5e7c --- /dev/null +++ b/connect.md @@ -0,0 +1,10 @@ +# Initial connection to the Raspberry Pi +Now that you have an image with ssh and Raspberry Pi connect on your SD, you can connect to the pi + + +## Connecting using Raspberry Pi Connect +1. Login to https://connect.raspberrypi.com if you haven't already +1. Look at the list of devices, find the one you want, and click on "Connect" +![connect-devices.png](Graphics/connect-devices.png) +1. A remote shell window will pop up +![connect-shell.png](Graphics/connect-shell.png) diff --git a/imager.md b/imager.md index 939db9a..69377ef 100644 --- a/imager.md +++ b/imager.md @@ -42,12 +42,5 @@ We don't have many monitors and keyboards in V207 for students to use, so we wil 1. Now you get to watch the writing then verifying. ![imager-writeimage-progress.png](Graphics/imager-writeimage-progress.png) ![imager-writeimage-verifying.png](Graphics/imager-writeimage-verifying.png) -1. The process is complete! +1. The process is complete! Now you can [connect to your pi](connect.md) ![imager-complete.png](Graphics/imager-complete.png) - -## Connecting using Raspberry Pi Connect -1. Login to https://connect.raspberrypi.com if you haven't already -1. Look at the list of devices, find the one you want, and click on "Connect" -![connect-devices.png](Graphics/connect-devices.png) -1. A remote shell window will pop up -![connect-shell.png](Graphics/connect-shell.png) From b6679263156007838f4dbcfa99433d3395539632 Mon Sep 17 00:00:00 2001 From: Joseph Timothy Foley Date: Thu, 2 Jul 2026 09:49:02 +0000 Subject: [PATCH 12/13] API link --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index d01d895..42174c0 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ Scripts and documentation for setting up a Raspberry Pi (Zero W 1 or 2) for use - [Turning your Raspberry Pi Zero into a USB Gadget](https://learn.adafruit.com/turning-your-raspberry-pi-zero-into-a-usb-gadget/serial-gadget) Official Adafruit guide to gadget mode to allow the USB port to be used as a serial console to connect to it. We had trouble getting it to work in 2026 due to some changes in Raspberry Pi OS. - [Python gpiozero library](https://gpiozero.readthedocs.io/en/stable/) a simple interface for working with GPIO devices - [CircuitPython Libraries on Linux and Raspberry Pi](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/installing-circuitpython-on-raspberry-pi) This is one option for GPIO, I2C, SPI, and PWM access in python. +- [Comparing Rasbperry Pi python interfaces](https://raspberry.tips/en/raspberrypi-tutorials/raspberry-pi-gpio-python) ## For the Future - [Setting up Zeroconf to use local names (.local) to access your Pi](https://learn.adafruit.com/bonjour-zeroconf-networking-for-windows-and-linux): this does not work on iot-research because multicast and MDNS are broken. From 29fb570ae5b08113ca51c4beb39f9241f0841c9c Mon Sep 17 00:00:00 2001 From: Joseph Timothy Foley Date: Thu, 2 Jul 2026 10:05:09 +0000 Subject: [PATCH 13/13] Adding module detect functionality --- Scripts/gadget.sh | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/Scripts/gadget.sh b/Scripts/gadget.sh index 148f635..0918cba 100755 --- a/Scripts/gadget.sh +++ b/Scripts/gadget.sh @@ -2,6 +2,17 @@ # Adapted from # "Using OTG mode on Raspberry Pi SBCs" # https://pip-assets.raspberrypi.com/categories/685-app-notes-guides-whitepapers/documents/RP-009276-WP/Using-OTG-mode-on-Raspberry-Pi-SBCs + +# Is the dwc2 overlay installed? Nothing will work if it isn't. +LOGGER="systemd-cat -t gadget.sh" +if lsmod | grep -q "dwc2"; then + $LOGGER -p info "DWC2 module loaded, setting up OTG gadget serial and ethernet" +else + $LOGGER -p warning "DWC2 module missing. Aborting OTG setup" + exit 1 +fi + + sudo modprobe libcomposite cd /sys/kernel/config/usb_gadget # Create our new gadget @@ -50,4 +61,4 @@ ln -s functions/ecm.usb0 configs/c.1/ ## USB Device Controller update UDC=`ls /sys/class/udc` -echo $UDC > UDC \ No newline at end of file +echo $UDC > UDC