Skip to main content
D
DSebastian
Associate II
May 3, 2026
Solved

Import ioc-file into existing project - workflow in CubeIDE 2.x not totally clear

  • May 3, 2026
  • 6 replies
  • 333 views

Hi,

using STM32CubeIDE 2.1.1 and STM32CubeMX 6.17, I'm a little confused on how to import an existing ioc-file created by CubeMX into an existing project in CubeIDE. And to later modify it.

Confusion is drawn from this tutorial: https://community.st.com/t5/stm32-mcus/stm32cubeide-2-0-0-workflow-tutorial/ta-p/864831 

At the end, it is somehow saying to use the import function of CubeIDE for an ioc-File which is located (physically) on a different location than the project itself (ioc-file in §2.3 tutorial c:/users/ST/Documents while project is in workspace 2.0.0, from which I assume it is stored in a different folder).

Then, later on in §2.5, MCU gets some modification (added I2C in the example) and code is newly generated (in c:/users/ST/Documents and CubeIDE requires a refresh (F5) to capture the updated MCU configuration) (see also equivalent video tutorial at around 4:05min)

So good, so confusing. Why?

1) CubeIDE shows the ioc-file in the project tree, and is physically stored in the folder as the project (see attached screenshot)ioc-File in product tree and storage locationioc-File in product tree and storage location

Note that workspace is "Cpp_KeithBentely" (I'm investigating usage of C++).

So why is the ioc-File not directly saved in the location of the project? And the need to refresh is somehow indicating that there is a link between the ioc-File generated by CubeMX and the ioc-File used by CubeIDE. As, hopefully made clear enough, there are two ioc-files ... Shouldn't be one sufficient?

So, why not simply doing something like, where the new ioc-file is directly stored inside the workspace's folder on the harddisk. Note that project location is actually the workspace!

Screenshot 2026-05-03 125103.png

What I simply fear is something might be broken by doing so. Bascially because I haven't understood this eclipse-world just to a minor fraction in best case.

End of Question 1.

Question 2:

In the tutorials of CubeIDE 2.x it is said that CubeMX shall be launched separately to modify the MCU's configuration. Hm, I still can double click on the ioc-File in CubeIDE and CubeMX opens. Is this, even possible, forbidden to do?

Screenshot 2026-05-03 125724.png

You see, I haven't understood the new philosophy. I hope you can help in put some light into the dark.

 

Best answer by Pavel A.

@DSebastian 

>  I have no experience about workflow in CubeIDE 1.x because I just recently started with STM32

This is only to the better IMHO, you just skipped developing wrong habits :)

Then, here's a very simple explanation - assuming the "old" project is not based on .ioc and Cube-generated files (but may use the "HAL" and "middleware" libraries of older versions).

 1. Start clean with CubeMX, create a new project for your board (or find a closest ST example that has an .ioc ). This will, of course, contain nothing of your custom code.

 2. Compare it with the "old" project. Are the structures of two projects totally different or have something in common ?(besides the startup .s file and system_stm32xx.c)  Does merging them look viable?

3. Now you have a principal choice: merge the old one to the new one and maintain your project further with CubeMX and .ioc, or stay with the original code and transplant just the pieces and changes from the cube-generated project (which you'll have to keep aside).

In the former case, of course, mind the "user areas" and move as much of your code out of the cube generated files to your own. Even then, be prepared to "surprises" when CubeMX code generation suddenly acts up and breaks things. This happens sometimes, even to the modern AI things.  Use version control.

Hope this looks much less confusing now.

6 replies

Pavel A.
Pavel A.
Super User
May 3, 2026

> Note that project location is actually the workspace!

Not sure about CubeIDE 2.x behavior, but generally Eclipse CDT does not like when a project root directory is same as the workspace directory. This isn't forbidden explicitly but known as a sure recipe for problems.

 

    D
    DSebastianAuthor
    Associate II
    May 3, 2026

    Not sure about CubeIDE 2.x behavior, but generally Eclipse CDT does not like when a project root directory is same as the workspace directory.

    Probably some misleading wordings in the GUI of STM32CubeMX - I had similar thoughts as you, but at the end, in conjunction with "Project Name" a sub-folder is created (named what has been entered in the field "Project Name")  under the folder "Project Location", which actually STM32CubeIDE will identify as workspace later on.

    So, with "Project Name" = "Cpp_KeithBentley" and "Project Location" = "51_Cpp_Test" I get the folders as shown below, and its equvialent in CubeIDE

    File LocationsFile LocationsView in CubeIDEView in CubeIDE

    So root directories are actually not the same. The project is one level below.

    Despite, what came into my mind is that there seems to be a link between the original ioc-file and the imported one. I.e. the imported ioc-file at one physical location is still linked to its origin at another physical location. So when taken from another project it will updated also when its original has been updated. Kind of bad if not desired. A solution could be if it is possible to break that link - any chance to do this?

    Pavel A.
    Pavel A.
    Super User
    May 3, 2026

    Well, then to the point of importing .ioc file into existing CubeIDE project.

    Was the project initially created by some version of standalone CubeMX or integrated in CubeIDE 1.x?

    Not all CubeIDE projects are (or must be) associated with .ioc files.  They are just sort of Eclipse CDT projects. Many older examples are not based on CubeMX at all.

    AFAIK if a project has not been created with CubeMX, there is no any "automatic" workflow for adopting CubeMX generated code into it. The merge can be done manually, it's boring but not a rocket science.

    The change from CubeIDE 1.x with integrated CubeMX is that standalone CubeMX (the only option for CubeIDE 2.x) no longer insist that .ioc file must be in certain location or has the same name as the Eclipse project. It just generates the new code where ever the .ioc file happens to be. If you just put a .ioc file in existing project, generation with standalone CubeMX can corrupt the existing project. Take caution, make backups, merge new and existing code carefully.

     

    D
    DSebastianAuthor
    Associate II
    May 5, 2026

    Hi Pavel,

    first of all, I have no experience about workflow in CubeIDE 1.x because I just recently started with STM32, and so with CubeIDE 2.x from the very beginning. So any reference to workflow in CubeIDE 1.x will run, at least for my brain, nowhere ;)

    " If you just put a .ioc file in existing project, generation with standalone CubeMX can corrupt the existing project."

    Any specific procedure to do this in mind? What I tried is the following:

    1. In CubeIDE copy an existing project A and paste as project B with ioc file MX_A.ioc
    2. Project B as still ioc-file MX_A
    3. Open MX_A.ioc in CubeMX, modify it and save it into the folder of Project B as MX_B.ioc by "save project as"
    4. Project B has not two(!) ioc-files: MX_A and MX_B
    5. Code is created new, but code between /* User xxx Begin ...*/ and /* User xxx End */ is untouched.

    Just short feedback, I'm not totally sure if I have written my steps correctly - I have some time constraints and so can not investigate further every in a timely manner. At the end, to let you know what I'm investigating.

    As of know, I tried simply opening CubeMX by double click in CubeIDE, or letting CubeMX generating code into existing project. Don't know that is the better approach; the later one appear the more attractive one as it comes closer to the the idea of importing ioc-Files. The idea of copy and paste is that steps to merge CubeMX' generated code with own one seems not to be required is, as written above, everything is only (and only!) inside the dedicated "user-areas" sourround by the comments "/* User Begin */" and "/* User End*/"

    And, oh, if that sound all a little confused - this reflects my understanding as of today. As said, I will further play around, but it will take some time to do so.

    Pavel A.
    Pavel A.Answer
    Super User
    May 5, 2026

    @DSebastian 

    >  I have no experience about workflow in CubeIDE 1.x because I just recently started with STM32

    This is only to the better IMHO, you just skipped developing wrong habits :)

    Then, here's a very simple explanation - assuming the "old" project is not based on .ioc and Cube-generated files (but may use the "HAL" and "middleware" libraries of older versions).

     1. Start clean with CubeMX, create a new project for your board (or find a closest ST example that has an .ioc ). This will, of course, contain nothing of your custom code.

     2. Compare it with the "old" project. Are the structures of two projects totally different or have something in common ?(besides the startup .s file and system_stm32xx.c)  Does merging them look viable?

    3. Now you have a principal choice: merge the old one to the new one and maintain your project further with CubeMX and .ioc, or stay with the original code and transplant just the pieces and changes from the cube-generated project (which you'll have to keep aside).

    In the former case, of course, mind the "user areas" and move as much of your code out of the cube generated files to your own. Even then, be prepared to "surprises" when CubeMX code generation suddenly acts up and breaks things. This happens sometimes, even to the modern AI things.  Use version control.

    Hope this looks much less confusing now.

    D
    DSebastianAuthor
    Associate II
    May 7, 2026

    Hi,

    still not on the road of success.

    First have a look on my sketch below, in which I tried to draw what I like to do.

    STM32_WhatToDo.jpg

    So, far I have seperated folders on harddisk to seperate projects created by CubeMX and CubeIDE. On the bottom the desired "what I want to do" is outlined. It is developping an application with several version (initial, a feature added, code clean up)

    So far, the intial phase is doing fine. Project created in CubeMX in folder MX, generated code (in CubeMX), then close CubeMX, open CubeIDE and import project into CubeIDE. Link to ioc-File in Folder MX is maintained, i.e. when I modify something here, it will be updated in CubeIDE automatically, fine!

    But then, Project B is created (i.e. the next version) by copy and paste (because I like to maintain all my user code). Then, ioc-File is not anymore referenced to the one in folder MX but in folder IDE (well, a copy created in IDE, so appears logical)

    Unfortunately (see black arrow with ???) the import function is not available anymore, see below (Please note that I trying to import from folder MX (here: MX_Repository). It is not selectable (box can not be ticked, button select all is not doing anything)

    Screenshot 2026-05-07 225449.png

    Well, what does work is when I generated code directly from CubeMX into the workspace of CubeIDE - to the price that all user code gets deleted :( (there is a corresponding warning up front, so not a surprise at the end)

    Now one my say: I try manual version control through creating various projects. Hm, yes, this is somehow the intention. 

    So it sounds like manual merging, but, huh, that doesn't sound very smart. Except there is a list of files/folder I can just overwrite as long as the MCU (/board) remains the same? Ehm, really?

    No, I don't get it. With CubeMX as stand-alone application, projects in CubeMX have their own lifecycle, which can be, in general, different to the projects in CubeIDE. Still not where I like to be ...

    D
    DSebastianAuthor
    Associate II
    May 14, 2026

    Hi,

    I stopped further investigations on it with following conclusions:

    • My understanding is that there is strict one-to-one relationship between a CubeMX generated .ioc-file and a project in CubeIDE provided automatic update of main.h and main.c is desired when the .ioc-file is updated through CubeMX
    • THUS, creating a new project on CubeIDE requires an individual .ioc-file (easy in CubeMX just use "Save Project As"), and then merging files in CubeIDE is required.
    • For merging it is, as written by Pavel, quite helpful to leave main.h / main.c as fast as possible to keep efforts for merging low. Since I want to use C++ for my own code, I use the approach described here (https://shawnhymel.com/1941/how-to-use-c-with-stm32cubeide/) by Keith Bentley in the comment section, i.e. not the approach described by Shawn Hymel). It is working quite well for me (tested within my investigations driving an display using u8g2-Library and reading SD-card using the library of kiwih (https://github.com/kiwih/cubeide-sd-card))
    • Merging as manual task is boring (agree to Pavel here), but as said, no I could not find other solution. With the approach of leaving main.h/.c quickly it is limited to add/check just a few lines of code in the USER-Areas, and adjust project properties where individual changes have been made.

    Take this as a solution, however, marked Pavel's comment as solution because he made me thinking into the right direction (despite the not totally satisfying result, which is caused by CubeIDE/MX working principles)

    Final remark: I'll investigate version control, but this is another topic.

    Terms & ConditionsAccessibility statement