The EPaperDisplay class is similar to the Display class discussed previously, but is specific to electronic paper display (aka EPD, eInk, epaper, etc.) hardware.
Also much like Display, you rarely, if ever, will use the EPaperDisplay class directly. Instead, you will use a library which takes care of display specific setup for the many available EPD breakouts and boards. Some examples include:
If you have one of those EPDs, you can just use the corresponding library. The code there can be useful as examples for other EPDs.
Boards with Built in EPDs
If you are using a board with a built in EPD, like the Adafruit MagTag, then an EPaperDisplay will already be setup for you in the CircuitPython firmware. You can access it simply with:
import board epd = board.DISPLAY
EPD Usage
The general usage of EPaperDisplay is much like regular Display. Use display.root_group to establish what Group will be shown. There are width and height properties available to query display size. There is also a rotation property that can be used to query / set rotation.
To actually display the Group, you call refresh(). However, there are EPD specific things which must be taken into account. We discuss those next.
EPD Specific Behavior
EPDs are fundamentally different hardware than other displays like TFTs. The main difference is that they are slow to display and are limited in how often they can be refreshed. Therefore EPDs do not auto refresh.
To refresh the display, you simply call refresh(). However, to take care of the slowness and refresh limit, these additional properties are important:
-
time_to_refresh- This is the time, in seconds, until you can refresh the display. If you callrefresh()too soon, you will throw an exception. -
busy- This isTruewhile the display is in the process of refreshing. Use this if you want to make sure the display refresh is complete before doing something else.
Here is a simple example of how these properties might get used:
# wait until we can actually refresh
time.sleep(epd.time_to_refresh)
# refresh the display
epd.refresh()
# (optional) wait until display is fully updated
while epd.busy:
pass
# display is now updated
The exact usage would depend on your specific application. For example, you are free to move on to other things without querying busy. However, if you did something like immediately enter deep sleep after calling refresh(), you would want make sure the display is fully updated before doing so.
Also realize that you most likely can not call refresh() again immediately after busy is complete. You still need to use time_to_refresh appropriately. For example, the display may update in 5 seconds (busy becomes False) but can only be refreshed once every 60 seconds (time_to_refresh is > 0).
