Today we are going to see how to use Electronic Paper, or e-Paper, displays with both an Arduino and a Raspberry Pi. I’ll also show you a “no-code” method of creating a fancy e-Paper display panel using an amazing utility called “PaperPi”.
While e-Paper displays might not be perfect for every application, they are great choices if you need a low-powered display that is visible in daylight.
We’ve used a number of different types of displays in our projects here in the DroneBot Workshop. Liquid Crystal Displays, or LCDs, are low-cost and are suitable for use in normal or low-light situations. Organic Light-Emitting Diodes, or OLEDs, are high-brightness displays that can be used in almost all lighting conditions, although they are a bit hard to see in direct sunlight.
Electronic Paper, or e-Paper, displays are a bit of a different beast. They are very much like conventional paper, readable in normal and brightly lit situations, but not in dim or dark lighting. They work well in bright sunlight, and they provide a very wide viewing angle.
Aside from visibility, there are other factors to consider with e-Paper displays.
- They consume very little electricity.
- They don’t have very fast refresh rates.
- They have limited color capabilities.
- They are more expensive than most other technologies.
Despite these disadvantages, there are areas where e-Paper displays really shine. A very common application is with e-readers, like the Amazon Kindle. Their low-power consumption and paper-like appearance make them ideal for replacing standard paper in books.
e-Paper also finds application in large display panels, such as the ones used in airports or bus terminals. They also can be a good choice for portable instruments and “intelligent” price tags.
How e-Paper Works
e-Paper displays were originally developed in the early 1970s by Nick Sheridon at the XEROX Palo Alto Research Center (PARC). The original product was called “Gyricon”, and it consisted of polyethylene spheres measuring about 100 micrometers across.
e-Paper displays work using the principle of Electrophoresis, the movement of electrically charged molecules within an electric field. When a charge is applied, the spheres move towards or away from the electric field, depending upon polarity.
These displays employ millions of e-Ink capsules, each of these capsules contains both spheres that are either positively or negatively charged. The two different spheres have different colors, so their arrangement within the e-Ink capsule depends upon external electrical charges.
By altering the polarity of the electrical field around the capsules, their internal spheres can be attracted or repelled to show either a black or white surface. Multicolored e-Ink displays use colors other than black.
In an e-Paper display, these e-Ink capsules are suspended in a liquid polymer between two grids of electrodes, with each electrode being the width of an individual pixel. The top layer is transparent.
When electrical charges are applied to the electrodes, with the top and bottom electrodes at the opposite polarity, the e-Ink capsules align themselves according to the electric charge. This has the effect of changing the display pixels, which produces the pattern you see from the top.
As an added bonus the charge on the capsules is retained indefinitely, the polarity reversal only needs to happen to change the existing display. As a result, the pattern is retained for a very long time, literally years or even decades.
Advances in e-Paper technology have allowed for full-color displays, as well as improved switching time. These advanced displays are beyond the reach of most experimenters, at least for now. But in the future, you could see e-Paper being used for video displays, ones that require very little current and that have a very wide viewing angle and that are useable in daylight.
The display I’m using in my experiments is a Waveshare 2.7-Inch e-Paper HAT. The only reason I chose this display was that it was in my parts drawer, and you could use other displays instead. Waveshare makes a wide variety of these displays, and as I’ll be making use of their libraries and example code you’d be best to use one of theirs if you want to follow along.
This display can be used either as a HAT (Hardware Attached on Top) for a Raspberry Pi or as a stand-alone unit connected via its SPI bus connector. Thai allows it to be used with pretty well any microcontroller or microcomputer.
The display is a 3.3-volt unit, but it is 5-volt tolerant, so you can use it with 5-volt devices as well.
The SPI bus on the display is “input-only”, so only the MOSI (Master Out – Slave In) connection is used for data.
The version I have can actually display two colors (black and red), but the code I’ll be using only uses the black display.
e-Paper with Arduino
For our first experiments, we will be using an Arduino, connected to the e-Paper display via the SPI connector. While I used an Arduino Nano 33 IoT board, any Arduino, including an Uno, will work with this display, as it accepts 5-volt microcontrollers. If you are using a different display, you’ll want to make sure it is also 5-volt tolerant.
Here is how I hooked up my Arduino to the e-Paper display:
If you are using a different microcontroller you may need to modify the wiring, you can use this description of the connections to make the changes:
- 3.3v – The 3.3-volt power input for the display. Note that if you are using a 5-volt microcontroller you still need to supply the display with 3.3-volts. Don’t connect this to a 5-volt power supply.
- GND – A ground connection, pretty self-explanatory!
- DIN – the Data In, which is the MOSI connection on the SPI port.
- CLK – The SPI bus clock input.
- CS – The SPI bus chip select (sometimes called device select).
- DC – Data/Command input. If held HIGH then the SPI bus is sending data, if LOW then it is sending command signals.
- RST – External Reset, send this pin LOW to reset the display.
- BUSY – An output from the display, if LOW then the display is busy and cannot accept data.
Waveshare provides a handy cable to make the connections to a microcontroller. If you are using it, then the colors in the schematic above match those on the cable.
The easiest way to get started with the e-Paper display is to make use of the libraries provided by Waveshare. These libraries also include some example code you can test your display with.
Unlike other Arduino libraries, you cannot install these using your Library Manager. Instead, you’ll need to do it manually.
I have actually found two sources, both on GitHub, for obtaining these libraries.
- The official Waveshare repository at https://github.com/waveshare/e-Paper
- Another repository at https://github.com/soonuse/epd-library-arduino
The Waveshare repository has a much biggest selection of displays to choose from, it also has code for the Raspberry Pi, which we will be using later. The ”soonuse” repository contains fewer e-Paper boards, but it is structured properly for the Arduino IDE, whereas the Waveshare one is not. In both cases, the code was created by Waveshare.
Either way, the installation procedure is to first download the repository as a ZIP file. Then extract it to somewhere convenient.
Now probe through the extracted files to find the folder that matches your display. If you are not sure which folder to use the “soonuse” page has an image illustrating the different displays.
Once you have found the folder, copy it into your Arduino “libraries” folder or directory.
Now that you have your example code inside the libraries folder, start your Arduino IDE. If it was already running you may need to close and open it again.
Open the File menu and then click on Examples. A sub-menu will open. Scroll down into “Examples from Custom Libraries”. Look through the examples until you find your e_aper board name.
If you used the “soonuse” files then the listing will open a sub-menu with the example code in it. If you used the Waveshare download, then the code will be directly inside the menu (which is why I said it wasn’t structured correctly for the Arduino IDE).
Either way, open the file and take a look at it. It is a good example of how to use the e-Paper display. It also includes additional files with images in them.
After you examine the sketch, upload it to your Arduino, and watch the display.
The code is all in the Setup function, so it only runs once and then ends. It cycles through a number of display examples.
After you finish, you might want to power everything down and observe the display. As this is an e-Paper display, it will hold the last image written to it.
e-Paper with Raspberry Pi
As the board I am using is a Raspberry Pi HAT, it is quite simple to use it with a Pi. Any Raspberry Pi with a 40-pin GPIO connector will work, I used a 2GB Raspberry Pi 4 in my tests.
With the Pi powered off, mount the HAT onto the GPIO, making sure to align the pins correctly. Now boot up the Pi with a copy of the latest version of the Raspberry Pi OS.
Before you do anything, you’ll need to enable the SPI bus, as it is disabled by default. Go into the Preferences menu and choose Interfaces. Toggle the SPI slider on.
Running Raspberry Pi Demos
As with the Arduino, we are going to get started by running some demonstration software provided by Waveshare.
Open the Terminal by clicking the icon on the top menu bar. Now type the following at the command prompt:
sudo git clone https://github.com/waveshare/e-Paper
This will create a directory called e-Paper inside your Home directory, and it will be populated with the Waveshare libraries and code. You can open the File Manager and examine the contents if you wish.
Now, back at the terminal, change into the directory for Raspberry Pi and Jetson Nano by typing the following:
If you list the directory contents (type “ls” to do this) you will see two more directories, one for C, and one for Python. We want to go to the Python one, so change into that:
Finally, go into the examples directory:
The examples directory has a long list of python files, one for each display type. As with the Arduino, you will need to know which display you are using.
Now run the file associated with your display, For my display, the 2.7-inch e-Paper HAT, I ran the file as follows:
The resulting demo is similar to the Arduino one, with text and images displayed in various orientations.
You can look through the demo code to understand how it works.
e-Paper coding with Python
Running demonstration code is a great way to make sure that all of your hardware is working, and examining the code can teach you how to use the display. But the real fun in working with devices like Arduino’s and Raspberry Pi is writing your own code.
So, let’s write a simple Python program to drive our e-Paper display with a Raspberry Pi.
The code example that I will use can write both text (in 2 font styles) and an image to your display. You can, of course, modify it to suit your own requirements.
Before we jump into the Python code, we should set up a directory on our Raspberry Pi to hold the code and all the required files.
You can get all the files used in my example in a ZIP file in the Resources section at the end of this article.
First, create a new directory off of your Home directory, you can use the File Manager to do this. You can name it anything you wish, I called mine “mypython”.
You will need the Python library files from Waveshare in your new directory. Technically you don’t really need to do this, as you can just point to the ones you downloaded in the example code, but it is a lot easier just to copy them to your new directory.
Grab the “lib” directory from the following location and copy it to your new folder:
Next, you will need to add another folder, one called “pic”, which you will use for images and fonts.
You can use the font I did if you wish, it’s in the ZIP file in the Resources section. It’s called “Avenir Next”, and I obtained it from GitHub. Or you can use your own TrueType font.
For the image, I would suggest a bitmap (.BMP) picture, although a PNG will also work. Make sure you scale it to the required size. I’ve included my “robot” file in the ZIP file.
Both of these files need to be in the “pic” folder”
Now, finally, you can write your code (or copy mine) into your main folder. You can use the Thonny IDE, included with the Raspberry Pi, to edit the code. The code looks like this:
# import required python libraries
# get display from Waveshare library
from waveshare_epd import epd2in7
# get functions from Pillow
from PIL import Image, ImageDraw, ImageFont
# image directory
pic_dir = 'pic'
# initialize display
epd_disp = epd2in7.EPD()
# clear display, 0 is black, 255 is white
# reverse width and height as display is sideways
w = epd_disp.height
h = epd_disp.width
top_font = ImageFont.truetype(os.path.join(pic_dir, 'Avenir Next.ttc'), 18, index=1)
bottom_font = ImageFont.truetype(os.path.join(pic_dir, 'Avenir Next.ttc'), 16, index=5)
# define and draw background
image = Image.new(mode='1', size=(w, h),color=255)
draw = ImageDraw.Draw(image)
# position and draw text
draw.text((15, 0), 'Welcome to the Workshop!', font=top_font, fill=0, align='left')
draw.text((10, 150), 'https://dronebotworkshop.com', font=bottom_font, fill=0, align='left')
# get robot image
dbwsbot = Image.open('pic/dbws-robot.bmp')
# paste image onto background image
image.paste(dbwsbot, (80, 35))
# write buffer contents to display
except IOError as e:
We begin by importing the required Python libraries, as well as the custom libraries from Waveshare.
We then import libraries from Pillow, a popular imaging library. It should already be on your Raspberry Pi, but if you have an older version of the operating system it may not. If so, you can install it at the command line as follows:
sudo apt-get install python3-pil
Back to the code. The last item in the definitions is to create a variable that defines the location of the “pic” directory.
In the try section, we do the following:
- Initialize the display
- Clear the display, making it all white.
- Reverse height and width. I do this as I want a horizontal display, if you want a vertical one then change the definitions. I also print these values to the console, it helps when “fine-tuning” the text and image positions.
- Define the fonts. Note that we define the font location, the font size, and the style, which is called “index”. Every font has different index values, check your documentation if you use a different font.
- Draw the background, which in this case is all white (255). You can change the value of “color” to make it black (0) or a shade in between.
- Position and draw the text. Specify the location and font, plus the text itself.
- Get the image.
- Paste the image onto the background
So far we have been writing everything into a buffer, it isn’t actually written to the display yet. The final command writes the buffer contents to the display.
We also define an exception routine to print errors to the console.
Run the Demo
Click the Run button at the top of the Thonny IDE, and observe the display.
After a refresh, you should see your text and image on the display. You can modify the code and reposition it, or experiment with the fonts.
As you can see, it’s pretty easy to write to an e-Paper display using Python on a Raspberry Pi.
Earlier, I had promised that I would show you a method of creating an advanced e-Paper display without requiring any coding. That method is PaperPi.
PaperPi is a project that allows you to use a Raspberry Pi to create a dynamic e-Paper display panel. It makes use of plugins, and there are several to choose from. Some examples are:
- A Music Player
- Several varieties of clocks
- A cryptocurrency value monitor
- A weather display
- Phases of the moon
And many more.
PaperPi Hardware Requirements
The basic hardware requirements for PaperPi are pretty simple:
- A Raspberry Pi – Models 3 and 4 are supported, but it might also work on a Pi Zero model 2.
- A Waveshare e-Paper display – There is support for virtually any Waveshare e-Paper display.
Most of the plugins will require an Internet connection, which you also need to install PaperPi in the first place. Wired or WiFi and both fine. You’ll also need to have the SPI port activated on the Raspberry Pi, which we already did when we performed our e-Paper demos earlier.
If you want to create a music player that can link to either Spotify or the Logitech Media Server, then you’ll also need a sound card, or DAC, that can be mounted on the Raspberry Pi GPIO along with your display.
While any size of e-Paper display can be used, you’ll have the best results with larger displays. The small 2.7-inch display I’m using is actually too small for some of the provided applications, nonetheless, it’s a good way to get familiar with PaperPi, and it will run several plugins.
PaperPi runs under the Raspberry Pi Operating System, so you’ll need a microSD card with the OS (as you would for any Raspberry Pi project).
The GitHub page for PaperPi gives complete installation instructions, and you should refer to it in the unlikely chance that you run into problems.
Begin by opening up a Terminal window on the Raspberry Pi and typing the following command to obtain a compressed file with the latest version of PaperPi:
The file is not very big and should download in a few seconds.
Next, you’ll need to extract the files from the archive:
tar xvzf paperpi_latest.tgz
During the extraction process, a directory called “paperpi” will be created in your Home directory.
The first time you run PaperPi it will detect that it hasn’t been used before, and it will create a configuration file. Get this process in motion by typing the following:
Once it has run, you’ll get a message saying that the configuration file has been created. You will need to edit this file to let PaperPi know what sort of e-paper display you are using.
Edit the file using the nano editor:
In the configuration file look for a line that says “display_type = none” . Replace the word “none” with the type of Waveshare display you are using.
For example, using my 2.7-inch Waveshare display I edited the file as follows:
display_type = epd2in7
Save the file (Ctrl-X) and run PaperPi again.
If everything is working correctly, you’ll get a PaperPi splash-screen on your e-Paper display, along with a message saying that no active plugins were detected. The display will also show the time from your Raspberry Pi clock.
On the Terminal, the PaperPi process will end, and you’ll be returned to the command line.
In order to make use of PaperPi, you’ll need to set up at least one plugin. You can use as many as you wish, the display will cycle between them.
There is no additional software to install, as all the plugins are already included with PaperPi. They just need to be activated by editing the configuration file.
Open the configuration file for editing in nano again and scroll down to the section listing all the plugins.
Every plugin will have an entry that begins with “xPlugin”. In order to activate the plugin, you simply need to remove the letter “x”, so that it just reads “Plugin”.
For many of the plugins that’s all there is to it, but some plugins require additional information. For example, the weather plugin needs to know your location (longitude and latitude) in order to display your local weather. Some services like Spotify will require your account information.
I suggest you enable the plugins one at a time, saving and exiting nano after you do. Then run PaperPi and see the results.
The GitHub page for PaperPi contains more information, including information about running PaperPi so that it starts as soon as the Raspberry Pi is started. There is also information about building your own plugins, and even some instructions for creating a very nice “picture frame” display for your project.
While e-Paper displays tend to be a bit expensive and have some limitations, they are still useful for many tasks. You can use the examples presented here to design your own e-Paper projects.
If you just want to make a cool project without coding, then experiment with PaperPi, it’s a fast way to produce a very impressive e-Paper based project.
Hopefully, this article, and its accompanying video, have given you some ideas for using e-Paper displays in your own designs.
Python Example Code – The Python example code, along with image, library, and font files.
Waveshare e-Paper Repository on GitHub – Get the C++ and Python code for driving Waveshare e-Paper displays.
Alternate Arduino Repository – The “soonuse” repository on GitHub.