adafruit / adafruit_circuitpython_il0373

CircuitPython `displayio` driver for IL0373-based ePaper displays

Introduction

CircuitPython displayio driver for IL0373-based ePaper displays

Dependencies

This driver depends on:

• Adafruit CircuitPython

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.

Installing from PyPI

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:

pip3 install adafruit-circuitpython-il0373

To install system-wide (this may be required in some cases):

sudo pip3 install adafruit-circuitpython-il0373

To install in a virtual environment in your current project:

mkdir project-name && cd project-name
python3 -m venv .venv
source .venv/bin/activate
pip3 install adafruit-circuitpython-il0373

Usage Example

Documentation

API documentation for this library can be found on Read the Docs.

For information on building library documentation, please check out this guide.

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

adafruit_circuitpython_il0373's Issues

Code comment seems to conflict with code

This doc and this code seem to conflict. This is of concern because it affects the Vcom voltage. I think the intention is to specify -1.0V where you may be setting -2.6V.

b"\x82\x81\x12\x32"  # VCM DC and delay 50ms

The doc implies that the delay is the third byte (0x12 == 18ms) with a single data value in the fourth byte (0x32, which happens to equal 50). I think the code should read:

b"\x82\x81\x32\x12"  # VCM DC and delay 50ms

The doc itself is ambiguous because it states

When the top bit of the second byte is 1, the next byte will be the delay time in milliseconds.

This implies that the third byte is the delay time, but it then goes on to say

The third through final bytes are the remaining command parameters.

I think that should read the fourth through final bytes, but clarification would be appreciated.

Black border around the edge of the display

When using this library with the 2.9" B/W displays from GoodDisplay (GDEW029T5), the black border is very noticeable. This is outside the controllable pixels, but if you have graphics right up to the edge, this border will touch the black pixels.

The border is also there on the smaller 2.13" tri-color displays (eg. on the Adafruit 2.13" E-Ink FeatherWing), but it is not as noticeable, since most is covered by the edge of the screen.

It seems that the color of this border is controlled by the VBD bits in the CDI command of the startup sequence, but the datasheet for IL0373 seems to skip the description for those two bits.

There are a bit more info in the datasheet for GDEW029T5 (2.9" B/W) and GDEW029T5 (2.13" tri color) and it seems like the color of the border depends on other settings in addition to the two VBD bits.

My experimentation has resulted in:
VBD[1:0] = 0, 0 // black border on both, last byte in CDI 0x37
VBD[1:0] = 0, 1 // white border on tri color, black border on b/w, last byte in CDI 0x77
VBD[1:0] = 1, 0 // red border on try color, white border on b/w, last byte in CDI 0xB7
VBD[1:0] = 1, 1 // white border on both, last byte in CDI 0xF7

I think the last one (1, 1) is what they call floating, with the other settings that are used (DDX[0]=1).

I think "white" of "floating" will blend in best with the displays, if it was to be fixed, but an option to select this in CircuitPython when using this driver would be nice, since that would allow use cases where the edge isn't covered by a case to have the border follow the general background color used.

I can work on that and make a pull request if there is interest.

Make examples compatible with both 8.x.x and 9.0.0

The example code with import fourwire shows up on this guide:
https://learn.adafruit.com/adafruit-2-9-eink-display-breakouts-and-featherwings/circuitpython-usage

So the guide is using only 9.0.0-compatible code. The example(s) should be reworked to be compatible with both, at least for now.

There are probably other libraries where this happened.

Grayscale driver not working.

When using the grayscale 2.9" e-ink display and the driver along with the grayscale example, images only come out in black and white, no grey at all.

Tried using a variety of images, including these:
https://cdn-learn.adafruit.com/assets/assets/000/096/274/original/adafruit_products_29gray4.bmp?1603484677
https://learn.adafruit.com/assets/96273
https://learn.adafruit.com/assets/96272

Have also tried blitting grey fonts/backgrounds using adafruit_display_text library and it still comes out in black and white.

Anyone know why or how to fix?

Missing Type Annotations

There are missing type annotations for some functions in this library.

The typing module does not exist on CircuitPython devices so the import needs to be wrapped in try/except to catch the error for missing import. There is an example of how that is done here:

try:
    from typing import List, Tuple
except ImportError:
    pass

Once imported the typing annotations for the argument type(s), and return type(s) can be added to the function signature. Here is an example of a function that has had this done already:

def wrap_text_to_pixels(
    string: str, max_width: int, font=None, indent0: str = "", indent1: str = ""
) -> List[str]:

If you are new to Git or Github we have a guide about contributing to our projects here: https://learn.adafruit.com/contribute-to-circuitpython-with-git-and-github

There is also a guide that covers our CI utilities and how to run them locally to ensure they will pass in Github Actions here: https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/check-your-code In particular the pages: Sharing docs on ReadTheDocs and Check your code with pre-commit contain the tools to install and commands to run locally to run the checks.

If you are attempting to resolve this issue and need help, you can post a comment on this issue and tag both @FoamyGuy and @kattni or reach out to us on Discord: https://adafru.it/discord in the #circuitpython-dev channel.

The following locations are reported by mypy to be missing type annotations:

• adafruit_il0373.py:131

This code does not match device datasheet

These lines show a 2-bit number shifted left 5 to set RES1 and RES0 resolution selection bits. The datasheet shows these as being D7 and D6, consequently the left shift should be 6.

FeatherWing EPD Shows all black screen

CircuitPython Version: Adafruit CircuitPython 8.1.0-beta.0-29-g76d590bc0 on 2023-03-15; Adafruit Feather ESP32S3 4MB Flash 2MB PSRAM with ESP32S3

import time
import board
import displayio
import adafruit_il0373

# Used to ensure the display is free in CircuitPython
displayio.release_displays()

# Define the pins needed for display use
# This pinout is for a Feather M4 and may be different for other boards
spi = board.SPI()  # Uses SCK and MOSI
epd_cs = board.D9
epd_dc = board.D10
epd_reset = None
epd_busy = None

# Create the displayio connection to the display pins
display_bus = displayio.FourWire(
    spi, command=epd_dc, chip_select=epd_cs, reset=epd_reset, baudrate=1000000
)
time.sleep(1)  # Wait a bit

# Create the display object - the third color is red (0xff0000)
display = adafruit_il0373.IL0373(
    display_bus,
    width=296,
    height=128,
    rotation=270,
    busy_pin=epd_busy,
    highlight_color=0xFF0000,
)

# Create a display group for our screen objects
g = displayio.Group()

# Display a ruler graphic from the root directory of the CIRCUITPY drive
with open("/display-ruler.bmp", "rb") as f:
    pic = displayio.OnDiskBitmap(f)
    # Create a Tilegrid with the bitmap and put in the displayio group
    # CircuitPython 6 & 7 compatible
    t = displayio.TileGrid(
        pic, pixel_shader=getattr(pic, "pixel_shader", displayio.ColorConverter())
    )
    # CircuitPython 7 compatible only
    # t = displayio.TileGrid(pic, pixel_shader=pic.pixel_shader)
    g.append(t)

    # Place the display group on the screen
    display.show(g)

    # Refresh the display to have it actually show the image
    # NOTE: Do not refresh eInk displays sooner than 180 seconds
    display.refresh()
    print("refreshed")

    time.sleep(180)

Convert `.show()` to `.root_group =` for CircuitPython 9

in examples/ and README.rst

`__init__()` arguments are not Pin objects

We recently changed argument names for initializing the ESP32SPI library to use the suffix _dio rather than _pin because the arguments need to be instantiated DigitalInOut objects, not microcontroller.Pin objects.

See: adafruit/Adafruit_CircuitPython_ESP32SPI#121

This library uses the same *_pin names for it's arguments which are also expected to the DigitalInOuts rather than Pins.

I think we'll want to change the names here and any other libraries that have _pin to keep things consistent across libraries.

EPD Breakout board schematic does not match hardware

This is probably the wrong place for this issue but I couldn't figure out where to raise it. Apologies.
[EDITED]
This webpage for the "eInk breakout friend" has a link to this schematic. The two do not match: the schematic is of a display rather than of the breakout which is confusing. There seems to be no link to the breakout schematic itself.