Zephyr

This is an initial port of CircuitPython onto Zephyr. We intend on migrating all existing boards onto Zephyr. To start, we’ll only support new boards. Existing boards will be switched as the Zephyr port reaches parity with the existing implementation.

Getting Started

First, install Zephyr tools (see Zephyr’s Getting Started Guide). (These are fish commands because that’s what Scott uses.)

pip install west
west init -l zephyr-config
west update
west zephyr-export
pip install -r zephyr/scripts/requirements.txt
west sdk install

Now to build from ports/zephyr-cp:

make BOARD=nordic_nrf7002dk

This uses Zephyr’s cmake to generate Makefiles that then delegate to tools/cpbuild/build_circuitpython.py to build the CircuitPython bits in parallel.

Native simulator build container

Building the native sim requires libsdl2-dev:i386 and other 32bit dependencies that can cause conflicts on 64bit systems resulting in the removal of 64bit versions of critical software such as the display manager and network manager. A Containerfile and a few scripts are provided to set up a container to make the native sim build inside without affecting the host system.

The container automatically mounts this instance of the circuitpython repo inside at /home/dev/circuitpython. Changes made in the repo inside the container and on the host PC will sync automatically between host and container.

To use the container file:

  1. Build the container with podman build -t zephyr-cp-dev -f native_sim_build_Containerfile .

  2. Run/Start the container by running ./native_sim_build_run_container.sh on the host PC. The script will automatically run or start based on whether the container has been run before.

  3. Init requirements inside the container with ./native_sim_build_init_container.sh

To delete the container and cleanup associated files:

podman ps -a --filter ancestor=zephyr-cp-dev -q | xargs -r podman rm -f
podman rmi zephyr-cp-dev
podman image prune -f
podman rm -f zcp

Running the native simulator

From ports/zephyr-cp, run:

make run-sim

run-sim starts the native simulator in realtime. It prints the PTY path to connect to the simulator REPL. If a local ./CIRCUITPY/ folder exists, its files are used as the simulator’s CIRCUITPY drive.

Edit files in ./CIRCUITPY (for example code.py) and rerun make run-sim to test changes.

Shields

Board defaults can be set in boards/<vendor>/<board>/circuitpython.toml:

SHIELDS = ["shield1", "shield2"]

For example, boards/renesas/ek_ra8d1/circuitpython.toml enables:

SHIELDS = ["rtkmipilcdb00000be"]

You can override shield selection from the command line:

# Single shield
make BOARD=renesas_ek_ra8d1 SHIELD=rtkmipilcdb00000be

# Multiple shields (comma, semicolon, or space separated)
make BOARD=my_vendor_my_board SHIELDS="shield1,shield2"

Behavior and precedence:

  • If SHIELD or SHIELDS is explicitly provided, it overrides board defaults.

  • If neither is provided, defaults from circuitpython.toml are used.

  • Use SHIELD= (empty) to disable a board default shield for one build.

Testing other boards

Any Zephyr board can be used with CircuitPython. To test a different board, use west directly to build the board. The build will do its best to support as much as possible. By default the Zephyr console will be used for output. USB support is limited by initialization support in supervisor/usb.c. Only flash regions not used by Zephyr are used for CIRCUITPY. A manual circuitpython partition can be specified instead.

For example, to test the nrf52840dk board:

west build -b nrf52840dk/nrf52840

This is already supported in ports/nordic as pca10056.