🧰 esp32forth-things

Libraries and tooling for ESP32forth (ueForth)

esp32forth-things is a growing collection of libraries and host-side tooling for ESP32forth (ueForth). Everything targets stock, unmodified firmware -- plain Forth loaded onto the board at boot from SPIFFS, with Python tooling on the host. No fork, no C patches.

Right now it holds one thing: a driver, 5x7 font, and serial console for the AITRIP ESP32-C3 + 0.42" OLED.

Hardware

• ESP32-C3FH4 (RISC-V, 4 MB flash), native USB-Serial-JTAG (enumerates as /dev/cu.usbmodem*)
• 0.42" SSD1306 OLED, I2C address 0x3C, SDA=GPIO5, SCL=GPIO6; 72x40 visible (28-column offset)
• Onboard LED on GPIO8

Usage

The Makefile is the entry point; override the serial port with PORT=....

# Regenerate the font and installer, then persist everything to the device's
# /spiffs/autoexec.fs so it loads on every boot
make install

# Open a serial terminal (115200)
make monitor

# Target a different port
make install PORT=/dev/cu.usbmodemXXXX

On boot the panel initialises, the serial->OLED mirror turns on, and the board greets ESP32forth ready. See the Makefile for the rest of the targets (reload, probe, clean, ...).

How It Works

• Built on the firmware's Wire.* I2C words. No Adafruit or U8g2 libraries, no reflash -- the stock firmware already ships I2C support.
• The 72x40 panel sits offset 28 columns into the SSD1306's 128-wide GDDRAM. That single magic number (from U8g2's dedicated 72x40 device) is what the firmware's bundled Adafruit oled.h can't express, so the driver is hand-rolled.
• The serial console is mirrored by teeing type. ESP32forth funnels every byte of output -- emit, cr, ., string printing -- through one deferred word, type. console.fs saves the original vector and installs its own, which runs the original (serial) and then draws the same bytes on the OLED as a scrolling character terminal. The OLED path only touches RAM and Wire, so it can't recurse.
• The font is generated, not hand-written. make_font.py holds each glyph as ASCII art and emits the packed 5x7 bitmap, so glyphs are edited legibly and the hex is never touched by hand.

Rebuilding the Firmware

The flashed firmware is exactly what ueForth's own build produces (v7.0.8.1); rebuild only if needed:

# Clone upstream
make ueforth

# Configure, ninja, then arduino-cli compile and upload
make flash-firmware

The only non-default board option is CDCOnBoot=cdc, required for the native-USB console.

License

This project is licensed under the MIT License.