circuitpython/examples/natmod/README.md

Dynamic Native Modules

Dynamic Native Modules are .mpy files that contain native machine code from a language other than Python. For more info see [the documentation] (https://docs.micropython.org/en/latest/develop/natmod.html).

This should not be confused with [User C Modules] (https://docs.micropython.org/en/latest/develop/cmodules.html) which are a mechanism to add additional out-of-tree modules into the firmware build.

Examples

This directory contains several examples of writing dynamic native modules, in two main categories:

1. Feature examples.

   • features0 - A module containing a single "factorial" function which demonstrates working with integers.

   • features1 - A module that demonstrates some common tasks:

     • defining simple functions exposed to Python
     • defining local, helper C functions
     • defining constant integers and strings exposed to Python
     • getting and creating integer objects
     • creating Python lists
     • raising exceptions
     • allocating memory
     • BSS and constant data (rodata)
     • relocated pointers in rodata

   • features2 - This is a hybrid module containing both Python and C code, and additionally the C code is spread over multiple files. It also demonstrates using floating point (only when the target supports hardware floating point).

   • features3 - A module that shows how to use types, constant objects, and creating dictionary instances.

   • features4 - A module that demonstrates how to define a class.

2. Dynamic version of existing built-ins.

   This provides a way to add missing functionality to firmware that doesn't include certain built-in modules. See the heapq, random, re, deflate, btree, and framebuf directories.

   So for example, if your firmware was compiled with MICROPY_PY_FRAMEBUF disabled (e.g. to save flash space), then it would not include the framebuf module. The framebuf native module provides a way to add the framebuf module dynamically.

   The way these work is they define a dynamic native module which #include's the original module and then does the necessary initialisation of the module's globals dict.

Build instructions

To compile an example, you need to have the same toolchain available as required for your target port. e.g. arm-none-eabi-gcc for any ARM Cortex M target. See the port instructions for details.

You also need to have the pyelftools Python package available, either via your system package manager or installed from PyPI in a virtual environment with pip.

Each example provides a Makefile. You should specify the ARCH argument to make (one of x86, x64, armv6m, armv7m, xtensa, xtensawin):

$ cd features0
$ make ARCH=armv7m
$ mpremote cp features0.mpy :