#Test Waveshare ePaper (eInk) 2.7” inch SPI screen on Raspberry Pi in Python

We are used to using OLED or LCD screens for our connected object projects. If energy consumption is a crucial problem for your projects, e-paper screens (also called e-Ink) are a very interesting alternative. The display is obtained by the orientation of colored spheres (black and white or black, white, red) under the effect of an electric field. Once the display has been refreshed, the display needs no power source to maintain the display. I propose you to test in this tutorial an e-Paper screen of the Chinese company Waveshare which offers a complete range of eInk screens. We will test a 2.7 ” diagonal screen. It comes in the form of an expansion card (HAT) compatible with all models and generations of Raspberry Pi. It communicates with the screen via the SPI bus. We will see in the next tutorials how to use this same screen on Arduino, ESP8266 and ESP32.

Contents

Principle of ePaper / eInk screens, advantages and disadvantages

No need to go into the technical details of ePaper screens too much. Everything is already very well explained on Wikipedia here and this article published in 2013 on framboise314 (in french). The screen consists of balls, one side black, the other white, like a frog egg;) By applying a voltage between the two faces of the screen, it causes the orientation of the balls. Some screens even have three orientations, which allows to have a display in three colors. In general, white – black – red. The technology has existed since the 1970s.

Source : Wikipedia, https://fr.wikipedia.org/wiki/Papier_%C3%A9lectronique

The huge advantage of an ePaper screen is that it consumes absolutely nothing. There is no backlight (source of energy consumption). The display being obtained by a change of orientation of colored bubbles, the display persist even in the absence of current. This is a huge advantage over OLED and liquid crystal displays.

However, the orientation of the beads is quite slow. These are the same screens that are used for digital readers (Kindle Amazon or Fnac). To display a new page (image), you must first reposition all the balls in the same direction before you can orient the balls to create the pattern (text, geometric shapes, image …). The operation lasts one to two seconds.

The e-Paper screens are therefore very well suited for making displays that do not require frequent refresh. For example, the temperature, the humidity, the atmospheric pressure, the CO2 content in a room, the weather forecast for the next 5 days, the receipt of a parcel in the letter box … are data that evolves very slowly. It is not a scandal to update the display once an hour.

By cons, rather use a LCD / TFT touch screen to achieve a dashboard (dashboard) for a home automation server.

EPaper screens (eInk) from Waveshare

When looking for e-Paper screens for Arduino or Raspberry Pi projects, there are two major manufacturers. Adafruit and Waveshare. It is quite difficult to get Adafruit screens (apart from living in the USA). Waveshare screens are marketed on major Asian merchant sites as well as on Amazon. I ordered mine on the Waveshare store on AliExpress. Equivalent size, e-Paper screens cost almost the same price as an LCD/TFT. Count around €47 for a 7.5-inch screen.

Waveshare has developed a very complete range. The table below summarizes all available screens. All screens are available with a 3-color display (white, red, black), except for the 4.3 “UART model. The (B) in the reference makes it possible to locate them. Be careful, the refresh time is much longer for 3-color displays. For example, the refresh time for a 1.54 ” screen changes from 2 seconds to 8 seconds. The refresh time is even 31 seconds for a 7.5 inch screen. There is only one display capable of communicating via the UART serial port. All other displays communicate using the 3- or 4-wire SPI bus (default).

Screen

Colrs

Grey level

Resolution (pixels)

Screen size (mm)

Total size (mm)

Refresh time (s)

Interface

Compatible with HAT(1)

1.54 inch

black, white

2

200×200

27.60 × 27.60

48.0 × 33.0

2

SPI

x

1.54 inch (B)

red, black, white

2

200×200

27.60 × 27.60

48.0 × 33.0

8

SPI

x

2.13 inch

black, white

2

250×122

48.55 × 23.71

65.0 × 30.2

2

SPI

2.13 inch (B)

red, black, white

2

212×104

48.55 × 23.71

65.0 × 30.2

15

SPI

2.7 inch

black, white

2

264×176

57.29 × 38.19

85.0 × 56.0

6

SPI

2.7 inch (B)

red, black, white

2

264×176

57.29 × 38.19

85.0 × 56.0

15

SPI

2.9 inch

black, white

2

296×128

66.89 × 29.05

89.5 × 38.0

2

SPI

x

2.9 inch (B)

red, black, white

2

296×128

66.89 × 29.05

89.5 × 38.0

15

SPI

x

4.2 inch

black, white

2

400×300

84.80 × 63.60

103.0 × 78.5

4

SPI

x

4.2 inch (B)

red, black, white

2

400×300

84.80 × 63.60

103.0 × 78.5

15

SPI

x

4.3 inch

black, white

4

800×600

88.00 × 66.00

118.0 × 75.0

1.5

UART

x

7.5 inch

black, white

2

640×384

163.20×97.92

170.2×111.2

6

SPI

7.5 inch (B)

red, black, white

2

640×384

163.20×97.92

170.2×111.2

31

SPI

(1) Connector compatible with Raspberry Pi 2B / 3B / Zero / Zero W. Other displays must be connected using Jumpers.

Last update was on: 27 May 2018 18 h 08 min

2.7 “Waveshare screen test on a Raspberry Pi 3

Waveshare provides several examples on its Wiki. In addition to the code for Arduino and STM32, Waveshare offers three examples. Two examples in C++. The first uses the BCM library, the second the WiringPi library. Here, I propose to you to discover the operation of the screen in Python.

Installing the screen on the Raspberry Pi

Depending on the size of the screen, Waveshare integrates the SPI controller on the screen. For some models (dimension), it is possible to buy separately the controller and the screen. The 2.7 “HAT for Raspberry Pi is similar to LCD / FTF displays. It just fits on the GPIO of Raspberry Pi. Unlike some cards, the GPIO is doomed. If you have used the GPIO for other functions, there is nothing to stop you from using jumpers to wire the screen. There is also a second 8-pin connector on the edge of the screen.

By default, the screen is configured for a 4-wire SPI bus. It is possible to modify the configuration using the cable delivered with the screen. It comes connected below the screen. The screen comes with a spacer set that makes the Raspberry Pi screen stand together.

Configuring Raspbian

Before installing the necessary Python libraries, activate the SPI and I2C bus on Raspbian. Start by updating the system.

Now run the configuration tool with the sudo raspi-config command. Go to option (5) Interfacing Option and then activate the SPI bus and I2C successively. Accept the restart when you exit raspi-config to activate the buses.

raspberry pi i2c activate raspi-config

Once restarted, open the driver configuration file with the command sudo nano /etc/modules . Check that the following drivers are present. Restart Raspbian to reload the drivers ( sudo reboot ).

Installing python libraries

There is some useful info on WiFi Waveshare but it is necessary to delve a little to find out especially to find the Python libraries to install. I spent a lot of time finding good bookstores. If you encounter difficulties, do not hesitate to put them back in the comments.

Here is what I install to develop in Python. Run the following command that will install python-dev and the python-pil and python-imaging libraries. In fact, the drivers delivered in the examples “just” display an image that we have previously built using the Python Imaging library. The advantage is that we have all the primitives of the library, namely geometric shapes (line, rectangle …), text, font management and writing size …

Then you have to install the libraries to manage the SPI communication

And last with the help of the pip command that installs the library spidev

That’s it, everything is ready, let’s get down to business now!

Get the epd driver

For this step, you will have easier to connect to the Raspberry Pi in SSH. You can easily paste links and code from your usual computer. Follow this tutorial to learn how to do it.

There are no universal drivers. Waveshare has developed (and configured) a driver for each screen. This one comes with the examples. Go to the WiKi and go to the page that corresponds to your screen. The 2.7 inch screen page is here. At the bottom of each page is a place to the examples page (Demo code). Open the example page to retrieve the link to the compressed file by right-clicking on the link.

From the Terminal on the Raspberry Pi, create a working directory, for example mkdir epaper  then open this one cd epaper . Then, using the wget command, we will retrieve the sample file.

To decompress it, we will use the tool p7zip. Run the following command to install it

We just have to decompress the archive with the command 7z x file_name.7z like this

Then go to the python sample directory

First test, displaying a full square in the center of the screen

Open a new script named rectangle.py with the nano rectangle.py  command and paste the following code. At a minimum, we need to import the epd driver (here eps2in7 for 2.7 ”), as well as the Python Image and ImageDraw libraries.

What does this code do:

  • We create an epd object and initialize it. This object will provide access to the screen management functions. The only really important is the display_frame() refresh method
  • An object of type Image is then created having as dimension the width(width) and the height(height) of the screen in pixels. Here 176×264 pixels.
  • Then draw a rectangle in the center of the screen based on the width and height of the screen
  • Finally we call the display_frame() method to refresh the display.

Save the script with the combination CTRL + X then Y. Run the script with the python rectangle.p y command

You must get this nice rectangle in the center of the epaper screen. You can see the refresh process at the same time

Bonus, recover the events of the 4 function buttons

You must have noticed the presence of 4 buttons on the side of the screen (key 1 to key 4). It is possible to retrieve in the python code a press of a button and trigger for example the refresh of the screen. It can also be used for other functions. One could also trigger a scenario on a home automation server.

Each button is connected to a GPIO pin of the Raspberry Pi.

  • Key 1 on pin 12
  • Key 2 on pin 16
  • Key 3 on pin 18
  • Key 4 on pin 4

Depending on your screen, the pins can change, we find the info on the technical diagram. For example here for the 2.7 ” screen

Create a new nano demo.py script and paste the following code

It intercepts a press on each button. Pressing the 4 button updates the display



As you can see, the text is created horizontally on the image. We will see how to orient it correctly soon.

Here it is, finished for this tutorial. We will see in future articles how to use it on an Arduino microcontroller (and probably ESP32, ESP8266). We’ll see how to retrieve info from a Jeedom and Domoticz home automation server to create a small viewer.

Subscribe to the weekly newsletter

No spam and no other use will be made of your email. You can unsubscribe anytime.

DIY Projects