ZEReader
<!-- SPDX-FileCopyrightText: 2025 Anna-Lena Marx <[email protected]> SPDX-License-Identifier: MPL-2.0 --> # ZEReader [](https://github.com/Allegra42/ZEReader/actions/workflows/build-zephyr.yaml) [](https://github.com/Allegra42/ZEReader/actions/workflows/build-docs.yaml) <a href="https://allegra42.github.io/ZEReader/"> <img alt="Documentation" src="https://img.shields.io/badge/documentation-3D578C?logo=sphinx&logoColor=white"> </a> <a href="https://allegra42.github.io/ZEReader/doxygen"> <img alt="API Documentation" src="https://img.shields.io/badge/API-documentation-3D578C?logo=c&logoColor=white"> </a> <!-- <img alt="ZEReader in Action" src='/doc/pics/ZEReader.webp' width="500" /> -->  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](https://github.com/Allegra42/ZEReader-KiCad). ## Setup for local development ``` west init -m [email protected]: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 ``` ### Build for the ZEReader Rev2 Board ``` west build -b zereader_rev2/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.