Frustration-free e-paper usage for Linux

Intro

E-paper (electrophoretic display technology) has found its way into more and more products and personal projects over the last few years. One thing that hasn't come with this widespread adoption is a way to make them easier to use - they're uniquely difficult and frankly they're frustrating. Why frustrating? There are some aspects of using these displays that offer unique challenges. These tend to be one of the following:

  • They need an external DC/DC boost circuit and 24-pin 0.5mm FPC. Difficult to create on your own
  • Many displays share the same exact size/look, but are incompatible. There are two main families of controller chips (Solomon Systech and UltraChip), but even within those two there are multiple versions that can be incompatible.
  • They behave very differently compared to other all-points-addressable displays. It is unfortunately necessary to learn a bit about the physical properties of them in order to use them correctly.
  • The vendors don't provide good documentation nor good example code. The provided code may work on your hardware, but offers a minimal starting point for your project.
I've created a few ways to reduce this frustration...

The Library

I've been working with these displays for several years and have written a lot of code to talk to them. About a year ago I decided to start from a clean slate and write a comprehensive, well designed library to control them ALL. The result is bb_epaper. A portable C (with C++ wrapper) library which can talk to nearly every SPI-connected e-paper display in the market. It includes 2D graphics primitives, compressed fonts and images and uses the same API as my other display libraries. The C code is completely portable to any target hardware and I've included I/O wrapper functions to allow it to build on Arduino, ESP-IDF, and Linux. If you want to use it on STM32 or some other system, it's quite easy to provide a few lines of wrapper code to enable it. I've included a bunch of examples and relatively voluminous documentation.

A library and documentation aren't always sufficient to get things working with these displays. There are some fundamental barriers to getting them to function that create significant frustration for a large portion of the people using them.

The Tool (show_png)

Linux offers something unique and helpful to enable simplifying use of these displays. The large memory spaces, robust infrastructure and standard tooling allow the creation of powerful command line tools that can be easily executed from a shell or called from within your favorite high level programming language. I came up with the idea of an image display tool as a way to simply many common use cases of e-paper displays. It has the secondary benefit of being a very complete example project from which to grow your own. My original idea was to provide an easy way to display PNG (and BMP) images, but it has already grown into a much more complex program. The input file format is less of an issue than the other features. It currently manages grayscale thresholding and color matching to look best on the display you're using. For example, in the photo below I passed it a full color PNG image and configured the output for a 3-color (Black/White/Red) display. It does a "best effort" to match the colors and the result looks quite good. The display in use is a Pimoroni Inkyphat 3-color 2.13":

The original image below



At the time of this writing, 3-color (B/W/R) displays are being removed from the market and replaced with 4-color (Black/White/Yellow/Red). It makes sense since the addition of 1 more color doesn't add significant cost or complexity compared with the 3-color versions. The red color 'wasted' a whole memory plane and now red+yellow take its place.

To display the image above, you need to provide the tool with some info:

The e-paper adapter (GPIO connections are implied from that)
The epaper panel type
The update mode (full, fast, partial)
The input filename

All of the above can be provided in a JSON file (epaper.json) or command line parameters or both. To display that image above, you pass the following parameters:

./show_png file=~/snoopy.png adapter=pimoroni panel_2bit=EP213R_122x250

The only real challenge is correctly choosing the panel. I created a Wiki page which maps product names to my internal panel names.

Going Further

Like all software, this current version should not be considered 'the end'. Beyond its current features, I can see the next step would be to add additional image file support such as JPEG. What do you think? Please leave a comment below.

Comments

Post a Comment

Popular posts from this blog

How much current do OLED displays use?

Image
Those little OLED displays are everywhere, and there's a good reason. They're inexpensive, easy to program and they look good. I wanted to explore how much current they draw so that I can plan better for battery powered projects. Questions I want answered: How much idle current is drawn when the controller is off versus on (blank display)? What's the minimum current to see text indoors? What's the maximum current when all pixels are on at their brightest? How does display size affect current draw? How does active data writing affect current draw? It's obvious they use more, but how much current do grayscale and color OLEDs use? How practical are OLED displays compared to common LCDs for battery powered projects? Materials: Cheap multimeter (manual scale, assumed accuracy +/-10% at worst) Various OLED displays (72x40, 96x16, 128x32, 64x32, 128x64-0.96", 128x64-1.3") Arduino compatible microcontroller ( Adafruit nRF52840 Feather Express ) ...
Read more

How to speed up your project with DMA

Image
Intro DMA ( direct memory access ) is a topic that's similar to pointers in C - it's not easy for everyone to visualize how it works. My goal for this blog post is to explain, in the simplest way possible, how it works and why your project can benefit from proper use of it. What's it all about? DMA is a useful feature for a CPU/MCU to have because it means that data can move around without the CPU (your code) having to do the work. In other words, DMA can move a block of data from memory-to-memory, peripheral-to-memory or memory-to-peripheral independently from the CPU. For people used to programming multi-core CPUs with a multi-threaded operating system, that may not sound very special. For those of us familiar with programming slow, low power, single threaded, embedded processors, it can make quite a difference. Here's a practical example - sending data to an SPI device (e.g. a small LCD display): Without DMA <prepare data1 - 10ms > <send data1 to SPI - 10ms...
Read more

Fast SSD1306 OLED drawing with I2C bit banging

Image
What The  SSD1306  OLED displays are very popular with hobbyists due to their low cost and easy interfacing. The majority of the ones sold expose a two wire interface (TWI) aka I2C. The default speed for I2C is 100Khz and the "fast" mode is 400Khz. These are the 2 standard speeds supported by most AVR Arduinos. An I2C clock rate of around 800Khz is also possible on AVR MCUs, but not supported directly by the Wire library. The I2C standard recently added some higher speeds (1Mhz and 3.4Mhz). The 3.4Mhz version uses a slightly different protocol. At 400Khz, using the I2C hardware and the Wire library, I was able to refresh the display around 23.5 frames per second (FPS) with my code. Why I have already written a SSD1306  library for both Linux and Arduino, but I wanted to drive the display from an ATtiny85 and learn about the I2C protocol in the process. The ATtiny85 doesn't have I2C hardware built in, so it needs to be emulated in software using GPIO pins. There ...
Read more