A from-scratch EPUB reader for the Data Frog SF2000 and GB300.
FroggyReader is a Libretro core for
sf2000_multicore. It runs
on the 320x240 RGB565 display, uses integer/fixed-point layout only, and
contains no hardware-FPU instructions. The library follows the clean, flat
look of an e-reader rather than a game console: light paper background, a 3x2
cover grid, titles under the covers, and a restrained blue accent.
| Library | Reading | Night library |
|---|---|---|
![]() |
![]() |
![]() |
More captures: screenshots/final,
screenshots/mips, and
screenshots/edge. The full test notes are in
TEST_REPORT.md.
- EPUB 2 and EPUB 3 —
container.xml, OPF metadata, spine, NCX, EPUB 3 navigation documents, nested tables of contents, and#fragmentlinks. - XHTML + CSS — tags, classes, IDs, descendant/child selectors,
:first-child,:last-child,:nth-child, and!important. - Book formatting — headings, paragraphs, indentation, justification,
bold/italic/underline, superscript/subscript, ordered and unordered lists,
block quotes, tables,
pre,hr, page breaks, backgrounds, and borders. - Images — JPEG, PNG (including alpha), GIF (first frame), and BMP. Images are scaled with integer arithmetic and composited onto the page.
- Kindle-style library — flat light/night themes, 3x2 grid with 62x82 covers, titles under each cover, a smooth marquee for a selected long title, author and key hints in the footer, title/author sorting, shelf paging, progress bars, and bookmark markers.
- Comfortable reading — Paper, Sepia, and Night themes; four text sizes; three margin widths; optional justification; reflow that keeps the reading position; smooth vertical scrolling with the D-pad; independent page turns.
- Bookmarks and resume — add, jump to, and delete bookmarks; reading position is restored after a reboot.
- Four UI languages — English (default), Polish, German, and Japanese. The choice is saved in the reader configuration.
- No FPU — all layout, scaling, and animation math is integer or fixed-point. Final device ELFs are checked for hardware-FPU instructions.
| Button | Action |
|---|---|
| D-pad | Select a book |
| A | Open the selected book |
| Y | Sort by title / author |
| L / R | Previous / next shelf |
| Start | Help |
| Select | Settings (language, theme, text) |
| B | Close help |
| Button | Action |
|---|---|
| D-pad Up / Down | Smooth vertical scrolling |
| D-pad Left / Right | Previous / next page |
| A | Book menu |
| B | Back to the library |
| Y | Table of contents |
| X | Add / remove bookmark |
| L / R | Previous / next chapter |
| Start | Settings |
| Select | Cycle theme |
The book menu contains Contents, Bookmarks, Settings, Info, and Library. Settings include theme, text size, justification, margins, and UI language. In the bookmark list, A jumps to a bookmark and X deletes it.
- A Data Frog SF2000 or GB300 / GB300V2 running a multicore firmware
based on
sf2000_multicore. - A FAT32 SD card with about 5 MB free for the core, plus space for books.
- EPUB files without DRM. The reader opens
.epubfiles only.
- Open the latest release.
- Download
froggyReader-sd-files.zip. - Extract it. Inside there are
GB300andSF2000folders. - Copy the contents of the folder for your console to the root of the SD card, merging folders when asked.
- Insert the card and start ROMS/EPUB.gba from the menu.
- Copy your books to
ROMS/epub/books/.
The SD bundle already installs the core under the name the loader expects, plus the launcher stub, menu artwork, and display-name configuration.
Download the core for your console:
| Console | Release asset |
|---|---|
| SF2000 | epub.sf2k |
| GB300 / GB300V2 | epub.gb3k |
Then copy it to the loader's core directory as epub.sf2k — the
sf2000_multicore loader always appends .sf2k, including on GB300:
/system/Deimos/cores/epub.sf2k
Create the launcher stub ROMS/EPUB.gba with exactly this text:
epub;epub;EPUB.gba
Also create these optional copies if your frontend scans several locations:
ROMS/epub/EPUB.gba
ROMS/gba/EPUB.gba
Finally, copy your books into ROMS/epub/books/ and start
ROMS/EPUB.gba from the menu. Menu artwork and display names are optional;
the complete layout is shown below.
On Linux, put the two release cores in dist/ (or build them with
make device), then run the installer:
git clone https://github.com/Synaps33/FroggyReader.git
cd FroggyReader
# copy epub.sf2k and epub.gb3k from the release into dist/
./install_to_sd.sh /media/$USER/GB300The script detects GB300/SF2000, chooses the matching core, and installs the launcher files and the 12 sample books. To keep your own library untouched:
./install_to_sd.sh --no-samples /media/$USER/GB300If dist/epub.sf2k or dist/epub.gb3k is missing, build them first with
make device (see Building).
/system/Deimos/cores/epub.sf2k core (required)
/cores/epub/core_87000000 optional secondary copy
/ROMS/EPUB.gba launcher stub (required)
/ROMS/epub/EPUB.gba optional duplicate stub
/ROMS/gba/EPUB.gba optional duplicate stub
/ROMS/epub/books/*.epub your books
/ROMS/EPUB.rgb565 menu thumbnail (optional)
/ROMS/epub/EPUB.png menu thumbnail (optional)
/ROMS/epub/.res/EPUB.rgb565 menu thumbnail (optional)
/configs/custom_cores/epub/games.opt display names (optional)
/system/saves/epub_reader/reader.cfg created on first run
/ROMS/epub/epub.log log (optional)
Settings and reading progress are saved to
/mnt/sda1/system/saves/epub_reader/reader.cfg on the device. Delete that file
to reset the reader to its defaults.
Requirements: GCC, GNU Make, Python 3, and Pillow (for PNG conversion and the sample-library/font generators).
make # host test runner: runner/test_runner
make test # 101 PNG captures in screenshots/final
make edge-test # empty folder, corrupt EPUB, missing cover: 5 PNGsRequirements: a mipsel-linux-muslsf cross compiler and qemu-mipsel.
Override the paths from the Makefile if your toolchain lives elsewhere:
make test-mips \
MIPS_MUSL=/path/to/mipsel-linux-muslsf-cross/bin/mipsel-linux-muslsf- \
QEMU=/path/to/qemu-mipsel \
SYSROOT=/path/to/mipsel-linux-muslsfThis produces 42 PNGs in screenshots/mips and runs the same code as the
device build with -msoft-float -static.
Requirements: the mipsel-mti-elf toolchain and a checkout of
sf2000_multicore.
make device \
MIPS_ELF=/opt/frog-toolchain/mipsel-mti-elf_stable/bin/mipsel-mti-elf- \
MULTICORE=/path/to/sf2000_multicoreThe build creates separate directories for each console so the two builds do not share stale objects:
dist/epub.sf2k SF2000 core
dist/epub.gb3k GB300 / GB300V2 core
dist/epub_sf2000_core.elf unstripped SF2000 ELF
dist/epub_gb300_core.elf unstripped GB300 ELF
The final step checks both ELFs for hardware-FPU instructions. The expected count is 0.
The pre-generated 4-bit atlases in src/fonts_data.c (book text, DejaVu Serif
Condensed) and src/fonts_ui_data.c (UI, DejaVu Sans Condensed) are part of
the repository, so a normal build needs no font libraries on the target.
To regenerate them after changing Japanese UI strings in src/lang.c:
python3 tools/gen_fonts.pyThe generator uses the system DejaVu fonts and VL Gothic. Edit the paths at the
top of tools/gen_fonts.py if they differ on your machine.
| Path | Contents |
|---|---|
src/, include/ |
Reader, EPUB/CSS/XHTML parsers, layout, graphics, UI, languages |
third_party/ |
miniz and stb_image |
runner/ |
Deterministic host/MIPS test runner |
tools/ |
Font, sample-library, edge-case, and PPM-to-PNG generators |
library/ |
12 generated sample EPUBs (Polish text, original fixtures) |
library_src/ |
Generated cover and illustration sources |
screenshots/ |
Host, MIPS, and edge-case captures |
dist/ |
Device builds and launcher artwork |
install_to_sd.sh |
SD-card installer for Linux |
- Text: two embedded 4-bit glyph atlases. Book content uses DejaVu Serif Condensed; the interface uses DejaVu Sans Condensed for a clean e-reader look. No FreeType or font files are needed at runtime.
- Layout: a fixed-point, integer-only pagination engine. Pages are built as display lists (text, images, backgrounds, rules) and cached. Smooth scrolling composes two page buffers line by line instead of re-rasterizing text every frame.
- Images:
stb_imagedecodes JPEG/PNG/GIF/BMP without HDR or SIMD; area sampling and alpha composition are integer operations. - EPUB/ZIP:
minizin read-only mode, with archive writing and time APIs disabled. - No FPU: built with
-msoft-float; the reader algorithms use no floating point.make deviceverifies the final ELFs.
The interface is available in:
- English (default)
- Polski
- Deutsch
- 日本語
The Japanese UI font includes the kana and kanji used by the menus and help screens. Full Japanese books need a larger CJK font, which is outside this build. The embedded book font covers Latin, Greek, Cyrillic, and common typographic punctuation; other scripts show a replacement glyph.
- SVG images and SVG covers are not rasterized; those images are skipped.
- DRM-protected or encrypted EPUBs are not supported.
- No right-to-left layout or complex-script shaping (Arabic, Devanagari, etc.).
- CSS support is a practical subset: no
float,position,columns,@font-face, animations, pseudo-elements, or advanced selectors. font-familyis mapped to the built-in serif face; there is no dictionary hyphenation.- Links inside the text are not clickable; the table of contents handles internal anchors.
- No search, delete/rename, or metadata cache. The library is rescanned at startup.
- The core has been tested on the host and on MIPS under QEMU, and installed to a GB300 SD card. A hands-on session on physical hardware is still recommended.
The current build passes:
| Test | Result |
|---|---|
make test (host) |
exit 0, 101 PNG captures |
make test-mips (QEMU) |
exit 0, 42 PNG captures |
make edge-test |
exit 0, 5 PNG captures |
| Hardware-FPU instructions | 0 in both final ELFs |
| SF2000 ELF text / data / bss | 4,392,752 / 3,224 / 3,352 bytes |
Details and observations: TEST_REPORT.md.
The core is not listed in the menu.
Check that the file is exactly /system/Deimos/cores/epub.sf2k, that
/ROMS/EPUB.gba contains epub;epub;EPUB.gba, and that the card is FAT32.
Reboot the console after copying files.
A book does not appear in the library.
Use a DRM-free .epub file and put it in /ROMS/epub/books/. The folder name
is case-sensitive on some card readers; keep it lower-case.
The GB300 build does not start.
The loader looks for epub.sf2k on both consoles. Rename the GB300 asset
epub.gb3k to epub.sf2k when installing it manually, or use the SD bundle.
The cover is missing. SVG-only covers are not supported. The reader shows a generated fallback cover using the title and author.
Text looks wrong or the console freezes on start. Make sure you installed the build for the correct console. The SF2000 and GB300 cores are built separately and are not interchangeable.
The reader, layout engine, UI, and device integration were written for this project. It uses:
- miniz — MIT / public domain
- stb_image — MIT / public domain
- DejaVu Serif Condensed and DejaVu Sans Condensed — Bitstream Vera License
- VL Gothic (Japanese UI glyphs) — BSD-3-Clause / M+ / Sazanami
See NOTICE for the complete third-party notices.
The 12 sample books in library/ are original test fixtures generated by
tools/make_test_library.py; they contain no copyrighted book content.
If FroggyReader is useful to you, you can support further work on Ko-fi:


