Introducing USB MIDI gadget support

[rsta2]

There is an initial USB MIDI gadget support on the branch usb-gadget. This allows to connect the Raspberry Pi models (3)A(+), Zero (2) (W) and 4B directly to a host computer (e.g. for running a sequencer program). Before the Raspberry Pi was always the USB host with Circle and required an additional USB MIDI serial adapter for that purpose.

The sample/29-miniorgan and the test/usb-midi-send are prepared to work as a MIDI gadget. Please read the README files in the sample's / test's directory for details and infos about the required configuration. Beside the define USB_GADGET_MODE, which enables the gadget mode in the samples, you have to define your USB vendor ID as USB_GADGET_VENDOR_ID in Config.mk or include/circle/sysconfig.h. Please note that Circle does not support OTG protocols, so the USB controller always works in host or gadget mode and the connected peer must work in the opposite mode.

Adapting your own application to be used as an USB MIDI gadget should not be difficult. You have to create an object of the class CUSBMIDIGadget (see include/circle/usb/gadget/usbmidigadget.h) instead of CUSBHCIDevice and call Initialize() and UpdatePlugAndPlay() on it as before in host mode. You have to add the library lib/usb/gadget/libusbgadget.a to your LIBS variable. The USB MIDI API device umidi1 has the same interface in host mode. There is a shared base class CUSBController for CUSBHCIDevice and CUSBMIDIGadget, so it is easy to implement host and gadget mode in one application and to select it on user configuration.

I tested this support successfully with a PC/Linux 6.3.9 and a Windows 10 host. Nevertheless problems are still possible, because it's a development version.

Feedback is welcome. If you have questions, please ask them here!

[ArnoldUK]

Cool..I will check this out.

[u77345]

What structure would you recommend to generalize and implement other gadget classes, like USB TMC?

[rsta2]

There should be one C++ class for each USB device class, which is derived from CDWUSBGadget, and provides the functions, which are specific to the USB device class. For the USB MIDI device class this is CUSBMIDIGadget and for TMC is could be CUSBTMCGadget. Implementations of USB device sub-classes are possible in C++ classes, which are derived from CUSBTMCGadget for example for USB TMC.

[rsta2]

The USB MIDI gadget support is now on the develop branch and will be part of the next release. The branch usb-gadget has been removed.

[probonopd]

Hi @rsta2, this is interesting for MiniDexed. I have 2 quick questions:

• Is this a compile time option (#define USB_GADGET_MODE) or can it also be made a run-time option (e.g., using a configuration file)?
• Is it possible for the same device to act both as a USB gadget (on one USB port) and as a host (on all other ports)? Use case: I want a synthesizer to work both as a USB gadget attached to a PC, and also using a MIDI USB keyboard attached to the Raspberry Pi

[rsta2]

Hi @probonopd, the option USB_GADGET_MODE is only used in sample/29-miniorgan and test/usb-midi-send, not in the Circle libraries itself. Yes, it's possible to implement USB in a way in MiniDexed, that the USB mode (host or gadget) can be configured in minidexed.ini for example.

Unfortunately the USB gadget mode can only be used on RPis, which do not have an USB hub on board (RPi 1A(+), 3A+, Zero (2) (W)), so the answer of the second question is no. An exception is the RPi 4B, where the USB gadget mode uses the USB-C connector, which is also used for powering the RPi 4B. But you can attach the USB MIDI keyboard also to your PC, parallel to the RPi running MiniDexed in USB gadget mode. Sequencers (e.g. like Rosegarden) should be able to route the MIDI events from the USB MIDI keyboard to MiniDexed.

[probonopd]

Thanks for your detailed response @rsta2. I didn't necessarily mean to use gadget and host at the same time, but without recompilation and ideally without configuration (plug and play for both modes).

[rsta2]

Recompilation is not necessary, but configuration, because OTG protocols are not supported.

[diyelectromusic]

Does the USB gadget device have to be umidi1? If I try other device names then it doesn't seem to get registered on a plug and play event...

But if it is umidi1 then what happens if both gadget and host support is built in for a run-time configuration option? doesn't host use umidi1 onwards too?

Kevin

[probonopd]

Is there any possibility to dynamically switch between the two modes at runtime, based on which type of devices are attached to the RPi's USB port(s)?

[rsta2]

No, there is no possibility.

[diyelectromusic]

Thanks Rene that seems to be doing the trick (my first attempt was attempting to do it one step further back - it mostly worked, but this is now a lot easier :)). Another question - do I need conditional compilation for the different Pi versions or is the library already aware of when it can and can't be used?

We currently build 32-bit versions for Pi 1 and 2, and 64-bit versions for Pi 3 and 4, so the granularity at build time isn't really quite enough, but I guess there maybe options for run-time detection of specific Pi boards if required...

Thanks,
Kevin

[rsta2]

I think, the only necessary modification to the MiniDexed build system is adding the library $(CIRCLEHOME)/lib/usb/gadget/libusbgadget.a to LIBS in src/Rules.mk. But you also have to set the system option USB_GADGET_VENDOR_ID in build.sh. Please see sysconfig.h for more info on this option. If you need the RPi model, you're running on, you can use CMachineInfo::GetMachineModel().

Rene

[diyelectromusic]

Yes, I have it all up and running. I don't think MiniDexed needs to know the RPi model, the question is more does there need to be some runtime checking to prevent trying to turn on Gadget mode on a version of the board that doesn't support it. As I say, I don't think we can do that at build time...

Basically we can guarantee that if there is a config option for it, someone will enable it by mistake on a Pi that won't support it! I just want to know what expectations you have from the circle side to be sure I'm meeting them :)

Kevin

[rsta2]

If your question was, if there is a RPi model check in the Circle gadget library: No it isn't. In any way users must be careful, when they want to use the USB gadget mode, because powering the RPi may be difficult (bus-powering may not deliver enough current, and a separate power supply must have exactly the same voltage as the USB bus). And one must not connect a RPi, which is in USB host mode to an other USB host (e.g. a PC). Please read sample/29-miniorgan/ README ("USB GADGET MODE" section) and give this info to your users! Rene

[rsta2]

Thank you Kevin, I'm glad to hear, that the gadget mode is working for you!

I think, I have to add a RPi model check to Initialize() in the gadget library. I will do this soon, so you do not need to care about this any more.

But yes, this mode remains "advanced" :) and users must be careful. This forum thread about self-powering might be interesting.

Rene

[rsta2]

The RPi model check is implemented on the develop branch. I think, you have the possibility to checkout any Circle commit for build in MiniDexed, so an immediate release should not be necessary.

[diyelectromusic]

Brilliant! I'll take a look later this evening :)

Many thanks again,
Kevin

[diyelectromusic]

That all seems to work fine for me. Tested on following:

• RPi V1 B: host - ok; gadget - rejected
• RPi V1 A: host - ok; gadget - ok
• RPi Zero V1: host - ok; gadget - ok
• RPi 3 B+: host - ok; gadget - rejected
• RPi 3 A+: host - ok; gadget - ok
• RPi 4 B: host - ok; gadget - ok

So I'd say that all looks fine to me! We're just waiting on a VID/PID for MiniDexed then this should be good to go!

Many thanks,
Kevin

[rsta2]

Great. I didn't know this method to get an USB VID/PID yet. That's interesting. Thanks for testing!

Rene