TinyUSB component package version doesn't match documentation (IEC-357)

[projectgus]

Answers checklist.

• I have read the component documentation ESP-IDF Components and the issue is not addressed there.
• I am using target and esp-idf version as defined in component's idf_component.yml
• I have searched the issue tracker for a similar issue and not found any related issue.

Which component are you using? If you choose Other, provide details in More Information.

device/esp_tinyusb

ESP-IDF version.

v5.4.2

Development Kit.

ESP32-S3-DevKitC

Used Component version.

1.7.6~1 with tinyusb component 0.18.0~4

More Information.

This issue report relates to the tinyusb component, not esp_tinyusb, but that repo has GitHub issues disabled.

The documentation for ESP-IDF Component Manager says that the "Revision" version increments when "there are only downstream code changes between two revisions." This is not the case for recent revision increments of the TinyUSB component which contain unreleased breaking changes from upstream TinyUSB.

For example, TinyUSB commit hathach/tinyusb@db53786#diff-d34d3b84d6fa19c64b96ed57ceae385cfddea1c7e74e76f55ffe61f2eb2ddf2cR54-R67 makes a backwards incompatible behaviour change (new flag tx_overwritabe_if_not_connected). This change is not yet released in any TinyUSB version, but it's included in Espressif downstream releases v0.18.0~3 and v0.18.0~4. According to the versioning documentation this shouldn't happen.

This new flag has caused a regression in MicroPython (the CDC FIFO mode becomes blocking). It's hard for us to work around it because according to the TinyUSB version macros this is TinyUSB v0.18.0. This is clearly not true, this version is actually a random snapshot of TinyUSB upstream master branch.

If it's necessary to release components based on unreleased upstream TinyUSB then suggest tagging them as v0.19.0-dev0 or similar (with a change in the TUSB_VERSION macros as well, if possible, for projects like MicroPython that also use upstream TinyUSB). This would be compatible with ESP-IDF's own component version documentation, and make it easier for users to understand that there may be new - possibly unstable - code changes included from upstream.

[github-actions]

Hi @projectgus! Please be aware that the following suggestions are generated by a bot and haven't been fact-checked by Espressif Systems. We hope that this message will help you until an Espressif Engineer looks at your issue.

---

Thank you for your detailed report and for referencing the ESP-IDF Component Manager versioning documentation.

Based on the available knowledge sources, your observation is correct: the Espressif tinyusb component (e.g., v0.18.0~4) is based on a snapshot of the upstream TinyUSB repository, not strictly on the official TinyUSB v0.18.0 release. The component documentation confirms that Espressif's tinyusb is an upstream fork integrated into the ESP-IDF build system, but it does not specify the exact upstream commit or clarify how versioning is handled when unreleased upstream changes are included. The documentation also does not address the use of pre-release or development tags (such as v0.19.0-dev0) for such cases, nor does it mention updating the TUSB_VERSION macros to reflect the true upstream state of the codebase being used Espressif TinyUSB component.

Your suggestion to use a versioning scheme that clearly indicates when the component is based on an unreleased upstream snapshot (e.g., v0.19.0-dev0) is reasonable and aligns with the ESP-IDF Component Manager's guidance that revision increments should only be used for downstream changes, not for upstream breaking changes. However, the knowledge sources do not provide any official Espressif policy or guidance on this specific scenario.

In summary, your report is valid, and the current versioning approach for the tinyusb component does not appear to follow the documented guidelines. There is no information in the knowledge sources about plans to address this or about recommended practices for handling unreleased upstream changes in component versioning. Your feedback and suggestion would be valuable for the maintainers to consider for future releases.

If you need to reference this in your issue, you can cite the Espressif TinyUSB component documentation as the source for the current state of the component and its versioning.

[tore-espressif]

Hello Angus,

thank you for pointing out the problem, and sorry for the trouble it has caused.
We intended to provide ESP users with more frequent TinyUSB updates, but we overlooked this breaking change. Since upstream TinyUSB does not release often enough to keep pace with our new chip support, our plan is to start using our own versioning scheme. This should help us avoid similar issues in the future.

That said, we would like to avoid yanking the already published version 0.18.0~4.
Would it be acceptable for you to pin TinyUSB to a specific version in MicroPython?
Going forward, we will release 0.19 and later versions in sync with upstream TinyUSB releases.

(Note: v0.19.0-dev0 is a pre-release version, so version solvers will not select it by default.)

[projectgus]

@tore-espressif Thanks for the quick and thoughtful response, I appreciate your explanation. I didn't expect that you'd yank the version or anything like that, I only wanted to make you aware for future releases.

We will indeed pin the version in MicroPython now (and this was a good reminder to be vigilant about tracking dependency lock files!)

Setting up your own Espressif TinyUSB versioning scheme seems like a good path forward.