From f4283353a21867dfdf15dd6427c27ab4d3f54533 Mon Sep 17 00:00:00 2001 From: Joe Foley Date: Tue, 11 Aug 2026 22:02:54 +0000 Subject: [PATCH 1/9] reminder to use ssh while updating --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 2e38861..a37f2c0 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,10 @@ Scripts and documentation for setting up a Raspberry Pi (Zero W 1 or 2) for use 1. [Raspberry Pi Imager procedure to setup ssh and Raspberry Pi Connect](imager.md) 1. Find out your Pi's ethernet addresss in case you need to find it on `iot-research` again. Type `ip addr show dev wlan0` and for something like `link/ether 01:23:45:67:89:ab`. Write this information (the 12 characters and colons) in your notebook. In T-411-MECH we want you to put this information in a spreadsheet links from the main page: this allows us connect Pi's to people in case of any issues. 1. [Solder the GPIO header pins](solder-gpio.md) +1. Login to the pi using ssh or serial. (Pi Connect breaks wihle upgrading the Pi Connect program). You will be doing updates as part of the next procedure. 1. [Gadget Mode to setup a serial connection over USB](gadget.md) 1. [Marcel's script on github to show the IP address on the OLED screen](https://github.com/mkyas/cpsy-display-ip) + 1. Install Blinka by following the guide [CircuitPython Libraries on Linux and Raspberry Pi](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/installing-circuitpython-on-raspberry-pi)] ## RU student-only guides at ROB-IOT From ba377393a5db4b3dc1a708b3be21e5cf3d720aa1 Mon Sep 17 00:00:00 2001 From: Joe Foley Date: Tue, 11 Aug 2026 22:07:57 +0000 Subject: [PATCH 2/9] listed how to do the updates --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a37f2c0..10d008e 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,12 @@ Scripts and documentation for setting up a Raspberry Pi (Zero W 1 or 2) for use 1. [Raspberry Pi Imager procedure to setup ssh and Raspberry Pi Connect](imager.md) 1. Find out your Pi's ethernet addresss in case you need to find it on `iot-research` again. Type `ip addr show dev wlan0` and for something like `link/ether 01:23:45:67:89:ab`. Write this information (the 12 characters and colons) in your notebook. In T-411-MECH we want you to put this information in a spreadsheet links from the main page: this allows us connect Pi's to people in case of any issues. 1. [Solder the GPIO header pins](solder-gpio.md) -1. Login to the pi using ssh or serial. (Pi Connect breaks wihle upgrading the Pi Connect program). You will be doing updates as part of the next procedure. +1. Login to the pi using ssh or serial. (Pi Connect breaks wihle upgrading the Pi Connect program). Now update the packages on your pi: + ``` + sudo apt-get update + sudo apt-get -y upgrade + ``` + 1. [Gadget Mode to setup a serial connection over USB](gadget.md) 1. [Marcel's script on github to show the IP address on the OLED screen](https://github.com/mkyas/cpsy-display-ip) From 447a0fcca37f0be7a1df0c2c9f2750860f0dc02e Mon Sep 17 00:00:00 2001 From: Joe Foley Date: Tue, 11 Aug 2026 22:29:21 +0000 Subject: [PATCH 3/9] reboot after changing the dtoverlay --- gadget.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/gadget.md b/gadget.md index 3c75f9d..edcad0d 100644 --- a/gadget.md +++ b/gadget.md @@ -29,9 +29,16 @@ echo "dwc2" >> /etc/modules ``` modprobe libcomposite ``` +1. Reboot +1. Open a new connection and become root (the superuser) +``` +sudo su +``` + 1. Put a copy of this repository in root's home directory using git ``` apt install -y git +cd /root 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 From 104aaabde4a63204ca2aff3625095c1a8ef7f35f Mon Sep 17 00:00:00 2001 From: Joe Foley Date: Tue, 11 Aug 2026 23:29:28 +0000 Subject: [PATCH 4/9] reminder about quality of usb cable --- gadget.md | 1 + 1 file changed, 1 insertion(+) diff --git a/gadget.md b/gadget.md index edcad0d..30afa82 100644 --- a/gadget.md +++ b/gadget.md @@ -5,6 +5,7 @@ Based upon Adafruit guide: https://learn.adafruit.com/turning-your-raspberry-pi- 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 : +- Some of the serial cables we get from our supplier are flakey: if wiggling the cable when plugged into your computer causes it to sometimes see the serial port and sometimes not, get a new one. - **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. From 9c49411159038efc998d723b9e31ccdb79b4ed23 Mon Sep 17 00:00:00 2001 From: Joe Foley Date: Fri, 4 Sep 2026 09:42:39 +0000 Subject: [PATCH 5/9] Adding aleksa24 detect for pre-compiled DWC2 --- Scripts/gadget.sh | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Scripts/gadget.sh b/Scripts/gadget.sh index 490c1ef..719aa08 100755 --- a/Scripts/gadget.sh +++ b/Scripts/gadget.sh @@ -11,8 +11,10 @@ fi # Is the dwc2 overlay installed? Nothing will work if it isn't. -if lsmod | grep -q "dwc2"; then - systemd-cat -t gadget.sh -p info echo "DWC2 module loaded, setting up OTG gadget serial and ethernet" +if [ -d /sys/class/udc ] && [ -n "$(ls -A /sys/class/udc)" ]; then + systemd-cat -t gadget.sh -p info echo "DWC2 precompiled, setting up OTG gadget serial and ethernet" +elif lsmod | grep -q "dwc2"; then + systemd-cat -t gadget.sh -p info echo "Pre 6.18.39 kernel. DWC2 module loaded, setting up OTG gadget serial and ethernet" else systemd-cat -t gadget.sh -p warning echo "DWC2 module missing. Aborting OTG setup." systemctl disable serial-getty@ttyGS0.service From e6a0556147a62b18a81237024c9d8c5278a7ed31 Mon Sep 17 00:00:00 2001 From: Joe Foley Date: Fri, 4 Sep 2026 10:01:40 +0000 Subject: [PATCH 6/9] Check for GADGET_MODE in boot/firmware to enable --- Scripts/gadget.sh | 7 ++++++ gadget.md | 54 ++++++++++++++++++++++++++++------------------- 2 files changed, 39 insertions(+), 22 deletions(-) diff --git a/Scripts/gadget.sh b/Scripts/gadget.sh index 719aa08..de1e432 100755 --- a/Scripts/gadget.sh +++ b/Scripts/gadget.sh @@ -9,6 +9,13 @@ if [ $(id -u) -ne 0 ]; then exit 1 fi +if [ -f /boot/firmware/GADGET_MODE ]; then + systemd-cat -t gadget.sh -p info echo "/boot/firmware/GADGET_MODE exists: GADGET mode enabled" +else + systemd-cat -t gadget.sh -p warning echo "/boot/firmware/GADGET_MODE missing: GADGET mode disabled" + systemctl disable serial-getty@ttyGS0.service + exit 1 +fi # Is the dwc2 overlay installed? Nothing will work if it isn't. if [ -d /sys/class/udc ] && [ -n "$(ls -A /sys/class/udc)" ]; then diff --git a/gadget.md b/gadget.md index 2b46559..d36483b 100644 --- a/gadget.md +++ b/gadget.md @@ -18,14 +18,6 @@ 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 -``` -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 @@ -94,7 +86,38 @@ This is similar to the procedure for accessing an Arduino. ``` 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 +# Enabling/Disabling the OTG mode to use a keyboard and mouse again + +**WARNING: Untested** +1. Disable: Delete a file called `GADGET_MODE` in the boot partition/drive when not on a pi. If the Pi is booted, you can delete `sudo rm /boot/firmware/GADGET_MODE` and reboot +1. Enable: create a file called `GADGET_MODE` in the boot partition/drive when not on a pi. If the Pi is booted, you can create `sudo touch /boot/firmware/GADGET_MODE` and reboot + +# 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/ + + +# 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) + +# Old DWC Instructions (for older versions) + +## Setting up +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 +``` + + +## 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 @@ -114,16 +137,3 @@ This is similar to the procedure for accessing an Arduino. ``` 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/ - - -# 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 a73e40b960beb2eb0d37cb9e29168a2baa19721d Mon Sep 17 00:00:00 2001 From: Joseph Timothy Foley Date: Fri, 4 Sep 2026 16:08:27 +0000 Subject: [PATCH 7/9] Tested. IT works. Updating directions to enable and disable --- gadget.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/gadget.md b/gadget.md index d36483b..4712d74 100644 --- a/gadget.md +++ b/gadget.md @@ -88,9 +88,15 @@ This is similar to the procedure for accessing an Arduino. # Enabling/Disabling the OTG mode to use a keyboard and mouse again -**WARNING: Untested** -1. Disable: Delete a file called `GADGET_MODE` in the boot partition/drive when not on a pi. If the Pi is booted, you can delete `sudo rm /boot/firmware/GADGET_MODE` and reboot -1. Enable: create a file called `GADGET_MODE` in the boot partition/drive when not on a pi. If the Pi is booted, you can create `sudo touch /boot/firmware/GADGET_MODE` and reboot +## Disable +1. Remove the SD card and access it on your computer +1. Delete the file called `GADGET_MODE` in the boot partition/drive usually called `bootfs`. +1. If the Pi is booted, you can `sudo rm /boot/firmware/GADGET_MODE` and reboot. + +## Enable +1. Remove the SD card and access it on your computer +1. Create a file called `GADGET_MODE` in the boot partition/drive called `bootfs`. +2. If the Pi is booted, you can `sudo touch /boot/firmware/GADGET_MODE` and reboot # Connecting over the USB ethernet to ssh into your Pi From 9ba6b30e1f3b63daa6215612bcff5f3f009814fe Mon Sep 17 00:00:00 2001 From: Joseph Timothy Foley Date: Fri, 4 Sep 2026 16:15:29 +0000 Subject: [PATCH 8/9] Update gadget.md --- gadget.md | 1 + 1 file changed, 1 insertion(+) diff --git a/gadget.md b/gadget.md index 4712d74..e6f19c0 100644 --- a/gadget.md +++ b/gadget.md @@ -5,6 +5,7 @@ Based upon Adafruit guide: https://learn.adafruit.com/turning-your-raspberry-pi- 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 : +- **We are still working out the kinks with the gadget mode switching on the Pi Zero W 2** - **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. - The blue USB cables included in the kit in 2026 are flakey. We recommend replacing them ASAP. - 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. From 73b4e98a363583adcc2d2143ff478f139274d559 Mon Sep 17 00:00:00 2001 From: Joseph Timothy Foley Date: Fri, 4 Sep 2026 19:45:55 +0000 Subject: [PATCH 9/9] suggested using supported rpi-usb-gadget instead of my script --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a477c5e..14d5808 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Scripts and documentation for setting up a Raspberry Pi (Zero W 1 or 2) for use sudo apt-get -y upgrade ``` -1. [Gadget Mode to setup a serial connection over USB](gadget.md) +1. [Gadget Mode to setup a network connection over USB](https://github.com/raspberrypi/rpi-usb-gadget) 1. [Setup the OLED screen to print the IP](oled-display/README.md) Based upon [Marcel's script on github to show the IP address on the OLED screen](https://github.com/mkyas/cpsy-display-ip) 1. Install Blinka by following the guide [CircuitPython Libraries on Linux and Raspberry Pi](https://learn.adafruit.com/circuitpython-on-raspberrypi-linux/installing-circuitpython-on-raspberry-pi)]