No Wi-Fi credentials yet, a locked-down network, or a device on a bench: with rpi-usb-gadget one USB cable gives you a network link to the Pi for SSH, file copy or remote development.
What it does
- Uses the kernel's
g_etherUSB gadget. The host sees a network adapter: CDC-ECM on Linux/macOS, RNDIS on Windows (install the supplied Raspberry Pi USB RNDIS driver for the fastest setup). - Configures two NetworkManager profiles on
usb0and a watcher service (rpi-usb-gadget-ics.service) that picks one automatically:
| Mode | When | Addressing |
|---|---|---|
| CLIENT | the host shares its internet connection (ICS) | the Pi gets an IP from the host (typical host gateways 192.168.137.1 Windows, 192.168.2.1 macOS, 10.42.0.1 Linux) |
| SHARED | no ICS on the host | the Pi is 10.12.194.1/28 and serves DHCP (10.12.194.2–14) and NAT |
- USB Ethernet only. No serial gadget (
/dev/ttyGS0) is enabled by default. - The README lists Zero/Zero 2 W, 3A+, 4B, 5, 500 and Compute Module 0/5; CM4 needs more setup.
Setup
sudo apt update
sudo apt install rpi-usb-gadget # or install the .deb from the repo's releases page
sudo rpi-usb-gadget on
sudo reboot
Then from the host:
ssh <user>@10.12.194.1 # SHARED mode
ssh <user>@<hostname>.local # CLIENT mode, via mDNS
Pitfalls
- VPNs on the host can interfere with the local link. Disable them while connecting.
- Several Pis on one host in SHARED mode all use 10.12.194.0/28, so the host sees overlapping subnets. Enable ICS on the host (each Pi then gets its own address) or give each Pi its own subnet:
sudo nmcli connection modify "USB Gadget (shared)" ipv4.addresses 10.12.195.1/28
sudo nmcli connection down "USB Gadget (shared)"; sudo nmcli connection up "USB Gadget (shared)"
- The README describes it as a package to be included in a future Raspberry Pi OS release. If
apt installdoesn't find it on your image, use the.debfrom the releases page.