Raspberry Pi zero USB Gadget Mode

[fhirschmann]

Description

This implements USB Gadget Mode on the Raspberry Pi Zero as discussed in #216.

This is not ready to merge yet. I can't figure out how to include dwc2.dtbo during the build process - maybe somebody can help with this?

I'd also like to discuss how to best enable this mode from a user-perspective. Right now, /boot/config.txt has to be edited to enable the dwc2 overlay. This should be fine, but will a RaspberryMatic upgrade reset /boot/config.txt again?

Changes:

• Add init script to enable gadget mode
• Add udev rule to rename network device from usb0 to eth0
• Deploy dwc2.dtbo during the build process to the sd card (image)

Related Issues

• Ethernet Gadget mode on RPi Zero #216

Types of changes

• Docs change / refactoring / dependency upgrade
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Possible Drawbacks

I expect no side-effects because:

• The init script only runs if the user manually edited /boot/config.txt
• The udev rule only targets an artificial MAC address defined in the init script

Verification Process

• Mode has to be explicitly enabled by the user by modifying /boot/config.txt

Release Notes

• Add support for USB Gadget Mode Ethernet on the Raspberry Pi Zero

Contributing checklist

• My code follows the code style of this project.
• I have read the CONTRIBUTING and LICENSE document.
• I fully agree to distribute my changes under Apache 2.0 license.

[jens-maus]

Thanks for this great PR. I will try to review it during the next days, but I cannot promise to integrate it already with the next upcoming release. But what I can already state is, that instead of checking for the dtoverlay change in config.txt I think it would be smarter/better to simply check if the underlying hardware is a RaspberryPi-Zero and if so activate it accordingly.

Or do you think that there is some use-case for also having USB Gadget mode available for anything else than a RaspberryPiZero (RaspberryPi3, etc.?!?)

[fhirschmann]

There is no time pressure. :)

I think the problem with enabling this by default is that it would break any USB dongles people attach to the Zero. I don't know if this is a common use case, but people may also attach an Ethernet adapter via USB.

I don't think it makes sense to enable gadget mode for anything but the Zero, because other boards usually have ethernet.

[jens-maus]

Ok, haven't tested Gadget mode myself yet. But does that mean that if the dwc2.dtbo is loaded in config.txt then the whole USB port is not available for other USB devices anymore? Or does this just happen at the time the init script is executed? Because then we could add some actual env variable checking and just execute the modeprobe calls if the user has added this specific ENV variable to his environment.

[fhirschmann]

It is my understanding that dwc2 disables the root hub of the pi in favour of gadget mode. However, I have not tested this.

According to config.txt's documentation, it is also possible to have include statements in config.txt. We could include an empty user config that survives any updates. I do not think we can put this into /usr/local, because it is not mounted during boot time.

By the way, the other Raspberries do not support gadget mode.

[jens-maus]

Could you please test if loading dwc2.dtbo in config.txt alone already takes over the whole USB or if loading the module does this?

[fhirschmann]

I had some time to test this now. I attached to the serial port of the pi zero, and the usb port seems to stay active no matter what I do, even after loading g_ether. Hence, it should be safe to enable the overlay by default (at least on the pi zero).

In addition, it is also possible to load the overlay at run time using the dtoverlay command and move everything except the udev rule to the init script. This way, we can do all the platform checking in the init script itself.

The only problem is that dtoverlay is somehow broken on RaspberryMatic:

# dtoverlay
dtoverlay: error while loading shared libraries: libfdt.so: cannot open shared object file: No such file or directory

The lib is actually missing on the RaspberryMatic image, but is there after building it from soruce in build-raspmatic_rpi0/host/lib. I do not yet know enough about buildroot to include it in the image.

[fhirschmann]

Ok, I found the missing lib via make menuconfig -> Target packages -> Libraries -> Hardware handling -> dtc. I'll try to rebuild RaspberryMatic and include everything in the init script.

[jens-maus]

@fhirschmann why do you need configfs in fstab? IMHO this is not required and should be omitted.

[fhirschmann]

@fhirschmann why do you need configfs in fstab? IMHO this is not required and should be omitted.

The dtoverlay command line utility does not work without configfs. If you still want to just include dwc2.dtbo by default and not the init script, I can remove the functionality to only enable it optionally.

[fhirschmann]

I still cannot get the dtoverlay command to work reliably. I guess some more digging is required.

[fhirschmann]

@jens-maus, I can now confirm this working and ready to merge. dwc2 is enabled by default and gadget mode is enabled after creating /etc/config/gadgetEnabled on the userfs, i.e. /usr/local/etc/config/gadgetEnabled on RaspberryMatic.

The USB ports still works with the default RaspberryMatic configuration. I tested this with an USB keyboard.

[jens-maus]

Thanks. However, can you please also test USB Sticks and large file transfers, etc. Because the dwc2 overlay replaces the whole USB driver AFAIK. In addition, please also test old RaspberryPis like Pi1 because the rpi0 image is also used by these hardware models.

[fhirschmann]

Unfortunately, I neither have the time nor the equipment (pi1) for these tests. Hence, I suggest to not touch config.txt and then leave it up to the user to modify config.txt like in my initial proposal.

The other option, the dtoverlay command, seems to require a lot of work and changes to RaspberryMatic to work reliably. On vanilla raspbian, it just works though.

The third option is of course to close this PR and I can provide a patch against RaspberryMatic to enable gadget mode for users to apply and compile themselves.

[jens-maus]

What‘s the problem with dtoverlay command exactly?!? Shouldn‘t it work reliably when configfs is added to fstab?

[fhirschmann]

I think configfs isn't enough for dtoverlay to work reliably. There were some errors that dtoverlay-pre and dtoverlay-post cannot be found, but looking at these shells scripts it seems this should not be an issue. I think I need to dig into the differences between raspbian and buildroot to see what exactly is missing.

[jens-maus]

I just had some time in testing your proposed changes here and in fact, it works! :) Great job. Thus, I will merge your PR into master and get it stabilised there with some more minor changes applied (e.g. applying it also to the recoveryfs setup...)

Thanks again for this great PR!