ZEReader

ZEReader is a Zephyr based firmware for an open hardware eBook reader approach. See https://github.com/Allegra42/ZEReader-KiCad for more information about the hardware design.

The firmware is currently in a really early PoC stage. Nevertheless, due to Zephyr, it is easily portable and adaptable to different hardware platforms which provide the essential components and a proper device tree (overlay) configuration.

ZEReader Hardware

The ZEReader firmware is, based on Zephyr, highly flexible and can be adopted to a wide range of different hardware with a proper device tree (overlay). In general, the development and testing is based on the following components:

• Raspberry Pi Pico 1/2
• Waveshare ePaper Display 7,5" (Gooddisplay GDEW075T7, GDEY075T7) with UC8179 controller
• SD Card Reader (SPI)
• 4 Buttons for navigation

The ZEReader PCB itself is developed in a seperated git repository available here.

Setup for local development

west init -m git@github.com:Allegra42/ZEReader.git zereader-workspace

cd zereader-workspace

python3 -m venv .venv
source .venv/bin/activate

west update
pip install -r zephyr-rtos/scripts/requirements.txt
cd zephyr-rtos
west sdk install

Build

Always source the venv environment first!

cd zereader-workspace
source .venv/bin/activate

cd ZEReader

Build for Raspberry Pi Pico 1 using a Device Tree Overlay

west build -b rpi_pico app -p always

Build for Raspberry Pi Pico 2 using a Device Tree Overlay

west build -b rpi_pico2/rp2350a/m33 app -p always

Build for the ZEReader Rev1 Board

west build -b zereader_rev1/rp2350a/m33 app -p always

Other useful build commands

# Update Zephyr and external modules
# The west.yml of this project uses potentially unstable main branches from Zephyr and the modules.
# This was needed as neighter Pi Pico 2 nor LVGL v9 were included in the 4.0 release, but more or less important for this project.
# Be aware this can break!

west update

# May check if patches in this repo are (still) needed or new ones needed or new issues showed up.

# Generate SBoM
west spdx

Flash Pico

• disconnect USB
• press the 'BOOTSEL' button during reconnect
• the device shows up as a mass storage
• copy 'build/zephyr/zephyr.uf2' to the device
• it flashes itself and restarts running the firmware

Logs

Logs are printed via the Pi Pico default UART pins with 115200 bauds.

Debugging

With Blackmagic Debug Probe using the SWD interface:

• connect the Blackmagic Debug Probe to the Pi Pico's SWD header

• west debug --runner blackmagicprobe -> Connects to a GDB session

• set breakpoint with break <full/source/code/file/path>:<linenumber>

• step through / step in with GDB commands (next/n, step in/si, ..)

Emulator

Note: the Zephyr native simulator only works on Linux.

To build the emulator, build the ZEReader app for the native_sim board:

west build -b native_sim/native/64 app

To run the emluator, execute this command:

./build/zephyr/zephyr.exe

The native simulator uses emulated flash to provide storage, which replaces the SD card from the actual board. This emulated storage is backed by a 100 MB file named flash.bin, located in the directory where the emulator is run. If this file does not exist, the emulator creates it. To put data onto the simulated SD card, mount the file on the host and copy the data into it:

sudo mount -o loop flash.bin /mnt
sudo cp -r my-book /mnt
sudo umount /mnt

Alternatively, if the FUSE development headers are installed, FUSE access to the simulated storage can be enabled:

west build -b native_sim/native/64 app -- -DCONFIG_FUSE_FS_ACCESS=y

When the emulator is running, it mounts the simulated SD card on the directory flash/SD:, so the book can be copied there:

cp -r my-book flash/SD\:/

In any case, the emulator needs to be restarted after new books are added to the simulated SD card.

Current state

This is still a work-in-process. The firmware shows a proof-of-concept that reading EPUBs as they are is possible with the available resources of a cheap microcontroller unit like the RP2040/RP2350. (Right now, without unzipping the EPUB files directly from Zephyr.)

The firmware supports showing the contents of a book in correct order while jumping over pictures and leave (X)HTML formatting untouched.

The UI implementation is still very basic. The display orientation is still landscape and refresh configurations need to be tuned for an actually usable reading experience.

Config options for EPUB handling are still part of epub.h and should move to an own KConfig definition as the project proceeds in order to keep these configurations in a central location adopt Zephyr idioms.

See the GitHub issue page for a closer look on planned tasks.