Source code for displaydev.busdisplay

# SPDX-FileCopyrightText: 2024 Brad Barnett and Kevin Schlosser
#
# SPDX-License-Identifier: MIT

"""
displaydev.busdisplay
"""

import gc
import struct
import sys

try:
    from micropython import const
except ImportError:

    def const(value):
        return value

from displaydev import DisplayDriver

if sys.implementation.name == "micropython":
    from time import sleep_ms

    from machine import Pin
    from micropython import alloc_emergency_exception_buf

    alloc_emergency_exception_buf(256)
elif sys.implementation.name == "circuitpython":
    from time import sleep

    import digitalio

    def sleep_ms(ms):
        return sleep(ms / 1000)
else:
    # Any other host, CPython on the desktop above all. There is no GPIO here,
    # but BusDisplay is portable logic driving a caller-supplied bus object, and
    # keeping it importable is what makes that logic testable off-device. Not
    # having that is why a silently skipped init sequence shipped: the panel
    # bring-up path had no unit test anywhere. Pin configuration stays
    # unavailable and says so (see _config_output_pin).
    from time import sleep

    def sleep_ms(ms):
        return sleep(ms / 1000)


# MIPI DCS (Display Command Set) Command Constants
_INVOFF = const(0x20)
_INVON = const(0x21)
_CASET = const(0x2A)
_RASET = const(0x2B)
_RAMWR = const(0x2C)
_COLMOD = const(0x3A)
_MADCTL = const(0x36)
_SWRESET = const(0x01)
_SLPIN = const(0x10)
_SLPOUT = const(0x11)
_VSCRDEF = const(0x33)
_VSCSAD = const(0x37)

# fmt: off

# MIPI DCS MADCTL bits
# Bits 0 (Flip Vertical) and 1 (Flip Horizontal) affect how the display is refreshed, not how frame memory is written.
# Instead of using them, we only change Bits 6 (column/horizontal) and 7 (page/vertical).
_RGB = const(0x00)  # (Bit 3: 0=RGB order, 1=BGR order)
_BGR = const(0x08)  # (Bit 3: 0=RGB order, 1=BGR order)
_MADCTL_MV = const(0x20)  # 0=Normal, 1=Row/column exchange (Bit 5: Page/Column Addressing Order)
_MADCTL_MX = const(0x40)  # 0=Left to Right, 1=Right to Left (Bit 6: Column Address Order)
_MADCTL_MY = const(0x80)  # 0=Top to Bottom, 1=Bottom to Top (Bit 7: Page Address Order)

# MADCTL values for each of the rotation constants.
_DEFAULT_ROTATION_TABLE = (
    _MADCTL_MX,  # mirrored = False, rotation = 0
    _MADCTL_MV,  # mirrored = False, rotation = 90
    _MADCTL_MY,  # mirrored = False, rotation = 180
    _MADCTL_MY | _MADCTL_MX | _MADCTL_MV,  # mirrored = False, rotation = 270
)

_MIRRORED_ROTATION_TABLE = (
    0,  # mirrored = True, rotation = 0
    _MADCTL_MV | _MADCTL_MX,  # mirrored = True, rotation = 90
    _MADCTL_MX | _MADCTL_MY,  # mirrored = True, rotation = 180
    _MADCTL_MV | _MADCTL_MY,  # mirrored = True, rotation = 270
)
# fmt: on


[docs] class BusDisplay(DisplayDriver): """ Base class for displays connected via a bus. Args: display_bus (SPIBus, I80Bus): The bus the display is connected to. init_sequence (bytes, list): The initialization sequence for the display. width (int): The width of the display in pixels. height (int): The height of the display in pixels. colstart (int): The column start address for the display. rowstart (int): The row start address for the display. rotation (int): The rotation of the display in degrees. mirrored (bool): If True, the display is mirrored. color_depth (int): The color depth of the display in bits. bgr (bool): If True, the display uses BGR color order. invert (bool): If True, the display colors are inverted. reverse_bytes_in_word (bool): If True, the bytes in 16-bit colors are reversed. brightness (float): The brightness of the display as a float between 0.0 and 1.0. backlight_pin (int, Pin): The pin the display backlight is connected to. backlight_on_high (bool): If True, the backlight is on when the pin is high. reset_pin (int, Pin): The pin the display reset is connected to. reset_high (bool): If True, the reset pin is high. power_pin (int, Pin): The pin the display power is connected to. power_on_high (bool): If True, the power pin is high. set_column_command (int): The command to set the column address. set_row_command (int): The command to set the row address. write_ram_command (int): The command to write to the display RAM. brightness_command (int): The command to set the display brightness. data_as_commands (bool): If True, data is sent as commands. single_byte_bounds (bool): If True, single byte bounds are used. Attributes: display_bus (SPIBus, I80Bus): The bus the display is connected to. color_depth (int): The color depth of the display in bits. bgr (bool): If True, the display uses BGR color order. rotation_table (tuple): The rotation table for the display. """ def __init__( # noqa: PLR0913 self, display_bus, init_sequence=None, *, width=0, height=0, colstart=0, rowstart=0, rotation=0, mirrored=False, color_depth=16, bgr=False, invert=False, reverse_bytes_in_word=False, brightness=1.0, backlight_pin=None, backlight_on_high=True, reset_pin=None, reset_high=True, power_pin=None, power_on_high=True, set_column_command=_CASET, set_row_command=_RASET, write_ram_command=_RAMWR, brightness_command=None, # For color OLEDs data_as_commands=False, # For color OLEDs single_byte_bounds=False, # For color OLEDs quiet=False, ): gc.collect() self.display_bus = display_bus self._width = width self._height = height self._colstart = colstart self._rowstart = rowstart self._rotation = rotation self.color_depth = color_depth self.bgr = bgr self._invert = invert self._requires_byteswap = reverse_bytes_in_word self._set_column_command = set_column_command self._set_row_command = set_row_command self._write_ram_command = write_ram_command self._brightness_command = brightness_command self._data_as_commands = data_as_commands # not implemented self._single_byte_bounds = single_byte_bounds # not implemented # CircuitPython's fourwire.FourWire.send requires ``data`` positionally; # the MicroPython bus defaults it. Parameterless commands (INVON, SWRESET, # SLPIN/SLPOUT) therefore pass an explicit b"" rather than omitting it. self.send = display_bus.send self.send_color = ( display_bus.send if not hasattr(display_bus, "send_color") else display_bus.send_color ) self.rotation_table = _DEFAULT_ROTATION_TABLE if not mirrored else _MIRRORED_ROTATION_TABLE self._param_buf = bytearray(4) self._param_mv = memoryview(self._param_buf) # Reused fill_rect strip (grows to max(width, height) * bpp on demand). self._fill_strip_buf = None self._fill_strip_color = None self._fill_strip_valid = 0 self._reset_pin = self._config_output_pin(reset_pin, value=not reset_high) self._reset_high = reset_high self._power_pin = self._config_output_pin(power_pin, value=power_on_high) self._power_on_high = power_on_high self._backlight_pin = self._config_output_pin(backlight_pin, value=backlight_on_high) self._backlight_on_high = backlight_on_high if self._backlight_pin is not None: try: from machine import PWM self._backlight_pin = PWM(self._backlight_pin, freq=1000, duty_u16=0) self._backlight_is_pwm = True except ImportError: # PWM not implemented on this platform or Pin self._backlight_is_pwm = False # Panels whose init sequence sets COLMOD itself must keep that value: # GC9A01A needs 0x05 where the generic 16-bit code is 0x55, and driving # it through the wrong format and back leaves some panels washed out or # blank. See the guarded COLMOD send below. self._init_set_color_mode = False # Run the display driver init_sequence. # # bytearray and memoryview must be accepted alongside bytes: bytearray is # NOT a subclass of bytes, and drivers write their sequences either way # (gc9a01 uses bytearray). Dispatching on bytes alone silently skipped # the entire panel bring-up -- no error, no output, just a display that # never initialised and looked intermittently blank or washed out. # Hence the explicit else: an unusable init_sequence must be loud. if isinstance(init_sequence, (bytes, bytearray, memoryview)): self._init_bytes(init_sequence) elif isinstance(init_sequence, (list, tuple)): self._init_list(init_sequence) elif init_sequence is not None: raise TypeError( "init_sequence must be bytes/bytearray/memoryview or list/tuple, got " + type(init_sequence).__name__ ) # Run the display driver init() method, which also gets called by rotation.setter # This should run immediately after _init_bytes() or _init_list() but before # sending other commands such as _INVON, _INVOFF, _COLMOD, brightness, etc. self._initialized = False super().__init__(quiet=quiet) if not self._initialized: raise RuntimeError("Display driver init() must call super().init()") # Set COLMOD (color mode) based on color_depth, unless the init # sequence already chose one -- the driver knows its panel better than # this generic table does. if not self._init_set_color_mode: pixel_formats = {3: 0x11, 8: 0x22, 12: 0x33, 16: 0x55, 18: 0x66, 24: 0x77} self._param_buf[0] = pixel_formats[self.color_depth] self.send(_COLMOD, self._param_mv[:1]) self.brightness = brightness gc.collect() ############### Required API Methods ################
[docs] def init(self) -> None: """ Post initialization tasks. This method may be overridden by subclasses to perform any post initialization. If it is overridden, it must call super().init() or set self._initialized = True. """ self._initialized = True # Convert from degrees to one quarter rotations. Wrap at the number of entries in the rotations table. # For example, rotation = 90 -> index = 1. With 4 entries in the rotation table, rotation = 540 -> index = 2 index = (self._rotation // 90) % len(self.rotation_table) # Set the display MADCTL bits for the given rotation. # Parenthesised: without them this parsed as ``(table | _BGR) if bgr else _RGB``, # so every bgr=False panel got MADCTL 0 whatever its rotation. self._param_buf[0] = self.rotation_table[index] | (_BGR if self.bgr else _RGB) self.send(_MADCTL, self._param_mv[:1]) # Set the display inversion mode self.invert_colors(self._invert)
[docs] def blit_rect(self, buf: memoryview, x: int, y: int, w: int, h: int): """ Blit a buffer to the display. This method takes a buffer of pixel data and writes it to a specified rectangular area of the display. The top-left corner of the rectangle is specified by the x and y parameters, and the size of the rectangle is specified by the width and height parameters. Args: buf (memoryview): The buffer containing the pixel data. x (int): The x-coordinate of the top-left corner of the rectangle. y (int): The y-coordinate of the top-left corner of the rectangle. w (int): The width of the rectangle in pixels. h (int): The height of the rectangle in pixels. Returns: (tuple): A tuple containing the x, y, width, and height of the rectangle. """ if self._auto_byteswap: self.byteswap(buf) x1 = x + self.colstart x2 = x1 + w - 1 y1 = y + self.rowstart y2 = y1 + h - 1 self._set_window(x1, y1, x2, y2) self.send_color(self._write_ram_command, buf) return (x, y, w, h)
def _fill_strip(self, length_px, color_bytes): """Return a memoryview of ``length_px`` RGB565 pixels filled with ``color_bytes``. Reuses ``_fill_strip_buf`` across calls so fill_rect does not allocate a new strip buffer every time. """ bpp = len(color_bytes) need = length_px * bpp buf = self._fill_strip_buf if buf is None or len(buf) < need: grow = max(need, max(self._width, self._height) * bpp) buf = bytearray(grow) self._fill_strip_buf = buf self._fill_strip_color = None self._fill_strip_valid = 0 if self._fill_strip_color != color_bytes: memoryview(buf)[:need] = color_bytes * length_px self._fill_strip_color = color_bytes self._fill_strip_valid = need elif self._fill_strip_valid < need: valid = self._fill_strip_valid mv = memoryview(buf) while valid < need: copy = valid if valid < (need - valid) else (need - valid) mv[valid : valid + copy] = mv[:copy] valid += copy self._fill_strip_valid = need return memoryview(buf)[:need]
[docs] def fill_rect(self, x: int, y: int, w: int, h: int, c: int): """ Draw a rectangle at the given location, size and filled with color. This method draws a filled rectangle on the display. The top-left corner of the rectangle is specified by the x and y parameters, and the size of the rectangle is specified by the width and height parameters. The rectangle is filled with the specified color. Args: x (int): The x-coordinate of the top-left corner of the rectangle. y (int): The y-coordinate of the top-left corner of the rectangle. w (int): The width of the rectangle in pixels. h (int): The height of the rectangle in pixels. c (int): The color of the rectangle. Returns: (tuple): A tuple containing the x, y, width, and height of the rectangle. """ color_bytes = ( (c & 0xFFFF).to_bytes(2, "big") if self._auto_byteswap else (c & 0xFFFF).to_bytes(2, "little") ) x1 = x + self.colstart x2 = x1 + w - 1 y1 = y + self.rowstart y2 = y1 + h - 1 # One Memory Write (0x2C) per strip. Do not use Memory Write Continue (0x3C): # SPI buses release CS between sends, and many ST7789 panels ignore 0x3C, which # scatters later chunks (dots / misplaced bars). Each strip gets its own window. if h > w: buf = self._fill_strip(h, color_bytes) for i in range(w): self._set_window(x1 + i, y1, x1 + i, y2) self.send_color(_RAMWR, buf) else: buf = self._fill_strip(w, color_bytes) for i in range(h): self._set_window(x1, y1 + i, x2, y1 + i) self.send_color(_RAMWR, buf) return (x, y, w, h)
[docs] def pixel(self, x: int, y: int, c: int): """ Set a pixel on the display. Args: x (int): The x-coordinate of the pixel. y (int): The y-coordinate of the pixel. c (int): The color of the pixel. Returns: (tuple): A tuple containing the x, y, width, and height of the pixel. """ xpos = x + self.colstart ypos = y + self.rowstart self._set_window(xpos, ypos, xpos, ypos) c16 = c & 0xFFFF if self._auto_byteswap: self._param_buf[0] = (c16 >> 8) & 0xFF self._param_buf[1] = c16 & 0xFF else: self._param_buf[0] = c16 & 0xFF self._param_buf[1] = (c16 >> 8) & 0xFF self.send(_RAMWR, self._param_mv[:2]) return (x, y, 1, 1)
############### API Method Overrides ################
[docs] def vscrdef(self, tfa: int, vsa: int, bfa: int) -> None: """ Set Vertical Scrolling Definition. To scroll a 135x240 display these values should be 40, 240, 40. There are 40 lines above the display that are not shown followed by 240 lines that are shown followed by 40 more lines that are not shown. You could write to these areas off display and scroll them into view by changing the TFA, VSA and BFA values. Args: tfa (int): Top Fixed Area. vsa (int): Vertical Scrolling Area. bfa (int): Bottom Fixed Area. """ super().vscrdef(tfa, vsa, bfa) self.send(_VSCRDEF, struct.pack(">HHH", tfa, vsa, bfa))
[docs] def vscsad(self, vssa=None) -> int: """ Set the vertical scroll start address. Args: vssa (int, None): The vertical scroll start address. Returns: int: The vertical scroll start address. """ if vssa is not None: super().vscsad(vssa) self.send(_VSCSAD, struct.pack(">H", self._vssa)) return self._vssa
############### Optional API Methods ################ @property def colstart(self): """ The offset in pixels to the first column of the visible display. """ rot = self.rotation % 360 if rot == 0 or rot == 180: return self._colstart return self._rowstart @property def rowstart(self): """ The offset in pixels to the first row of the visible display. """ rot = self.rotation % 360 if rot == 0 or rot == 180: return self._rowstart return self._colstart @property def power(self) -> bool: """ The power state of the display. Returns: bool: The power state of the display. """ if self._power_pin is None: return -1 state = self._power_pin.value() if self._power_on_high: return state return not state @power.setter def power(self, value: bool) -> None: """ Set the power state of the display. Args: value (bool): The power state to set, True for on, False for off. """ if self._power_pin is None: return if self._power_on_high: self._power_pin.value(value) else: self._power_pin.value(not value) @property def brightness(self) -> float: """ The brightness of the display. """ if self._backlight_pin is None and self._brightness_command is None: return -1 return self._brightness @brightness.setter def brightness(self, value: float) -> None: """ Set the brightness of the display. Args: value (float): The brightness of the display as a float between 0.0 and 1.0. """ if 0 <= float(value) <= 1: self._brightness = value if self._backlight_pin: if not self._backlight_on_high: value = 1 - value if self._backlight_is_pwm: if sys.implementation.name == "micropython": self._backlight_pin.duty_u16(int(value * 0xFFFF)) elif sys.implementation.name == "circuitpython": self._backlight_pin.duty_cycle = int(value * 0xFFFF) else: if sys.implementation.name == "micropython": self._backlight_pin.value(value > 0.5) # noqa: PLR2004 elif sys.implementation.name == "circuitpython": self._backlight_pin.value = value > 0.5 # noqa: PLR2004 elif self._brightness_command is not None: self._param_buf[0] = int(value * 255) self.send(self._brightness_command, self._param_mv[:1])
[docs] def invert_colors(self, value: bool) -> None: """ Invert the colors of the display. Args: value (bool): If True, invert the colors of the display. """ if value: self.send(_INVON, b"") else: self.send(_INVOFF, b"")
[docs] def reset(self) -> None: """ Reset display. This method resets the display. If the display has a reset pin, it is reset using the reset pin. Otherwise, the display is reset using the software reset command. """ if self._reset_pin is not None: self.hard_reset() else: self.soft_reset()
[docs] def hard_reset(self) -> None: """ Hard reset display. """ self._reset_pin.value(self._reset_high) sleep_ms(120) self._reset_pin.value(not self._reset_high)
[docs] def soft_reset(self) -> None: """ Soft reset display. """ self.send(_SWRESET, b"") sleep_ms(150)
[docs] def sleep_mode(self, value: bool) -> None: """ Enable or disable display sleep mode. Args: value (bool): If True, enable sleep mode. If False, disable sleep mode. """ self.send(_SLPIN if value else _SLPOUT, b"")
def _deinit(self) -> None: """Best-effort hardware teardown.""" try: self.brightness = 0 except Exception: pass try: self.power = False except Exception: pass bus = getattr(self, "display_bus", None) if bus is not None and hasattr(bus, "deinit"): bus.deinit() self.display_bus = None for attr in ("_backlight_pin", "_reset_pin", "_power_pin"): pin = getattr(self, attr, None) if pin is not None and hasattr(pin, "deinit"): try: pin.deinit() except Exception: pass setattr(self, attr, None) ############### Class Specific Methods ############## def _set_window(self, x1, y1, x2, y2): # See https://github.com/adafruit/Adafruit_Blinka_Displayio/blob/main/<<<KEEP_ADAFRUIT_DISPLAYDEV>>>#L271-L363 # TODO: Add `if self._single_byte_bounds is True:` for Column and Row _param_buf packing # Column addresses self._param_buf[0] = (x1 >> 8) & 0xFF self._param_buf[1] = x1 & 0xFF self._param_buf[2] = (x2 >> 8) & 0xFF self._param_buf[3] = x2 & 0xFF self.send(self._set_column_command, self._param_mv[:4]) # Row addresses self._param_buf[0] = (y1 >> 8) & 0xFF self._param_buf[1] = y1 & 0xFF self._param_buf[2] = (y2 >> 8) & 0xFF self._param_buf[3] = y2 & 0xFF self.send(self._set_row_command, self._param_mv[:4]) def _init_bytes(self, init_sequence): """ Send an initialization sequence to the display. Used by display driver subclass if init_sequence is a CircuitPython displayIO compatible bytes object. The ``init_sequence`` is bitpacked to minimize the ram impact. Every command begins with a command byte followed by a byte to determine the parameter count and if a delay is need after. When the top bit of the second byte is 1, the next byte will be the delay time in milliseconds. The remaining 7 bits are the parameter count excluding any delay byte. The third through final bytes are the remaining command parameters. The next byte will begin a new command definition. Args: init_sequence (bytes): The initialization sequence to send to the display. """ DELAY = 0x80 i = 0 while i < len(init_sequence): command = init_sequence[i] data_size = init_sequence[i + 1] delay = (data_size & DELAY) != 0 data_size &= ~DELAY if command == _COLMOD: self._init_set_color_mode = True self.send(command, init_sequence[i + 2 : i + 2 + data_size]) delay_time_ms = 10 if delay: data_size += 1 delay_time_ms = init_sequence[i + 1 + data_size] if delay_time_ms == 255: delay_time_ms = 500 sleep_ms(delay_time_ms) i += 2 + data_size def _init_list(self, init_sequence): """ Send an initialization sequence to the display. Used by display driver subclass if init_sequence is a list of tuples. As a list, it can be modified in .init(), for example: self._INIT_SEQUENCE[-1] = (0x29, b"\x00", 100) Each tuple contains the following: - The first element is the register address (command) - The second element is the register value (data) - The third element is the delay in milliseconds after the register is set Args: init_sequence (list): The initialization sequence to send to the display """ for line in init_sequence: if line[0] == _COLMOD: self._init_set_color_mode = True self.send(line[0], line[1]) if line[2] != 0: sleep_ms(line[2]) def _config_output_pin(self, pin, value=None): if pin is None: return None if sys.implementation.name == "micropython": p = Pin(pin, Pin.OUT) if value is not None: p.value(value) elif sys.implementation.name == "circuitpython": p = digitalio.DigitalInOut(pin) p.direction = digitalio.Direction.OUTPUT if value is not None: p.value = value else: raise NotImplementedError( "BusDisplay cannot configure GPIO on " + sys.implementation.name ) return p