MX Convert
MX Convert is a tool to convert Cube MX generated projects to the ISTSAT-2 repository structure.
Notice
This guide and the MX Convert were built with the goal of cleanly separating STM generated code from application code. As such, files produced by Cube MX are treated as disposable, and any code in said files is likely to be lost. This applies to C files, header files, CMakeLists and possibly more. Do not include any code of your own in the MX files.
When adapting existing code for use with MX Convert, make sure to back up the original code and to double check all code is present in the final version of your project.
Installation
MX Convert can be installed via pipx or pip. The pipx method is recommended as it will not mess with your system packages.
pipx method
First ensure you have pipx installed and the PATH variable set adequately:
- On Ubuntu/Debian based distros use
sudo apt install pipx && pipx ensurepath - On Arch Linux use
sudo pacman -S python-pipx && pipx ensurepath - On Fedora/Red hat based distros use
sudo dnf install pipx && pipx ensurepath
Then installation is as simple as running pipx install git+https://git.didas72.com/didas/mx-convert.git.
You can later update MX Convert with pipx update mx-convert.
pip method
To install with pip you can simply run pip install git+https://git.didas72.com/didas/mx-convert.git.
And to update use pip install --upgrade git+https://git.didas72.com/didas/mx-convert.git.
Cube MX Configuration
For simplicity of development of this tool and for uniformity across different firmware projects, the same configuration should be used when creating the projects with Cube MX.
All the relevant settings are under the 'Project Manager' tab and should be set as listed below. Any unspecified settings can be set to whatever is most convinient.
| Setting | Value |
|---|---|
| Project > Do not generate the main() | SET |
| Project > Toolchain / IDE | 'CMake' |
| Code Generator > STM32Cube MCU packages and embedded software packages | 'Copy only necessary library files' |
| Code Generator > Generate peripheral initialization as a pair of '.c/.h' files per peripheral | UNSET |
| Code Generator > Backup previously generated files when re-generating | UNSET |
| Code Generator > Keep User Code when re-generating | UNSET |
| Code Generator > Delete previously generated files when not re-generated | SET |
Usage
Project Creation
The project creation process differs somewhat from creating a standard MX project.
- Start with the creation of a project folder, from now on called ROOT. This will NOT be the destination of the code generation nor the
.iocfile. - Open the Cube MX program, select the board or MCU, setup the hardware as needed and configure the project as described before. Save the project, navigating to the ROOT folder, and name the project 'cubemx'. This will create a new directory where generated code and the ioc will reside.
- Follow the Code generation / IOC Update guide.
Code generation / IOC Update
After project creation of after modifying the IOC, code generation needs to be invoked. Assuming Cube MX is open with the relevant IOC:
- Save the project and press 'Generate Code'. Any existing code will be deleted, and the new code will be placed in the previously created CubeMX folder.
- In a terminal, navigate to the ROOT folder and run
mx-convert cubemx. This will ask for confirmation to delete files and generate the CMakeLists.txt files.
The remaining work
After code generation and convertion, a more manual part of project setup remains. MX Convert only prepares code for integration with CMake projects, the base CMake should be built around the cubemx folder, and it's setup is outside the scope of this tool and guide.