diff --git a/CHANGELOG.md b/CHANGELOG.md index bd3dc83..b9355bc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -314,6 +314,7 @@ - Fixed: update embedding example to match the current API - Fixed: `setup.cfg`: specify supported PySide2 version - Fixed: `setup.cfg`: PyPA parsing issues + - Fixed: revert default CubeMX paths that seems more widespread among users - Fixed: GUI. Recursive layout warning in Settings window - Fixed: GUI. Remove the `ProjectID` parameter for the `initialized` signal to get rid of the annoying Shiboken overflow error - Changed: bump up CubeMX, packages, test `.ioc` file, PlatformIO versions (both for local and CI builds) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 07874b8..75a0290 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,14 +3,14 @@ Find actual tasks at [TODO.md list](/TODO.md) / [GitHub issues](https://github.c ## Build -Staring from v2.0.0, the PEP517-compatible build process is supported. This process, yet described and standardized in several PEPs, is still a pretty early one and not fully adopted by official Python tools (such as pip, twine) though (at the time of publication at least). So the current way to pack is a little bit messy and relies on different instruments. Better use the latest Python and build packages versions. +Staring from v2.0.0, the PEP517-compatible build process is supported. This process, yet described and standardized in several PEPs, is still a pretty early one and not fully adopted by official Python tools (such as pip, twine), though (at the time of publication at least). So the current way to pack is a little messy and relies on different instruments. Better use the latest Python and build packages versions. For the dependencies list see [pyproject.toml](/pyproject.toml) file: ```shell script $ pip install wheel setuptools setuptools_scm ``` -To build a _wheel_ `setup.py` is not even required: +To build a Python _wheel_ `setup.py` is not even required: ```shell script $ pip wheel . --wheel-dir dist ``` @@ -25,7 +25,7 @@ Testing (code is located at the [`tests`](/tests) directory) is done via the `un ```shell script stm32pio-repo/ $ STM32PIO_TEST_CASE=nucleo_f031k6 python -m unittest -b -v ``` -Every run automatically creates a temporary directory (using `tempfile` module) where all the actions are performed so no repository file will be "disturbed". To run the specific group of tests or a particular test function you can use: +Every run automatically instantiates a temporary directory (using `tempfile` module) where all the actions are performed so no repository file will be "disturbed". To run the specific group of tests or a particular test function you can use: ```shell script stm32pio-repo/ $ python -m unittest tests.test_integration.TestIntegration stm32pio-repo/ $ python -m unittest tests.test_cli.TestCLI.test_verbosity @@ -33,12 +33,12 @@ stm32pio-repo/ $ python -m unittest tests.test_cli.TestCLI.test_verbosity `.ioc` files and installed tools' versions should match otherwise the CubeMX will complain about their incompatibility. -## CI -Azure Pipelines is used to automate test, build, and publish tasks (see [azure-pipelines.yml](/azure-pipelines.yml), [CI](/CI) for more information). The repo is tested against the matrix of all 3 major OSes and latest Python interpreters. Also, for the Linux runs the test coverage is calculated. Therefore, for these purposes some additional external dependencies are required: +## CI/CD +Azure Pipelines is used to automate test, build, and publish tasks (see [azure-pipelines.yml](/azure-pipelines.yml), [CI](/CI) for more information). The repo is tested against the matrix of all 3 major OSes and latest Python interpreters. Also, for the Linux runs the test percentage and coverage are calculated. Therefore, for these purposes some additional external dependencies are required: - pytest - coverage - yaml There are some elements of the "reproducible builds" approach using several "lockfiles", isolated test fixtures and caching. Optional `platformio.ini.lockfile`, "freezing" the PlatformIO packages' versions needed for a successful build, can be placed inside an every fixture folder. This config is an ordinary .INI-style file which will be merged into the `platformio.ini` during testing. -Overall, due to a number of such a diverse tools in use, the full-fledged "canonical" CI seems challenging to implement, and the current set up is far from ideal. +Overall, due to a number of such a diverse tools in use, the full-fledged "canonical" CI seems challenging to implement, and the current set up is far from ideal in that regard. diff --git a/README.md b/README.md index a06e4dc..6ae0cf0 100644 --- a/README.md +++ b/README.md @@ -16,16 +16,15 @@ The [GUI version](/docs/GUI/README.md) is available, too (please, read this main > - [Requirements](#requirements) > - [Installation](#installation) > - [Usage](#usage) - - [Troubleshooting](#troubleshooting) -> - [Embedding](#embedding) +> - [Troubleshooting](#troubleshooting) > - [Restrictions](#restrictions) ## Features - Originate the new full-fledged project in a single directory starting only from an `.ioc` file - - Seamlessly update the existing project after hardware changes in the CubeMX + - Seamlessly update an existing project after the hardware changes by CubeMX - Quickly check the current state - - Inspect the tools (CubeMX, PlatformIO, etc.) + - Inspect tools (CubeMX, PlatformIO, etc.) - Clean-up the project - *[optional]* Automatically run your favorite editor or initiate a build in the end - *[optional]* GUI edition (see [the dedicated README](/docs/GUI/README.md) file) (please, read this main introduction first) @@ -37,11 +36,11 @@ The [GUI version](/docs/GUI/README.md) is available, too (please, read this main **Python:** 3.6+ The app introduces zero dependencies by itself. Of course, you need to have all the necessary tools installed in order to perform the operations: - - STM32CubeMX with the desired downloaded frameworks (F0, F1, etc.). All recent versions are fine + - STM32CubeMX with the desired downloaded frameworks (F0, F1, etc.). All recent versions are fine (5.x, 6.x) - Java (JRE, Java runtime environment) for the CubeMX (already installed if the CubeMX is working). Which version is appropriate for the CubeMX you can find in its own description - - PlatformIO (4.2.0 and above) CLI (most likely is already present if you have installed it via some package manager (`pip`, `apt`, `brew`, etc.) or need to be installed as a "command line extension" from the PlatformIO IDE (see its [docs](https://docs.platformio.org/en/latest/core/installation.html) for more information)) + - PlatformIO (4.2.0 and above) CLI (most likely is already present if you have installed it via some package manager (`pip`, `apt`, `brew`, etc.) or need to be installed as a "command line extension" from the PlatformIO IDE (see its [docs](https://docs.platformio.org/en/latest/core/installation.html#piocore-install-shell-commands) for more information)) -If you, for some reasons, don't want to (or simply cannot) install (i.e. register in PATH) command line versions of these applications in your system, you can always specify the direct paths to them overriding the default values in the project configuration file `stm32pio.ini`. Check the [config reference](/docs/CONFIG.md) to see all possible ways of telling the stm32pio where the tools are residing on your machine. +If you, for some reasons, don't want to (or simply cannot) install (i.e. register in PATH) command line versions of these applications in your system, you can always specify the direct paths to them overriding the default values in the project configuration file `stm32pio.ini`. Check the [config reference](/docs/CONFIG.md) to see all possible ways of telling stm32pio where the tools are residing on your machine. ## Installation @@ -51,7 +50,7 @@ stm32pio-repo/ $ python3 stm32pio/cli/app.py stm32pio-repo/ $ python3 -m stm32pio.cli # or as the Python module any-path/ $ python3 path/to/stm32pio-repo/stm32pio/cli/app.py ``` -(we assume `python3` and `pip3` hereinafter). +Note: we will assume `python3` and `pip3` hereinafter. However, it's handier to install the utility to be able to run from anywhere. The PyPI distribution is available: ```shell script @@ -72,42 +71,39 @@ $ stm32pio --help to see help on available commands. Basically, you need to follow such a workflow (refer to the [example](/examples/cli) which explains the same just illustrating it with some screenshots/command snippets): - 1. Create the CubeMX project (`.ioc` file) like you're used to, set up your hardware configuration, but in the end save it with the compatible parameters - 2. Run the stm32pio that automatically invokes the CubeMX to generate a code, creates the PlatformIO project, patches the `platformio.ini` file. + 1. Create the CubeMX project (`.ioc` file) like you're used to, set up your hardware configuration, but after all save it with the compatible parameters + 2. Run stm32pio that automatically invokes CubeMX to generate a code, creates the PlatformIO project, patches the `platformio.ini` file. 3. Work with your project normally as you wish, build/upload/debug etc. 4. When necessary, come back to the hardware configuration in the CubeMX, then run stm32pio again to re-generate the code -See the [commands reference](/docs/CLI/COMMANDS.md) file listing the complete help on the available commands/options. On the first run, the stm32pio will create a config file `stm32pio.ini`, syntax of which is similar to the `platformio.ini`. You can also create this config without any following operations by initializing the project: +See the [commands reference](/docs/CLI/COMMANDS.md) file listing the complete help about the available commands/options. On the first run, stm32pio will create a config file `stm32pio.ini`, syntax of which is similar to the `platformio.ini`. You can also create this config without any following operations by initializing the project: ```shell script $ stm32pio init -d path/to/project ``` -It may be useful to tweak some parameters before proceeding. See the [config reference](/docs/CONFIG.md) showing the meaning of every key. +It may be useful to tweak some parameters before proceeding. See the [config reference](/docs/CONFIG.md) showing meanings for every key. -### Troubleshooting +## Troubleshooting If you're stuck and the basic logs doesn't clear the situation, try the following: - Run the same command in the verbose mode using the `-v` key: ```shell script $ stm32pio -v [command] [options] ``` This will unlock additional logs which might help to clarify - - Validate your environment, i.e. check whether the stm32pio can find all the necessary tools on your machine: + - Validate your environment, i.e. check whether the stm32pio can find all the essential tools on your machine: ```shell script $ stm32pio validate -d path/to/project ``` - This will print the report about the current set up according to the config `stm32pio.ini` file. + This will print the report about the current set up according to your config `stm32pio.ini` file. - Use the dynamic help feature which outputs information specifically about the requested command, e.g.: ```shell script $ stm32pio new -h ``` -### Embedding -You can also use the stm32pio as an ordinary Python package and embed it in your own application. Find the minimal example [here](/examples/embedding). Long story short, you need to import the core module' project class, _optionally_ set up a logging and you are good to go. If you prefer a higher-level API similar to the CLI version, use the `main()` function from the `stm32pio/cli/app.py` passing same CLI arguments to it. - ## Restrictions - - The tool doesn't check for different parameters' compatibility, e.g. CPU frequency, allocated memory and so on. It simply eases your workflow with these 2 programs (PlatformIO and STM32CubeMX) a little bit. - - In order to add CubeMX middlewares to your build the manual adjustments should be applied to your project, the stm32pio doesn't handle them automatically. For example, FreeRTOS can be added via PlatformIO' `lib` feature or be directly compiled in its own directory using `lib_extra_dirs` option: + - The tool doesn't check for different parameters' compatibility, e.g. CPU/IO/etc frequencies, allocated memory and so on. It simply eases your workflow with these 2 programs (PlatformIO and STM32CubeMX) a little bit. + - In order to add CubeMX middlewares to your build the manual adjustments should be applied, the stm32pio doesn't handle them automatically. For example, FreeRTOS can be added via PlatformIO' `lib` feature or be directly compiled in its own directory using `lib_extra_dirs` option: ```ini lib_extra_dirs = Middlewares/Third_Party/FreeRTOS ``` diff --git a/docs/CONFIG.md b/docs/CONFIG.md index 4a52e4c..96c86dc 100644 --- a/docs/CONFIG.md +++ b/docs/CONFIG.md @@ -1,7 +1,7 @@ # INI-config description Consider this file as a reference when editing the project parameters. -The project's configuration file (by default, its name is `stm32pio.ini`) controls the aspects of how the stm32pio treating your project. INI-format is convenient and familiar to PlatformIO users. +The project's configuration file (by default, its name is `stm32pio.ini`) controls aspects of how the stm32pio treating your project. INI-format is convenient and familiar to PlatformIO users. It has 2 main sections. As the stm32pio has no global config (keeping be simple and non-intrusive), the `[app]` section consists of some properties that could belong to the global app settings rather being set per-project. We're talking here about the CLI tools' (used by the stm32pio) paths/commands. The second section – `[project]` – is more related to the particular project. @@ -36,7 +36,7 @@ Note: this is not an only source of the program settings but more like a "public Specify commands of the corresponding tools if they are present in your PATH env variable (e.g. `java`, `platformio`). Alternatively, provide an absolute path (e.g. `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX/STM32CubeMX.exe`). If the path contains whitespaces, do not escape them manually, this will be done automatically. ### `java_cmd` -As you're probably already know, the CubeMX uses Java to run. So it is most likely already installed on your machine. By default, this command will be used to start the CubeMX as `java -jar` as it is the most universal and reliable approach. If omitted, there will be an attempt to run `cubemx_cmd` on its own, without preceding `java`. See `cubemx_cmd` below for more information. +As you're probably already know, the CubeMX uses Java to run. So most likely it is already installed on your machine. By default, this command will be used to start the CubeMX as `java -jar` as it is the most universal and reliable approach. If omitted, there will be an attempt to run `cubemx_cmd` on its own, without preceding `java`. See `cubemx_cmd` below for more information. #### Default `java` @@ -46,9 +46,11 @@ As you're probably already know, the CubeMX uses Java to run. So it is most like `platformio` ### `cubemx_cmd` -As the CubeMX doesn't by default append itself to a PATH, this probably will be a path on your machine. Based on my observations, recent CubeMX versions doesn't ship with some kind of installer so one just need to unpack the downloaded archive and hit that executable. Also, after the internal updates, the main CubeMX executable losing its `.exe` extension making set earlier property invalid. Such behavior was discovered at least on macOS, this is an annoying one... See `java_cmd` below for more information. +As the CubeMX doesn't by default append itself to a PATH, this probably will be a path on your machine. #### Default -`~/cubemx/STM32CubeMX.exe` for POSIX, `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX/STM32CubeMX.exe` on Windows. + - macOS: `/Applications/STMicroelectronics/STM32CubeMX.app/Contents/Resources/STM32CubeMX` + - Linux: `~/STM32CubeMX/STM32CubeMX` + - Windows: `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX/STM32CubeMX.exe` ## `project` section @@ -63,7 +65,7 @@ exit ``` ### `platformio_ini_patch_content` -Changes that should be applied to the `platformio.ini` file to conform the CubeMX and PlatformIO projects structures. For those who wants to modify the patch: it has a general .INI-style syntax, so it is possible to specify several sections and apply composite patches. This works totally fine for the most cases except, perhaps, some really huge complex patches involving, say, the parameters' interpolation feature. It's turned off for both `platformio.ini` and user's patch parsing by default. If there are some problems you've encountered due to a such thing please modify the source code to match the parameters' interpolation behavior for the configs you need to. Seems like `platformio.ini` uses `ExtendedInterpolation` for its needs, by the way. +Changes that should be applied to the `platformio.ini` file to conform the CubeMX and PlatformIO projects structures. For those who want to modify the patch: it has a general .INI-style syntax, so it is possible to specify several sections and apply composite patches. This works totally fine for the most cases except, perhaps, some really huge complex patches involving, say, the parameters' interpolation feature. It's turned off for both `platformio.ini` and user's patch parsing by default. If there are some problems you've encountered due to a such thing please modify the source code to match the parameters' interpolation behavior for the configs you need to. Seems like `platformio.ini` uses `ExtendedInterpolation` for its needs, by the way. #### Default ``` [platformio] @@ -72,26 +74,26 @@ src_dir = Src ``` ### `board` -Same as the corresponding CLI option. +Same as the corresponding CLI option – PlatformIO name (ID) of the board. #### Default None. ### `ioc_file` -`.ioc` file to work with (sitting in the project root). This is not particularly useful when there is only a single one, but can be valuable when there are multiple. +`.ioc` file to work with (placed in the project root). This is not particularly useful when there is only a single one, but can be valuable when there are multiple. #### Default Name of the first `.ioc` file found, or an explicitly specified one. ### `cleanup_ignore` -List of paths relatively to the project root that should be ignored (left) during the cleaning operation. Alternatively, every line specified can be a glob-style pattern. The list will be ignored if `cleanup_use_git` is set to True. +List of paths relative to the project root that should be ignored (left) during the cleaning operation. Alternatively, each line specified can be a glob-style pattern. The list will be ignored if `cleanup_use_git` is set to True. #### Default Value of the `ioc_file`. ### `cleanup_use_git` -Boolean controlling the `clean` method: whether to utilize custom ignore list and remove the rest of the files or to delegate the task to the git tool (`git clean`). +Boolean controlling the `clean` method: whether to utilize custom ignore list and remove the rest of the files or to delegate the task to git (`git clean`). #### Default `False` ### `last_error` -This isn't really a "parameter" and initially doesn't exist at all but appears in your config after some error occurs. This will contain an error string and its traceback so you can examine it later to solve the problem. This will be automatically cleared after the next successful operation with this project. +This isn't really a "parameter" and initially doesn't exist at all but appears in your config after some error occurs. This will contain an error string and its Python traceback so you can examine it later to solve the problem. This will be automatically cleared after the next successful operation on this project. #### Default None. diff --git a/docs/GUI/README.md b/docs/GUI/README.md index 33d8d4d..f073690 100644 --- a/docs/GUI/README.md +++ b/docs/GUI/README.md @@ -47,11 +47,11 @@ Add a folder with an `.ioc` file to begin with - it will be your first project. ![Init](usage_tutorial_screenshots/init_screen.png) -Skip it or enter one of the available PlatformIO STM32 boards identifier. Select "Run" to apply all actions to the project (analog of the `new` CLI command). +Skip it or enter one of the available PlatformIO STM32 boards identifier. Optionally select "Run" to apply all actions to the project (analog of the `new` CLI command). At the main screen the buttons row allows you to run specific actions while, at the same time, is representing the current state of project. Green color means that this stage is fulfilled. The active project is monitored automatically while all the others refreshes only when you click on them, so the "stage" line at the projects list item can be outdated. -Let's assume you've worked on some feature for some time (outside of the stm32pio) and now need to re-generate and rebuild the configuration. To schedule all the necessary actions to run one after another, navigate to the last desired action while pressing the **Shift** key. All the actions prior this one should be colored light-green now: +Let's assume you've worked on some feature for some time (outside the stm32pio) and now need to re-generate and rebuild the configuration. To schedule all the necessary actions to run one after another, navigate to the last desired action while pressing the **Shift** key. All the actions prior this one should be colored light-green now: ![Highlighting](usage_tutorial_screenshots/highlighting.png) diff --git a/examples/README.md b/examples/README.md index 4b1afe6..b44c470 100644 --- a/examples/README.md +++ b/examples/README.md @@ -6,7 +6,7 @@ This directory contains some useful examples related to the stm32pio project. > - [embedding](#embedding) ## CLI -Illustrated step-by-step guide to create your first project. +Illustrated step-by-step guide to establish your first project. ## Embedding -Refer to this script to see a minimal basic set-up enough to perform most of the tasks with stm32pio projects in your code (i.e. how to establish a core library (`stm32pio` folder) in a 3rd party tools). +Refer to this script to see a minimal basic set-up enough to perform most of the tasks with stm32pio projects in your code (i.e. how to include a core library (`stm32pio` folder) in 3rd party tools). diff --git a/examples/cli/README.md b/examples/cli/README.md index 8637974..e09c80a 100644 --- a/examples/cli/README.md +++ b/examples/cli/README.md @@ -9,13 +9,13 @@ ![Project tab](/examples/cli/tab_Project.png) -4. Use the copied string (project folder) as a `-d` argument for the stm32pio (can be omitted if your current working directory is already a project directory). +4. Use the copied string (project folder) as a `-d/--directory` argument for the stm32pio (can be omitted if your current working directory is already a project directory). 5. Run `platformio boards` (`pio boards`) or go to [boards](https://docs.platformio.org/en/latest/boards) to list all supported devices. Pick one and use its ID as a `-b/--board` argument (for example, `nucleo_f031k6`) 6. All done! You can now run ```shell script $ stm32pio new -d path/to/project/ -b nucleo_f031k6 --start-editor=code --with-build ``` - to trigger the code generation, compile the project and start the VSCode editor with the folder opened (last 2 options are given as an example and not required). Make sure you have all the tools in PATH (`java`, `platformio`, `python`, editor) (or set them in `stm32pio.ini`). You can use a slightly shorter syntax if you are already located in the project directory: + to trigger the code generation, compile the project and start the VSCode editor with the folder opened (last 2 options are given as an example and not required). Make sure you have all the tools in your PATH (`java`, `platformio`, `python`, editor) (or set them in `stm32pio.ini`). You can use a slightly shorter syntax if you are already located in the project directory: ```shell script path/to/project/ $ stm32pio new -b nucleo_f031k6 ``` @@ -25,4 +25,4 @@ $ stm32pio generate -d /path/to/project ``` 9. To clean-up the directory and keep only an `.ioc` file run the `clean` command. -10. If you're facing some errors complaining about some tool incorrectness, run `validate` command to check the current environment in terms of the tools' presence in your system. +10. If you're facing some errors complaining about tools absence, run `validate` command to check the current environment in terms of the tools' presence in your system. diff --git a/examples/embedding/README.md b/examples/embedding/README.md new file mode 100644 index 0000000..9430bb3 --- /dev/null +++ b/examples/embedding/README.md @@ -0,0 +1,3 @@ +# Embedding + +You can also use the stm32pio as an ordinary Python package and embed it in your own application. It is a minimal example. Long story short, you need to import the core module' project class, _optionally_ set up a logging and you are good to go. If you prefer a higher-level API similar to the CLI version, use the `main()` function from the `stm32pio.cli.app` passing same CLI arguments to it. diff --git a/stm32pio/core/settings.py b/stm32pio/core/settings.py index 653ce24..263e4c9 100644 --- a/stm32pio/core/settings.py +++ b/stm32pio/core/settings.py @@ -21,19 +21,24 @@ config_default = collections.OrderedDict( # guarantees printing to the file in the same order app={ - # (default is OK) How do you start Java from the command line? (edit if Java not in PATH). Set to 'None' - # (string) if in your setup the CubeMX can be invoked straightforwardly + # How do you start Java from the command line? (edit if Java not in PATH). Can be safely set to 'None' (string) + # if in your setup the CubeMX can be invoked directly 'java_cmd': 'java', - # (default is OK) How do you start PlatformIO from the command line? (edit if not in PATH, if you use PlatformIO - # IDE check https://docs.platformio.org/en/latest/installation.html#install-shell-commands) - # ("python -m platformio" isn't supported yet) + # How do you start PlatformIO from the command line? (edit if not in PATH, if you use PlatformIO IDE see + # https://docs.platformio.org/en/latest/core/installation.html#piocore-install-shell-commands). + # Note: "python -m platformio" isn't supported yet 'platformio_cmd': 'platformio', - # (default is OK) Trying to guess the STM32CubeMX location. STM actually had changed the installation path - # several times already. Note that STM32CubeMX will be invoked as 'java -jar CUBEMX' + # Trying to guess the STM32CubeMX location. ST actually had changed the installation path several times already. + # It also depends on how do one obtain a distribution archive (logging in on web-site or just downloading by the + # direct link). STM32CubeMX will be invoked as 'java -jar [cubemx_cmd]' 'cubemx_cmd': - str(Path.home() / 'cubemx/STM32CubeMX.exe') if my_os in ['Darwin', 'Linux'] else + # macOS default: 'Applications' folder + '/Applications/STMicroelectronics/STM32CubeMX.app/Contents/Resources/STM32CubeMX' if my_os == 'Darwin' else + # Linux (Ubuntu) default: home directory + str(Path.home() / 'STM32CubeMX/STM32CubeMX') if my_os == 'Linux' else + # Windows default: Program Files 'C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX/STM32CubeMX.exe' if my_os == 'Windows' else None }, project={ @@ -93,7 +98,7 @@ config_default['app'] = { 'java_cmd': 'java', 'platformio_cmd': 'platformio', - 'cubemx_cmd': str(Path(os.getenv('STM32PIO_CUBEMX_CACHE_FOLDER')).joinpath('STM32CubeMX.exe')) + 'cubemx_cmd': str(Path(os.getenv('STM32PIO_CUBEMX_CACHE_FOLDER')) / 'STM32CubeMX.exe') } TEST_FIXTURES_PATH = Path(os.environ.get('STM32PIO_TEST_FIXTURES',