Raspberry Pi USB Gadget Mode Comparison: Ethernet, HID, MIDI, and Storage¶

Raspberry Pi USB Gadget Mode makes a Pi behave like a USB device connected to another computer. The correct setup depends on whether the host needs an Ethernet adapter, keyboard, MIDI port, storage device, or several functions at once.

The managed Ethernet workflow and supported-port list come from Raspberry Pi's current USB gadget mode in Raspberry Pi OS documentation.

Quick answer

Use Raspberry Pi OS Trixie's rpi-usb-gadget package for supported USB Ethernet and SSH setups. Use a purpose-built legacy gadget module or ConfigFS only when you specifically need HID, MIDI, storage, or a composite device. Do not let two configurations claim the same USB Device Controller (UDC).

Choose the gadget function¶

Goal	USB function	Best starting guide	Important limitation
SSH over one cable	Ethernet	Trixie USB Gadget Mode	The official package focuses on networking
Custom USB network	Ethernet	Manual USB Ethernet	You maintain descriptors, addressing, and boot integration
Appear as a flash drive	Mass storage	USB mass-storage emulation	The host and Pi must not write the same filesystem together
Send keyboard or mouse reports	HID	USB HID keyboard or mouse	Treat automated input as a security-sensitive capability
Connect to a DAW or synthesizer	MIDI	USB MIDI gadget	Check the ALSA port and host application separately
Expose several functions	Composite ConfigFS gadget	Composite gadget with ConfigFS	Descriptor and host-driver compatibility become your responsibility

Official package or manual configuration?¶

Method	Use it when	Avoid it when
`rpi-usb-gadget`	You want Ethernet, SSH, and optional host internet sharing on a current Trixie image	You need HID, MIDI, storage, or custom descriptors
Legacy module such as `g_midi`	You need one simple, dedicated function and have tested it on the target kernel	You need several functions or detailed descriptor control
ConfigFS/libcomposite	You need a composite device or precise control of functions and descriptors	The supported Ethernet workflow already meets the requirement

The three methods are alternatives, not layers to stack together. Disable the active configuration before testing another one.

Model and port compatibility¶

Raspberry Pi's current rpi-usb-gadget documentation lists the following model/port combinations. This table describes the official Ethernet package; it does not guarantee that every manual HID, MIDI, or storage recipe works unchanged on every board.

Raspberry Pi	Device-mode connection
Zero, Zero W, Zero 2 W	Micro-USB port labelled `USB`, not `PWR IN`
3A+	USB port with device-mode support
4 and 5	On-board USB-C port
500 and 500+	On-board USB-C port
Compute Module 5	USB-C on the CM5 IO Board
Compute Module 4	Possible with additional hardware and manual setup

When a dual-role port is in device mode, it is not simultaneously a normal USB host port. Always use a data-capable cable; a charge-only cable can power the Pi while carrying no USB data.

Fastest supported Ethernet setup on Trixie¶

Start with an updated Raspberry Pi OS Trixie image and confirm the package's current command syntax:

sudo apt update
sudo apt install rpi-usb-gadget
rpi-usb-gadget --help
sudo rpi-usb-gadget on
sudo reboot

After reconnecting the data cable, find the new network interface on the host and try the configured hostname. Follow the complete SSH-over-USB procedure for Imager settings, host-specific checks, and internet sharing.

The one-UDC rule¶

Linux exposes available USB Device Controllers under /sys/class/udc. One active gadget configuration binds to a controller by writing its name to a ConfigFS UDC file. If another service, module, or script already owns it, the next configuration fails or behaves unpredictably.

Inspect the current state before changing anything:

ls -la /sys/class/udc
lsmod | grep -E 'g_(ether|midi|mass_storage|hid)|libcomposite'
find /sys/kernel/config/usb_gadget -maxdepth 2 -type f -name UDC -print -exec cat {} \; 2>/dev/null
systemctl --failed
journalctl -b -k | grep -iE 'dwc2|udc|gadget|usb'

Do not auto-load g_ether or g_midi while a ConfigFS service or rpi-usb-gadget is active.

Host compatibility checklist¶

Symptom	Check first	Next evidence
Pi powers on but no USB device appears	Replace the cable with a known data cable; use the correct port	Host USB device list and Pi kernel log
Device appears but SSH fails	Host network interface, DHCP address, hostname, and route	`ip address`, `ip route`, NetworkManager state
MIDI device appears but the DAW is silent	DAW input/output routing and ALSA MIDI port	`amidi -l` and a raw MIDI monitor
Storage appears corrupt	Confirm exclusive ownership and a clean detach	Read-only filesystem check on the backing image
Composite gadget has one missing function	Inspect descriptors and host driver binding	ConfigFS tree and host Device Manager/system log

Change one variable at a time: cable, host port, Pi image, gadget configuration, then host application. This produces a useful failure report instead of hiding the cause with several simultaneous edits.

Power, data, and security¶

A laptop port may not supply enough power for a Pi 4 or Pi 5 plus peripherals. Check vcgencmd get_throttled and the kernel log after disconnects.
A USB HID gadget can inject input into the host. Run only reviewed scripts and require explicit authorization on systems you do not own.
A mass-storage backing image needs one writer at a time. USB networking plus SFTP is safer when both computers need concurrent file access.
Use locally administered MAC addresses for custom Ethernet gadgets and avoid copying arbitrary vendor/product IDs into deployed products.
Keep a recovery path before enabling a boot-time gadget service, especially on a headless Pi.

FAQ¶

Is USB Gadget Mode the same as USB OTG?¶

USB OTG or dual-role capability is the hardware/controller feature. Linux USB Gadget is the software framework that exposes functions such as Ethernet, MIDI, HID, or storage.

Can one cable carry power and data?¶

Yes, if the board, device-mode port, host port, and cable support it. Larger boards may still need a supported power arrangement because the host's current limit can be too low.

Can Ethernet, MIDI, and HID run at the same time?¶

They can be functions of one carefully designed ConfigFS composite gadget. Loading independent legacy gadget modules is not the correct way to combine them, and host support must be tested.

Why does an old `g_ether` tutorial differ from Trixie?¶

Current Raspberry Pi OS provides an official Ethernet workflow that manages the standard case. Manual tutorials remain useful for custom images and descriptors, but they also transfer upgrade and compatibility responsibility to you.

Which option should a first-time user choose?¶

Choose the official Trixie Ethernet workflow when the goal is SSH. Move to a single-function module or ConfigFS only after defining a requirement the supported package does not meet.