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:

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:

cp demo.mp3 /media/$USER/CIRCUITPY/demo.mp3
cp demo.gif /media/$USER/CIRCUITPY/demo.gif

Expected next hardware tests

Boot with only code.py and libraries copied.
Confirm display init + dashboard text appears.
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.
Copy a short MP3 and test I2S/ES8311 playback.
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.

README.md Unescape Escape