Raspberry Pi dwc2 USB Ethernet Gadget Setup¶
For USB Ethernet gadget mode, the Raspberry Pi must act as the USB peripheral and the computer as the USB host. On this manual setup, dtoverlay=dwc2,dr_mode=peripheral selects the USB controller's role, and g_ether supplies the Ethernet function. Use this guide for custom or older images that need manual setup.
What has been tested
A Raspberry Pi 4 Model B and a Linux host have been tested with temporary static addresses and SSH over USB. The Pi's gadget interface was unmanaged by NetworkManager. Other Pi models, Windows and macOS hosts, the managed-device path, and automatic reconnection have not been tested for this guide. See Verification scope for the exact setup and limits.
If the setup is already in place but the host detects nothing or usb0 is missing, follow the USB gadget diagnostic checklist before changing boot files or IP profiles.
For current Raspberry Pi OS Trixie on a supported board, start with USB Gadget Mode 2026. The rpi-usb-gadget package handles host-specific USB networking and optional internet sharing without maintaining the manual kernel-command-line setup below.
Use this page only when you need explicit static addressing, custom images, or control of the low-level gadget configuration. Do not enable this manual path and rpi-usb-gadget at the same time; both need ownership of the USB device controller.
Check model and connector support first
Raspberry Pi Zero, Zero W, and Zero 2 W are the simplest targets: use the micro-USB port labelled USB, not PWR IN. Raspberry Pi 4 can use peripheral mode on its USB-C connector, but powering and connecting it safely is more complicated. The main USB-A ports are host-only. This guide does not target Pi 5.
What dwc2 and dr_mode mean¶
The dwc2 overlay selects the Linux driver for the supported USB controller. Its dr_mode option sets which data role the controller should use. Raspberry Pi overlay reference
| Setting | Role of the selected port |
|---|---|
dr_mode=host |
The Pi enumerates USB peripherals connected to this port, such as a keyboard or storage device. |
dr_mode=peripheral |
The connected computer enumerates the Pi. Use this role for the manual Ethernet gadget. |
dr_mode=otg |
The controller can select a role when the board and connection support role detection. Raspberry Pi 4 lacks the OTG ID signal used for this selection, so set the peripheral role explicitly for this setup. |
On the Pi 4, otg_mode=1 is a separate firmware setting. It requests an alternate xHCI host controller for the USB-C connector. These settings apply to the selected controller. The Pi 4's main USB-A ports use a different controller. Pi 4 firmware setting · Raspberry Pi OTG white paper
Compatibility Matrix¶
| Model | Gadget connector | Notes |
|---|---|---|
| Zero / Zero W / Zero 2 W | Micro-USB USB port |
Recommended; power and data over one suitable cable |
| Pi 4 Model B | USB-C power/OTG port | Peripheral mode supported; plan a safe power arrangement |
| Compute Module | Carrier-board USB device port | Depends on carrier-board wiring |
| Pi 3/2/1 Model B USB-A | None | USB-A ports are connected as hosts |
| Pi 5 | Not covered here | Use current model-specific OTG documentation |
Use a known data cable. Some charging cables contain no data conductors. On a Pi 4, the USB-C connection also affects power: follow the official USB gadget power guidance and do not improvise multiple power sources. A suitable externally powered data hub may be needed.
Check the configured role before editing¶
On the Pi, show dwc2 and otg_mode entries with their nearest preceding section header. The command also highlights include directives so you can inspect any files referenced there.
For example, one Pi 4 Model B returned:
On that Pi 4 Model B, [cm4] and [cm5] belong to other boards. The [all] entry applies to this board. The command shows where a setting was written. Read the complete file and included files when filters overlap. Raspberry Pi conditional filters
Check what the running kernel sees before deciding to edit or reboot. A device-tree property is a string ending in a zero byte, so tr removes that byte for display.
On the same Pi, the node ending in usb@7e980000 reported peripheral, and Linux listed the USB device controller (UDC) fe980000.usb. Node names vary by board. If you see several, check the node for your gadget port. The device tree shows the role requested of that controller. The UDC state in step 3 shows whether the host has configured the USB connection.
If the expected node already says peripheral, continue to controller and gadget checks. When only host appears for that port or the UDC list is empty, investigate the active boot section, model support and kernel logs before trying a static IP.
Before changing boot or network settings¶
Keep a local console or a separately verified Wi-Fi/Ethernet connection to the Pi. The USB connection being created is not yet a recovery route. Back up the boot files in a new directory on the Pi before editing:
Keep the printed directory path. If either copy fails, stop. Keep the files on persistent storage; a temporary directory may disappear after reboot. These copies contain the state before this change, so restoring either whole file later can overwrite subsequent edits. Record the exact lines you add and, for recovery, remove only those additions after checking for later changes.
Check that the example subnet 192.168.7.0/24 does not overlap an existing LAN or VPN route on either computer. If it does, choose a different private /24 and consistently replace both addresses in the steps below. Check existing NetworkManager profiles before creating new ones; do not take over an active connection that belongs to another service.
1. Enable the USB Device Controller¶
On Trixie and Bookworm, edit /boot/firmware/config.txt:
In the applicable configuration section, add the following only after checking for existing or conflicting dwc2/otg_mode entries:
On a Pi 4, review any otg_mode=1 setting that actually applies to this board before switching its USB-C port to peripheral mode. Leave settings intended for other boards in place. See how to check the section and role.
2. Load the Ethernet Gadget at Boot¶
/boot/firmware/cmdline.txt must remain one physical line. Inspect the current line before editing. If it already has a modules-load entry, investigate its existing modules and avoid adding a second conflicting entry or discarding modules used by another setup. Otherwise, add modules-load=dwc2,g_ether after rootwait without adding a newline:
Before rebooting, check that SSH is configured and the login user exists. Raspberry Pi OS no longer assumes a default pi account. Use the SSH startup and reconnection check while retaining another recovery route. Review both edits and make sure the boot-file backup is available on persistent storage.
Reboot the Pi only when you can recover it locally or through a separately verified path. An existing SSH session will disconnect:
3. Confirm Gadget Mode on the Pi¶
After reboot, connect through Wi-Fi or a local console for the first check:
usb0 may exist only after the gadget is bound; check the actual interface name with ip -brief link if it differs. A UDC state such as configured indicates a configured USB connection, not successful IP or SSH access. A built-in driver may not appear in lsmod. If the host sees no device, use the layer-by-layer diagnostic before changing addressing.
4. Assign an Address on the Pi¶
On the Pi, first inspect existing links and profiles:
The next examples assume the Pi's verified gadget interface is usb0 and the subnet is free on both machines. If another profile already manages this interface, stop and inspect it; do not add a competing profile or modify an unrelated connection.
Check whether NetworkManager manages the device. On the site's Debian 13-based Pi 4B, usb0 appeared as unmanaged and its udev properties included NM_UNMANAGED=1. The installed udev rule marks devices with DEVTYPE=gadget unmanaged. An offline-valid NetworkManager profile alone therefore would not activate this Pi's interface. Do not assume all Raspberry Pi OS versions or local configurations use the same rule.
If NetworkManager manages the gadget¶
The profile example requires GENERAL.NM-MANAGED: yes and no existing profile named usb-gadget. Use a different unique name if necessary and substitute it consistently below.
Create and explicitly activate this new Pi profile:
The profile is intentionally not set to autoconnect during the trial. Verify which connection is active and confirm that the unrelated default route is still as expected. The USB profile should not supply a default route; ipv4.never-default prevents NetworkManager assigning one through this profile. After a reboot you must explicitly reactivate this trial profile unless you deliberately change its startup policy after testing recovery.
If NetworkManager reports unmanaged¶
For a temporary test, if usb0 is the verified gadget interface and has no existing address or active manager, record its original link state and add just the test address on the Pi:
This changes the running network state but does not create a NetworkManager profile or survive reboot. It does not set a default gateway. Leave other interfaces and routes alone. To finish, verify that this exact address is still the one you added, then remove it:
Restore the recorded link state only when no other connection needs the interface. If you changed the example subnet, remove the exact address and prefix you actually added. For unattended operation, first choose and test one persistent network-management method with a separate recovery path; do not combine competing managers.
5. Configure the Host Computer¶
The host-side name is not necessarily usb0. On a Linux host, compare ip -brief link, nmcli device status, and, if installed, lsusb before and after connecting the gadget. If the Pi is already running and the cable also supplies power, do not disconnect it just to make a comparison. Inspect the actual USB device and its network interface in the host's device manager or system logs. A name beginning with enx alone does not prove it is your Pi.
After identifying the new USB Ethernet interface, inspect its properties. Replace the placeholder with the verified host interface name, not the Pi's usb0 by assumption:
udevadm is available on typical systemd Linux installations; it identifies device properties, not proof of the remote Pi's identity. If the interface is absent, the placeholder is unchanged, its identity is unclear, or it already has an active profile, stop and inspect it first. Confirm the intended device and recovery path before changing anything. Taking over the wrong interface can interrupt the host's network connection.
An enumerated USB device can still show NO-CARRIER until the gadget and host network interfaces are brought up. USB enumeration, link carrier, IP addressing and SSH are separate checks; see the diagnostic guide if the expected state does not appear.
This creates and activates a host profile, changing network state. First confirm no profile already uses the name raspberry-pi-usb and no unrelated connection needs the device. NetworkManager may automatically start a DHCP profile when the verified gadget link appears. If you deliberately replace that USB-only profile, record its name, UUID and settings first so you can restore it; do not delete it. Activation replaces the current connection on that device, and never-default does not prevent takeover. The new profile stays manual after reboot until you deliberately change autoconnect.
After a Pi reboot, identify the USB device and interface again before reusing this profile. In our test the host interface name changed, so the profile's old connection.interface-name no longer matched. After verifying the new interface and the profile's identity, update only the profile created for this test, then activate it on the verified interface:
Do not mix this with a NetworkManager-managed profile on the same interface. Record the prior link state. Remove only the address you added when finished, and restore the original link state deliberately.
Open System Settings → Network, select the new USB Ethernet interface, choose manual IPv4, and assign 192.168.7.1 with subnet mask 255.255.255.0.
Open ncpa.cpl, find the newly enumerated USB Ethernet adapter, and configure IPv4 as 192.168.7.1/24. Driver behaviour differs between Windows versions; a composite ConfigFS gadget with RNDIS may be required if g_ether is not recognised.
6. Test and Connect with SSH¶
From a Linux or macOS host:
In Windows PowerShell, use ping -n 3 192.168.7.2; the SSH command is the same when the OpenSSH client is available.
If Avahi is installed and multicast DNS is permitted on both ends, this may also work:
Replace your-user and the hostname with the values configured on the Pi. Verify its SSH host key through a trusted independent path before accepting it. Use the numeric address for troubleshooting because .local name resolution is a separate service. A ping failure alone does not prove SSH is unavailable; filtering can block ICMP.
Optional: Share the Host's Internet Connection¶
The static example establishes a private link; it does not provide internet access. Sharing changes host routing, DHCP/NAT and the Pi's addressing, and reconnecting the profile interrupts the USB session. Plan a separate recovery path and firewall policy first. For a supported Trixie installation, use the official package workflow, including its host-specific internet-sharing steps, rather than layering it over this manual gadget. Do not configure both ends as DHCP-sharing servers.
Finish or undo the trial¶
Confirm the Pi hostname and expected address through a second SSH session before relying on USB. Keep the other recovery route until you have deliberately tested any desired reboot behaviour. Since the sample profiles use connection.autoconnect no, they do not automatically establish the link after a reboot.
To stop a trial, disconnect the specific newly created profile on each machine using its verified name or UUID, then remove that same profile only if you created it for this test. Verify nmcli connection show --active and the intended routes afterwards; do not delete an older profile with a similar name. For the temporary ip method, remove only the address added to the verified interface and restore its original state. Restore boot settings from your recorded changes via the local/recovery route, checking for subsequent edits before using the saved backup. Rebooting to apply a boot-file reversal also interrupts USB access.
Security Hardening¶
- Use SSH keys and verify a second key login plus a recovery path before considering authentication-policy changes.
- Do not bridge the gadget directly to an untrusted network.
- Keep the static subnet unique; avoid collision with VPNs or home networks using
192.168.7.0/24. - When gadget access is no longer needed, reverse only the boot and profile changes you made, using the recovery procedure above.
- Avoid
--privilegedcontainers or broad device permissions merely to accessusb0.
Troubleshooting¶
Nothing appears on the host¶
Try another known data cable and host port. Verify the cable is connected to the Zero's USB connector. Check dtoverlay=dwc2,dr_mode=peripheral, confirm cmdline.txt is one line, and inspect the kernel journal.
The host sees USB but no network adapter¶
Check the host driver. Linux and macOS generally support CDC Ethernet. Windows may need a compatible RNDIS configuration. Confirm the USB device with lsusb, System Information, or Device Manager.
usb0 exists but ping fails¶
Run ip address on both ends, confirm the /24 prefix, temporarily inspect firewall rules, and make sure only one connection profile manages each interface.
The Pi repeatedly disconnects¶
Suspect power or cable quality first. A Pi 4 should not rely on an underpowered laptop port. Check for undervoltage messages:
Reproducible Link Test¶
This optional measurement requires iperf3 on both machines. Install it only if needed, and record the model, cable, host OS, and CPU load. The server listens until stopped; run it on a trusted private link and stop it with Ctrl+C after the client finishes:
Use the Pi's actual verified USB address for --bind and the client target if you chose a different subnet. Binding limits which local address the server listens on; stop it after the test. Do not publish a single throughput value without the cable type, Pi model, host controller, and test duration.
FAQ¶
Can one cable provide both power and SSH?¶
Some Pi Zero-family setups work with a capable host port and a proper data cable. Power demands and host port limits vary by model and connected devices. Use an officially documented power arrangement, and do not assume a laptop port is sufficient for a Pi 4.
Can USB serial and Ethernet be enabled together?¶
Yes, but use ConfigFS to build a composite gadget rather than loading several legacy gadget modules independently.
Why is the interface name different on every host?¶
Predictable network naming may derive the name from the gadget MAC address. Identify the new interface with NetworkManager or ip link instead of assuming usb0.
Related Guides¶
- Compare USB Gadget modes
- Create a USB Composite Multi-Function Gadget
- Turn Raspberry Pi into a USB HID Keyboard or Mouse
- Build a USB MIDI Device
- Raspberry Pi Headless Setup Guide
Verification scope¶
On 27 October 2026, read-only inspection of the site's Raspberry Pi 4B running Raspberry Pi OS based on Debian 13 (kernel 6.18.50+rpt-rpi-v8) found NetworkManager 1.52.1 and no registered UDC in its then-current configuration. NetworkManager's offline profile generation accepted the example properties on that Pi and on the Linux host; it did not create or activate a profile.
On 28 October, the manual boot settings were enabled and the Pi was connected to the Linux host. One connection powered the Pi but produced no host USB device and the Pi reported not attached; with another cable, the host identified a Raspberry Pi USB Gadget and the Pi's UDC reported configured. The Pi reported throttled=0x0 after that boot. This confirms enumeration on the tested connection, not the root cause of the first failure or sustained power stability. The Pi's usb0 was initially down and NetworkManager reported it unmanaged; the host interface also initially had no carrier or IP.
For a temporary link test, ip brought the unmanaged Pi interface up with 192.168.77.2/30. On the host, the verified USB Ethernet interface was assigned 192.168.77.1/30 using a non-autoconnecting, non-default-route NetworkManager profile. NetworkManager had automatically started a DHCP profile on that USB device; the test deliberately switched only that device to the temporary profile, leaving the existing host Ethernet and Pi Wi-Fi default routes in place. The test subnet differs from the illustrative 192.168.7.0/24 commands above.
The host received three ping replies and opened SSH over the USB link. For host identity, the connection used the Pi's previously verified Wi-Fi host key through OpenSSH's HostKeyAlias, and explicitly selected the USB source address. That initial test validated a terminal login on this particular Pi and host; it did not establish sustained throughput, unattended startup, recovery after reboot or compatibility with other hosts.
In a further manual test on the same Pi and Linux host, the unmanaged Pi interface was brought up using the article's 192.168.7.2/24 commands, and the host used the article's NetworkManager profile with 192.168.7.1/24. Three ping requests received replies and SSH succeeded using the previously verified Pi host key. Both machines retained their existing default routes. This checks the addressing and connection steps for this pairing, not every platform or configuration described above.
After a subsequent Pi reboot, the gadget enumerated again and Wi-Fi remained available, but the temporary Pi address was gone. The host saw a different USB Ethernet interface name, so the host profile bound to the previous name needed to be updated before reuse. After reapplying the temporary Pi address and updating the host profile to the verified new interface, three ping requests succeeded and the host reconnected over SSH with the previously verified host key. Both default routes remained unchanged. This was a manual recovery test, not automatic reconnection or a long-duration stability test.