How to Handle main.h Includes Without Circular Dependencies in CubeMX Projects?

[Bobbyschev]

Hi all,

I keep running into a circular include problem in STM32 CubeMX projects:

• main.h is auto-generated and contains pins and peripheral handles.

• main.c must include main.h (CubeMX forces it).

• User modules (i2c_user, adc_user, etc.) need access to pins/handles, but including main.h in them causes circular dependencies.

Workarounds I’ve tried:

• Creating a board.h wrapper — but CubeMX regenerates main.h, so it requires constant manual updates.

• Passing handles/pins as function arguments — clean but cumbersome.

• Including user modules only in main.c — works, but feels messy and unclear.

My question: How do you handle this in real-world CubeMX projects? Is there a clean pattern that survives main.h regeneration and avoids circular includes?

Sorry if this is not the perfect section of the forum, but I believe this topic is quite relevant due to the challenging architecture of the generator.

Thanks!

[TDK]

Include guards prevent include files from being ran more than once per compilation unit.

There should be no issues with the files that CubeMX generates in terms of this. If you have an IOC file which is producing bad output, please include it here so the issue can be replicated.