Add CircuitPython RLCD migration prototype

2026-06-21 21:14:18 -04:00
parent 2bc8fbeaca
commit edf3da1a30
9 changed files with 688 additions and 0 deletions
@@ -0,0 +1,83 @@
+# CircuitPython migration prototype for Waveshare ESP32-S3-RLCD-4.2
+
+This folder is an initial CircuitPython port attempt for the existing MicroPython ESP32-S3-RLCD project.
+
+## Goal
+
+Move the board firmware toward CircuitPython so we can use built-in CircuitPython media modules:
+
+- `audiomp3` for MP3 playback over I2S
+- `gifio` for frame-by-frame GIF decoding
+
+The current MicroPython project already has working low-level knowledge for:
+
+- ST7305 reflective LCD init and 2x4 packed monochrome framebuffer
+- ES8311 speaker DAC over I2C + I2S
+- GPIO46 speaker amp enable
+- ESP32-S3 board pins
+
+## Current status
+
+This is not a full replacement firmware yet. It is a bootable/iterable prototype layout:
+
+- `code.py` — demo entrypoint for CircuitPython
+- `lib/rlcd_cp.py` — custom ST7305/RLCD driver using `busio`/`digitalio`
+- `lib/audio_cp.py` — ES8311 + I2S MP3 playback helper
+- `lib/gif_player.py` — GIF-to-RLCD playback helper using `gifio`
+
+## Why a custom display driver is needed
+
+Antigravity’s review confirmed the important constraint: ST7305/RLCD is not a normal `displayio` panel here. The existing `rlcd.py` packs pixels into 15,000 bytes where each byte represents a 2×4 pixel block, with vertical inversion. CircuitPython does not appear to have a native `displayio` ST7305 driver for this exact layout, so this port keeps a Python-side canvas and manually packs it before SPI transfer.
+
+## Hardware pins copied from the working MicroPython firmware
+
+Display SPI:
+
+- SCK: IO11
+- MOSI: IO12
+- CS: IO40
+- DC: IO5
+- RST: IO41
+
+Audio/I2C:
+
+- I2C SDA: IO13
+- I2C SCL: IO14
+- I2S BCLK: IO9
+- I2S LRCK/WS: IO45
+- I2S DOUT: IO8
+- MCLK PWM: IO16
+- Speaker amp enable: IO46
+
+## Copy to CIRCUITPY
+
+After flashing a compatible CircuitPython build for the ESP32-S3 N16R8-style board:
+
+```bash
+cp circuitpython/code.py /media/$USER/CIRCUITPY/code.py
+mkdir -p /media/$USER/CIRCUITPY/lib
+cp circuitpython/lib/*.py /media/$USER/CIRCUITPY/lib/
+```
+
+Optional test assets:
+
+```bash
+cp demo.mp3 /media/$USER/CIRCUITPY/demo.mp3
+cp demo.gif /media/$USER/CIRCUITPY/demo.gif
+```
+
+## Expected next hardware tests
+
+1. Boot with only `code.py` and libraries copied.
+2. Confirm display init + dashboard text appears.
+3. Copy a tiny 320px-wide-or-smaller monochrome/low-color GIF and test GIF playback. `gifio` cannot load 400px-wide GIFs on current CircuitPython builds; the prototype centers 320px GIFs on the 400px screen.
+4. Copy a short MP3 and test I2S/ES8311 playback.
+5. If display is scrambled, compare `pack()` output against MicroPython `rlcd.py` and host `notetaker.py` mapping.
+
+## Known risks
+
+- CircuitPython may not expose every `board.IO##` name on the selected build. If so, update `PINS` in `code.py` with the names present in `dir(board)`.
+- `pwmio.PWMOut` at 12.288 MHz on IO16 may not work on all CircuitPython ESP32-S3 builds. If MCLK fails, MP3 playback may be silent even if I2S is writing.
+- Pure Python display packing loops may be slow. This prototype favors correctness first; optimize with lookup tables after the first visible frame works.
+- GIF playback on a 1-bit reflective LCD will be low-framerate and monochrome-thresholded.
+- CircuitPython SPI configuration is lock-scoped, so `rlcd_cp.py` configures 20 MHz SPI after every lock.