Add st7701s and rpi_dpi_rgb docs (#3546)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
2024-03-12 09:45:57 +11:00 · 2024-03-12 09:45:57 +11:00 · d2af542012
parent df6b8af452
commit d2af542012
6 changed files with 414 additions and 0 deletions
--- a/components/display/images/indicator.jpg
+++ b/components/display/images/indicator.jpg
--- a/components/display/images/waveshare_touch-s3.jpg
+++ b/components/display/images/waveshare_touch-s3.jpg
--- a/components/display/rpi_dpi_rgb.rst
+++ b/components/display/rpi_dpi_rgb.rst
@ -0,0 +1,213 @@
+RPI_DPI_RGB Display Driver
+===========================
+
+.. seo::
+    :description: Instructions for setting up 16 bit "RPI_DPI_RGB" parallel displays
+    :image: waveshare_touch-s3.jpg
+
+.. _rpi_dpi_rgb:
+
+Models
+------
+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.
+
+This driver has been tested with the following displays:
+
+  - Waveshare ESP32-S3-Touch-LCD-4.3
+  - Makerfabs 4.3" display (Sunton)
+
+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.
+
+.. figure:: images/waveshare_touch-s3.jpg
+    :align: center
+    :width: 75.0%
+
+    Waveshare ESP32-S3 Touch 4.3
+
+
+.. code-block:: yaml
+
+
+    # Example minimal configuration entry
+    display:
+      - platform: rpi_dpi_rgb
+        id: rpi_disp
+        dimensions:
+          width: 800
+          height: 480
+        de_pin: REPLACE_ME
+        hsync_pin: REPLACE_ME
+        vsync_pin: REPLACE_ME
+        pclk_pin: REPLACE_ME
+
+        data_pins:
+          red:
+            - XX        #r1
+            - XX        #r2
+            - XX        #r3
+            - XX        #r4
+            - XX        #r5
+          green:
+            - XX        #g0
+            - XX        #g1
+            - XX        #g2
+            - XX        #g3
+            - XX        #g4
+            - XX        #g5
+          blue:
+            - XX        #b1
+            - XX        #b2
+            - XX        #b3
+            - XX        #b4
+            - XX        #b5
+
+Configuration variables:
+************************
+
+- **data_pins** (**Required**) A list of pins used for the databus. Specified in 3 groups:
+
+    - **red**: (**Required**, :ref:`Pin Schema <config-pin_schema>`) Exactly 5 pin numbers for the red databits, listed from least to most significant bit.
+    - **green**: (**Required**, :ref:`Pin Schema <config-pin_schema>`) Exactly 6 pin numbers for the green databits, listed from least to most significant bit.
+    - **blue**: (**Required**, :ref:`Pin Schema <config-pin_schema>`) Exactly 5 pin numbers for the blue databits, listed from least to most significant bit.
+- **de_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The DE pin
+- **pclk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The PCLK pin.
+- **hsync_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The Horizontal sync pin.
+- **vsync_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The Vertical sync pin.
+- **reset_pin** (*Optional*, :ref:`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.
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
+- **auto_clear_enabled** (*Optional*, boolean): Whether to automatically clear the display in each loop (''true'', default),
+  or to keep the existing display content (must overwrite explicitly, e.g., only on data change).
+- **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`.
+- **id** (*Optional*, :ref:`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.
+
+- **pclk_frequency** (*Optional*): Set the pixel clock speed. Default is 16MHz.
+- **pclk_inverted** (*Optional* bool): If the pclk is active negative (default is True)
+- **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°``.
+- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the display.
+  See :ref:`display-engine` for more information.
+
+
+The horizontal and vertical ``pulse_width``, ``front_porch`` and ``back_porch`` values are optional, but may require
+changing for a specific display. Refer to the manufacturer's sample code for suitable values. These specify timing
+requirements for the display.
+
+Example configurations
+----------------------
+
+
+Waveshare ESP32-S3 Touch 4.3
+****************************
+
+.. code-block:: yaml
+
+    display:
+      - platform: rpi_dpi_rgb
+        auto_clear_enabled: false
+        color_order: RGB
+        pclk_frequency: 16MHz
+        dimensions:
+          width: 800
+          height: 480
+        de_pin:
+          number: 5
+        hsync_pin:
+          number: 46
+          ignore_strapping_warning: true
+        vsync_pin:
+          number: 3
+          ignore_strapping_warning: true
+        pclk_pin: 7
+        hsync_back_porch: 30
+        hsync_front_porch: 210
+        hsync_pulse_width: 30
+        vsync_back_porch: 4
+        vsync_front_porch: 4
+        vsync_pulse_width: 4
+        data_pins:
+          red:
+            - 1         #r3
+            - 2         #r4
+            - 42        #r5
+            - 41        #r6
+            - 40        #r7
+          blue:
+            - 14        #b3
+            - 38        #b4
+            - 18        #b5
+            - 17        #b6
+            - 10        #b7
+          green:
+            - 39        #g2
+            - 0         #g3
+            - 45        #g4
+            - 48        #g5
+            - 47        #g6
+            - 21        #g7
+
+
+Makerfabs 4.3" 800x480 display
+******************************
+
+.. code-block:: yaml
+
+    display:
+      - platform: rpi_dpi_rgb
+        update_interval: never
+        auto_clear_enabled: false
+        id: rpi_display
+        color_order: RGB
+        rotation: 90
+        dimensions:
+          width: 800
+          height: 480
+        de_pin:
+          number: 40
+        hsync_pin: 39
+        vsync_pin: 41
+        pclk_pin: 42
+        data_pins:
+          red:
+            - 45        #r1
+            - 48        #r2
+            - 47        #r3
+            - 21        #r4
+            - 14        #r5
+          green:
+            - 5         #g0
+            - 6         #g1
+            - 7         #g2
+            - 15        #g3
+            - 16        #g4
+            - 4         #g5
+          blue:
+            - 8         #b1
+            - 3         #b2
+            - 46        #b3
+            - 9         #b4
+            - 1         #b5
+
+
+
+See Also
+--------
+
+- :doc:`index`
+- :apiref:`rpi_dpi_rgb/rpi_dpi_rgb.h`
+- :ghedit:`Edit`
--- a/components/display/st7701s.rst
+++ b/components/display/st7701s.rst
@ -0,0 +1,199 @@
+ST7701S Display Driver
+======================
+
+.. seo::
+    :description: Instructions for setting up ST7701S 16 bit "RGB" parallel displays
+    :image: indicator.jpg
+
+.. _st7701s:
+
+Models
+------
+This display driver supports displays with 16 bit parallel interfaces, often referred to as "RGB". It currently
+supports the ST7701S chip.
+
+This driver has been tested with the following displays:
+
+  - Seeed Sensecap Indicator
+  - Makerfabs 4" display
+
+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.
+
+.. figure:: images/indicator.jpg
+    :align: center
+    :width: 75.0%
+
+    Sensecap Indicator display
+
+
+.. code-block:: yaml
+
+    # Example minimal configuration entry
+    display:
+      - platform: st7701s
+        dimensions:
+          width: 480
+          height: 480
+        cs_pin: REPLACE_ME
+        reset_pin: REPLACE_ME
+        de_pin: REPLACE_ME
+        hsync_pin: REPLACE_ME
+        vsync_pin: REPLACE_ME
+        pclk_pin: REPLACE_ME
+        # Replace XX with the correct pin number
+
+        data_pins:
+          red:
+            - XX        #r1
+            - XX        #r2
+            - XX        #r3
+            - XX        #r4
+            - XX        #r5
+          green:
+            - XX        #g0
+            - XX        #g1
+            - XX        #g2
+            - XX        #g3
+            - XX        #g4
+            - XX        #g5
+          blue:
+            - XX        #b1
+            - XX        #b2
+            - XX        #b3
+            - XX        #b4
+            - XX        #b5
+
+Configuration variables:
+************************
+
+- **init_sequence** (*Optional*, A list of byte arrays): Specifies the init sequence for the display
+- **data_pins** (**Required**): A list of pins used for the databus. Specified in 3 groups.
+
+    - **red**: (**Required**, :ref:`Pin Schema <config-pin_schema>`) Exactly 5 pin numbers for the red databits, listed from least to most significant bit.
+    - **green**: (**Required**, :ref:`Pin Schema <config-pin_schema>`) Exactly 6 pin numbers for the green databits, listed from least to most significant bit.
+    - **blue**: (**Required**, :ref:`Pin Schema <config-pin_schema>`) Exactly 5 pin numbers for the blue databits, listed from least to most significant bit.
+- **de_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The DE pin.
+- **dc_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The DC pin.
+- **pclk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The PCLK pin.
+- **hsync_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The Horizontal sync pin.
+- **vsync_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The Vertical sync pin.
+- **reset_pin** (*Optional*, :ref:`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)
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to re-draw the screen. Defaults to ``5s``.
+- **auto_clear_enabled** (*Optional*, boolean): Whether to automatically clear the display in each loop (''true'', default),
+  or to keep the existing display content (must overwrite explicitly, e.g., only on data change).
+- **pages** (*Optional*, list): Show pages instead of a single lambda. See :ref:`display-pages`.
+- **id** (*Optional*, :ref:`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_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``.
+- **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``.
+
+   - **swap_xy** (*Optional*, boolean): If true, exchange the x and y axes.
+   - **mirror_x** (*Optional*, boolean): If true, mirror the x axis.
+   - **mirror_y** (*Optional*, boolean): If true, mirror the y axis.
+- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use for rendering the content on the display.
+  See :ref:`display-engine` for more information.
+
+
+**Note:** To rotate the display in hardware use one of the following combinations:
+
+    - 90 degrees - use ``swap_xy`` with ``mirror_x``
+    - 180 degrees - use ``mirror_x`` with ``mirror_y``
+    - 270 degrees - use ``swap_xy`` with ``mirror_y``
+
+The horizontal and vertical ``pulse_width``, ``front_porch`` and ``back_porch`` values are optional, but may require
+changing for a specific display. Refer to the manufacturer's sample code for suitable values. These specify timing
+requirements for the display.
+
+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.
+
+These will be collected and sent to the display via SPI during initialisation.
+
+Example configurations
+----------------------
+
+Seeed Sensecap Indicator
+************************
+
+.. code-block:: yaml
+
+    display:
+      - platform: st7701s
+        auto_clear_enabled: false
+        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
+          - [ 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
+--------
+
+- :doc:`index`
+- :apiref:`st7701s/st7701s.h`
+- :ghedit:`Edit`
--- a/images/waveshare_touch-s3.jpg
+++ b/images/waveshare_touch-s3.jpg
--- a/index.rst
+++ b/index.rst
@ -673,6 +673,7 @@ Display Components
    Nextion, components/display/nextion, nextion.jpg
    PCD8544 (Nokia 5110/ 3310), components/display/pcd8544, pcd8544.jpg
    PVVX MiThermometer, components/display/pvvx_mithermometer, ../components/sensor/images/xiaomi_lywsd03mmc.jpg
+    RPI_DPI_RGB, components/display/rpi_dpi_rgb, waveshare_touch-s3.jpg
    SSD1306, components/display/ssd1306, ssd1306.jpg
    SSD1322, components/display/ssd1322, ssd1322.jpg
    SSD1325, components/display/ssd1325, ssd1325.jpg
@ -681,6 +682,7 @@ Display Components
    SSD1351, components/display/ssd1351, ssd1351.jpg
    ST7567, components/display/st7567, st7567.jpg
    ST7735, components/display/st7735, st7735.jpg
+    ST7701S, components/display/st7701s, indicator.jpg
    ST7789V, components/display/st7789v, st7789v.jpg
    ST7796, components/display/ili9xxx, st7796.svg
    ST7920, components/display/st7920, st7920.jpg