class SPIDisplay – SPI Display Driver

The SPIDisplay class drives small SPI-attached TFT and OLED panels – most commonly the SSD1351 128x160 RGB OLED on the OpenMV LCD Shield. The driver owns the SPI bus and a GPIO chip-select / DC line internally, so callers only configure the panel geometry, refresh rate and any orientation flags. Panel-specific initialisation (register sequences, RAM-write framing) is supplied through the controller keyword argument – pass an SSD1351 instance to drive the LCD Shield, or implement your own controller class for other panels.

Frames are presented by calling write() with an image.Image. The driver converts the source to RGB565 and applies scaling, ROI, palette and orientation transforms internally, so the caller does not need to pre-size the image. Backlight brightness can be left as a simple on/off GPIO (default) or driven by DACBacklight / PWMBacklight by passing one as the backlight keyword argument.

Example – mirror the camera onto the OpenMV LCD Shield’s SSD1351 OLED:

import csi
import display

csi0 = csi.CSI()
csi0.reset()
csi0.pixformat(csi.RGB565)
csi0.framesize((128, 160))        # matches the SSD1351 panel

lcd = display.SPIDisplay(controller=display.SSD1351())

while True:
    lcd.write(csi0.snapshot())

Constructors

class display.SPIDisplay(width: int = 128, height: int = 160, refresh: int = 60, bgr: bool = False, byte_swap: bool = False, hmirror: bool = True, vflip: bool = True, triple_buffer: bool | None = None, *, controller: object | None = None, backlight: object | None = None)

width SPI LCD width in pixels (1..32767).

height SPI LCD height in pixels (1..32767).

refresh LCD refresh rate in hertz (1..120). Controls the SPI clock rate.

bgr set to True to swap the red and blue channels.

byte_swap set to True to swap RGB565 pixel bytes sent to the LCD.

hmirror set to True to horizontally mirror the display output.

vflip set to True to vertically flip the display output.

triple_buffer if True makes updates to the screen non-blocking at the cost of 3X the display size in RAM. Default depends on the board (on for boards with SDRAM).

controller keyword-only. Pass a controller chip class instance to initialize it along with the display. When provided, the controller’s init, display_on, display_off, and ram_write methods (if present) are invoked instead of the built-in commands.

backlight keyword-only. Pass a backlight controller module to use. By default the backlight is controlled via a GPIO pin.

width() → int

Returns the width of the screen.

height() → int

Returns the height of the screen.

refresh() → int

Returns the refresh rate.

bgr() → bool

Returns whether the red and blue channels are swapped.

byte_swap() → bool

Returns whether RGB565 pixels are sent byte-reversed.

triple_buffer() → bool

Returns whether triple buffering is enabled.

framesize() → int

Returns the configured framesize identifier.

write(image: image.Image, x: int = 0, y: int = 0, x_scale: float = 1.0, y_scale: float = 1.0, roi: Tuple[int, int, int, int] | None = None, rgb_channel: int = -1, alpha: int = 255, color_palette: int | image.Image | None = None, alpha_palette: image.Image | None = None, hint: int = 0) → None

Displays image with its top-left corner at (x, y). A path string may be passed in place of an image to load and draw it in one step.

x_scale x-axis scale factor. Negative values flip horizontally. If y_scale is omitted it follows x_scale to preserve aspect ratio.

y_scale y-axis scale factor. Negative values flip vertically (requires triple_buffer=True). If x_scale is omitted it follows y_scale.

roi region-of-interest rectangle (x, y, w, h) of the source image to draw.

rgb_channel RGB channel to extract from an RGB565 source image (0=R, 1=G, 2=B, -1=all). Range: -1..2.

alpha opacity of the image. 0 is fully transparent (black), 255 is opaque. Range: 0..255.

color_palette color palette enum (e.g. image.PALETTE_RAINBOW) or a 256-pixel RGB565 image used as a color lookup table on the grayscale value of the source. Applied after rgb_channel extraction.

alpha_palette 256-pixel grayscale image used as a per-pixel alpha lookup table modulating alpha based on source grayscale value.

hint logical OR of the flags:

clear(display_off: bool = False) → None

Clears the LCD screen to black.

display_off if True, turns off the display logic instead of clearing the framebuffer. The backlight should also be disabled afterwards.

backlight(value: int | None = None) → int | None

With value, sets the backlight intensity (0=off..100=full). Without arguments, returns the current backlight value.

Unless a DACBacklight or PWMBacklight controller is passed at construction, the backlight is driven as a GPIO pin and only goes from 0 (off) to non-zero (on).

bus_write(cmd: int, args: int | bytes | None = None, *, dcs: bool = False) → None

Sends cmd to the display over the SPI bus, optionally followed by args (an int byte or a buffer of bytes). dcs selects DCS framing when supported by the controller.

bus_read(cmd: int, len: int, args: int | bytes | None = None, *, dcs: bool = False) → bytearray

Sends cmd over the SPI bus and reads len bytes back, returning them as a bytearray. args is optionally written before the read (an int byte or a buffer of bytes). dcs selects DCS framing when supported by the controller.

ioctl(cmd: int, arg: object | None = None) → object

Issues a controller-specific ioctl cmd with optional arg. Raises ValueError if the underlying display does not support ioctl.