|
| 1 | +.. seo:: |
| 2 | + :description: Details for the MIPI DSI display driver component in ESPHome |
| 3 | + :image: tab5.jpg |
| 4 | + |
| 5 | +.. _mipi_dsi: |
| 6 | + |
| 7 | +MIPI DSI Display Driver |
| 8 | +======================= |
| 9 | + |
| 10 | +Introduction |
| 11 | +------------ |
| 12 | + |
| 13 | +This driver is for displays that use the MIPI DSI display interface available in the ESP32-P4. |
| 14 | + |
| 15 | +.. figure:: /images/tab5.jpg |
| 16 | + :align: center |
| 17 | + :width: 75.0% |
| 18 | + |
| 19 | + M5STACK-TAB5 with ESP32-P4 |
| 20 | + |
| 21 | +Background |
| 22 | +---------- |
| 23 | + |
| 24 | +The MIPI (Mobile Industry Processor Interface) Alliance publishes various hardware and software interface specifications |
| 25 | +including the Display Serial Interface (DSI), which transfers pixel data over a high-speed serial bus to an LCD display. |
| 26 | + |
| 27 | +The display panels controlled by the driver may be of various types, including TFT, IPS, and others. Each driver |
| 28 | +chip and panel combination requires a specific set of initialisation commands, and standard initialisation sequences are provided for many common |
| 29 | +boards and chips, but the driver is also designed to be customisable in YAML for other displays. |
| 30 | + |
| 31 | +Supported boards and driver chips |
| 32 | +--------------------------------- |
| 33 | + |
| 34 | +There are specific configurations for several ESP32 boards with integrated displays. For those boards |
| 35 | +the predefined configuration will set the correct pins and dimensions for the display. |
| 36 | + |
| 37 | +For custom displays, the driver can be configured with the correct pins and dimensions, and the driver chip can be |
| 38 | +specified, or a custom init sequence can be provided. |
| 39 | + |
| 40 | +Driver chips |
| 41 | +^^^^^^^^^^^^ |
| 42 | + |
| 43 | +.. csv-table:: |
| 44 | + :header: "Driver Chip", "Typical Dimensions" |
| 45 | + :widths: 15, 20 |
| 46 | + |
| 47 | + "CUSTOM", "Customisable" |
| 48 | + |
| 49 | +Boards with integrated displays |
| 50 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 51 | + |
| 52 | +.. csv-table:: |
| 53 | + :header: "Model", "Manufacturer", "Product Description" |
| 54 | + :widths: 30, 20, 30 |
| 55 | + |
| 56 | + "JC1060P470", "Guition", "https://aliexpress.com/item/1005008328088576.html" |
| 57 | + "M5STACK-TAB5", "M5Stack", "https://shop.m5stack.com/products/m5stack-tab5-iot-development-kit-esp32-p4" |
| 58 | + "WAVESHARE-P4-NANO-10.1", "Waveshare", "https://www.waveshare.com/esp32-p4-nano.htm?sku=29031" |
| 59 | + "WAVESHARE-P4-86-PANEL", "Waveshare", "https://www.waveshare.com/esp32-p4-wifi6-touch-lcd-4b.htm?sku=31570" |
| 60 | + |
| 61 | + |
| 62 | +Configuration |
| 63 | +------------- |
| 64 | + |
| 65 | +.. code-block:: yaml |
| 66 | +
|
| 67 | + # Example minimal configuration entry |
| 68 | + display: |
| 69 | + - platform: mipi_dsi |
| 70 | + model: WAVESHARE-P4-NANO-10.1 |
| 71 | +
|
| 72 | +Configuration options |
| 73 | +^^^^^^^^^^^^^^^^^^^^^ |
| 74 | + |
| 75 | +All :ref:`graphical display configuration<display-configuration>` options are available, plus the following. For integrated display boards |
| 76 | +most of the configuration will be set by default, but can be overridden if needed. |
| 77 | + |
| 78 | +- **model** (**Required**): Chosen from the lists of supported chips and models above, or ``CUSTOM`` for custom displays. |
| 79 | +- **reset_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): The RESET pin, if required. |
| 80 | +- **enable_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): An optional pin to enable the display, if required. A list of pins can be provided for displays that require multiple enable pins. A full pin configuration may be provided |
| 81 | + to set the pin mode and inverted property. By default the pin will be driven high to enable the display. |
| 82 | +- **color_order** (*Optional*): Should be one of ``bgr`` (default) or ``rgb``. This specifies the order of the color channels in the display panel. The default is ``bgr`` for most displays, but some displays may require ``rgb``. It does not affect the color order of the display buffer, which is always RGB. |
| 83 | +- **dimensions** (*Optional*): Dimensions of the screen, specified either as *width* **x** *height* (e.g ``320x240``) or with separate config keys. If not provided the dimensions will be determined by the model selected. This is required for the ``CUSTOM`` model, and is optional for other models. The dimensions are specified in pixels, and the width and height must be greater than 0. The following keys are available: |
| 84 | + |
| 85 | + - **height** (**Required**, int): Specifies height of display in pixels. |
| 86 | + - **width** (**Required**, int): Specifies width of display. |
| 87 | + - **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 |
| 88 | + - **offset_height** (*Optional*, int): Specify an offset for the y-direction of the display. Default is 0. |
| 89 | + |
| 90 | +- **invert_colors** (*Optional*, boolean): Specifies whether the display colors should be inverted. Options are ``true`` or ``false``. Defaults to ``false``. |
| 91 | +- **rotation** (*Optional*): Rotate the display presentation in software. Choose one of ``0°``, ``90°``, ``180°``, or ``270°``. If the driver chip supports hardware rotation for the given orientation this will be translated to the appropriate hardware command. If hardware rotation is not supported, the display will be rotated in software. |
| 92 | +- **transform** (*Optional*): If ``rotation`` is not sufficient, use this to transform the display. If this option is specified, then the ``dimensions`` option must also be provided. Options are: |
| 93 | + |
| 94 | + - **swap_xy** (**Required**, boolean): If true, exchange the x and y axes. |
| 95 | + - **mirror_x** (**Required**, boolean): If true, mirror the x axis. |
| 96 | + - **mirror_y** (**Required**, boolean): If true, mirror the y axis. |
| 97 | + |
| 98 | +- **hsync_pulse_width** (*Optional*, int): The horizontal sync pulse width. |
| 99 | +- **hsync_front_porch** (*Optional*, int): The horizontal front porch length. |
| 100 | +- **hsync_back_porch** (*Optional*, int): The horizontal back porch length. |
| 101 | +- **vsync_pulse_width** (*Optional*, int): The vertical sync pulse width. |
| 102 | +- **vsync_front_porch** (*Optional*, int): The vertical front porch length. |
| 103 | +- **vsync_back_porch** (*Optional*, int): The vertical back porch length. |
| 104 | +- **pclk_frequency** (*Optional*): Set the pixel clock speed. Default is 40MHz. |
| 105 | +- **pclk_inverted** (*Optional*, bool): If the pclk is active negative (default is True) |
| 106 | +- **lanes** (*Optional*, int): Number of serial data lanes to use - 1 or 2. Default is 2. |
| 107 | +- **lane_bit_rate** (*Optional*, int): The bit rate of the serial data lanes. No default unless a non-custom model is selected. |
| 108 | + |
| 109 | +Advanced options |
| 110 | +^^^^^^^^^^^^^^^^ |
| 111 | + |
| 112 | +- **init_sequence** (*Optional*): Allows custom initialisation sequences to be added. See below for more information. |
| 113 | +- **pixel_mode** (*Optional*): Select the interface mode for the display driver. Options are ``16bit`` (default) and ``24bit``. |
| 114 | +- **color_depth** (*Optional*): The color depth of the display buffer, expressed in bits. Options are ``16`` (default) and ``24``. Preferably should be the same as the ``pixel_mode`` option. |
| 115 | +- **draw_rounding** (*Optional*): The rounding factor for drawing operations. Defaults to 2. Some chips require a higher value to avoid display artifacts. Must be a power of 2. |
| 116 | +- **use_axis_flips** (*Optional*): If true, the driver will use alternate bits in the MADCTL register to implement x and y mirroring. Defaults to false. |
| 117 | +- **byte_order** (*Optional*): The byte order of the display buffer. Options are ``big_endian`` and ``little_endian`` (default). This affects the byte order for the buffer when |
| 118 | + using 16 bit color depth. The default is appropriate for the majority of displays. |
| 119 | + |
| 120 | + |
| 121 | +Additional initialisation sequences |
| 122 | +----------------------------------- |
| 123 | + |
| 124 | +The ``init_sequence`` option allows additional configuration of the driver chip. Provided commands will be sent to the |
| 125 | +driver chip in addition to, and after the chosen model's pre-defined commands. It requires a list of byte sequences: |
| 126 | + |
| 127 | +.. code-block:: yaml |
| 128 | +
|
| 129 | + init_sequence: |
| 130 | + - [ 0xD0, 0x07, 0x42, 0x18] |
| 131 | + - delay 10ms |
| 132 | + - [ 0xD1, 0x00, 0x07, 0x10] |
| 133 | +
|
| 134 | +Each entry represents a single-byte command followed by zero or more data bytes. Delays can be inserted with the ``delay`` keyword followed by a time in milliseconds. The delay is not precise, but will be at least the specified time. |
| 135 | +If converting from other code, make sure the length byte, if present, is not copied as the length of each command sequence is determined by the number of bytes in the list. |
| 136 | + |
| 137 | +CUSTOM model |
| 138 | +------------ |
| 139 | + |
| 140 | +The ``CUSTOM`` model selection is provided for otherwise unsupported displays, and requires both ``dimensions:`` and ``init_sequence:`` to be specified. There is no pre-defined init sequence. |
| 141 | + |
| 142 | +Using the ``transform`` options |
| 143 | +------------------------------- |
| 144 | + |
| 145 | +In most cases, the ``rotation`` option will be sufficient to orient the display correctly. However, some displays may require additional transformations. The ``transform`` option allows for these transformations to be applied in any of 8 different |
| 146 | +combinations. It may be necessary to experiment with different combinations to achieve the desired result. When using the ``transform`` option, the ``rotation`` option should not be set unless the display does not support axis-swapping. |
| 147 | +If the ``swap_xy`` option is set, then the ``dimensions`` option is required, and the ``width`` and ``height`` values should be set to reflect the final screen dimensions after rotation. |
| 148 | + |
| 149 | +.. code-block:: yaml |
| 150 | +
|
| 151 | + transform: |
| 152 | + swap_xy: true |
| 153 | + mirror_x: true |
| 154 | + mirror_y: false |
| 155 | + dimensions: |
| 156 | + height: 480 |
| 157 | + width: 320 |
| 158 | +
|
| 159 | +
|
| 160 | +LCD Backlights |
| 161 | +-------------- |
| 162 | + |
| 163 | +Many displays have an integrated backlight, which may need to be turned on for the display to show. This backlight is not controlled |
| 164 | +by the driver, but can be controlled by a separate GPIO pin. Depending on the display, the backlight may be active high or active low, and may |
| 165 | +be able to be dimmed using a :doc:`/components/light/monochromatic` with a :doc:`/components/output/ledc`. |
| 166 | + |
| 167 | +Touchscreens |
| 168 | +------------ |
| 169 | + |
| 170 | +A touchscreen, if present, must be configured separately. See the :doc:`/components/touchscreen/index` documentation for more information. |
| 171 | + |
| 172 | +See Also |
| 173 | +-------- |
| 174 | + |
| 175 | +- :doc:`index` |
| 176 | +- :doc:`/components/lvgl/index` |
| 177 | +- :apiref:`mipi_dsi/mipi_dsi.h` |
| 178 | +- :ghedit:`Edit` |
0 commit comments