Fixing AT32F405 USB HS: A Missing Definition Solved!

Aug 3, 2025 by Omar Yusuf 53 views

AT32F405 USB HS Not Working? Missing `TUP_RHPORT_HIGHSPEED` Definition Fixed!

Hey everyone! Today, we're diving deep into a fascinating issue encountered while working with the AT32F405 microcontroller and its USB High-Speed (HS) capabilities within the TinyUSB framework. Specifically, we'll explore a problem where the USB HS functionality wasn't working as expected due to a missing definition: TUP_RHPORT_HIGHSPEED. Let's get started!

The Problem: AT32F405 USB HS Not Recognized

So, the core issue was that a custom board based on the AT32F405 wasn't being recognized by the host computer when attempting to use USB HS. This can be a major roadblock, especially when you're relying on high-speed data transfer for your application. The user, who goes by peppapighs, encountered this while working on a custom firmware project. They were using Windows 11 and the latest TinyUSB commit (87d9e05efa951d6e1b1c63cbb7f4261be96741e1) at the time.

Digging deeper, the firmware was set up similarly to the AT32F405's family.c within the TinyUSB library, with the RH port (Root Hub Port) set to 1 for USB HS. However, despite this configuration, the board remained unrecognized. This is where the troubleshooting journey began, and it led to an interesting discovery related to a missing definition.

When dealing with USB issues, especially at the hardware level, it's crucial to verify the clock configurations. USB HS requires a precise 480MHz clock to function correctly. If the clock isn't properly set up, the device won't enumerate, or you might experience other erratic behavior. Ensure that the PLL (Phase-Locked Loop) is correctly configured and that the USB clock source is properly selected in your code. Check the reference manual for your specific microcontroller to understand the clock tree and how to configure it for USB HS operation.

Another common pitfall is incorrect pin configurations. USB data lines (D+ and D-) need to be connected to the correct pins on the microcontroller. Double-check the datasheet for your AT32F405 and ensure that the USB data lines are mapped to the appropriate pins as defined in your hardware schematic. Sometimes, a simple mistake in the pin mapping can prevent the device from being recognized.

Lastly, power supply issues can also lead to USB failures. Make sure that your board is receiving the correct voltage and that there are no voltage drops or fluctuations that might affect USB operation. If the USB transceiver doesn't receive sufficient power, it won't function correctly. It's always a good practice to use a stable power supply and ensure that the voltage levels are within the specified range for your microcontroller and USB circuitry.

The Solution: Defining `TUP_RHPORT_HIGHSPEED`

The breakthrough came when peppapighs identified that the missing piece of the puzzle was the TUP_RHPORT_HIGHSPEED definition. By adding this definition to the tusb_mcu.h file, the issue was resolved. Here's the code snippet that fixed the problem:

#elif TU_CHECK_MCU(OPT_MCU_AT32F402_405)
  #define TUP_USBIP_DWC2
  #define TUP_USBIP_DWC2_AT32
  #define TUP_DCD_ENDPOINT_MAX    8
+ #define TUP_RHPORT_HIGHSPEED    1

This seemingly small change made a significant difference. By defining TUP_RHPORT_HIGHSPEED, the firmware was now able to properly initialize and utilize the USB HS functionality of the AT32F405. The board was finally recognized by the host, and the USB HS connection was established.

Understanding the role of TUP_RHPORT_HIGHSPEED is key to grasping why this fix worked. This definition essentially tells the TinyUSB stack that the USB High-Speed functionality is enabled on the specified Root Hub Port. Without this definition, the stack might not initialize the USB HS PHY (Physical Layer) correctly, leading to the device not being recognized.

However, there's a catch! The AT32F402 doesn't actually support USB HS. So, while this fix worked for the AT32F405, it raises a question about the broader implications of this change. Is this the correct way to handle this, considering the different capabilities of the AT32F402 and AT32F405?

Why This Fix Works (and the Potential Caveat)

So, you might be wondering, why does defining TUP_RHPORT_HIGHSPEED make such a difference? Let's break it down. This definition essentially tells the TinyUSB stack that the USB High-Speed functionality is enabled on the specified Root Hub Port. Without this, the stack might not properly initialize the USB HS PHY (Physical Layer), which is the hardware interface responsible for handling high-speed USB communication. Think of it as flipping a switch that tells the microcontroller, “Hey, we're going to use USB HS!”

Now, here’s the slightly tricky part. The fix was applied within a conditional block that checks for both the AT32F402 and AT32F405 MCUs. While the AT32F405 does support USB HS, the AT32F402 does not. This means that this fix might inadvertently enable USB HS settings for the AT32F402, even though it's not capable of running at those speeds. This could potentially lead to unexpected behavior or issues on AT32F402-based systems. It's like putting racing tires on a car that can't go over 60 mph – it won't hurt, but it won't help either.

This is where the importance of targeted configurations comes into play. Ideally, we want to define TUP_RHPORT_HIGHSPEED only when we're dealing with an AT32F405. This ensures that we're enabling USB HS only on devices that actually support it. A more robust solution might involve adding a specific check for the AT32F405 within the tusb_mcu.h file, like this:

#elif TU_CHECK_MCU(OPT_MCU_AT32F405)
  #define TUP_USBIP_DWC2
  #define TUP_USBIP_DWC2_AT32
  #define TUP_DCD_ENDPOINT_MAX    8
  #define TUP_RHPORT_HIGHSPEED    1
#elif TU_CHECK_MCU(OPT_MCU_AT32F402)
  #define TUP_USBIP_DWC2
  #define TUP_USBIP_DWC2_AT32
  #define TUP_DCD_ENDPOINT_MAX    8
  // No TUP_RHPORT_HIGHSPEED for AT32F402

By explicitly checking for each MCU type, we can ensure that the TUP_RHPORT_HIGHSPEED definition is applied only where it's needed. This kind of precision in configuration is crucial for maintaining the stability and reliability of your embedded systems.

Reproducing the Issue

If you're curious to see this issue in action, you can try to reproduce it yourself. The user, peppapighs, has generously provided a link to their custom firmware on GitHub. By compiling and running this firmware on an AT32F405-based board without the TUP_RHPORT_HIGHSPEED definition, you should observe that the board is not recognized by the host. Then, by applying the fix, you should see the USB HS connection come to life. This hands-on approach can be incredibly valuable for understanding the problem and the solution.

However, there's a small challenge in this case. Peppapighs mentioned that their custom board doesn't have a UART (Universal Asynchronous Receiver/Transmitter) interface available. This means that we can't easily capture debug logs, which would typically provide valuable insights into what's happening under the hood. Debug logs can be a treasure trove of information, showing the step-by-step execution of your code and any errors or warnings that might occur. Without them, we're relying more on observation and deduction.

If you find yourself in a similar situation, where you need to debug a USB issue without UART access, there are still some strategies you can use. One option is to use a USB analyzer, which can capture the USB traffic between your device and the host. This can give you a detailed view of the USB transactions and help you identify any issues with enumeration, data transfer, or other aspects of the communication. Another approach is to use an oscilloscope to probe the USB data lines and look for signal integrity issues or timing problems. While these methods might require specialized equipment, they can be invaluable for troubleshooting complex USB problems.

Final Thoughts and Key Takeaways

This journey into the AT32F405 and its USB HS capabilities highlights several important lessons for embedded systems developers. First and foremost, pay close attention to configuration definitions. A seemingly small detail, like the absence of TUP_RHPORT_HIGHSPEED, can have a significant impact on functionality. Always double-check your configurations and ensure that they align with the hardware capabilities of your target device.

Secondly, understand the broader implications of your fixes. While a quick patch might solve an immediate problem, it's crucial to consider whether it might have unintended consequences in other contexts. In this case, the fix worked for the AT32F405 but raised concerns about the AT32F402. A more targeted approach is often the best way to ensure long-term stability and maintainability.

Finally, debugging embedded systems can be challenging, but it's also incredibly rewarding. When you encounter a problem, take a systematic approach. Start by gathering as much information as you can, including error messages, debug logs (if available), and any relevant hardware documentation. Then, break the problem down into smaller parts and test your assumptions. Don't be afraid to experiment and try different solutions. And most importantly, share your findings with the community – you never know who else might benefit from your experience!

So, the key takeaways from this adventure are to double-check your configurations, understand the scope of your fixes, and embrace the debugging process. These principles will serve you well as you continue your journey in the world of embedded systems. Keep exploring, keep learning, and keep building amazing things!