Sample ESP-IDF integration using MicroPython as a custom component

This repository contains an example showing how to integrate MicroPython 1.26.1 as an ESP-IDF component.

From MicroPython's version 1.26.0 it is now possible to wrap it as an ESP-IDF component without performing any changes to its repository. All the necessary changes to make it happen have been upstreamed after the 1.25.0 release.

Post-checkout Setup

This project references Git submodules for both MicroPython and its standard library. To properly use this project after you check it out from GitHub (or elsewhere), you need to run these two commands from the root directory of this project:

git submodule init
git submodule update

This will take a little while while it checks out MicroPython's source tree and its dependencies. This needs to be done only whenever you check this project out to a new location, or when the project is updated to track a different version of MicroPython.

Configuration

Configuration is more or less similar to what you would need to do if you need to customise a stand-alone MicroPython build. What is different is that some paths now need to be referenced through CMake variables, as they are no longer relative to MicroPython's root but to your project's root instead. Here's a list of what's configurable and available for you to use:

Configuration entries you need to provide in your CMakeLists.txt file

Name	Description	Required
MICROPY_BOARD	The same value you would pass to "make BOARD="	Yes
MICROPY_BOARD_VARIANT	The same value you would pass to "make VARIANT="	No
MPY_BOARDS_DIR	The directory containing all available boards definition - this is the equivalent of MicroPython's /ports/esp32/boards but for your project instead	Yes

Configuration variables available in your board's CMake configuration files

Name	Description
MPY_SOURCE_ROOT	MicroPython's relocated root directory
MPY_ESP32_ROOT	MicroPython's ESP32 port's root directory
MPY_COMPONENT_ROOT	The ESP-IDF component's root directory (you shouldn't need this but it is available nonetheless)

Caveats

ESP-IDF Dependencies

The ESP-IDF component needs to provide its own idf_component.yml file, containing a set of dependencies needed by the component itself in order to function. Given recent changes in MicroPython regarding ESP32 dependencies handling (caused by USB libraries versioning issues), the component's idf_component.yml file is a symbolic link to the one used by MicroPython.

If you don't need changes in ESP-IDF dependencies, unless MicroPython changed in an incompatbile way, then this component will follow MicroPython's dependencies whenever its source tree is updated. However, if you need more (or fewer) dependencies then you'll have to delete the symbolic link and put your own updated idf_component.yml in its place (using the one provided by MicroPython as a template).

MicroPython Dependencies

The sample board configuration has been crafted to require no additional submodules (the btree module is not included in the build). If this situation changes, then you will have to fit a make submodules invocation somewhere along the build process (you can use the value of MPY_ESP32_ROOT as the directory to execute make from). This may or may not confuse ESP-IDF as it suddenly gets new directories to track after the submodules have been checked out

Flash Partitioning

The sample board configuration targets an ESP32S3 with PSRAM (the ESP32S3-DevKitC-N8R16 to be precise) and shows how to provide a custom board definition. Re-using MicroPython's board definitions requires a few workarounds (which may or may not made redundant with a PR to MicroPython one day):

• Copy /components/micropython/micropython/ports/esp32/partitions-4MiBplus.csv (or your board's default partition table) to your project's root directory
• Set MPY_BOARDS_DIR to "${MPY_ESP32_ROOT}/boards" after the end of the last MicroPython configuration block in your project's root CMakeLists.txt file.

Firmware Main Loop

Once control is given to the MicroPython interpreter, it won't give it back. MicroPython's ESP32 port main loop is designed to take over the system anyway; maybe in the future the main loop can be modified to shut itself down and give back control to its caller but it's not the case right now.

Licence

The whole lot is licensed, where applicable, under the same terms as MicroPython itself (which should cover everything anyway).