From d63867ea0b8844072d1ba2d8e66627bf64d713a9 Mon Sep 17 00:00:00 2001 From: Didas72 Date: Wed, 12 Nov 2025 18:41:01 +0000 Subject: [PATCH] License and README completion --- LICENSE.md | 21 +++++++++++++++++++++ README.md | 42 ++++++++++++++++++++++++++++++++++-------- 2 files changed, 55 insertions(+), 8 deletions(-) create mode 100644 LICENSE.md diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..ebfbe09 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Diogo Cruz Diniz + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 7d9acb2..25d4c97 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,32 @@ -# MX Converter +# MX Convert -MX Converter is a tool to convert Cube MX generated projects to the ISTSAT-2 repository structure. +MX Convert is a tool to convert Cube MX generated projects to the ISTSAT-2 repository structure. ## Notice -This guide and the MX Converter 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. +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 Converter, make sure to back up the original code and to double check all code is present in the final version of your project. +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 @@ -24,17 +44,23 @@ 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 -## Project Creation +## Usage + +### Project Creation The project creation process differs somewhat from creating a standard MX project. 1. 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 `.ioc` file. -1. Open the CubeMX 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. +1. 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. 1. Follow the Code generation / IOC Update guide. -## Code generation / IOC Update +### 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: 1. 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. -1. TODO: Define how to use the CMakeLists generator +1. 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.