Add support for fixed Zephyr displays

This adds zephyr_display. It acts similar to BusDisplay because
we write regions to update to Zephyr.

Author: tannewt

.github/actions/deps/ports/zephyr-cp/action.yml

@@ -3,11 +3,18 @@ name: Fetch Zephyr port deps
 runs:
   using: composite
   steps:
-    - name: Get libusb and mtools
+    - name: Get Linux build dependencies
       if: runner.os == 'Linux'
       run: |
+        echo "--- cpu model ---"
+        grep "model name" /proc/cpuinfo | head -1
+        sudo dpkg --add-architecture i386
         sudo apt-get update
-        sudo apt-get install -y libusb-1.0-0-dev libudev-dev mtools
+        sudo apt-get install -y libusb-1.0-0-dev libudev-dev pkg-config mtools
+        # We have to hold python3 so the following install works. See https://github.com/actions/runner-images/issues/13803
+        sudo apt-mark hold python3
+        sudo apt-get install -y libsdl2-dev:i386 libsdl2-image-dev:i386
+        echo "PKG_CONFIG_PATH=/usr/lib/i386-linux-gnu/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}" >> $GITHUB_ENV
       shell: bash
     - name: Setup Zephyr project
       uses: zephyrproject-rtos/action-zephyr-setup@v1

AGENTS.md

@@ -1,3 +1,4 @@
 - Capture CircuitPython output by finding the matching device in `/dev/serial/by-id`
 - You can mount the CIRCUITPY drive by doing `udisksctl mount -b /dev/disk/by-label/CIRCUITPY` and access it via `/run/media/<user>/CIRCUITPY`.
 - `circup` is a command line tool to install libraries and examples to CIRCUITPY.
+- When connecting to serial devices on Linux use /dev/serial/by-id. These will be more stable than /dev/ttyACM*.

locale/circuitpython.pot

@@ -113,6 +113,7 @@ msgstr ""
 
 #: ports/espressif/common-hal/espulp/ULP.c
 #: ports/espressif/common-hal/mipidsi/Bus.c
+#: ports/espressif/common-hal/qspibus/QSPIBus.c
 #: ports/mimxrt10xx/common-hal/audiobusio/__init__.c
 #: ports/mimxrt10xx/common-hal/usb_host/Port.c
 #: ports/raspberrypi/common-hal/picodvi/Framebuffer_RP2040.c
@@ -135,6 +136,7 @@ msgstr ""
 
 #: ports/analog/common-hal/busio/SPI.c ports/analog/common-hal/busio/UART.c
 #: shared-bindings/digitalio/DigitalInOutProtocol.c
+#: shared-module/busdisplay/BusDisplay.c
 msgid "%q init failed"
 msgstr ""
 
@@ -166,8 +168,8 @@ msgstr ""
 msgid "%q must be %d"
 msgstr ""
 
-#: py/argcheck.c shared-bindings/busdisplay/BusDisplay.c
-#: shared-bindings/displayio/Bitmap.c
+#: ports/zephyr-cp/bindings/zephyr_display/Display.c py/argcheck.c
+#: shared-bindings/busdisplay/BusDisplay.c shared-bindings/displayio/Bitmap.c
 #: shared-bindings/framebufferio/FramebufferDisplay.c
 #: shared-bindings/is31fl3741/FrameBuffer.c
 #: shared-bindings/rgbmatrix/RGBMatrix.c
@@ -459,6 +461,7 @@ msgstr ""
 msgid ", in %q\n"
 msgstr ""
 
+#: ports/zephyr-cp/bindings/zephyr_display/Display.c
 #: shared-bindings/busdisplay/BusDisplay.c
 #: shared-bindings/epaperdisplay/EPaperDisplay.c
 #: shared-bindings/framebufferio/FramebufferDisplay.c
@@ -647,6 +650,7 @@ msgstr ""
 msgid "Baudrate not supported by peripheral"
 msgstr ""
 
+#: ports/zephyr-cp/common-hal/zephyr_display/Display.c
 #: shared-module/busdisplay/BusDisplay.c
 #: shared-module/framebufferio/FramebufferDisplay.c
 msgid "Below minimum frame rate"
@@ -669,6 +673,7 @@ msgstr ""
 msgid "Both RX and TX required for flow control"
 msgstr ""
 
+#: ports/zephyr-cp/bindings/zephyr_display/Display.c
 #: shared-bindings/busdisplay/BusDisplay.c
 #: shared-bindings/framebufferio/FramebufferDisplay.c
 msgid "Brightness not adjustable"
@@ -856,8 +861,7 @@ msgstr ""
 msgid "Coordinate arrays types have different sizes"
 msgstr ""
 
-#: shared-module/usb/core/Device.c
-#: ports/espressif/common-hal/qspibus/QSPIBus.c
+#: ports/espressif/common-hal/qspibus/QSPIBus.c shared-module/usb/core/Device.c
 msgid "Could not allocate DMA capable buffer"
 msgstr ""
 
@@ -1023,10 +1027,6 @@ msgstr ""
 msgid "Failed to buffer the sample"
 msgstr ""
 
-#: ports/zephyr-cp/common-hal/_bleio/Adapter.c
-msgid "Failed to connect"
-msgstr ""
-
 #: ports/espressif/common-hal/_bleio/Adapter.c
 #: ports/nordic/common-hal/_bleio/Adapter.c
 #: ports/zephyr-cp/common-hal/_bleio/Adapter.c
@@ -1144,6 +1144,7 @@ msgstr ""
 msgid "Generic Failure"
 msgstr ""
 
+#: ports/zephyr-cp/bindings/zephyr_display/Display.c
 #: shared-bindings/framebufferio/FramebufferDisplay.c
 #: shared-module/busdisplay/BusDisplay.c
 #: shared-module/framebufferio/FramebufferDisplay.c
@@ -1242,8 +1243,8 @@ msgstr ""
 msgid "Internal define error"
 msgstr ""
 
-#: ports/espressif/common-hal/qspibus/QSPIBus.c
-#: shared-bindings/pwmio/PWMOut.c supervisor/shared/settings.c
+#: ports/espressif/common-hal/qspibus/QSPIBus.c shared-bindings/pwmio/PWMOut.c
+#: supervisor/shared/settings.c
 msgid "Internal error"
 msgstr ""
 
@@ -1518,8 +1519,7 @@ msgstr ""
 #: ports/stm/common-hal/busio/UART.c shared-bindings/fourwire/FourWire.c
 #: shared-bindings/i2cdisplaybus/I2CDisplayBus.c
 #: shared-bindings/paralleldisplaybus/ParallelBus.c
-#: shared-bindings/qspibus/QSPIBus.c
-#: shared-module/bitbangio/SPI.c
+#: shared-bindings/qspibus/QSPIBus.c shared-module/bitbangio/SPI.c
 msgid "No %q pin"
 msgstr ""
 
@@ -3237,10 +3237,6 @@ msgstr ""
 msgid "float unsupported"
 msgstr ""
 
-#: shared-bindings/_stage/Text.c
-msgid "font must be 2048 bytes long"
-msgstr ""
-
 #: extmod/moddeflate.c
 msgid "format"
 msgstr ""
@@ -3322,10 +3318,6 @@ msgstr ""
 msgid "generator raised StopIteration"
 msgstr ""
 
-#: shared-bindings/_stage/Layer.c
-msgid "graphic must be 2048 bytes long"
-msgstr ""
-
 #: extmod/modhashlib.c
 msgid "hash is final"
 msgstr ""
@@ -4047,10 +4039,6 @@ msgstr ""
 msgid "pack expected %d items for packing (got %d)"
 msgstr ""
 
-#: shared-bindings/_stage/Layer.c shared-bindings/_stage/Text.c
-msgid "palette must be 32 bytes long"
-msgstr ""
-
 #: py/emitinlinerv32.c
 msgid "parameters must be registers in sequence a0 to a3"
 msgstr ""

ports/zephyr-cp/AGENTS.md

@@ -4,3 +4,4 @@
 - To flash it on a board do `make BOARD=<vendor>_<board_name> flash`.
 - Zephyr board docs are at `zephyr/boards/<vendor>/<board_name>`.
 - Run zephyr-cp tests with `make test`.
+- Do not add new translatable error strings (`MP_ERROR_TEXT`). Instead, use `raise_zephyr_error()` or `CHECK_ZEPHYR_RESULT()` from `bindings/zephyr_kernel/__init__.h` to convert Zephyr errno values into Python exceptions.

ports/zephyr-cp/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

ports/zephyr-cp/Makefile

@@ -8,13 +8,24 @@ BUILD ?= build-$(BOARD)
 
 TRANSLATION ?= en_US
 
-.DEFAULT_GOAL := $(BUILD)/zephyr-cp/zephyr/zephyr.elf
+# Compute shield args once. Command-line SHIELD/SHIELDS values override board defaults from circuitpython.toml.
+ifneq ($(strip $(BOARD)),)
+WEST_SHIELD_ARGS := $(shell SHIELD_ORIGIN="$(origin SHIELD)" SHIELDS_ORIGIN="$(origin SHIELDS)" SHIELD="$(SHIELD)" SHIELDS="$(SHIELDS)" python cptools/get_west_shield_args.py $(BOARD))
+endif
 
-.PHONY: $(BUILD)/zephyr-cp/zephyr/zephyr.elf flash recover debug run run-sim clean menuconfig all clean-all test fetch-port-submodules
+WEST_CMAKE_ARGS := -DZEPHYR_BOARD_ALIASES=$(CURDIR)/boards/board_aliases.cmake -Dzephyr-cp_TRANSLATION=$(TRANSLATION)
+
+# When DEBUG=1, apply additional Kconfig fragments for debug-friendly settings.
+DEBUG_CONF_FILE ?= $(CURDIR)/debug.conf
+ifeq ($(DEBUG),1)
+WEST_CMAKE_ARGS += -Dzephyr-cp_EXTRA_CONF_FILE=$(DEBUG_CONF_FILE)
+endif
+
+.PHONY: $(BUILD)/zephyr-cp/zephyr/zephyr.elf flash recover debug debug-jlink debugserver attach run run-sim clean menuconfig all clean-all test fetch-port-submodules
 
 $(BUILD)/zephyr-cp/zephyr/zephyr.elf:
 	python cptools/pre_zephyr_build_prep.py $(BOARD)
-	west build -b $(BOARD) -d $(BUILD) --sysbuild -- -DZEPHYR_BOARD_ALIASES=$(CURDIR)/boards/board_aliases.cmake -Dzephyr-cp_TRANSLATION=$(TRANSLATION)
+	west build -b $(BOARD) -d $(BUILD) $(WEST_SHIELD_ARGS) --sysbuild -- $(WEST_CMAKE_ARGS)
 
 $(BUILD)/firmware.elf: $(BUILD)/zephyr-cp/zephyr/zephyr.elf
 	cp $^ $@
@@ -37,6 +48,15 @@ recover: $(BUILD)/zephyr-cp/zephyr/zephyr.elf
 debug: $(BUILD)/zephyr-cp/zephyr/zephyr.elf
 	west debug -d $(BUILD)
 
+debug-jlink: $(BUILD)/zephyr-cp/zephyr/zephyr.elf
+	west debug --runner jlink -d $(BUILD)
+
+debugserver: $(BUILD)/zephyr-cp/zephyr/zephyr.elf
+	west debugserver -d $(BUILD)
+
+attach: $(BUILD)/zephyr-cp/zephyr/zephyr.elf
+	west attach -d $(BUILD)
+
 run: $(BUILD)/firmware.exe
 	$^
 
@@ -51,7 +71,7 @@ run-sim:
 	build-native_native_sim/firmware.exe --flash=build-native_native_sim/flash.bin --flash_rm -wait_uart -rt
 
 menuconfig:
-	west build --sysbuild -d $(BUILD) -t menuconfig
+	west build $(WEST_SHIELD_ARGS) --sysbuild -d $(BUILD) -t menuconfig -- $(WEST_CMAKE_ARGS)
 
 clean:
 	rm -rf $(BUILD)

ports/zephyr-cp/README.md

@@ -42,6 +42,36 @@ If a local `./CIRCUITPY/` folder exists, its files are used as the simulator's C
 
 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`:
+
+```toml
+SHIELDS = ["shield1", "shield2"]
+```
+
+For example, `boards/renesas/ek_ra8d1/circuitpython.toml` enables:
+
+```toml
+SHIELDS = ["rtkmipilcdb00000be"]
+```
+
+You can override shield selection from the command line:
+
+```sh
+# 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](https://docs.zephyrproject.org/latest/boards/index.html#) can