esphome 2025.8.4__py3-none-any.whl → 2025.9.0b2__py3-none-any.whl

esphome/components/mipi/__init__.py

@@ -2,7 +2,7 @@
 # Various configuration constants for MIPI displays
 # Various utility functions for MIPI DBI configuration
 
-from typing import Any
+from typing import Any, Self
 
 from esphome.components.const import CONF_COLOR_DEPTH
 from esphome.components.display import CONF_SHOW_TEST_CARD, display_ns
@@ -222,7 +222,13 @@ def delay(ms):
 
 
 class DriverChip:
-    models = {}
+    """
+    A class representing a MIPI DBI driver chip model.
+    The parameters supplied as defaults will be used to provide default values for the display configuration.
+    Setting swap_xy to cv.UNDEFINED will indicate that the model does not support swapping X and Y axes.
+    """
+
+    models: dict[str, Self] = {}
 
     def __init__(
         self,
@@ -232,7 +238,7 @@ class DriverChip:
     ):
         name = name.upper()
         self.name = name
-        self.initsequence = initsequence or defaults.get("init_sequence")
+        self.initsequence = initsequence
         self.defaults = defaults
         DriverChip.models[name] = self
 
@@ -246,6 +252,17 @@ class DriverChip:
         return models
 
     def extend(self, name, **kwargs) -> "DriverChip":
+        """
+        Extend the current model with additional parameters or a modified init sequence.
+        Parameters supplied here will override the defaults of the current model.
+        if the initsequence is not provided, the current model's initsequence will be used.
+        If add_init_sequence is provided, it will be appended to the current initsequence.
+        :param name:
+        :param kwargs:
+        :return:
+        """
+        initsequence = list(kwargs.pop("initsequence", self.initsequence))
+        initsequence.extend(kwargs.pop("add_init_sequence", ()))
         defaults = self.defaults.copy()
         if (
             CONF_WIDTH in defaults
@@ -260,23 +277,39 @@ class DriverChip:
         ):
             defaults[CONF_NATIVE_HEIGHT] = defaults[CONF_HEIGHT]
         defaults.update(kwargs)
-        return DriverChip(name, initsequence=self.initsequence, **defaults)
+        return self.__class__(name, initsequence=tuple(initsequence), **defaults)
 
     def get_default(self, key, fallback: Any = False) -> Any:
         return self.defaults.get(key, fallback)
 
+    @property
+    def transforms(self) -> set[str]:
+        """
+        Return the available transforms for this model.
+        """
+        if self.get_default("no_transform", False):
+            return set()
+        if self.get_default(CONF_SWAP_XY) != cv.UNDEFINED:
+            return {CONF_MIRROR_X, CONF_MIRROR_Y, CONF_SWAP_XY}
+        return {CONF_MIRROR_X, CONF_MIRROR_Y}
+
     def option(self, name, fallback=False) -> cv.Optional:
         return cv.Optional(name, default=self.get_default(name, fallback))
 
     def rotation_as_transform(self, config) -> bool:
         """
         Check if a rotation can be implemented in hardware using the MADCTL register.
-        A rotation of 180 is always possible, 90 and 270 are possible if the model supports swapping X and Y.
+        A rotation of 180 is always possible if x and y mirroring are supported, 90 and 270 are possible if the model supports swapping X and Y.
         """
+        transforms = self.transforms
         rotation = config.get(CONF_ROTATION, 0)
-        return rotation and (
-            self.get_default(CONF_SWAP_XY) != cv.UNDEFINED or rotation == 180
-        )
+        if rotation == 0 or not transforms:
+            return False
+        if rotation == 180:
+            return CONF_MIRROR_X in transforms and CONF_MIRROR_Y in transforms
+        if rotation == 90:
+            return CONF_SWAP_XY in transforms and CONF_MIRROR_X in transforms
+        return CONF_SWAP_XY in transforms and CONF_MIRROR_Y in transforms
 
     def get_dimensions(self, config) -> tuple[int, int, int, int]:
         if CONF_DIMENSIONS in config:
@@ -301,10 +334,10 @@ class DriverChip:
 
         # if mirroring axes and there are offsets, also mirror the offsets to cater for situations where
         # the offset is asymmetric
-        if transform[CONF_MIRROR_X]:
+        if transform.get(CONF_MIRROR_X):
             native_width = self.get_default(CONF_NATIVE_WIDTH, width + offset_width * 2)
             offset_width = native_width - width - offset_width
-        if transform[CONF_MIRROR_Y]:
+        if transform.get(CONF_MIRROR_Y):
             native_height = self.get_default(
                 CONF_NATIVE_HEIGHT, height + offset_height * 2
             )
@@ -314,7 +347,7 @@ class DriverChip:
             90,
             270,
         )
-        if transform[CONF_SWAP_XY] is True or rotated:
+        if transform.get(CONF_SWAP_XY) is True or rotated:
             width, height = height, width
             offset_height, offset_width = offset_width, offset_height
         return width, height, offset_width, offset_height
@@ -324,27 +357,50 @@ class DriverChip:
         transform = config.get(
             CONF_TRANSFORM,
             {
-                CONF_MIRROR_X: self.get_default(CONF_MIRROR_X, False),
-                CONF_MIRROR_Y: self.get_default(CONF_MIRROR_Y, False),
-                CONF_SWAP_XY: self.get_default(CONF_SWAP_XY, False),
+                CONF_MIRROR_X: self.get_default(CONF_MIRROR_X),
+                CONF_MIRROR_Y: self.get_default(CONF_MIRROR_Y),
+                CONF_SWAP_XY: self.get_default(CONF_SWAP_XY),
             },
         )
+        # fill in defaults if not provided
+        mirror_x = transform.get(CONF_MIRROR_X, self.get_default(CONF_MIRROR_X))
+        mirror_y = transform.get(CONF_MIRROR_Y, self.get_default(CONF_MIRROR_Y))
+        swap_xy = transform.get(CONF_SWAP_XY, self.get_default(CONF_SWAP_XY))
+        transform[CONF_MIRROR_X] = mirror_x
+        transform[CONF_MIRROR_Y] = mirror_y
+        transform[CONF_SWAP_XY] = swap_xy
 
         # Can we use the MADCTL register to set the rotation?
         if can_transform and CONF_TRANSFORM not in config:
             rotation = config[CONF_ROTATION]
             if rotation == 180:
-                transform[CONF_MIRROR_X] = not transform[CONF_MIRROR_X]
-                transform[CONF_MIRROR_Y] = not transform[CONF_MIRROR_Y]
+                transform[CONF_MIRROR_X] = not mirror_x
+                transform[CONF_MIRROR_Y] = not mirror_y
             elif rotation == 90:
-                transform[CONF_SWAP_XY] = not transform[CONF_SWAP_XY]
-                transform[CONF_MIRROR_X] = not transform[CONF_MIRROR_X]
+                transform[CONF_SWAP_XY] = not swap_xy
+                transform[CONF_MIRROR_X] = not mirror_x
             else:
-                transform[CONF_SWAP_XY] = not transform[CONF_SWAP_XY]
-                transform[CONF_MIRROR_Y] = not transform[CONF_MIRROR_Y]
+                transform[CONF_SWAP_XY] = not swap_xy
+                transform[CONF_MIRROR_Y] = not mirror_y
             transform[CONF_TRANSFORM] = True
         return transform
 
+    def add_madctl(self, sequence: list, config: dict):
+        # Add the MADCTL command to the sequence based on the configuration.
+        use_flip = config.get(CONF_USE_AXIS_FLIPS)
+        madctl = 0
+        transform = self.get_transform(config)
+        if transform[CONF_MIRROR_X]:
+            madctl |= MADCTL_XFLIP if use_flip else MADCTL_MX
+        if transform[CONF_MIRROR_Y]:
+            madctl |= MADCTL_YFLIP if use_flip else MADCTL_MY
+        if transform.get(CONF_SWAP_XY) is True:  # Exclude Undefined
+            madctl |= MADCTL_MV
+        if config[CONF_COLOR_ORDER] == MODE_BGR:
+            madctl |= MADCTL_BGR
+        sequence.append((MADCTL, madctl))
+        return madctl
+
     def get_sequence(self, config) -> tuple[tuple[int, ...], int]:
         """
         Create the init sequence for the display.
@@ -367,21 +423,9 @@ class DriverChip:
             pixel_mode = PIXEL_MODES[pixel_mode]
         sequence.append((PIXFMT, pixel_mode))
 
-        # Does the chip use the flipping bits for mirroring rather than the reverse order bits?
-        use_flip = config.get(CONF_USE_AXIS_FLIPS)
-        madctl = 0
-        transform = self.get_transform(config)
         if self.rotation_as_transform(config):
             LOGGER.info("Using hardware transform to implement rotation")
-        if transform.get(CONF_MIRROR_X):
-            madctl |= MADCTL_XFLIP if use_flip else MADCTL_MX
-        if transform.get(CONF_MIRROR_Y):
-            madctl |= MADCTL_YFLIP if use_flip else MADCTL_MY
-        if transform.get(CONF_SWAP_XY) is True:  # Exclude Undefined
-            madctl |= MADCTL_MV
-        if config[CONF_COLOR_ORDER] == MODE_BGR:
-            madctl |= MADCTL_BGR
-        sequence.append((MADCTL, madctl))
+        madctl = self.add_madctl(sequence, config)
         if config[CONF_INVERT_COLORS]:
             sequence.append((INVON,))
         else:

esphome/components/mipi_rgb/__init__.py

@@ -0,0 +1,2 @@
+CODEOWNERS = ["@clydebarrow"]
+DOMAIN = "mipi_rgb"

esphome/components/mipi_rgb/display.py

@@ -0,0 +1,321 @@
+import importlib
+import pkgutil
+
+from esphome import pins
+import esphome.codegen as cg
+from esphome.components import display, spi
+from esphome.components.const import (
+    BYTE_ORDER_BIG,
+    BYTE_ORDER_LITTLE,
+    CONF_BYTE_ORDER,
+    CONF_DRAW_ROUNDING,
+)
+from esphome.components.display import CONF_SHOW_TEST_CARD
+from esphome.components.esp32 import const, only_on_variant
+from esphome.components.mipi import (
+    COLOR_ORDERS,
+    CONF_DE_PIN,
+    CONF_HSYNC_BACK_PORCH,
+    CONF_HSYNC_FRONT_PORCH,
+    CONF_HSYNC_PULSE_WIDTH,
+    CONF_PCLK_PIN,
+    CONF_PIXEL_MODE,
+    CONF_USE_AXIS_FLIPS,
+    CONF_VSYNC_BACK_PORCH,
+    CONF_VSYNC_FRONT_PORCH,
+    CONF_VSYNC_PULSE_WIDTH,
+    MODE_BGR,
+    PIXEL_MODE_16BIT,
+    PIXEL_MODE_18BIT,
+    DriverChip,
+    dimension_schema,
+    map_sequence,
+    power_of_two,
+    requires_buffer,
+)
+from esphome.components.rpi_dpi_rgb.display import (
+    CONF_PCLK_FREQUENCY,
+    CONF_PCLK_INVERTED,
+)
+import esphome.config_validation as cv
+from esphome.const import (
+    CONF_BLUE,
+    CONF_COLOR_ORDER,
+    CONF_CS_PIN,
+    CONF_DATA_PINS,
+    CONF_DATA_RATE,
+    CONF_DC_PIN,
+    CONF_DIMENSIONS,
+    CONF_ENABLE_PIN,
+    CONF_GREEN,
+    CONF_HSYNC_PIN,
+    CONF_ID,
+    CONF_IGNORE_STRAPPING_WARNING,
+    CONF_INIT_SEQUENCE,
+    CONF_INVERT_COLORS,
+    CONF_LAMBDA,
+    CONF_MIRROR_X,
+    CONF_MIRROR_Y,
+    CONF_MODEL,
+    CONF_NUMBER,
+    CONF_RED,
+    CONF_RESET_PIN,
+    CONF_ROTATION,
+    CONF_SPI_ID,
+    CONF_SWAP_XY,
+    CONF_TRANSFORM,
+    CONF_VSYNC_PIN,
+    CONF_WIDTH,
+)
+from esphome.final_validate import full_config
+
+from ..spi import CONF_SPI_MODE, SPI_DATA_RATE_SCHEMA, SPI_MODE_OPTIONS, SPIComponent
+from . import models
+
+DEPENDENCIES = ["esp32", "psram"]
+
+mipi_rgb_ns = cg.esphome_ns.namespace("mipi_rgb")
+mipi_rgb = mipi_rgb_ns.class_("MipiRgb", display.Display, cg.Component)
+mipi_rgb_spi = mipi_rgb_ns.class_(
+    "MipiRgbSpi", mipi_rgb, display.Display, cg.Component, spi.SPIDevice
+)
+ColorOrder = display.display_ns.enum("ColorMode")
+
+DATA_PIN_SCHEMA = pins.internal_gpio_output_pin_schema
+
+DriverChip("CUSTOM")
+
+# Import all models dynamically from the models package
+
+for module_info in pkgutil.iter_modules(models.__path__):
+    importlib.import_module(f".models.{module_info.name}", package=__package__)
+
+MODELS = DriverChip.get_models()
+
+
+def data_pin_validate(value):
+    """
+    It is safe to use strapping pins as RGB output data bits, as they are outputs only,
+    and not initialised until after boot.
+    """
+    if not isinstance(value, dict):
+        try:
+            return DATA_PIN_SCHEMA(
+                {CONF_NUMBER: value, CONF_IGNORE_STRAPPING_WARNING: True}
+            )
+        except cv.Invalid:
+            pass
+    return DATA_PIN_SCHEMA(value)
+
+
+def data_pin_set(length):
+    return cv.All(
+        [data_pin_validate],
+        cv.Length(min=length, max=length, msg=f"Exactly {length} data pins required"),
+    )
+
+
+def model_schema(config):
+    model = MODELS[config[CONF_MODEL].upper()]
+    if transforms := model.transforms:
+        transform = cv.Schema({cv.Required(x): cv.boolean for x in transforms})
+        for x in (CONF_SWAP_XY, CONF_MIRROR_X, CONF_MIRROR_Y):
+            if x not in transforms:
+                transform = transform.extend(
+                    {cv.Optional(x): cv.invalid(f"{x} not supported by this model")}
+                )
+    else:
+        transform = cv.invalid("This model does not support transforms")
+
+    # RPI model does not use an init sequence, indicates with empty list
+    if model.initsequence is None:
+        # Custom model requires an init sequence
+        iseqconf = cv.Required(CONF_INIT_SEQUENCE)
+        uses_spi = True
+    else:
+        iseqconf = cv.Optional(CONF_INIT_SEQUENCE)
+        uses_spi = CONF_INIT_SEQUENCE in config or len(model.initsequence) != 0
+    swap_xy = config.get(CONF_TRANSFORM, {}).get(CONF_SWAP_XY, False)
+
+    # Dimensions are optional if the model has a default width and the swap_xy transform is not overridden
+    cv_dimensions = (
+        cv.Optional if model.get_default(CONF_WIDTH) and not swap_xy else cv.Required
+    )
+    pixel_modes = (PIXEL_MODE_16BIT, PIXEL_MODE_18BIT, "16", "18")
+    schema = display.FULL_DISPLAY_SCHEMA.extend(
+        {
+            model.option(CONF_RESET_PIN, cv.UNDEFINED): pins.gpio_output_pin_schema,
+            cv.GenerateID(): cv.declare_id(mipi_rgb_spi if uses_spi else mipi_rgb),
+            cv_dimensions(CONF_DIMENSIONS): dimension_schema(
+                model.get_default(CONF_DRAW_ROUNDING, 1)
+            ),
+            model.option(CONF_ENABLE_PIN, cv.UNDEFINED): cv.ensure_list(
+                pins.gpio_output_pin_schema
+            ),
+            model.option(CONF_COLOR_ORDER, MODE_BGR): cv.enum(COLOR_ORDERS, upper=True),
+            model.option(CONF_DRAW_ROUNDING, 2): power_of_two,
+            model.option(CONF_PIXEL_MODE, PIXEL_MODE_16BIT): cv.one_of(
+                *pixel_modes, lower=True
+            ),
+            model.option(CONF_TRANSFORM, cv.UNDEFINED): transform,
+            cv.Required(CONF_MODEL): cv.one_of(model.name, upper=True),
+            model.option(CONF_INVERT_COLORS, False): cv.boolean,
+            model.option(CONF_USE_AXIS_FLIPS, True): cv.boolean,
+            model.option(CONF_PCLK_FREQUENCY, "40MHz"): cv.All(
+                cv.frequency, cv.Range(min=4e6, max=100e6)
+            ),
+            model.option(CONF_PCLK_INVERTED, True): cv.boolean,
+            iseqconf: cv.ensure_list(map_sequence),
+            model.option(CONF_BYTE_ORDER, BYTE_ORDER_BIG): cv.one_of(
+                BYTE_ORDER_LITTLE, BYTE_ORDER_BIG, lower=True
+            ),
+            model.option(CONF_HSYNC_PULSE_WIDTH): cv.int_,
+            model.option(CONF_HSYNC_BACK_PORCH): cv.int_,
+            model.option(CONF_HSYNC_FRONT_PORCH): cv.int_,
+            model.option(CONF_VSYNC_PULSE_WIDTH): cv.int_,
+            model.option(CONF_VSYNC_BACK_PORCH): cv.int_,
+            model.option(CONF_VSYNC_FRONT_PORCH): cv.int_,
+            model.option(CONF_DATA_PINS): cv.Any(
+                data_pin_set(16),
+                cv.Schema(
+                    {
+                        cv.Required(CONF_RED): data_pin_set(5),
+                        cv.Required(CONF_GREEN): data_pin_set(6),
+                        cv.Required(CONF_BLUE): data_pin_set(5),
+                    }
+                ),
+            ),
+            model.option(
+                CONF_DE_PIN, cv.UNDEFINED
+            ): pins.internal_gpio_output_pin_schema,
+            model.option(CONF_PCLK_PIN): pins.internal_gpio_output_pin_schema,
+            model.option(CONF_HSYNC_PIN): pins.internal_gpio_output_pin_schema,
+            model.option(CONF_VSYNC_PIN): pins.internal_gpio_output_pin_schema,
+            model.option(CONF_RESET_PIN, cv.UNDEFINED): pins.gpio_output_pin_schema,
+        }
+    )
+    if uses_spi:
+        schema = schema.extend(
+            {
+                cv.GenerateID(CONF_SPI_ID): cv.use_id(SPIComponent),
+                model.option(CONF_DC_PIN, cv.UNDEFINED): pins.gpio_output_pin_schema,
+                model.option(CONF_DATA_RATE, "1MHz"): SPI_DATA_RATE_SCHEMA,
+                model.option(CONF_SPI_MODE, "MODE0"): cv.enum(
+                    SPI_MODE_OPTIONS, upper=True
+                ),
+                model.option(CONF_CS_PIN, cv.UNDEFINED): pins.gpio_output_pin_schema,
+            }
+        )
+    return schema
+
+
+def _config_schema(config):
+    config = cv.Schema(
+        {
+            cv.Required(CONF_MODEL): cv.one_of(*MODELS, upper=True),
+        },
+        extra=cv.ALLOW_EXTRA,
+    )(config)
+    schema = model_schema(config)
+    return cv.All(
+        schema,
+        only_on_variant(supported=[const.VARIANT_ESP32S3]),
+        cv.only_with_esp_idf,
+    )(config)
+
+
+CONFIG_SCHEMA = _config_schema
+
+
+def _final_validate(config):
+    global_config = full_config.get()
+
+    from esphome.components.lvgl import DOMAIN as LVGL_DOMAIN
+
+    if not requires_buffer(config) and LVGL_DOMAIN not in global_config:
+        # If no drawing methods are configured, and LVGL is not enabled, show a test card
+        config[CONF_SHOW_TEST_CARD] = True
+    if CONF_SPI_ID in config:
+        config = spi.final_validate_device_schema(
+            "mipi_rgb", require_miso=False, require_mosi=True
+        )(config)
+    return config
+
+
+FINAL_VALIDATE_SCHEMA = _final_validate
+
+
+async def to_code(config):
+    model = MODELS[config[CONF_MODEL].upper()]
+    width, height, _offset_width, _offset_height = model.get_dimensions(config)
+    var = cg.new_Pvariable(config[CONF_ID], width, height)
+    cg.add(var.set_model(model.name))
+    if enable_pin := config.get(CONF_ENABLE_PIN):
+        enable = [await cg.gpio_pin_expression(pin) for pin in enable_pin]
+        cg.add(var.set_enable_pins(enable))
+
+    if CONF_SPI_ID in config:
+        await spi.register_spi_device(var, config)
+        sequence, madctl = model.get_sequence(config)
+        cg.add(var.set_init_sequence(sequence))
+        cg.add(var.set_madctl(madctl))
+
+    cg.add(var.set_color_mode(COLOR_ORDERS[config[CONF_COLOR_ORDER]]))
+    cg.add(var.set_invert_colors(config[CONF_INVERT_COLORS]))
+    cg.add(var.set_hsync_pulse_width(config[CONF_HSYNC_PULSE_WIDTH]))
+    cg.add(var.set_hsync_back_porch(config[CONF_HSYNC_BACK_PORCH]))
+    cg.add(var.set_hsync_front_porch(config[CONF_HSYNC_FRONT_PORCH]))
+    cg.add(var.set_vsync_pulse_width(config[CONF_VSYNC_PULSE_WIDTH]))
+    cg.add(var.set_vsync_back_porch(config[CONF_VSYNC_BACK_PORCH]))
+    cg.add(var.set_vsync_front_porch(config[CONF_VSYNC_FRONT_PORCH]))
+    cg.add(var.set_pclk_inverted(config[CONF_PCLK_INVERTED]))
+    cg.add(var.set_pclk_frequency(config[CONF_PCLK_FREQUENCY]))
+    index = 0
+    dpins = []
+    if CONF_RED in config[CONF_DATA_PINS]:
+        red_pins = config[CONF_DATA_PINS][CONF_RED]
+        green_pins = config[CONF_DATA_PINS][CONF_GREEN]
+        blue_pins = config[CONF_DATA_PINS][CONF_BLUE]
+        if config[CONF_COLOR_ORDER] == "BGR":
+            dpins.extend(red_pins)
+            dpins.extend(green_pins)
+            dpins.extend(blue_pins)
+        else:
+            dpins.extend(blue_pins)
+            dpins.extend(green_pins)
+            dpins.extend(red_pins)
+        # swap bytes to match big-endian format
+        dpins = dpins[8:16] + dpins[0:8]
+    else:
+        dpins = config[CONF_DATA_PINS]
+    for index, pin in enumerate(dpins):
+        data_pin = await cg.gpio_pin_expression(pin)
+        cg.add(var.add_data_pin(data_pin, index))
+
+    if dc_pin := config.get(CONF_DC_PIN):
+        dc = await cg.gpio_pin_expression(dc_pin)
+        cg.add(var.set_dc_pin(dc))
+
+    if reset_pin := config.get(CONF_RESET_PIN):
+        reset = await cg.gpio_pin_expression(reset_pin)
+        cg.add(var.set_reset_pin(reset))
+
+    if model.rotation_as_transform(config):
+        config[CONF_ROTATION] = 0
+
+    if de_pin := config.get(CONF_DE_PIN):
+        pin = await cg.gpio_pin_expression(de_pin)
+        cg.add(var.set_de_pin(pin))
+    pin = await cg.gpio_pin_expression(config[CONF_PCLK_PIN])
+    cg.add(var.set_pclk_pin(pin))
+    pin = await cg.gpio_pin_expression(config[CONF_HSYNC_PIN])
+    cg.add(var.set_hsync_pin(pin))
+    pin = await cg.gpio_pin_expression(config[CONF_VSYNC_PIN])
+    cg.add(var.set_vsync_pin(pin))
+
+    await display.register_display(var, config)
+    if lamb := config.get(CONF_LAMBDA):
+        lambda_ = await cg.process_lambda(
+            lamb, [(display.DisplayRef, "it")], return_type=cg.void
+        )
+        cg.add(var.set_writer(lambda_))