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_nrf5340dk
This uses Zephyr’s cmake to generate Makefiles that then delegate to
tools/cpbuild/build_circuitpython.py to build the CircuitPython bits in parallel.
DEBUG=1 adds the debug Kconfig settings in debug.conf. CONSOLE=1 (implied
by DEBUG=1) applies a board’s console.overlay, if it has one, together with
the port’s console.conf, which turns the Zephyr UART console back on. Boards
whose console UART pins are also user pins, such as the Feather nRF52840, have
the Zephyr UART console only in those builds.
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:
Build the container with
podman build -t zephyr-cp-dev -f native_sim_build_Containerfile .Run/Start the container by running
./native_sim_build_run_container.shon the host PC. The script will automatically run or start based on whether the container has been run before.Init requirements inside the container with
./native_sim_build_init_container.sh
ZCP_CONTAINER and ZCP_IMAGE override the container and image names, and ZCP_PODMAN_ARGS
adds options to podman run when the container is first created.
If DISPLAY is set when the container is first created, the run script shares the host’s X11
socket and a copy of your X cookie with it, so the simulator can open its display window. This
works on a Linux desktop and under WSLg. The cookie is copied with xauth each time the script
runs. Set ZCP_NO_DISPLAY=1 to turn it off. A container created before this needs to be removed
with podman rm -f zcp and created again.
If west sdk install fails with Cannot change mode to ...: Operation not permitted, the
container runtime is rejecting the fchmodat2 syscall that Ubuntu 24.04’s tar uses. This
happens with older runtimes such as crun 0.17 from Ubuntu 22.04. Remove the container with
podman rm -f zcp and create it again with ZCP_PODMAN_ARGS="--runtime runc" if runc is
installed, or with ZCP_PODMAN_ARGS="--security-opt seccomp=unconfined" otherwise.
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.
Running the simulator interactively
make run-sim opens a window for the simulated display and waits until something connects to
its UART before it starts CircuitPython. Look for the PTY path in its output:
uart connected to pseudotty: /dev/pts/1
and open it from a second terminal. In the build container, open the second shell with
podman exec -it zcp bash and use pyserial’s terminal (exit with Ctrl-]):
python -m serial.tools.miniterm /dev/pts/1 115200
If the container has no display (it was created without DISPLAY or with ZCP_NO_DISPLAY=1),
run the simulator as SDL_VIDEODRIVER=dummy make run-sim.
Testing LVGL with AddressSanitizer
The native_native_sim_lvgl_asan board runs the LVGL displayio compositor with
AddressSanitizer enabled for CircuitPython and LVGL. It also poisons allocations in
LVGL’s private sys_heap to catch buffer overruns and use-after-free, and stops on
the first ASan error. ASan does not replace explicit leak checks.
make BOARD=native_native_sim_lvgl_asan
make test TEST_BOARDS=native_native_sim_lvgl_asan \
PYTEST_ARGS="tests/ --ignore=tests/bsim -k native_native_sim_lvgl_asan"
The executable is build-native_native_sim_lvgl_asan/zephyr-cp/zephyr/zephyr.exe.
The regular make test target includes this board as well as the unsanitized LVGL
and legacy-compositor variants.
Running the core test suite
make test-run-tests runs tests/run-tests.py against the native simulator. It needs
mtools and the lib/micropython-lib submodule (for unittest). By default it runs the
basics, float, misc and unicode tests on several simulators at once. Other
directories still have tests that fail on the simulator.
make test-run-tests
make test-run-tests RUN_TESTS_ARGS="-j 4 -d basics extmod"
make test-run-tests RUN_TESTS_ARGS="basics/int1.py"
The results, including the .exp and .out files of failed tests, are in
build-native_native_sim/run-tests/.
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
SHIELDorSHIELDSis explicitly provided, it overrides board defaults.If neither is provided, defaults from
circuitpython.tomlare used.Use
SHIELD=(empty) to disable a board default shield for one build.
Pin names
Human readable pin names (the board module) come from the devicetree by
default: gpio-leds and gpio-keys labels, node aliases, and connector
gpio-maps. Boards can add names without any devicetree involvement by
listing them in boards/<vendor>/<board>/circuitpython.toml under [pins].
Each entry maps a board module name to the pin number exposed by the board’s
hardware: the SoC package pin (or, for ball grid array packages, the
datasheet’s ball id, e.g. "B2"), or the castellated module pin when the
board uses a module like the Raytac MDBT50Q:
[pins]
LED = 17 # QFN package pin number
SDA = "B2" # ball id for BGA/CSP packages
D13 = 8 # MDBT50Q-1MV2 module pin number
The build resolves each package pin to a SoC pad using the iobroker package
pin map selected by CONFIG_IOBROKER_PACKAGE_<PACKAGE>
(modules/iobroker/packages/<package>.toml) and exposes the name on the
matching pad in the board module. A name that already maps to the same pin
(from the devicetree or an earlier entry) is deduplicated; a name that maps
to two different pins is a build error. The package map must not be CUSTOM
or missing, and the pad must be on an enabled GPIO controller; otherwise the
build fails with an error naming the offending entry.
Connector names
Devicetree connector nodes (gpio-map) get their names from a generic
per-compatible list in cptools/zephyr2cp.py. A board whose silkscreen
differs can override them per position in circuitpython.toml under
[connectors.<node label>], keying the gpio-map position (the header pin
number, as a string) to a name:
[connectors.nordic_expansion_header]
0 = "EXP_00" # header GPIO 00
21 = "EXP_21" # header GPIO 21 (QSPI CS)
Positions left out of the table get no name.
OTA firmware updates over BLE
Boards with Bluetooth and a slot1_partition can update CircuitPython
itself over the air. A board opts in by shipping a sysbuild.conf in its
board folder:
boards/<vendor>/<board>/sysbuild.conf:
SB_CONFIG_BOOTLOADER_MCUBOOT=y
That makes sysbuild build the MCUboot bootloader into the board’s
boot_partition and link the application into slot0_partition (it must
link into slot0 — see nrf54lm20dk for an example of a board that does
not). The app image is wrapped with an MCUboot header using imgtool —
signed, or hash-only when the board sets SB_CONFIG_BOOT_SIGNATURE_TYPE_NONE
(like nordic_nrf54l15dk does). The port Kconfig then enables Zephyr’s
MCUmgr/SMP server over the Bluetooth SMP service:
img uploadwrites the uploaded image into slot 1img test/img confirmplusos resetreboot into the new imagethe app confirms the running image once it has booted, so an update that fails to start is automatically reverted (the
TEST_AND_CONFIRMflow in the reference clients)
The service requires an encrypted connection. CircuitPython has no
display or keyboard IO capability, so authenticated (MITM) pairing can
never complete; the OTA boards pair with Just Works instead
(CONFIG_BT_SMP_ENFORCE_MITM=n and the SMP service’s GATT permissions set
to encryption-only, in the OTA boards’ board.conf). Once paired and
bonded, the client can upload.
To update a device, flash it with make BOARD=<board> flash (which flashes
both MCUboot and the app) and then use an SMP client such as Nordic’s open
source nRF Connect Device Manager
apps (the sample app is what’s published on the app stores) or the mcumgr
CLI, uploading the signed app image (zephyr.signed.bin from the build
directory).
Resetting into the bootloader
Code (and update tools) can enter the bootloader’s update mode
programmatically, the way a double-tap of the reset button does:
supervisor/port.c’s reset_to_bootloader() (invoked by the 1200-bps CDC
touch) and microcontroller.OnNextReset(RunMode.UF2 / RunMode.BOOTLOADER)
set a request before resetting, via the adaboot fork’s
adaboot/update_mode.h helpers.
The mechanism depends on which bootloader the board boots: fork adaboot
(MCUboot) boards read the boot-mode retention flag, so the app needs
RETENTION_BOOT_MODE (defaulted in the port Kconfig for boards whose layout
provides a zephyr,boot-mode region) and the board’s bootloader conf
(bootloader/mcuboot/conf/<vendor>/<board>.conf) needs the matching entrance
option (MCUBOOT_UF2_ENTRANCE_BOOT_MODE, or BOOT_SERIAL_BOOT_MODE on USB-less
boards like nrf54l15dk). Boards that boot the stock Adafruit nRF52
bootloader (the Adafruit boards) read the request from the raw GPREGRET
register instead and need no bootloader-side changes.
nordic_nrf54l15dk is the first MCUboot board with this enabled.
RP2 boards have no MCUboot. The request is a flag in a few bytes of RAM that survive the reset. Early in the next boot Zephyr sees the flag and jumps to the chip’s built-in ROM bootloader, which shows up as the RPI-RP2 (RP2040) or RP2350 UF2 drive. adaboot sets up that RAM region for the RP2 boards.
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.
The manifest in zephyr-config/west.yml skips the HALs of vendors that no board
here uses, so a board from one of them needs its entry removed from the
name-blocklist and a west update to fetch it. For the
esp32s3_devkitc board, that is hal_espressif:
west update
west build -b esp32s3_devkitc/esp32s3/procpu