diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c4dd399 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,3 @@ +## 1.22.1 + +- Initial version based on [micropython v1.22.1](https://github.com/micropython/micropython/tree/v1.22.1) diff --git a/README.md b/README.md new file mode 100644 index 0000000..ab4cc36 --- /dev/null +++ b/README.md @@ -0,0 +1,39 @@ +# MicroPython Helper + +[![Component Registry](https://components.espressif.com/components/mr9you/micropython-helper/badge.svg)](https://components.espressif.com/components/mr9you/micropython-helper) + +In some cases, developers may wish to integrate MicroPython into existing ESP-related projects as an ESP-IDF component, rather than developing it as standalone ESP32 firmware. This component facilitates the use of MicroPython within the ESP-IDF framework. + +In this component, the original MicroPython is integrated without any modifications. This allows for the full utilization of the build logic, code, and configurations, with only minimal modifications made outside of MicroPython itself. + +All features and use cases should be exactly the same as in the original MicroPython. + +## How to use? + +This component is distributed via [IDF component manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html). Just add `idf_component.yml` file to your main component with the following content: + +```yaml +## IDF Component Manager Manifest File +dependencies: + mr9you/micropython-helper: "~1.22.1" +``` + +Or simply run: + +``` +idf.py add-dependency "micropython-helper" +``` + +In the CMakeLists.txt file at the top level of your application, you need to add the following code before including IDF's project.cmake: + +```cmake +if(NOT MICROPY_HELPER_DIR) + set(MICROPY_HELPER_DIR ${CMAKE_CURRENT_SOURCE_DIR}/managed_components/mr9you__micropython-helper) +endif() + +if(EXISTS ${MICROPY_HELPER_DIR}) + include(${MICROPY_HELPER_DIR}/mpy.cmake) +endif() +``` + +At this stage, the `micropython-helper` component is not downloaded by the IDF component manager, so this part of the code will not take effect. To ensure its effectiveness, you need to run `idf.py set-target esp32s3`, or select any other target you intend to use. This will prompt the download of the micropython-helper component, allowing you to use the original command, such as `idf.py -D MICROPY_BOARD=ESP32_GENERIC_S3 build`. Please ensure to address this issue accordingly. diff --git a/examples/std_mpy/README.md b/examples/std_mpy/README.md new file mode 100644 index 0000000..f6c0ded --- /dev/null +++ b/examples/std_mpy/README.md @@ -0,0 +1,12 @@ +# Standard MicroPython Firmware + +This example utilizes `micropython-helper` to build standard MicroPython firmware. There are two ways to initiate the MicroPython service. One option is to simply call the `mpy_startup` function, which functions similarly to MicroPython's `app_main`. The other approach involves manually starting up MicroPython, in which case, you may wish to integrate some of your proprietary logic. + +For the build process, the following points should be noted: + +1. The `CMakeLists.txt` file at the top level of this project is slightly different from the normal example's `CMakeLists.txt`. +2. It is necessary to `run idf.py set-target esp32s3` or choose another target before building the firmware. +3. After completing step 2, you can run `idf.py -D MICROPY_BOARD=ESP32_GENERIC_S3` build to build the firmware. +4. To simplify the command, you may first `export MICROPY_BOARD=ESP32_GENERIC_S3`, and then run any other `idf.py` command, such as `idf.py menuconfig`, `idf.py build`, `idf.py flash monitor`, etc. + +For any other information about MicroPython itself, please refer to [MicroPython Documentation](https://docs.micropython.org/en/latest/index.html). \ No newline at end of file diff --git a/license.txt b/license.txt new file mode 100644 index 0000000..218dcd4 --- /dev/null +++ b/license.txt @@ -0,0 +1,22 @@ +The MIT License + +Copyright (c) 2024 Mr. 9You + +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.