Understanding C-modules in circuitpython

[maholli]

This issue co-locates a lot of resources for getting started building custom CircuitPython modules as well as specifics about handling large data arrays.

Example modules that use large matrix math

A good starting point might be looking at displayio. Displayio is a core piece of CircuitPython development used to drive complex LCD, OLED, and e-ink displays. This involves storing, manipulating, and refreshing large 2D arrays.

• Start by glancing at the readthedocs page to understand the different pieces of the module: https://circuitpython.readthedocs.io/en/latest/shared-bindings/displayio/__init__.html
• Implementation of the displayio module in circuitpython will be broken up into the following directories:
  • circuitpython/shared-bindings/displayio/
    • Bitmap.c is a decent place to start.
  • circuitpython/shared-module/displayio/
  • circuitpython/ports/atmel-samd/common-hal/displayio/

There's also plenty of glue-code that holds it all together and allows you to call things from CircuitPython. You'll get a feel for that by looking at:

• atmel-samd/background.c
• https://learn.adafruit.com/extending-circuitpython/overview
• https://epxx.co/logbook/entries/howto.html

Alternatively, good general implementation examples are the various c-modules that make up the "python" functionality.

• Check out circuitpython/tree/master/py
  • Specifically how upy implemented things like mod math: circuitpython/blob/master/py/modmath.c

💡 please jot down your findings as comments to this issue so others can benefit

[maholli]

Building CircuitPython

To build circuitpython, follow the instructions starting here: https://github.com/adafruit/circuitpython/tree/master/ports/atmel-samd#setup

Changing build configurations (like adding ulab)

When building CP, there are files that tell the compiler which aspects of MicroPython to include in the build. There are many of these files, which enable much of the modularity of CP/MP. Some of these files are:

1. circuitpy_mpconfig.h
2. the port-specific file (remember, CircuitPython is a port of MicroPython!) mpconfigport.h
3. and the board-specific file, for example, the kicksat-sprite board: mpconfigboard.h

To include ulab in the CP build, follow the instructions here. Ignore the first bit about cloning MicroPython (you already did that when you cloned CircuitPython). Pay specific attention to this part: ⭐ Make sure you can build vanilla CircuitPython before trying to add things in. If you've already successfully built CP, then make sure to skip this step for ulab as well: