Headless setup on Pi Zero SSH over USB OTG

[omnidepp]

Version: DietPi_v6.25_RPi-ARMv6-Buster

I'm trying to install my pi zero in headless mode with USB OTG as the only means of accessing the device via SSH.

All tutorials suggest to just add
dtoverlay=dwc2 to config.txt and modules-load=dwc2,g_ether after rootwait to cmdline.txt. This does not work for Dietpi unfortunately - any insights on why and how to fix this?

[MichaIng]

@omnidepp
Many thanks for your report.

The dwc2 driver is btw default on RPi Zero, hence the dtoverlay should be without any effect.
Not sure about the modules, but dtoverlays usually load the required modules automatically, hence replace any custom modprobe/modules-load entry. However both does not hurt.

What do you mean by it does not work? Does the host machine recognise the attached Pi Zero when attached and booting, hence drivers can be installed? How do you try to connect to the Pi? Note that the default hostname on DietPi is "dietpi" not raspberrypi.local or such, which is mentioned on most guides. Also in case leave it for a while to apply first run setup steps (which include some network-related steps as well), before SSH server will be accessible.

[omnidepp]

Thanks for the quick reply.

My mac recognizes the device as RNDIS/Ethernet Gadget, it remains "disconnected" though (red bubble indicator). I've tried the correct host name and I've performed arp- and ip-scans - it's not found. I've been successful at connecting to the Zero with standard raspbian.

[MichaIng]

I think I found the issue: Ethernet-over-USB network interfaces are called usb0 etc, not eth0. Hence they are not configured on DietPi by default. You need to add an /etc/network/interfaces.d/ config to have this done. This can currently be applied on DietPi via custom firstrun script (see dietpi.txt) before doing first boot. A related automation could be done with v6.28 as I plan some network setup rework anyway.

The config could contain:

allow-hotplug usb0
iface usb0 inet dhcp

I'll verify and give some more detailed instructions later to test.

[omnidepp]

Setting up the usb0-interface manually works indeed. I had to enable hdmi and get a keyboard to do so first, though ;-)
For some reason, I could only get internet connection sharing from my mac to work after adding options g_ether host_addr=00:22:82:ff:ff:29 dev_addr=00:22:82:ff:ff:29 to /etc/modprobe.d/g_ether.conf

[MichaIng]

@omnidepp
Probably, if one has multiple USB ports, g_ether is not able to apply to the correct one in every case 🤔. Although what you set is the MAC address. Requires some investigation if we implement this into our scripts.

[johnnyBrandom]

Hi, I'd really like to know how you got this to work because I'm having no success after making these changes to my Pi Zero W. I added a config file to interfaces.d as suggested above with the following text:

# USB
#auto usb0
allow-hotplug usb0
#iface eth0 inet dhcp
iface usb0 inet static
address 192.168.1.10
netmask 255.255.255.0
gateway 192.168.1.1

I've tried it with the "auto usb0" line uncommented as well. My Mac never sees the device on a network. Booting with RaspberryPi os works fine in this mode so not sure what's wrong. It would be great if this feature was added to DietPi. I'm using latest release of DietPi as of 3 Dec. 2021. Thanks.

[MichaIng]

You did enable the device tree overlay and adjusted the kernel module options?

[johnnyBrandom]

You did enable the device tree overlay and adjusted the kernel module options?

Not initially. But in continued searching, I found the following explanation echoing what is written above with more detail and tried it with the changes already made and now I can see and connect to the DietPi via usb network. I have a bit more work to do in order to get internet sharing working as the DietPi seems to demand that on boot (I tried disabling those switches in the config but DietPi still wants to call home). I'll come back and report full solution with internet sharing once I resolve it. Thanks for your reply and assistance. This will be a nice feature to include once you get the cycles to add it. I understand the challenges to doing so though. Thanks again.

[MichaIng]

The same is explained in the posts above 😄. If you want to configure this for first boot, try to disable Ethernet and WiFi both in dietpi.txt so that it does not try to setup any eth* or wlan* interface. Then edit/add the config.txt/cmdline.txt (FAT partition) and your /etc/network/interfaces.d/usb0.conf and in case /etc/modprobe.d/g_ether.conf (ext4 partition) in place. That way USB gadget mode and kernel module loading+configuration are done on first boot already, and ifupdown should then bring up the interface.

I tried disabling those switches in the config but DietPi still wants to call home

DietPi does not want to call "home" but wants to update your system, especially all APT packages to the latest versions, as a general best practice for any initial system setup. You can abort that, but whatever you do, setting up network at last one time to update the system is the first thing you should do in any case, optionally after some firewalling/hardening, of course.

[rhinot]

Can confirm the following makes a dietpi rpi Zero 2 W a USB gadget with a working data connection:

• Add dtoverlay=dwc2,dr_mode=peripheral to last line of `/boot/config.txt'

(Unclear if dr_mode=peripheral is necessary, but in my permutations of configs, this was added and it works for me)

• Add modules-load=dwc2,g_ether after rootwait in boot/cmdline.txt
• Add conf file in /etc/network/interfaces.d/ (I just unimaginatively called my conf file usb) which enables USB as a network device and sets a static ip; Example config:

allow-hotplug usb0
iface usb0 inet static
address 192.168.7.2
netmask 255.255.255.0
network 192.168.7.0
broadcast 192.168.7.255
gateway 192.168.7.1

• If using the rpi as a gadget with a Mac, I also needed to create /etc/modprobe.d/g_ether.conf which contains the single line options g_ether use_eem=0 for the Mac to have a usable data connection; In addition, you manually have to set an IP for the Mac for the RNDIS device that shares the same subnet and netmask as whatever you set for the rpi (e.g. 192.168.7.1 and 255.255.255.0, if you used the static settings above)

Understanding that this is with a Zero 2, not a Zero (1), sharing the above both as a datapoint that this can work with dietpi, and to help anyone else who stumbles upon this bug.

As an aside, when I connect my Mac to the rpi in gadget mode, the Mac's internet connection ceases, despite being connected on wifi AND being able to share the internet connecting with the rpi. Still trying to figure out what's causing that.

[MichaIng]

Great. You should be able to simplify the interface config to:

allow-hotplug usb0
iface usb0 inet static
address 192.168.7.2/24
gateway 192.168.7.1

• Merging netmask and network into CIDR notation of the address.
• *.255 is used for broadcasts by default.

[rhinot]

Thanks. Confirmed the CIDR notation works, and that leaving out the gateway means it uses another connection for internet.

[MichaIng]

and that leaving out the gateway means it uses another connection for internet.

Exactly, with gateway a default route is added for this device, hence where the system sends network requests to when no other more specific route applies, like when accessing a local IP:

ip r

[petersladek]

I tried to setup DietPi on pi zero 1.3 in headless mode using USB OTG on Windows. Didn't make it unfortunately 🙁 Followed these steps and used Automation_Custom_PreScript.sh to enable USB as network. For sure I messed something in the script, but as accessing ext4 on sd card on windows is troublesome, I couldn't easily check what went wrong. Frustrated I flashed Raspberry OS Lite on sd card, and just modified config.txt and cmdline.txt to enable USB OTG (no need for custom conf file in /etc/network/interfaces.d/) , and it worked on first try. I really prefer DietPi, but the experience for headless USB OTG is currently lacking.

[MichaIng]

You assured that the static IP and gateway match your local network and router? As it works on RPi OS without explicit network configuration (it uses dhcpcd), DHCP seems to work, so a simplified network configuration which assures that IP, network and gateway are correct, would then be:

allow-hotplug usb0
iface usb0 inet dhcp

[petersladek]

Thanks for advice, will give it a try in two weeks, busy right now. I wasn't connected to any real local network on host system the pi was connected to - I just set it to be in same subnet as RNDIS virtual adapter. I guess with RPi OS it defaulted to dhcp on dietpi and also on RNDIS adapter I could leave dhpc, and it worked.