pico-read

pico-read is an ESP32-C6 speed-reading device built with ESP-IDF and LVGL. The firmware reads .txt books from the ESP filesystem at runtime and renders them with a fixed anchor-letter reading UI.

Warning

This project is currently supported on macOS and Linux only.

Windows support is planned, but it is not documented or tested yet.

Repository Layout

• esp32-c6-gui/: ESP-IDF firmware project
• books/: source .txt books packaged into the device filesystem image

Dependency Model

This repo does not commit large vendored ESP-IDF components.

The firmware declares its dependencies in esp32-c6-gui/main/idf_component.yml, and ESP-IDF downloads them automatically on the first build. That keeps the repository small while still allowing a fresh clone to build directly.

Homebrew Dependencies

Install the required host tools with Homebrew:

brew install git cmake ninja ccache dfu-util python@3.11 pkg-config wget

ESP-IDF Setup

Clone and install ESP-IDF in a separate directory:

mkdir -p ~/esp
cd ~/esp
git clone -b v5.2 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32c6

Load the ESP-IDF environment in each shell before building or flashing:

source ~/esp/esp-idf/export.sh

Build

cd esp32-c6-gui
idf.py build

On the first build, ESP-IDF will fetch managed dependencies such as lvgl/lvgl and espressif/led_strip.

Flash

Do not use /dev/cu.usbmodem1101 blindly. That is only an example.

Find the real port first:

ls /dev/cu.*

Then unplug the board, run it again, plug the board back in, and run it again. The new device is the board you should flash. On macOS it is usually something like:

• /dev/cu.usbmodem...
• /dev/cu.SLAB_USBtoUART

Flash with the actual port:

cd esp32-c6-gui
idf.py -p /dev/cu.usbmodemACTUALPORT flash

If you want serial logs immediately after flashing:

cd esp32-c6-gui
idf.py -p /dev/cu.usbmodemACTUALPORT flash monitor

If flashing fails with:

• Could not open /dev/cu....
• the port is busy or doesn't exist

check these first:

1. The port name is real and matches the current plugged-in board.
2. No other serial monitor, terminal, or IDE is already using that port.
3. The board is still connected after the last reset.

If the board does not enter download mode automatically:

1. Hold BOOT.
2. Tap RESET.
3. Release BOOT.
4. Run the flash command again.

Updating Books

Add or edit .txt files inside books/, then rebuild and reflash:

cd esp32-c6-gui
idf.py build flash -p /dev/cu.usbmodemACTUALPORT

The firmware packages the books/ folder into a SPIFFS image during build and streams the selected book from the device filesystem at runtime.

Notes

• Do not activate the project-local .venv when running idf.py.
• Use the ESP-IDF environment from source ~/esp/esp-idf/export.sh.
• The active reader UI code lives in esp32-c6-gui/main/LVGL_UI/display_words.c.
• The runtime text filesystem backend lives in esp32-c6-gui/main/LVGL_UI/display.c.