Skip to content

Add support for TinyUSB Arduino Library #5333

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 15 commits into from

Conversation

hathach
Copy link
Contributor

@hathach hathach commented Jun 27, 2021

NOTE: This PR is superseded by adafruit/Adafruit_TinyUSB_Arduino#126 and can be safely closed now. 
Please update  Adafruit_TinyUSB_Arduino to version 1.5.0 to use with arduino core version 2.0.0

Adafruit has an Arduino version of TinyUSB https://github.com/adafruit/Adafruit_TinyUSB_Arduino, which provide cross-platform API for nrf, samd, rp2040 and is growing. I am hoping we could add support for esp32s2/s3 as well and this PR is doing just that with:

  • Add additional USB Stack menu to select existing stack provided by core or one provided by the Adafruit_TinyUSB_Arduino. Which requires a few #ifdef around core's USB code. USE_TINYUSB is macro to indicate the library is selected by user. (kind of odds since both use tinyusb, however, the name is introduced way back when we doing this for samd core which use Arduino pluggable stack). This menu option allow this PR to not change any behavior of existing cores at all.
  • Adafruit_TinyUSB_Arduino libraries is self-contained, it includes the entire tinyusb stack, and tusb_config, which allow is to be easily updated with latest usb stack without waiting for IDF release and have easy class driver customization for user without touching file within arduino-esp32 core.
  • All examples drivers are tested and working including CDC, HID, MSC, MIDI, WebUSB. And there are more to come in the future.
  • I also take the chance to correct USB VID for some of Adafruit boards.

Some background note: Unlike SPI/I2C, USB library is particularly difficult to be standalone, since arduino consider CDC Serial as part of the core, which require cdc header must be included by Arduino. This can be resolved by adding USB as one of bundles libraries and adding include path "-I{runtime.platform.path}/libraries/Adafruit_TinyUSB_Arduino/src/arduino" to prevent compile error. I am sorry for huge file changes of this PR due to addition of the libary. Normally I would do a submodule, however, I figure out this core does not use submodule. Normally this library does not need to be updated, since the newer version installed via IDE will overwrite this. Though, when there is breaking changes in API (only with cdc header), I will take responsibility to make update PR to get it all in sync with other MCU cores.

Please let me know if you are interested in the PR (or want to change its implementation etc ..). This will have an great addition, since Adafruit already has a numerous of library built around this TinyUSB API.

Screenshot from 2021-06-27 14-34-38

@ladyada

@CLAassistant
Copy link

CLAassistant commented Jun 27, 2021

CLA assistant check
All committers have signed the CLA.

@me-no-dev
Copy link
Member

Hi @hathach :) is there any way that we can have a talk about this? Maybe there is a better way to do it :)

BTW Arduino does not use TinyUSB from IDF, it has it's own and is regularly updated to the latest version (actually any time the IDF libs are built, latest TinyUSB is introduced.

I think it should be possible to use the tinyUSB we provide and just have the rest of te adafruit included. Maybe we need to sync up the config, but that should be more or less it.

@hathach
Copy link
Contributor Author

hathach commented Jun 27, 2021

Hi @hathach :) is there any way that we can have a talk about this? Maybe there is a better way to do it :)

BTW Arduino does not use TinyUSB from IDF, it has it's own and is regularly updated to the latest version (actually any time the IDF libs are built, latest TinyUSB is introduced.

Yeah, I know, it just an user-friendly term :D to make it easier for user to understand. Let me know which name you would prefer.

I think it should be possible to use the tinyUSB we provide and just have the rest of te adafruit included. Maybe we need to sync up the config, but that should be more or less it.

Yeah, sure once of the issue is with the tinyusb callback, since the library is designed to run all on cores. It does assume it has to done everything from constructing the configuration descriptor, handling all the callbacks etc ... I will probably requires lots of coupling between the core and library. This is actually best way so far I could come up. It is actually not that interfered to the core. Don't worry about the file changes, it is mostly only the inclusion of the library file. If you do a core file compare, it has little changes to core and how core manage USB. If you have some time, please give it a try.

PS: There is no duplication code in the flash otherwise we could have linker error. The linker just prefer to pick function from the library than the arduino_tinyusb one.

@me-no-dev
Copy link
Member

So, Adafruit_TinyUSB has two parts inside: The Arduino code and your TinyUSB source. What I proposed is to not include the TinyUSB source at all since that is already present and precompiled. If you just decouple our Arduino USB code from it, you should be set to use just the Arduino part of Adafruit and skip compiling the whole TinyUSB all over again.

@me-no-dev
Copy link
Member

arduino_tinyusb is just this: https://github.com/espressif/esp32-arduino-lib-builder/tree/master/components/arduino_tinyusb

the config and patched DCD for persistence (WIP). when persistence is stable and make it into TinyUSB itself, that source file will disappear as well.

@hathach
Copy link
Contributor Author

hathach commented Jun 27, 2021

So, Adafruit_TinyUSB has two parts inside: The Arduino code and your TinyUSB source. What I proposed is to not include the TinyUSB source at all since that is already present and precompiled. If you just decouple our Arduino USB code from it, you should be set to use just the Arduino part of Adafruit and skip compiling the whole TinyUSB all over again.

Ah that would be doable, though, since the library is also used by other MCU such as samd/nrf core which does has built-in tinyusb support. Those files still need to be there since it is currently used on nrf,samd and rp2040.

I could write a script to wrap all tinyusb sources within #ifndef ARDUINO_ARCH_ESP32. The more difficult issue is the multiple definition of callbacks mentioned here chegewara/EspTinyUSB#36 . Where the menu selection is used to address those.

arduino_tinyusb is just this: https://github.com/espressif/esp32-arduino-lib-builder/tree/master/components/arduino_tinyusb the config and patched DCD for persistence (WIP). when persistence is stable and make it into TinyUSB itself, that source file will disappear as well.

Ah I see, If you prefer the library to link with it. There should be no problems at all, though sometime there could be some API changes where the library/stack move a bit more aggressive than the one come with IDF. But it is all solvable with ifndef.

Anyway, please take your time to try it out and if possible, make any adjustment/modification as you see fit. I am not in rush, I actually expect this PR to be in review for quite some time. It is always a big PR to add it to a core BSP.

@me-no-dev
Copy link
Member

@hathach the version of TinyUSB in ESP-IDF is not related to Arduino at all :) For example, the lib builder pushed new libs to this PR last night: #5336
It includes the TinyUSB master from last night as well. It always provides the very latest source at time of compilation.
It is done by this part of the script: https://github.com/espressif/esp32-arduino-lib-builder/blob/master/tools/update-components.sh#L109-L119, so you can rest assured that the precompiled TinyUSB is always very recent.

@hathach
Copy link
Contributor Author

hathach commented Jun 28, 2021

@hathach the version of TinyUSB in ESP-IDF is not related to Arduino at all :) For example, the lib builder pushed new libs to this PR last night: #5336
It includes the TinyUSB master from last night as well. It always provides the very latest source at time of compilation.
It is done by this part of the script: https://github.com/espressif/esp32-arduino-lib-builder/blob/master/tools/update-components.sh#L109-L119, so you can rest assured that the precompiled TinyUSB is always very recent.

Superb !! That is great to hear, that could simplify the menu selection without having to pick the correct include path to tusb_config.h. I will do more update with the PR, let me know if there is any other modification that you want to make :)

@me-no-dev
Copy link
Member

If you find that the included config is missing something, please add PR to the lib builder's usb config and that will then be pushed on the next build :) https://github.com/espressif/esp32-arduino-lib-builder/blob/master/components/arduino_tinyusb/include/tusb_config.h

@hathach
Copy link
Contributor Author

hathach commented Jun 28, 2021

If you find that the included config is missing something, please add PR to the lib builder's usb config and that will then be pushed on the next build :) https://github.com/espressif/esp32-arduino-lib-builder/blob/master/components/arduino_tinyusb/include/tusb_config.h

Sure thing, that repo is kind of new to me as well. I don't quite catch up with changes from ESP 😅 I am looking to hear more feedback from you for the implementation and usage. Once checkout, you could run most examples in https://github.com/adafruit/arduino-esp32/tree/add-tinyusb-arduino/libraries/Adafruit_TinyUSB_Arduino/examples . There are some that aren't compatible mostly with SdFat - Adafruit Fork since may not yet be ported to work with esp32s2. Others should be just fine.

@hathach hathach force-pushed the add-tinyusb-arduino branch from 5f73f2e to 1d61f79 Compare July 12, 2021 06:56
@hathach
Copy link
Contributor Author

hathach commented Jul 12, 2021

@me-no-dev I have updated the PR following your request, using tusb_config.h from core's arduino_tinyusb and libarduino_tinyusb with included usb library. Please check it out to see there is any other request you would like to make.

In addition, I need a bit of help to fix ci build. All the examples within the libraries/Adafruit_TinyUSB_Arduino/examples requires the corresponding menu selection of "Adafruit TinyUSB". I am not entirely sure which is the best way to do this, If it is too problematic, I could remove these examples, user can just go to the actual library repo's example instead https://github.com/adafruit/Adafruit_TinyUSB_Arduino/tree/master/examples

fqbn=esp32:esp32:esp32s2:SerialMode=default,PSRAM=disabled,PartitionScheme=default,CPUFreq=240,FlashMode=qio,FlashFreq=80,FlashSize=4M,UploadSpeed=921600,DebugLevel=none,USBStack=tinyusb

@me-no-dev
Copy link
Member

@hathach I need to figure out how to implement custom board definitions for particular example builds in CI. No worries, will get to it :)

@hathach
Copy link
Contributor Author

hathach commented Jul 12, 2021

@hathach I need to figure out how to implement custom board definitions for particular example builds in CI. No worries, will get to it :)

I hope that wouldn't be issue, we can either skip all examples in CI or remove it for now to get CI happy. More importantly is the rest of modification, please give it a try, I would love to hear your feedback.

@hathach
Copy link
Contributor Author

hathach commented Sep 29, 2021

thanks to #5466 that declared most of tinyusb callback as weak function. It is possible now to have external USB libraries (Adafruit_TinyUSB_Arduino) co-exist with with usb code from core. This PR is superseded by adafruit/Adafruit_TinyUSB_Arduino#126 and can be safely closed now.

Thank @me-no-dev for making the changes to allow this since Adafruit_TinyUSB_Arduino is needed for @adafruit ecosystem. Because its API is widely used across existing cores (nrf, samd, rp2040) with lots of existing libraries.

Note: there is an esp32s2 port limit: dynamically changes the configurations is not possible since esp32-hal-tinyusb.c requires all descriptors must be config/set in constructor manner ( pre-setup() )

@hathach hathach closed this Sep 29, 2021
@hathach hathach deleted the add-tinyusb-arduino branch December 10, 2021 17:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants