epaperdisplay

displaysys.epaperdisplay

displaysys.epaperdisplay — E-paper / E-ink displays.

Wraps CircuitPython EPaperDisplay chip drivers with a pydisplay RAM buffer. On show(), buffer contents are pushed through displayio (CP) or bus.send (MP path) before calling refresh().

Classes

EPaperDisplay

EPaperDisplay(epaper, width=None, height=None, buffer=None, color_depth=None, *, quiet=False)

DisplayDriver wrapper around a CircuitPython EPaperDisplay chip driver.

Packed buffer depths: - color_depth=1 — monochrome (1 bit per pixel) - color_depth=2 — tri-color or 4-gray (2 bits per pixel: 0=white, 1=black, 2=accent) - color_depth=4 — ACeP / advanced color (4 bits per pixel, 2 per byte)

Parameters:

Name	Type	Description	Default
epaper		CircuitPython EPaperDisplay (or compatible) chip driver.	required
width		Panel width; defaults to epaper.width.	None
height		Panel height; defaults to epaper.height.	None
buffer		Optional preallocated RAM buffer; allocated when depth ≤ 8.	None
color_depth		Bits per pixel; defaults to epaper.color_depth or 1.	None
quiet		Suppress init chatter when True.	False

Attributes

width property

width

The width of the display in pixels.

height property

height

The height of the display in pixels.

rotation property writable

rotation

The rotation of the display.

touch_device property writable

touch_device

The touch device.

requires_byteswap property

requires_byteswap

Whether the display requires byte swapping.

vscroll property writable

vscroll

The vertical scroll position relative to the top fixed area.

Returns:

Type	Description
int	The vertical scroll position.

tfa property

tfa

The top fixed area set by set_vscroll or vscrdef.

Returns:

Type	Description
int	The top fixed area.

vsa property

vsa

The vertical scroll area set by set_vscroll or vscrdef.

Returns:

Type	Description
int	The vertical scroll area.

bfa property

bfa

The bottom fixed area set by set_vscroll or vscrdef.

Returns:

Type	Description
int	The bottom fixed area.

tfa_area property

tfa_area

Top fixed area for vertical scrolling.

Returns:

Type	Description
	tuple[int, int, int, int]: (x, y, width, height) of the top fixed band.

vsa_area property

vsa_area

The vertical scroll area as an Area object.

Returns:

Type	Description
tuple	The vertical scroll area.

bfa_area property

bfa_area

The bottom fixed area as an Area object.

Returns:

Type	Description
tuple	The bottom fixed area.

power property writable

power

The power state of the display.

brightness property writable

brightness

The brightness of the display.

Methods:

init

init()

No-op init hook (epaper chip drivers are already initialized).

fill_rect

fill_rect(x, y, w, h, c)

Fill a rectangle in the RAM buffer.

Parameters:

Name	Type	Description	Default
x		Left edge.	required
y		Top edge.	required
w		Width in pixels.	required
h		Height in pixels.	required
c		Packed color value for the configured color_depth.	required

Returns:

Name	Type	Description
tuple		(x, y, w, h) of the filled area.

Raises:

Type	Description
NotImplementedError	When no RAM buffer is allocated.

blit_rect

blit_rect(buf, x, y, w, h)

Blit packed pixel bytes into the RAM buffer.

Parameters:

Name	Type	Description	Default
buf		Source buffer matching color_depth packing.	required
x		Destination left edge.	required
y		Destination top edge.	required
w		Width in pixels.	required
h		Height in pixels.	required

Returns:

Name	Type	Description
tuple		(x, y, w, h) of the blitted area.

Raises:

Type	Description
NotImplementedError	When no RAM buffer is allocated.

pixel

pixel(x, y, c)

Set a single pixel in the RAM buffer.

Parameters:

Name	Type	Description	Default
x		X coordinate.	required
y		Y coordinate.	required
c		Packed color value.	required

Returns:

Name	Type	Description
tuple		(x, y, 1, 1).

show

show(_timer=None)

Push the RAM buffer to the panel and call epaper.refresh().

Prefers a displayio root-group path; falls back to bus.send when displayio is unavailable.

framebuffers

framebuffers()

Return panel buffers for direct GUI paint, or None.

When sharing is supported, returns (buf1, buf2_or_None, nbytes, stride_bytes).

fill

fill(color)

Fill the display with a color.

Parameters:

Name	Type	Description	Default
color	int	The color to fill the display with.	required

scroll

scroll(dx, dy)

Scroll the display.

Parameters:

Name	Type	Description	Default
dx	int	The number of pixels to scroll horizontally.	required
dy	int	The number of pixels to scroll vertically.	required

disable_auto_byteswap

disable_auto_byteswap(value)

Disable byte swapping in the display driver.

If self.requires_byteswap and the guest application is capable of byte swapping color data check to see if byte swapping can be disabled. If so, disable it.

Usage

# If byte swapping is required and the display driver is capable of having byte swapping disabled,
# disable it and set a flag so we can swap the color bytes as they are created.
if display_drv.requires_byteswap:
    needs_swap = display_drv.disable_auto_byteswap(True)
else:
    needs_swap = False

Parameters:

Name	Type	Description	Default
value	bool	Whether to disable byte swapping.	required

Returns:

Type	Description
bool	Whether byte swapping was disabled successfully.

blit_transparent

blit_transparent(buf, x, y, w, h, key)

Blit a buffer with transparency.

Parameters:

Name	Type	Description	Default
buf	memoryview	The buffer to blit.	required
x	int	The x coordinate to blit to.	required
y	int	The y coordinate to blit to.	required
w	int	The width to blit.	required
h	int	The height to blit.	required
key	int	The color key to use for transparency.	required

Returns:

Type	Description
tuple	The x, y, w, h coordinates of the blitted area.

set_vscroll

set_vscroll(tfa=0, bfa=0)

Set the vertical scroll definition and move the vertical scroll to the top.

Parameters:

Name	Type	Description	Default
tfa	int	The top fixed area.	0
bfa	int	The bottom fixed area.	0

translate_point

translate_point(point)

Translate a point from real coordinates to scrolled coordinates.

Useful for touch events.

Parameters:

Name	Type	Description	Default
point	tuple	The x and y coordinates to translate.	required

Returns:

Type	Description
tuple	The translated x and y coordinates.

scroll_by

scroll_by(value)

Scroll vertically by value pixels relative to the current offset.

Parameters:

Name	Type	Description	Default
value		Signed pixel delta applied to :attr:vscroll.	required

scroll_to

scroll_to(value)

Set the absolute vertical scroll offset.

Parameters:

Name	Type	Description	Default
value		New :attr:vscroll position.	required

vscrdef

vscrdef(tfa, vsa, bfa)

Set the vertical scroll definition. Should be overridden by the subclass and called as super().vscrdef(tfa, vsa, bfa).

Parameters:

Name	Type	Description	Default
tfa	int	The top fixed area.	required
vsa	int	The vertical scroll area.	required
bfa	int	The bottom fixed area.	required

vscsad

vscsad(vssa=None)

Set or get the vertical scroll start address. Should be overridden by the subclass and called as super().vscsad(y).

Parameters:

Name	Type	Description	Default
vssa	int	The vertical scroll start address.	None

Returns:

Type	Description
int	The vertical scroll start address.

invert_colors

invert_colors(value)

Invert the colors of the display. Should be overridden by the subclass.

Parameters:

Name	Type	Description	Default
value	bool	True to invert the colors, False to restore the colors.	required

reset

reset()

Perform a reset of the display. Should be overridden by the subclass.

hard_reset

hard_reset()

Perform a hardware reset of the display. Should be overridden by the subclass.

soft_reset

soft_reset()

Perform a software reset of the display. Should be overridden by the subclass.

sleep_mode

sleep_mode(value)

Set the sleep mode of the display. Should be overridden by the subclass.

Parameters:

Name	Type	Description	Default
value	bool	True to enter sleep mode, False to exit sleep mode.	required

deinit

deinit()

Run subclass cleanup. Idempotent.

The broker owns the shared refresh timer, so there is no display-owned timer to stop here; board_config stops the timer on quit via runtime.stop_timer.

quit

quit(code=0, force=False)

Release display resources (REPL-safe unless force=True). Called on QUIT.

force_quit

force_quit(code=0)

Release resources then exit the process (alias for quit(code, force=True)).

Functions: