An EPD (electronic paper display) class abstraction to simplify communications across multiple display types.
There are several great EPD projects all over the internet, many in written in Python. The problem with a lot of these is that the code is often for one specific type of display, or perhaps a family of displays. This project abstracts the EPD communications into a common interface so a variety of displays can be interchangeably used in the same project.
For project maintainers this expands the number of displays you can use for your project without having to code around each one. To utilize this in your project read the usage instructions. For a list of (known) projects that use this abstraction see the list below.
Installing this module installs any required Python library files. Refer to instructions for your specific display for any additional requirements that may need to be satisfied. A common requirement is enabling SPI support on a Raspberry Pi. Install any required libraries or setup files and then run:
sudo pip3 install git+https://github.com/robweber/omni-epd.git#egg=omni-epd
This will install the abstraction library. The test utility can be used to test your display and ensure everything is working properly. You can also clone this repo and install from source with:
git clone https://github.com/robweber/omni-epd.git
cd omni-epd
sudo pip3 install .
Usage in this case refers to EPD project implementers that wish to abstract their code with this library. In general, this is pretty simple. This library is meant to be very close to a 1:1 replacement for existing EPD code you may have in your project. Function names may vary slightly but most calls are very similar. Refer to the examples folder for some working code examples you can run. In general, once the VirtualEPD object is loaded it can interact with your display using the methods described below. For testing, the device omni_epd.mock can be used to write output to a JPEG file instead of to a display.
Objects returned by the displayfactory class all inherit methods from the VirtualEPD class. The following methods are available to be implemented once the object is loaded. Be aware that not all displays may implement all methods but display is required.
widthandheight- these are convience attributes to get the width and height of the display in your code. See the above example for their use.prepare()- does any initializing information on the display. This is waking up from sleep or doing anything else prior to a new image being drawn.display(image)- draws an image on the display. The image must be a Pillow Image object.sleep()- puts the display into sleep mode, if available for that device. Generally this is lower power consumption and maintains better life of the display.clear()- clears the displayclose()- performs any cleanup operations and closes access to the display. Use at the end of a program or when the object is no longer needed.
If the display you're implementing supports any advanced features, like multiple colors, these can be handled by setting some additional variables. Specifically you can set the variables below in the __init()__ method. See currently implemented displays for a better idea of how to handle multiple colors.
modes_available- a tuple containing the names of valid modes, BW available by defaultmax_colors- The maximum number of colors supported (up to 256 RGB)palette_filter- a tuple of RGB values for valid colors anImagecan send to the display
There is a utility, omni-epd-test to verify the display. This is useful to provide users with a way their hardware is working properly. Many displays have specific library requirements that need to be installed with OS level package utilities and may throw errors until they are resolved. The test utility helps confirm all requirements are met before doing more advanced work with the display. This can be run from the command line, specifying the device from the table below.
# this will draw a series of rectangles
user@server:~ $ omni-epd-test -e omni_epd.mock
# this will draw the specified image
user@server:~ $ omni-epd-test -e omni_epd.mock -i /path/to/image.jpg
There are scenarios where additional post-processing needs to be done for a particular project, or a particular display. An example of this might be to rotate the display 180 degrees to account for how the physical hardware is mounted. Another might be always adjusting the image with brightness or contrast settings. These are modifications that are specific to display requirements or user preferences and can be applied by use of a .ini file instead of having to modify code or allow for options via implementing scripts.
Two types of ini files can be used in these situations. A global file, named omni-epd.ini, or a device specific file; which is the device name from the table below with a .ini suffix. These must exist in the root directory where the calling script is run. This is the directory given by the os.getcwd() method call. Valid options for this file are listed below. These will be applied on top of any processing done to the passed in image object. For example, if the implementing script is already modifying the image object to rotate 90 degrees, adding a rotate command will rotate an additional X degrees. For precedence device specific configurations trump any global configurations. Some displays also have options specific to them only. Consult with that list if these additional options are needed in your situation.
# file shown with default values
[EPD]
type=none # only valid in the global configuration file, will load this display if none given to displayfactor.load_display_driver()
mode=bw # the mode of the display, typically b+w by default. See list of supported modes for each display below
[Display]
rotate=0 # rotate final image written to display by X degrees [0-360]
flip_horizontal=False # flip image horizontally
flip_vertical=False # flip image vertically
[Image Enhancements]
palette_filter=[[R,G,B], [R,G,B]] # for multi color displays the palette filter used to determine colors passed to the display, must be less than or equal to max colors the display supports
contrast=1 # adjust image contrast, 1 = no adjustment
brightness=1 # adjust image brightness, 1 = no adjustment
sharpness=1 # adjust image sharpness, 1 = no adjustment
Below is a list of displays currently implemented in the library. The Omni Device Name is what you'd pass to displaymanager.load_display_driver(deviceName) to load the correct device driver. Generally this is the packagename.devicename Devices in bold have been tested on actual hardware while others have been implemented but not verified. This often happens when multiple displays use the same libraries but no physical verification has happened for all models. The color modes are available modes that can be set on the device.
| Device Library | Device Name | Omni Device Name | Color Modes |
|---|---|---|---|
| Inky | Inky Impression 7 Color | inky.impression | bw, color |
| Inky pHAT Red/Black/White - 212x104 | inky.phat_red | black, red | |
| Inky pHAT Yellow/Black/White - 212x104 | inky.phat_yellow | black, yellow | |
| Inky pHAT Black/White - 212x104 | inky.phat_black | black | |
| Inky pHAT Red/Black/White - 250x122 | inky.phat1608_red | black, red | |
| Inky pHAT Yellow/Black/White - 250x122 | inky.phat1608_yellow | black, yellow | |
| Inky pHAT Black/White - 250x122 | inky.phat1608_black | black | |
| Inky wHAT Red/Black/White | inky.what_red | black, red | |
| Inky wHAT Yellow/Black/White | inky.what_yellow | black, yellow | |
| Inky wHAT Black/White | inky.what_black | black | |
| Omni-EPD | Mock Display (emulates EPD with no hardware) | omni_epd.mock | bw, color, palette |
| Waveshare | 1.02inch E-Ink display module | waveshare_epd.epdlin02 | bw |
| 1.54inch E-Ink display module | waveshare_epd.epdlin54 waveshare_epd.epdlin54_V2 |
bw | |
| 1.54inch e-Paper Module B | waveshare_epd.epdlin54b waveshare_epd.epdlin54b_V2 |
bw, red | |
| 1.54inch e-Paper Module C | waveshare_epd.epdlin54c | bw, yellow | |
| 2.13inch e-Paper HAT | waveshare_epd.epd2in13 waveshare_epd.epd2in13_V2 |
bw | |
| 2.13inch e-Paper HAT B | waveshare_epd.epd2in13b waveshare_epd.epd2in13b_V3 |
bw, red | |
| 2.13inch e-Paper HAT C | waveshare_epd.epd2in13c | bw, yellow | |
| 2.13inch e-Paper HAT D | waveshare_epd.epd2in13d | bw | |
| 2.66inch e-Paper Module | waveshare_epd.epd2in66 | bw | |
| 2.66inch e-Paper Module B | waveshare_epd.epd2in66b | bw, red | |
| 2.7inch e-Paper HAT | waveshare_epd.epd2in7 | bw | |
| 2.7inch e-Paper HAT B | waveshare_epd.epd2in7b waveshare_epd.epd2in7b_V2 |
bw, red | |
| 2.9inch e-Paper Module | waveshare_epd.epd2in9 waveshare_epd.epd2in9_V2 |
bw, red | |
| 2.9inch e-Paper Module B | waveshare_epd.epd2in9b waveshare_epd.epd2in9b_V3 |
bw, red | |
| 2.9inch e-Paper Module C | waveshare_epd.epd2in9c | bw, yellow | |
| 2.9inch e-Paper HAT D | waveshare_epd.epd2in9d | bw | |
| 3.7inch e-Paper HAT | waveshare_epd.epd3in7 | bw, gray4 | |
| 4.01inch 7 color e-Paper HAT | waveshare_epd.epd4in01f | bw, color | |
| 4.2inch e-Paper Module | waveshare_epd.epd4in2 | bw | |
| 4.2inch e-Paper Module B | waveshare_epd.epd4in2b waveshare_epd.epd4in2b_V2 |
bw, red | |
| 4.2inch e-Paper Module C | waveshare_epd.epd4in2c | bw, yellow | |
| 5.65inch e-Paper Module F | waveshare_epd.epd5in65f | bw, color | |
| 5.83inch e-Paper HAT | waveshare_epd.epd5in83 waveshare_epd.epd5in83_V2 |
bw | |
| 5.83inch e-Paper HAT B | waveshare_epd.epd5in83b waveshare_epd.epd5in83b_V2 |
bw, red | |
| 5.83inch e-Paper HAT C | waveshare_epd.epd5in83c | bw, yellow | |
| 7.5inch e-Paper HAT | waveshare_epd.epd7in5 waveshare_epd.epd7in5_V2 |
bw | |
| 7.5inch HD e-Paper HAT | waveshare_epd.epd7in5_HD | bw | |
| 7.5inch HD e-Paper HAT B | waveshare_epd.epd7in5b_HD | bw, red | |
| 7.5inch e-Paper HAT B | waveshare_epd.epd7in5b waveshare_epd.epd7in5b_V2 |
bw, red | |
| 7.5inch e-Paper HAT C | waveshare_epd.epd7in5c | bw, yellow |
Each display type has different install requirements depending on the platform. While loading this module will install any required Python libraries for supported displays; specific OS level configuration may need to be done. Basic instructions are below for each library type. Refer to instructions for your specific display to make sure you've satisfied these requirements. The omni-epd-test utility can be used to verify things are working properly.
Inky
Inky makes things pretty easy with a one-line installer. This makes the necessary OS level changes and pulls in the Inky library.
curl https://get.pimoroni.com/inky | bash
Waveshare
The Waveshare device library requires that SPI support be enabled on your system prior to use. The waveshare-epd module is automatically downloaded and installed as a dependency of this module.
Below is a list of known projects currently utilizing omni-epd. If you're interested in building a very small media player, check them out.
- VSMP+ - My own VSMP project with a built in web server for easy administration.
PRs accepted! If there a fix for any of the documentation or something is not quite clear, please point it out. If you test one of the listed displays, please mark it as verified by bolding it in the Displays Implemented section. If you want to extend this framework by adding a new display type; a good place to start is one of the existing display classes for an example.