diff --git a/content/components/_index.md b/content/components/_index.md index ba10755a78..d502ffcf88 100644 --- a/content/components/_index.md +++ b/content/components/_index.md @@ -673,6 +673,7 @@ Often known as "tag" or "card" readers within the community. {{< imgtable >}} "Addressable Light","components/display/addressable_light","addressable_light.jpg" "MIPI DSI Displays","components/display/mipi_dsi","tab5.jpg" +"MIPI RGB Displays","components/display/mipi_rgb","indicator.jpg" "MIPI SPI Displays","components/display/mipi_spi","t4-s3.jpg" "ILI9xxx","components/display/ili9xxx","ili9341.jpg" "ILI9341","components/display/ili9xxx","ili9341.svg" diff --git a/content/components/display/_index.md b/content/components/display/_index.md index 6a722c4146..28ef191119 100644 --- a/content/components/display/_index.md +++ b/content/components/display/_index.md @@ -9,14 +9,17 @@ params: -The `display` component houses ESPHome's powerful rendering and display -engine. Fundamentally, there are these types of displays: +The `display` component houses ESPHome's graphical rendering and display +engine. It caters for a wide range of different display types, from simple character displays to +graphical displays with fully addressable pixels. - Character displays like {{< docref "max7219" "7-Segment displays" >}} or {{< docref "lcd_display" "LCD displays" >}}. - Serial displays like {{< docref "nextion/" >}} that have their own processors for graphics rendering. -- Graphical displays with fully addressable pixels, like {{< docref "waveshare_epaper" "E-Paper" >}}, - {{< docref "ssd1306" "OLED" >}} or {{< docref "ili9xxx" "TFT" >}} displays. +- Graphical displays with fully addressable pixels, such as + {{< docref "mipi_spi" "SPI interfaced LCDs" >}}, + {{< docref "waveshare_epaper" "E-Paper" >}}, + and {{< docref "ssd1306" "OLED" >}}. For graphical displays, which offer the greatest flexibility, there are two options for displaying content: @@ -589,7 +592,7 @@ display: - **from** (*Optional*, [ID](#config-id)): A page id. If set the automation is only triggered if changing from this page. Defaults to all pages. - **to** (*Optional*, [ID](#config-id)): A page id. If set the automation is only triggered if changing to this page. Defaults to all pages. -Additionally the old page will be given as the variable `from` and the new one as the variable `to` . +Additionally, the old page will be given as the variable `from` and the new one as the variable `to` . ### Troubleshooting @@ -622,7 +625,10 @@ For displays in 8 bit mode you will see distinct color blocks rather than a smoo ### See Also - {{< apiref "display/display_buffer.h" "display/display_buffer.h" >}} -- {{< docref "/components/lvgl/index" "LVGL" >}} +- {{< docref "/components/lvgl/index" >}} +- {{< docref "/components/display/mipi_spi" >}} +- {{< docref "/components/display/mipi_rgb" >}} +- {{< docref "/components/display/mipi_dsi" >}} - [Fonts](#display-fonts) - [Graph Component](#display-graphs) - [QR Code Component](#display-qrcode) diff --git a/content/components/display/ili9xxx.md b/content/components/display/ili9xxx.md index 17d76fdf56..f6bff6f84f 100644 --- a/content/components/display/ili9xxx.md +++ b/content/components/display/ili9xxx.md @@ -46,8 +46,8 @@ beyond the basic SPI connections, and a reasonable amount of RAM, it is not well {{< warning >}} This component has been made redundant since this class of displays is now supported by the [MIPI SPI Display Driver](#mipi_spi). This component may be removed in a future release. - {{< /warning >}} + {{< note >}} PSRAM is not automatically enabled on the ESP32 (this changed with the 2025.2 release.) If PSRAM is available, you should enable it with the {{< docref "/components/psram" "PSRAM configuration" >}}. diff --git a/content/components/display/mipi_rgb.md b/content/components/display/mipi_rgb.md new file mode 100644 index 0000000000..b227046f7c --- /dev/null +++ b/content/components/display/mipi_rgb.md @@ -0,0 +1,196 @@ +--- +description: "Instructions for setting up 16 bit \"RGB\" parallel displays" +title: "MIPI RGB Display Driver" +params: + seo: + description: Instructions for setting up 16 bit "RGB" parallel displays + image: indicator.jpg +--- + +## Types of Display +This display driver supports displays with 16 bit parallel interfaces, often referred to as "RGB". +Two classes of display fall under this category, the first are those that only have the RGB interface and require +no special configuration of the driver chip. The second are those that have both the RGB interface and an SPI interface +which is used to configure the driver chip. + +## Supported boards and driver chips + +The driver supports a number of display driver chips, and can be configured for custom displays. As well as support for +driver chips, there are also specific configurations for several ESP32 boards with integrated displays. For those boards +the predefined configuration will set the correct pins and dimensions for the display. + +For custom displays, the driver can be configured with the correct pins and dimensions, and the driver chip can be +specified, or a custom init sequence can be provided. + +### Driver chips + +| Driver Chip | Typical Dimensions | +|-------------|--------------------| +| ST7701S | 480x480 | +| RPI | varies | + +The `RPI` driver chip represents displays without an SPI interface, so no init sequence is required. + +### Supported integrated display boards + +These boards have completely pre-filled configurations for the display driver, so the only required configuration +option is `model`. + +| Board | Driver Chip | Manufacturer | Product link | +|--------------------|-------------|--------------|----------------------------------------------------------------| +| GUITION-4848S040 | ST7701s | Guition | | +| T-PANEL-S3 | ST7701s | Lilygo | | +| T-RGB-2.1 | ST7701s | Lilygo | | +| T-RGB-2.8 | ST7701s | Lilygo | | +| SEEED-INDICATOR-D1 | ST7701s | Seeed Studio | | +| ESP32-S3-TOUCH-LCD-4.3 | RPI | Waveshare | | +| ESP32-S3-TOUCH-LCD-7-800X480 | RPI | Waveshare | | +| WAVESHARE-4-480x480 | RPI | Waveshare | | + +## Usage +This component requires an ESP32 (usually an ESP32-S3 because of the number of GPIO pins required) and the use of +ESP-IDF. PSRAM is a requirement due to the size of the display buffer. + +{{< img src="indicator.jpg" alt="Image" caption="Sensecap Indicator display" width="75.0%" class="align-center" >}} + +```yaml +# Example minimal configuration entry +display: + - platform: mipi_rgb + model: WAVESHARE-4-480x480 + id: my_display + +``` + +## Configuration variables: + +- **invert_colors** (*Optional*): With this boolean option you can invert the display colors. **Note** some of the displays have this option set automatically to true and can't be changed. +- **rotation** (*Optional*): Rotate the display presentation in software. Choose one of `0°` , `90°` , `180°` , or `270°` . This option cannot be used with `transform` . +- **transform** (*Optional*): Transform the display presentation using hardware. All defaults are `false` . This option cannot be used with `rotation` . + - **mirror_x** (*Optional*, boolean): If true, mirror the x-axis. + - **mirror_y** (*Optional*, boolean): If true, mirror the y-axis. + **Note:** To rotate the display in hardware by 180 degrees set both `mirror_x` and `mirror_y` to `true`. +- **update_interval** (*Optional*, [Time](#config-time)): The interval to re-draw the screen. Defaults to `5s` . +- **auto_clear_enabled** (*Optional*, boolean): If the display should be cleared before each update. Defaults to `true` + if a lambda or pages are configured, false otherwise. +- **lambda** (*Optional*, [lambda](#config-lambda)): The lambda to use for rendering the content on the display. + See [Display Rendering Engine](#display-engine) for more information. +- **pages** (*Optional*, list): Show pages instead of a single lambda. See [Display Pages](#display-pages). +- **id** (*Optional*, [ID](#config-id)): Manually specify the ID used for code generation. +- **color_order** (*Optional*): Should be one of `bgr` (default) or `rgb` . +- **dimensions** (**Required**): Dimensions of the screen, specified either as *width* **x** *height* (e.g `320x240` ) or with separate config keys. + + - **height** (**Required**, int): Specifies height of display in pixels. + - **width** (**Required**, int): Specifies width of display. + - **offset_width** (*Optional*, int): Specify an offset for the x-direction of the display, typically used when an LCD is smaller than the maximum supported by the driver chip. Default is 0 + - **offset_height** (*Optional*, int): Specify an offset for the y-direction of the display. Default is 0. + +- **data_pins** (**Required**): A list of pins used for the databus. Specified in 3 groups. + + - **red** (**Required**, [Pin Schema](#config-pin_schema)): Exactly 5 pins for the red databits, listed from least to most significant bit. + - **green** (**Required**, [Pin Schema](#config-pin_schema)): Exactly 6 pins for the green databits, listed from least to most significant bit. + - **blue** (**Required**, [Pin Schema](#config-pin_schema)): Exactly 5 pins for the blue databits, listed from least to most significant bit. + +- **de_pin** (**Required**, [Pin Schema](#config-pin_schema)): The DE pin. +- **pclk_pin** (**Required**, [Pin Schema](#config-pin_schema)): The PCLK pin. +- **hsync_pin** (**Required**, [Pin Schema](#config-pin_schema)): The Horizontal sync pin. +- **vsync_pin** (**Required**, [Pin Schema](#config-pin_schema)): The Vertical sync pin. +- **reset_pin** (*Optional*, [Pin Schema](#config-pin_schema)): The RESET pin. +- **hsync_pulse_width** (*Optional*, int): The horizontal sync pulse width. +- **hsync_front_porch** (*Optional*, int): The horizontal front porch length. +- **hsync_back_porch** (*Optional*, int): The horizontal back porch length. +- **vsync_pulse_width** (*Optional*, int): The vertical sync pulse width. +- **vsync_front_porch** (*Optional*, int): The vertical front porch length. +- **vsync_back_porch** (*Optional*, int): The vertical back porch length. +- **pclk_frequency** (*Optional*): Set the pixel clock speed. Default is 8MHz. +- **pclk_inverted** (*Optional*, bool): If the pclk is active negative (default is True) + + +The horizontal and vertical `pulse_width` , `front_porch` and `back_porch` values are optional, but will +likely require +changing from the default values for a specific display. Refer to the manufacturer's sample code for suitable values. These specify timing +requirements for the display. + +## Additional Configuration for non-RPI displays + +Displays needing a custom init sequence require an SPI bus to be configured, plus these options: + +- **dc_pin** (*Optional*, [Pin Schema](#config-pin_schema)): The DC pin. +- **data_rate** (*Optional*): Set the data rate of the SPI interface to the display. One of `80MHz` , `40MHz` , + `20MHz` , `10MHz` , `5MHz` , `2MHz` , `1MHz` (default), `200kHz` , `75kHz` or `1kHz` . +- **spi_mode** (*Optional*): Set the mode for the SPI interface to the display. Default is `MODE0` but some displays require `MODE3` . +- **spi_id** (*Optional*, [ID](#config-id)): The ID of the SPI interface to use - may be omitted if only one SPI bus is configured. +- **init_sequence** (*Optional*, A list of byte arrays): Specifies the init sequence for the display. Predefined boards have a default init sequence, which can be overridden. + A custom board can specify the init sequence using this variable. RPI displays should provide an empty sequence in which case the SPI bus is not required. + +The `init_sequence` requires a list of elements, one of which may be a single integer selecting a canned init +sequence (the default and currently the only sequence is 1), the remainder must be byte arrays providing additional +init commands, each consisting of a command byte followed by zero or more data bytes. + +A delay may be specified with `delay ms` + +These will be collected and sent to the display via SPI during initialisation. The SPI bus need not be implemented +in hardware (i.e. it may use `interface: software`) and it will be released after initialisation, before the RGB +driver is configured. This caters for boards that use the SPI bus pins as RGB pins. + +## Example configurations + +This is an example of a full custom configuration. + +```yaml +display: + - platform: mipi_rgb + update_interval: never + spi_mode: MODE3 + color_order: RGB + dimensions: + width: 480 + height: 480 + invert_colors: true + transform: + mirror_x: true + mirror_y: true + cs_pin: + pca9554: p_c_a + number: 4 + reset_pin: + pca9554: p_c_a + number: 5 + de_pin: 18 + hsync_pin: 16 + vsync_pin: 17 + pclk_pin: 21 + init_sequence: + - 1 # select canned init sequence number 1 + - delay 5ms + - [ 0xE0, 0x1F ] # Set sunlight readable enhancement + data_pins: + red: + - 4 #r1 + - 3 #r2 + - 2 #r3 + - 1 #r4 + - 0 #r5 + green: + - 10 #g0 + - 9 #g1 + - 8 #g2 + - 7 #g3 + - 6 #g4 + - 5 #g5 + blue: + - 15 #b1 + - 14 #b2 + - 13 #b3 + - 12 #b4 + - 11 #b5 + lambda: |- + it.fill(COLOR_BLACK); + it.print(0, 0, id(my_font), id(my_red), TextAlign::TOP_LEFT, "Hello World!"); + +``` +## See Also + +- {{< docref "index/" >}} +- {{< apiref "mipi_rgb/mipi_rgb.h" "mipi_rgb/mipi_rgb.h" >}} + diff --git a/content/components/display/qspi_dbi.md b/content/components/display/qspi_dbi.md index 9a23e82115..bdd304050c 100644 --- a/content/components/display/qspi_dbi.md +++ b/content/components/display/qspi_dbi.md @@ -14,6 +14,11 @@ params: ## Models This display driver supports AMOLED and LCD displays with quad SPI interfaces, using the MIPI DBI interface. +{{< warning >}} +This component has been made redundant since this class of displays is now supported by the {{< docref "mipi_spi" >}} +This component will be removed in a future release. +{{< /warning >}} + This driver has been tested with the following displays: - Lilygo T4-S3 diff --git a/content/components/display/rpi_dpi_rgb.md b/content/components/display/rpi_dpi_rgb.md index 6aedf6115d..9fcf319f5c 100644 --- a/content/components/display/rpi_dpi_rgb.md +++ b/content/components/display/rpi_dpi_rgb.md @@ -15,6 +15,11 @@ params: This display driver supports displays with 16 bit parallel interfaces, often referred to as "RPI_DPI_RGB" type. These have a parallel interface but no SPI interface and require no configuration of the driver chip. +{{< warning >}} +This component has been made redundant since this class of displays is now supported by the {{< docref "mipi_rgb" >}} +This component will be removed in a future release. +{{< /warning >}} + This driver has been tested with the following displays: - Waveshare ESP32-S3-Touch-LCD-4.3 diff --git a/content/components/display/st7735.md b/content/components/display/st7735.md index b5f7a1e1af..2d5b8ae02f 100644 --- a/content/components/display/st7735.md +++ b/content/components/display/st7735.md @@ -8,7 +8,6 @@ params: --- - ST7735 Display Driver. ## Usage @@ -21,12 +20,8 @@ It uses the [SPI Bus](#spi) for communication. {{< img src="st7735.jpg" alt="Image" caption="ST7735 Display" width="75.0%" class="align-center" >}} {{< warning >}} -This component has been made redundant since the ST7735 is now supported by the [ILI9XXX component](#ili9xxx). It is recommended -that you use the `ili9xxx` component as it will be maintained, whereas this component may not be, or may be removed completely -in the future. If migrating from this component to `ili9xxx` you may need to set the `dimensions:` option to -specify the screen size and offsets in the `ili9xxx` config. - - +This component has been made redundant since the ST7735 is now supported by the {{< docref "mipi_spi" >}}. +This component will be removed in a future release. {{< /warning >}} There are numerous board types out there. Some initialize differently as well. This driver will take a few options to narrow down the right settings.