FreEader - minimal e-book reader

How do we get from an arbitrary formatted e-book to our bi-level image byte-stream?

With a comletely free toolchain, of course. A graph says more than words.

Try it out for yourself at our repository: https://github.com/ventosus/freeader

All example schematic and firmware code examples from the good display GDE043A2 e-paper display seem to have disappeared from the web. Luckily I had downloaded them last year already and now uploaded to hackaday.io [4] so they shall be preserved until eternety.

In the meantime, the GDE043A2 seems to have been deprecated and replaced with the GDEP043WC3 [3], a new 4.3" display with dimensions 800x480px, a resolution of 217 DPI and 16 gray levels. I don't quite like the aspect ratio of that display (16:9.6). They promote it as e-paper phone display, in that regard, that ratio may well make sense, but it's not ideal for the FreEader.

However, the GDE043A2 [1] and its demo kit [2] seem to still be available, I'd better hurry up purchasing one...

1. http://www.buy-lcd.com/index.php?route=product/product&path=2897_8369&product_id=12515
2. http://www.buy-lcd.com/index.php?route=product/product&path=2897_8369&product_id=14630
3. http://www.good-display.com/products_detail/&productId=317.html
4. https://hackaday.io/project/4025-freeader-minimal-e-book-reader#menu-files

Which EPD should I design for?

An EPD from http://www.eink.com/ is ouf of question, as they don't sell to individuals.

But there are at least two others, that sell EPDs to individuals, have informative documentation and even offer development kits:

• http://www.pervasivedisplays.com/
• http://www.good-display.com

So which one should I go with?

My prerequisites are to get a small EPD around 4" with a good resolution.

I first looked at this here: http://www.pervasivedisplays.com/products/441, but it has only 113dpi (400x300 px) which may be suitable as an electronic shelf label, but not ideal for an e-book reader. This EPD is only black/white (1 bit color).

Then I found this here: http://www.good-display.com/products_detail/&productId=167.html which has awesome 230dpi (800x600 px). There is even a development kit based on an STM32F103xx with schematics and complete firmware code which should be easy to migrate to a STM32F303xx. This EPD is black/darkGray/lightGray/white (2 bit color).

I guess I will get one of their kits to experiment with before designing my own hardware.

Althoug freeader should be a minimal reader, there must be some way to navigate between books, e.g. a kind of menu structure.

This menu structure will also be prerendered pixel data, like the books themselves.

I use Edje from the Enlightenment Foundation Libraries (EFL) as underlying theming and layouting engine.

https://docs.enlightenment.org/auto/eio/edje_main.html

https://docs.enlightenment.org/auto/edje/edcref.html

Why Edje? I have built other things on top of the EFL, know them well and like them a lot.

https://github.com/ventosus/edje2yuv

https://openmusickontrollers.github.io/lv2/synthpod/

With Evas (the EFL canvas library) you can draw to pretty much everying (X11, openGL, Wayland, framebuffer, pixel buffer, ...). Here I draw to a pixel buffer and then compress it with JBIG1.

https://github.com/ventosus/freeader

I run my tests on a STM32F303CC for now, which has a nice feature called CCM (Core Coupled Memory).

From AN4296 (http://www.st.com/web/en/resource/technical/document/application_note/DM00083249.pdf):

[...] The STM32F303xB/C and STM32F358xC CCM RAM is tightly coupled with the CortexTM
core. it is primarily intended to execute code at maximum system clock frequency (72 MHz)
without any wait state penalty. It thus allows to significantly decrease critical task execution
time, compared to code execution from Flash memory.
CCM RAM is typically used for real-time and computation intensive routines [...]

[...] When code is located in CCM RAM and data stored in the regular SRAM, the Cortex-M4
core is in the optimum Harvard configuration. [...]

[...] A benchmark between the STM32F103xx and STM32F303xx microcontrollers using
STMicroelectronics MC library V3.4 shows [...] that the STM32F303xx is 20.33 % faster than the
STM32F103xx thanks to the CCM RAM [...]

I have of course tested this by adding support for CCM RAM to libopencm3 and was quite surprised with the speed up in decompressing 1 page of 800x600px JBIG1 encoded data from 768ms (code on FLASH) to 506ms (code on CCM RAM).

The speed up is quite substantial with -34 %.

Lessons learned:

• I will definitely design for an STM32F30x

• and put the decompression algorithm code (and other time critical code) into CCM RAM

I've measured decompression time of JBIG1 compressed page 0013 of 'flatland' on a STM32F303CC.

The source page was the following 800x600px image with an umcompressed size of 60kB.

The corresponding JBIG1 compressed image had a size of 7kB (11.6%) and was directly flashed to uC flash memory.

It took 768ms to decompress with the uC running @72MHz.

This may seem like a lot, but it will take around 1000-1500ms to refresh a 800x600 e-ink display in the first place.

With parallelising the three loops which load compressed image data from SD card, decompress and display it line by line, this should work out well, though.

Lessons learned:

• I'll need at least an ARM Cortex M3 running @72MHz with at least 8kB of RAM for the freeader hardware design, can't possibly go below if I want to use prerendered compressed image data and refresh the display under 1.5s.
• A will thus design for STM32F30[2,3], as it is pin-compatible with STM32F103, but features an embedded DFU bootloader.

The freeader will be designed to load prerendered text as bilevel (1 bit per pixel) image data.

Considering an image size of 800x600 pixels, this gives a raw storage size of (800*600/8=60kB) per page.

To safe space on the SD card and to speed up loading of pixel data from the SD card by the uC, we'd like to compress the pixel data if possible.

The following questions arise thereby:

• Are there special compression algorithms for bilevel text documents?
• Are there decompression algorithms suitable to run on a uC?

So, let us compare some widely used compression algorithms to the raw image data (pbm)

• LZO (https://en.wikipedia.org/wiki/Lempel–Ziv–Oberhumer)
• CCITT Group 3 (https://en.wikipedia.org/wiki/Modified_Huffman_coding)
• CCITT Group 4 (https://en.wikipedia.org/wiki/Group_4_compression)
• GZIP
• BZIP2
• XZ
• JBIG1 (https://en.wikipedia.org/wiki/JBIG)
• JBIG2 (https://en.wikipedia.org/wiki/JBIG2)

The CCITT*, and JBIG* are special compression algorithms for bilevel image data (FAX, scanned documents).

I use two cases for the comparison, in each one I have compressed the first 99 pages of 'Flatland'. Once all pages appended into a single image, and once each page on its own.

From the figures below, you can clearly see, that the JBIG* algorithms perform best. Only the Group 4 version of the CCITT compression may be suitable, though.

So, which one of CCITT Group 4, JBIG1 and JBIG2 whould we use on the uC to decode image data?

This is a matter of available libraries, computational cost and memory usage. Ideally, a given decompression algorithm should not use any dynamic memory and would be designed with a byte stream API, e.g. read some bytes of compressed data until a complete image line has been decompressed, update the decompressed image line on the display, read next chunk of compressed bytes from SD, ...

Are there any free decompression libraries out there:

CCITT: http://www.libtiff.org/, ftp://alpha.greenie.net/pub/mgetty/tools/viewfax-2.4.tar.gz

JBIG1: https://www.cl.cam.ac.uk/~mgk25/jbigkit/

JBIG2: http://www.ghostscript.com/jbig2dec.html

There is no standalone library for CCITT compression, but the algorithms could be extracted from various projects (libtiff, imagemagick, gimp, viewfax). CCITT compression is lightweight, can be implemented with a byte stream filter design and would thus be readonable to be run on a uC. But I would need to write the filters from scratch for usage on uC.

There is a library for JBIG1 compression/decompression, it uses only ~4kB static memory, uses no dynamic memory, has a byte stream API and is optimally suited to be run on a uC. It can directly be used on a uC.

There are separate projects for JBIG2 compression/decompression. The decompression library needs a lot of memory, as whole pages need to be present in memory (no byte stream filter design). It would need to be migrated to a a byte stream API design to be usuable on a uC. The JBIG2 compression has a lossless and lossy mode. The lossless mode is similar to JBIG1, the lossy mode can reach much higher decompression rates (but it needs a lot of memory).

We obviously have a winner, it's JBIG1, as it has a readily available library with a byte stream API design, uses little static memory only and offers very good compression (10%).

I will need to test the algorithm on a real uC, though, to find out how computationally expensive it is...

For doing tests with the freeader ebook conversion toolchain, I need a test ebook, right?

I chose a short classic as simple test ebook:

• Flatland: a romance of many dimensions by Edwin A. Abbott

https://en.wikipedia.org/wiki/Flatland

Why? Because it's short (short conversion times) and I like it alot.

It's about politics, hierarchy, power, suppression, religion, geometry, reality and it's a lot of fun to read.

The narrator is a rectangle living and explaining live in Flatland and to be chosen one day to experience the third dimension.

If you shouldn't know it already, go read it, it's freely available from project gutenberg.

https://www.gutenberg.org/ebooks/97