Merge pull request #106 from ussserrr/dev

2.1.2

CI/setup_test_env.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
 import os

CI/tests_runner.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python3
+#!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
 """

README.md

@@ -4,7 +4,7 @@
 
 Small cross-platform Python app that can create and update [PlatformIO](https://platformio.org) projects from [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html) `.ioc` files.
 
-It uses the STM32CubeMX to generate a HAL-framework-based code and alongside creates the PlatformIO project with compatible parameters to bind them both together.
+It uses the STM32CubeMX to generate a HAL-framework-based code and alongside creates the PlatformIO project with compatible parameters to glue them both together.
 
 The [GUI version](/docs/GUI/README.md) is available, too (but read this main introduction first, please).
 
@@ -21,26 +21,36 @@ The [GUI version](/docs/GUI/README.md) is available, too (but read this main int
 
 
 ## Features
-  - Originate the new full-fledged project in a single directory starting only from an `.ioc` file
-  - Seamlessly update an existing project after the hardware changes by CubeMX
-  - Quickly check the current state
+  - Originate new full-fledged project in a single directory starting only from an `.ioc` file
+  - Seamlessly update an existing project after making hardware changes from CubeMX
+  - Quickly check the project current state
   - Inspect tools (CubeMX, PlatformIO, etc.)
-  - Clean-up the project
+  - Easily 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)
 
 
 ## Requirements:
-**OS:** macOS, Linux, Windows 7-10
+**OS:** Linux, macOS, Windows (few latest versions of 7, and above)
 
 **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 (5.x, 6.x)
-  - Java (JRE, Java runtime environment) for the CubeMX. Starting from CubeMX v6.3.0 Java is included in the bundle (in form of a `jre` folder sitting alongside the executable) so you don't need to install it by yourself from now on. Hence, it can be omitted in the `stm32pio.ini` config file **except Windows** where it is still **highly recommended** to run CubeMX via `java.exe`. As mentioned, Java exists already, the only difference is that it is still will be listed in the default `stm32pio.ini` config. You can refer to STM32CubeMX own documentation to obtain more information on current situation if, suddenly, something will change in this regard
-  - 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))
+The app introduces zero dependencies by itself. Of course, you need to have all necessary tools installed on your machine in order to perform the operations:
+  - STM32CubeMX. All recent versions are fine (5.x, 6.x).
+
+    - CubeMX is written in Java, so Java Runtime Environment (JRE) is required. For CubeMX versions starting from 6.3.0 it is included in the installation bundle (of CubeMX). If you are using older versions of CubeMX, either upgrade or install JRE manually.
+
+    - STM32CubeMX CLI (which is used by stm32pio) can be invoked directly (by calling the executable file) or through the Java. First case is obviously simpler, and it is a default way of operating for UNIX and macOS. On Windows, however, the latter case is the only working one (for some reason), so Java executable (whether command or path) should be specified. As mentioned above, a method of its obtaining differs depending on CubeMX version, but default settings doing their best to figure out an appropriate setup and most likely all will just work out of the box.
 
-If you, for some reasons, don't want to (or 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.
+    - CubeMX embedded software packages of your choice (F0, F1, etc.) should be added into CubeMX. In case of their absence or versions mismatches you will probably be prompted by CubeMX during the code generation stage.
+
+    For more information on how STM32CubeMX functions please refer to its manual (that is shipped with the installation bundle) or community forum.
+
+  - PlatformIO CLI. Its presence in your system depends on how you're using it:
+    - If you have obtained it via some package manager like `pip`, `conda`, `apt`, `brew`, `choco`, etc. most likely the `platformio` command is already in your `PATH` environment variable, and you're able to start it through a command line. In this case you're good to go.
+    - If you're using PlatformIO IDE, the CLI extension should be installed in addition to your existing setup. See [PlatformIO docs](https://docs.platformio.org/en/latest/core/installation.html#piocore-install-shell-commands) for more information on how to do that.
+
+Either way, for every tool listed above, a simple direct path to the according executable can be specified just in case you cannot or don't want to register them in your `PATH`. Check the [config reference](/docs/CONFIG.md) to see all possible ways of telling stm32pio where the tools are residing on your machine.
 
 
 ## Documentation
@@ -51,15 +61,7 @@ If you, for some reasons, don't want to (or cannot) install (i.e. register in PA
 
 
 ## Installation
-As a normal Python package the app can be run in a completely portable way by downloading (or cloning) the snapshot of this repository and invoking the main script:
-```shell script
-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
-```
-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:
+The most straightforward way is to get the PyPI distribution:
 ```shell script
 $ pip install stm32pio
 ```
@@ -69,49 +71,59 @@ To uninstall run
 $ pip uninstall stm32pio
 ```
 
+As a normal Python package, the app can be run completely portable. Simply download or clone this repository and launch the main script:
+```shell script
+stm32pio-repo/ $   python stm32pio/cli/app.py  # call the file...
+stm32pio-repo/ $   python -m stm32pio.cli  # ...or run as Python module
+stm32pio-repo/ $   python -m stm32pio.cli.app
+any-path/ $   python path/to/stm32pio-repo/stm32pio/cli/app.py  # the script can be invoked from anywhere
+```
+
 
 ## Usage
 You can always run
 ```shell script
-$ stm32pio --help
+$ stm32pio
 ```
 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 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
+Essentially, you need to follow such a workflow:
+  1. Create new CubeMX project, set up your hardware configuration, and save with compatible parameters. You'll end up with the `.ioc` file.
+  2. Run stm32pio that automatically invokes CubeMX to generate a code, establishes new PlatformIO project with specific parameters and applies the patch.
+  3. Work with your PlatformIO project normally as you like, build/upload/debug etc.
+  4. When necessary, come back to hardware configuration in CubeMX, then run stm32pio again to re-generate the code.
+
+Refer to the [example](/examples/cli) guide which basically explains same concepts just in more details and illustrates with some screenshots/command snippets.
 
-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:
+See the [commands reference](/docs/CLI/COMMANDS.md) providing the complete help about available commands/options. On the first run in your project, stm32pio will create a config file `stm32pio.ini`, syntax of which is similar to `platformio.ini`. You can also create such config without any following operations by initializing the project:
 ```shell script
-$ stm32pio init -d path/to/project
+path/to/project $ stm32pio init
 ```
-It may be useful to tweak some parameters before proceeding. See the [config reference](/docs/CONFIG.md) showing meanings for every key.
+Might be useful to tweak some parameters before proceeding. See the [config reference](/docs/CONFIG.md) showing meanings for every key.
 
 
 ## 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:
+If you've encountered a problem and basic logs doesn't clear the situation, try the following:
+ - Run the same command in verbose mode adding `-v` key:
    ```shell script
-   $ stm32pio -v [command] [options]
+   $ stm32pio -v ...
    ```
-   This will unlock additional logs which might help to clarify
- - Validate your environment, i.e. check whether the stm32pio can find all the essential tools on your machine:
+   This will unlock extra logs helping to clarify what's wrong
+ - Validate your environment, i.e. check whether stm32pio can find all required tools on your machine:
    ```shell script
-   $ stm32pio validate -d path/to/project
+   $ stm32pio validate
    ```
-   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.:
+   This will print a small report about the current setup according to your config `stm32pio.ini` file.
+ - Use the dynamic help feature that outputs information exactly about the requested command, for example:
    ```shell script
-   $ stm32pio new -h
+   $ stm32pio new -h  # "new" command manual
    ```
 
 
 ## Restrictions
-  - 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:
+  - The tool doesn't check for compatibility of various parameters like clocks/pinout/periphery/memory and so on. It just eases your workflow with those 2 programs (PlatformIO and STM32CubeMX) a little bit.
+  - In order to introduce some CubeMX middleware into target build the manual adjustments should be applied – stm32pio will not handle them automatically. Tell PlatformIO what to link, set necessary build flags, etc. 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
     ```
-    You also need to move all `.c`/`.h` files to the appropriate folders respectively. See PlatformIO documentation for more information.
+    You also need to move all `.c`/`.h` sources into according directories. See PlatformIO documentation for more information.

docs/CONFIG.md

@@ -29,6 +29,7 @@ Note: this is not an only source of the program settings but more like a "public
 >   - [`ioc_file`](#ioc_file)
 >   - [`cleanup_ignore`](#cleanup_ignore)
 >   - [`cleanup_use_git`](#cleanup_use_git)
+>   - [`inspect_ioc`](#inspect_ioc)
 >   - [`last_error`](#last_error)
 
 
@@ -93,6 +94,11 @@ Boolean controlling the `clean` method: whether to utilize custom ignore list an
 #### Default
 `False`
 
+### `inspect_ioc`
+If true, `.ioc` file will be analyzed on certain operations for potential incompatibilities with recommended options (see the CLI example) and board/MCU values (compared to `platformio.ini`).
+#### Default
+`True`
+
 ### `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 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