What is it? It's a DIY ePub reader for the ESP32.

It will parse ePub files that can be downloaded from places such as Project Gutenberg.

It has limited support for formating - the CSS content of the ePub file is not parsed, so we just use the standard HTML tags such as <h1>,<h2> etc.. and <b> and <i>.

I've only included 4 font styles - regular, bold, italic and bold-italic. I've also only generated glyphs for Latin characters and punctuation.

Why did you build it?

It seemed like a nice challenge - ePub files are not the most friendly format to process on an embedded device. Making it work in a constrained environment is good fun.

Can you contribute/help?

Yes - please try the project out on any e-paper boards that you have and open up pull requests if you get it working with any fixes.

And if you find bugs, feel free to report (or better yet, fix!) them :)

How to get it?

Make sure you clone recursively - the code uses git submodules.

git clone --recursive git@github.com:atomic14/esp32-ereader.git

What boards does it work on?

I've tested it on the LilyGo EPD47, but it should work on any eInk display provided it has:

  • PSRAM - parsing the ePub files needs a fair amount of memory
  • 3 Buttons - these buttons can be active high or low
    • UP - moves up in the list of ePubs or to the previous page when reading
    • DOWN - moves down in the list of ePubs or to the next page when reading
    • SELECT - opens the ePub currently selected ePub file or goes back to the ePub list from reading mode
  • An SD Card - you can jury rig an SPI sd card using the instructions here:
  • [Optional] A battery if you want it to be portable

Porting to other boards

All the configuration is in platformio.ini using pre-processor directives. If you do add a new board then please create a new section in platofmrio.ini with the appropriate pre-processor directives for your board and open a pull request to add it to the project - I'm happy to answer any questions on this.

The important settings are the following:

The first two settings come from the vroland/epdiy library and defined the ePaper display that is being used.

; Setup display format and model via build flags

The second three settings are the pins that are used for the buttons. Change these to match your board.

; setup the pins to use for navigation

There is also a setting to tell the code if the buttons are active high or low.

; buttons are low when pressed

We have the pins for the SD card. I've got a video on how to hack an SD Card and connect it as a SPI device here

; setup the pins for the SDCard

And finally we have the ADC channel that the battery voltage divider is connected to:

; the adc channel that is connected to the battery voltage divider - this is GPIO_NUM_35

How does it work?

Epub files are a bit of a pain to parse. Despite the file extension epub, they are actually zip archives containing multiple files. To read the file I'm using a nice zip library from here: lbernstrone/miniz. This library has been modified to work on the ESP32 with PSRAM. Miniz is actually built into the ESP32 ROM, but support for multifile archives is disabled.

Parsing the ePub file

I've encapsulated the needed ZIP function in a small wrapper class which can be found here: ZipFile

The most interesting file in the epub archive is the OEBPS/content.opf file. This file contains the list of files in the epub archive. The OEBPS/content.opf file is a simple XML file so we need an XML parser to parse it.

To do the heavy...

Read more »