Normally, all imported Python modules in CircuitPython are loaded into RAM in compiled form, whether they start as .mpy
or .py
files. Especially on M0 boards, a user program can run out of RAM if too much code needs to be loaded.
To ameliorate this problem, a CircuitPython image can include compiled Python code that is stored in the image, in flash memory, and executed directly from there. These are "internal frozen modules". The circuitplayground_express
builds use this technique, for example.
If you would like to build a custom image that includes some frozen modules, you can imitate how it's done in the circuitplayground_express
build. Look at boards/circuit_playground_express/mpconfigboard.mk
:
Temporarily unable to load content:
Notice the FROZEN_MPY_DIRS
lines in the file. Pick the mpconfigboard.mk file for the board you are using, and add one or more similar lines. You will need to do add directories for the libraries you want to include. If these are existing libraries in GitHub, you can add them as submodules. For instance, suppose you want to add the Adafruit_CircuitPython_HID library to the feather_m0_express build. Add this line to boards/feather_m0_express/mpconfigboard.mk:
FROZEN_MPY_DIRS += $(TOP)/frozen/Adafruit_CircuitPython_HID
Then add the library as a submodule:
cd circuitpython/frozen git submodule add https://github.com/adafruit/Adafruit_CircuitPython_HID
When you add the submodule it will be cloned into the frozen/ directory.
Set the submodule to a commit that is a release tag. If you try to freeze a module that is at untagged commit, you'll get a git error when building. You can update all the frozen modules to the latest release tags by doing this, at the top level of your repository clone:
make update-frozen-modules
Alternatively, simply check out a tagged version of the submodule after you add the submodule and before you commit it:
cd circuitpython/frozen/The_Module_to_Freeze # example submodule name git checkout 2.11.0 # example version number
Note that there is limited unused space available in the images, especially in the non-Express M0 builds, and you may not be able to fit all the libraries you want to freeze. You can of course try to simplify the library code if necessary to make it fit.