Simple guide for setting up OTG modes on the Raspberry Pi Zero

HowToOTG.md

Raspberry Pi Zero OTG Mode

Simple guide for setting up OTG modes on the Raspberry Pi Zero - By Andrew Mulholland (gbaman).

The Raspberry Pi Zero (and model A and A+) support USB On The Go, given the processor is connected directly to the USB port, unlike on the B, B+ or Pi 2 B, which goes via a USB hub.
Because of this, if setup to, the Pi can act as a USB slave instead, providing virtual serial (a terminal), virtual ethernet, virtual mass storage device (pendrive) or even other virtual devices like HID, MIDI, or act as a virtual webcam!
It is important to note that, although the model A and A+ can support being a USB slave, they are missing the ID pin (is tied to ground internally) so are unable to dynamically switch between USB master/slave mode. As such, they default to USB master mode. There is no easy way to change this right now.
It is also important to note, that a USB to UART serial adapter is not needed for any of these guides, as may be documented elsewhere across the internet.

##Which process should I choose?
There are 2 routes you can take for setting up the Raspberry Pi Zero as a USB Slave (OTG mode).

1. The quick route - The quick route doesn't require anything beside your Pi Zero, SD card and a Windows, Mac or Linux computer. It though only supports setting up the Pi Zero as a virtual Ethernet device (allowing full SSH, SFTP, VNC etc). For any of the other USB Gadget drivers (beside g_ether), use route 2.
2. The modular slower, but more flexible route - This route requires a screen and keyboard to configure your Pi Zero once it has completed its first boot.

###1. Very quick way (No USB keyboard, mouse, HDMI monitor needed)
The newer method has now been brought out into a separate Gist, which can be found here.

###2. Modular, but slower to setup method For this method, a Pi Zero, SD card (with Raspbian Jessie lite or full), screen and keyboard are required.
You are able to set up any of the below modules using this method and are not just limited to g_ether. The required kernels are also now shipped with Raspbian 2016-05-10 releases and beyond. So no need to do a raspi-update.
No web connectivity is required, nor is a USB-UART adapter required for this method. This documentation is based off the initial excellent work done on this Github pull request.
Modules included

• Serial (g_serial)
• Ethernet (g_ether)
• Mass storage (g_mass_storage)
• MIDI (g_midi)
• Audio (g_audio)
• Keyboard/Mouse (g_hid)
• Mass storage and Serial (g_acm_ms)
• Ethernet and Serial (g_cdc)
• Multi (g_multi) - Allows you to configure 2 from Ethernet, Mass storage and Serial
  In addition to the above modules, a few other (less useful) modules are included.
• Webcam (g_webcam)
• Printer (g_printer)
• Gadget tester (g_zero)

1. First, flash Jessie (only tested on full, lite version may also work though) onto a blank microSD card.
2. (step only needed if running Raspbain version before 2016-05-10) Once it starts up again, run sudo BRANCH=next rpi-update. This will take a while.
3. Next we need to make sure we are using the dwc2 USB driver echo "dtoverlay=dwc2" | sudo tee -a /boot/config.txt.
4. And enable it in Raspbian echo "dwc2" | sudo tee -a /etc/modules
5. Need to now pick which module you want to use from the list above, for example for ethernet echo "g_ether" | sudo tee -a /etc/modules. You can only pick one of the above modules to use at a time.

Using the modules

• g_serial - To use the standard serial module, you need to tell the Pi to forward the serial console to it with sudo systemctl enable getty@ttyGS0.service, then you can connect to the device via Putty or Screen.
• g_ether - Using virtual ethernet, you should simply be able to ssh into the address of your Raspberry Pi. To do this, there is a little extra configuration required though. There is a few ways we could set up the point to point networking. The proper way would be to set up a DHCP server on one of the ends. A far simplier was though is just to give the Raspberry Pi a fixed IP address. To do this, you will need to run echo -e "interface usb0 \nstatic ip_address=169.254.64.64" | sudo tee -a /etc/dhcpcd.conf. You can then access the Raspberry Pi Zero by connecting to 169.254.64.64, or by using raspberrypi.local if your computer has Bonjour installed (Mac and most Linux OSs including Raspbian). Note this method does not support adding a fixed address to the cmdline.txt file. For that, you have to use the Ethernet only kernel below.
• g_mass_storage - To have your Pi Zero appear as a mass storage device (flash drive), first create a mini filesystem in a file on your Pi with sudo dd if=/dev/zero of=/piusb.bin bs=512 count=2880 and set it up as a fat32 filesystem with sudo mkdosfs /piusb.bin. Then, when enabling it, add file=/piusb.bin stall=0 onto the end, for example sudo modprobe g_mass_storage file=/piusb.bin stall=0.

In theory, most USB devices should work alongside these kernels, to switch to USB OTG mode, simply don't use an OTG adapter cable and use a standard USB cable to plug your Pi Zero into another computer, it should auto switch.

Legacy guides

The legacy guides can be found on a separate Gist.

Update for Raspberry pi OS (2021) :-
Few observations for anyone wandering the internet.

After first boot through HDMI display, if you want to set static IP address, you may want to add
sudo ifconfig usb0 169.254.3.14/16
by sudo nano /etc/rc.local
This works reliably.

If I attach a ethernet hat to the Zero will I still have the OTG functionality? I am asking because I saw a HAT from Waveshare where to OTG USB port is blocked by the box. So, maybe the ethernet HAT will make use of that USB port?

Also, the Raspberry Pi Compute Module 4 seems to have OTG but can it act as a USB slave? In the manual it says:

2.4. USB 2.0 (Highspeed)
The USB 2.0 interface supports up to 480MBps signalling. The differential pair should be routed as a 90Ω differential pair.
The P N signals should ideally be matched to 0.15mm
 TIP
The USB interface is disabled to save power by default on the CM4 . To enable it you need to add
dtoverlay=dwc2,dr_mode=host to the config.txt file
 NOTE
The port is capable of being used as a true USB On-The-Go (OTG) port. While there is no official documentation, some
users have had success making this work. The USB_OTG pin is used to select between USB host and device that is
typically wired to the ID pin of a Micro usb connector. To use this functionality it must be enabled in the OS that is
used. If using either as a fixed slave or fixed master, please tie the USB OTGID pin to ground

Should work if I understand it correctly?!

Good stuff, works great on RPI and plugged into a Mac. For g_audio, the devices show up as the following on the mac:

• Capture Inactive
• Playback Inactive

Is there a way to add a custom name the device?

Otherwise working well.

Hi. Good guide! Just wondering if after one has setup a USB Mass Storage gadget, is there a way to point to a different piusb.bin file without restarting the Pi?
I mean what I have in mind is on Windows, when it swaps to a different file, the Device Manager momentarily loses the storage and then reappears. Is there a way to do this?
Thank you!

sudo rmmod g_mass_storage sudo modprobe g_mass_storage file=/otherpiusb.bin stall=0

I don't think there is a "nice" way to do this though, it's like pulling out a usb stick without ejecting it first.

Do you maybe have any experience on how simultaneous access is handled?
I Use the Pi as a mass storage for windows with 'g_mass_storage ' and have the Partition simultaneously mounted inside the Pi, what happens when Pi and Windows both want to write or read at the same time?

Thank you so much for sharing.

It has served me well.

is there any way to use the route one (g_ether) and the route two which is the other g_ modules at the same time? I want to have the mass storage and the ssh on one windows without other internet connections.
I've tried .. after i finished the route 1 , when I am trying to emulate the storage device , the pc didnot have any sign after i did the modprobe command even i re-plugin , sometimes it cannot be recognized after doing that
is there a way to do this?
thanks

Will this work for raspberry pi 0 2W

It should.

Will this work for raspberry pi 0 2W

it does. for example, see PoC https://github.com/adam-burns/devuan-pi-gadgeteer

It should.

it displays as a floppy drive, can we change it to usb flash drive

Can someone explain to me how I can share the Internet from the Raspberry Pi 5 to the host-pc via g_multi mode? Ive manged to get the g_masstorage functions working but the internetshare wont work...

I have a RPi zero acting as a slave USB (debian bookworm, HID device) and basic operation is fine.

But I'm not able to detect when the USB cable is {un}plugged from the host. udevadm monitor seems not to pick up these events. Anyone know how to do that, or if this is known to be out of udevadm's domain? (Am I just missing a parameter?)