Merge branch 'feature/lcd_modify_documentation' into 'master'

docs(lcd): Modify the LCD user guide

Closes AEG-972

See merge request ae_group/esp-iot-solution!925

docs/en/display/lcd/lcd_development_guide.rst

@@ -66,20 +66,60 @@ Espressif Systems provides comprehensive support for all interface types introdu
 Driver and Examples
 ---------------------
 
-**LCD Peripheral Driver** is located in `components/esp_lcd <https://github.com/espressif/esp-idf/tree/master/components/esp_lcd>`_ directory under **ESP-IDF**. Currently, it supports the following interfaces ``I2C``, ``SPI(QSPI)``, ``I80`` as well as ``RGB``. For detailed information, please refer to the `documentation <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/lcd.html>`_. The following is the official Espressif system **LCD Driver component** based on ``esp_lcd``.
+**LCD Peripheral** Driver is located in the `components/esp_lcd <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/lcd.html>_` directory under **ESP-IDF**. Currently, it supports the ``I2C``, ``SPI (QSPI)``, ``I80``, and ``RGB`` interfaces. The following table lists the LCD driver components officially ported by Espressif based on esp_lcd, and these components will continue to be updated:
+
+.. list-table::
+    :widths: 10 15
+    :header-rows: 1
+
+    * - LCD Controller
+      - Interface
+    * - `st7789 <https://github.com/espressif/esp-idf/blob/master/components/esp_lcd/src/esp_lcd_panel_st7789.c>`_
+      - SPI/I80
+    * - `nt35510 <https://github.com/espressif/esp-idf/blob/master/components/esp_lcd/src/esp_lcd_panel_nt35510.c>`_
+      - SPI/I80
+    * - `ssd1306 <https://github.com/espressif/esp-idf/blob/master/components/esp_lcd/src/esp_lcd_panel_ssd1306.c>`_
+      - I2C
+    * - `gc9b71 <https://github.com/espressif/esp-iot-solution/tree/master/components/display/lcd/esp_lcd_gc9b71>`_
+      - SPI/QSPI
+    * - `nv3022b <https://github.com/espressif/esp-iot-solution/tree/master/components/display/lcd/esp_lcd_nv3022b>`_
+      - SPI
+    * - `sh8601 <https://github.com/espressif/esp-iot-solution/tree/master/components/display/lcd/esp_lcd_sh8601>`_
+      - SPI/QSPI
+    * - `spd2010 <https://github.com/espressif/esp-iot-solution/tree/master/components/display/lcd/esp_lcd_spd2010>`_
+      - SPI/QSPI
+    * - `st7701 <https://github.com/espressif/esp-iot-solution/tree/master/components/display/lcd/esp_lcd_st7701>`_
+      - 3-wire SPI + RGB
+    * - `st77916 <https://github.com/espressif/esp-iot-solution/tree/master/components/display/lcd/esp_lcd_st77916>`_
+      - SPI/QSPI
+    * - `gc9503 <https://github.com/espressif/esp-bsp/tree/master/components/lcd/esp_lcd_gc9503>`_
+      - 3-wire SPI + RGB
+    * - `gc9a01 <https://github.com/espressif/esp-bsp/tree/master/components/lcd/esp_lcd_gc9a01>`_
+      - SPI
+    * - `ili9341 <https://github.com/espressif/esp-bsp/tree/master/components/lcd/esp_lcd_ili9341>`_
+      - SPI
+    * - `ra8875 <https://github.com/espressif/esp-bsp/tree/master/components/lcd/esp_lcd_ra8875>`_
+      - Parallel Intel 8080
+    * - `sh1107 <https://github.com/espressif/esp-bsp/tree/master/components/lcd/esp_lcd_sh1107>`_
+      - I2C
+    * - `ssd1681 <https://github.com/espressif/esp-bsp/tree/master/components/lcd/esp_lcd_ssd1681>`_
+      - SPI
+    * - `st7796 <https://github.com/espressif/esp-bsp/tree/master/components/lcd/esp_lcd_st7796>`_
+      - SPI/I80
+
+**Please note:**
 
 .. _LCD_Driver_Component:
 
-  - `ESP-IDF <https://github.com/espressif/esp-idf/tree/master/components/esp_lcd/src>`_ : st7789、nt35510、ssd1306。
-  - `ESP component manager <https://components.espressif.com/components?q=espressif%2Fesp_lcd>`_ : gc9a01、ili9341、ra8875、sh1107、st7796、st7701、gc9503、gc9b71、spd2010、...(continuously updated)
+  - The **st7789**, **nt35510**, and **ssd1306** components are maintained in the `ESP-IDF <https://github.com/espressif/esp-idf/tree/master/components/esp_lcd/src>`_. Other components can be found in the `Espressif IDF Component Registry <https://components.espressif.com/components?q=espressif%2Fesp_lcd>`_.
+  - Although the models of the **LCD driver IC** might be identical, **different screens** require specific configurations through initialization commands provided by their respective manufacturers. Most driver components support the customization of initialization commands during the initialization of the LCD device. If it is not supported, please refer to the `method <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/lcd.html#steps-to-add-manufacture-specific-initialization>`_.
 
-**LCD Example** is located in the `examples/peripherals/lcd <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/lcd>`_ directory under **ESP-IDF** and the :project:`examples/display/lcd <examples/display/lcd>` directory under **esp-iot-solution**.
+**LCD Example** is located in the `examples/peripherals/lcd <https://github.com/espressif/esp-idf/tree/master/examples/peripherals/lcd>`_ directory under **ESP-IDF** and the :project:`examples/display/lcd <examples/display/lcd>` directory under **esp-iot-solution**. These serve as a reference for the usage of the LCD driver component.
 
 .. note::
 
     - It is recommended to develop based on ESP-IDF `release/v5.1 <https://github.com/espressif/esp-idf/tree/release/v5.1>`_ and above version branches, because lower versions may lack to support some parts of the important new features, especially for the ``RGB`` interface.
     - For LCDs using the ``3-wire SPI + RGB`` interface, please refer to the example `esp_lcd_st7701 - Example use <https://components.espressif.com/components/espressif/esp_lcd_st7701>`_.
-    - Even if the LCD driver IC is of the same model, different screens often need to be configured using the initialization commands provided by their respective manufacturers. Most driver components support after giving custom initialization commands when initializing the LCD device. if not, please refer to `method <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/lcd.html#steps-to-add-manufacture-specific-initialization>`_.
 
 Development Framework
 -------------------------

docs/en/display/lcd/lcd_guide.rst

@@ -214,7 +214,7 @@ Typical Connection Methods
 For the common LCD pins, the typical connection method is as follows:
 
 - **RST (RESET)**: It is recommended to connect to a GPIO pin and according to the LCD driver IC's datasheet, generate a reset timing sequence during power-on. In general, pull-up/pull-down resistors can also be used connected to the system power.
-- **Backlight (LEDA、LEDK)**: It is recommended to connect LEDA to the system power supply, and LEDK should be connected to the system power supply using switching devices. Control the on/off state through GPIO or use the LEDC peripheral to output PWM to adjust the backlight brightness.
+- **Backlight (LEDA、LEDK)**: It is recommended to connect LEDA(Anode) to the system power supply, and LEDK(Cathode) should be connected to the system power supply using switching devices. Control the on/off state through GPIO or use the LEDC peripheral to output PWM to adjust the backlight brightness.
 - **TE (Tear Effect)**: Recommend connecting to GPIO and using GPIO interrupts to obtain the TE signal for achieving frame synchronization.
 - **Power(VCC、GND)**: It is recommended to connect all to the corresponding system power sources and avoid leaving any pins floating.
 

docs/en/display/lcd/rgb_lcd.rst

@@ -37,6 +37,8 @@ The following diagram depicts the pin descriptions for the *ST7701S* ``SPI`` and
 
     Pin Description for ST7701S RGB Interface
 
+Note: RGB pin names: CS, SCK (SCL), SDA (MOSI), HSYNC, VSYNC, PCLK, DE, D[23:0] (D[17:0]/D[7:0]).
+
 For LCDs using the ``SPI + RGB`` interfaces, you can typically configure the ``RGB`` interface to operate in either ``DE mode`` or ``SYNC mode`` through commands. The following section illustrates these two modes using *ST7701S* as an example.
 
 Mode Selection
@@ -129,14 +131,17 @@ From the above diagrams, it can be observed that *ST77903* supports three color
 
     Although ESP32-S3 only supports ``16-bit RGB565`` and ``8-bit RGB888`` color formats, it can be configured to drive LCDs with ``18-bit RGB666`` or ``24-bit RGB888`` color formats through special hardware connections. For the connection details, please refer to the development board `ESP32-S3-LCD-EV-Board <https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32s3/esp32-s3-lcd-ev-board/index.html>`_ and its `LCD Subboard 2 <https://docs.espressif.com/projects/esp-dev-kits/en/latest/_static/esp32-s3-lcd-ev-board/schematics/SCH_ESP32-S3-LCD-EV-Board-SUB2_V1.2_20230509.pdf>`_ (3.95' LCD_QMZX) and `LCD Subboard 3 <https://docs.espressif.com/projects/esp-dev-kits/en/latest/_static/esp32-s3-lcd-ev-board/schematics/SCH_ESP32-S3-LCD-EV-Board-SUB3_V1.1_20230315.pdf>`_ schematics.
 
+RGB LCD Driver Process
+------------------------------
+
+The RGB LCD driver process can be roughly divided into three parts: initializing interface devices, porting driver components, and initializing the LCD device.
+
 .. _rgb_init_interface_device:
 
 Initialization of Interface Devices
 ----------------------------------------
 
-**For LCDs using only the RGB interface**, as they do not support the transmission of commands and parameters, there is no need to initialize an interface device. Please refer directly to :ref:`Initializing the LCD device <rgb_initialize_lcd>`.
-
-**For LCDs using both the 3-wire SPI and RGB interfaces**, only the creation of the ``3-wire SPI`` interface device is required. Since ESP's SPI peripheral does not directly support the transmission of 9-bit data, and this interface is only used for transmitting commands and parameters with a small data volume, and the bandwidth and timing requirements for data transmission are not high, GPIO or IO expander chip pins (such as `TCA9554 <https://components.espressif.com/components/espressif/esp_io_expander_tca9554>`_) can be used to simulate the SPI protocol through software. The following is an example code using the `esp_lcd_panel_io_additions <https://components.espressif.com/components/espressif/esp_lcd_panel_io_additions>`_ component to create a ``3-wire SPI`` interface device:
+Here is the code explanation for creating a 3-wire SPI interface device using the  `esp_lcd_panel_io_additions <https://components.espressif.com/components/espressif/esp_lcd_panel_io_additions>`_ component:
 
 .. code-block:: c
 
@@ -170,6 +175,10 @@ Initialization of Interface Devices
     esp_lcd_panel_io_handle_t io_handle = NULL;
     ESP_ERROR_CHECK(esp_lcd_new_panel_io_3wire_spi(&io_config, &io_handle));
 
+**For LCDs that only use the RGB interface**, as they do not support the transmission of commands and parameters, there is no need to initialize an interface device. Please refer directly to :ref:`Initializing the LCD device <rgb_initialize_lcd>`.
+
+**For LCDs using both the 3-wire SPI and RGB interface**, only the creation of the ``3-wire SPI`` interface device is required. Since ESP's SPI peripheral does not directly support the transmission of 9-bit data, and this interface is only used for transmitting commands and parameters with a small data volume, and the bandwidth and timing requirements for data transmission are not high, GPIO or IO expander chip pins (such as `TCA9554 <https://components.espressif.com/components/espressif/esp_io_expander_tca9554>`_) can be used to simulate the SPI protocol through software. The following is an example code using the `esp_lcd_panel_io_additions <https://components.espressif.com/components/espressif/esp_lcd_panel_io_additions>`_ component to create a ``3-wire SPI`` interface device:
+
 Creating the interface device provides a handle of data type ``esp_lcd_panel_io_handle_t``. Subsequently, you can use ``esp_lcd_panel_io_tx_param()`` to send **commands** to the LCD driver IC.
 
 .. _rgb_porting_driver_components:
@@ -179,7 +188,7 @@ Porting Driver Components
 
 **For LCDs using only the RGB interface**, the `RGB interface driver <https://github.com/espressif/esp-idf/blob/release/v5.1/components/esp_lcd/src/esp_lcd_panel_rgb.c>`_ already implements the functionalities specified in the `esp_lcd_panel_t <https://github.com/espressif/esp-idf/blob/release/v5.1/components/esp_lcd/interface/esp_lcd_panel_interface.h>`_ structure through registered callback functions. Additionally, it provides the function ``esp_lcd_new_rgb_panel()`` to create an LCD device with the data type ``esp_lcd_panel_handle_t``, allowing the application to use the `LCD Generic APIs <https://github.com/espressif/esp-idf/blob/release/v5.1/components/esp_lcd/include/esp_lcd_panel_ops.h>`_ to operate the LCD device. Therefore, no driver component porting is needed for this type of LCD; please refer directly to :ref:`Initializing the LCD device <rgb_initialize_lcd>`.
 
-**For LCDs using both the 3-wire SPI and RGB interfaces**, in addition to the `RGB interface driver <https://github.com/espressif/esp-idf/blob/release/v5.1/components/esp_lcd/src/esp_lcd_panel_rgb.c>`_, you also need to send commands and parameters through the ``3-wire SPI`` interface. The basic principles for implementing this LCD driver component include the following three points:
+**For LCDs using both the 3-wire SPI and RGB interface**, in addition to the `RGB interface driver <https://github.com/espressif/esp-idf/blob/release/v5.1/components/esp_lcd/src/esp_lcd_panel_rgb.c>`_, you also need to send commands and parameters through the ``3-wire SPI`` interface. The basic principles for implementing this LCD driver component include the following three points:
 
   #. Send commands and parameters in the specified format through the interface device with data type ``esp_lcd_panel_io_handle_t``.
   #. Create an LCD device using the function ``esp_lcd_new_rgb_panel()``, then use the registered callback functions to **save and override** **some** functionalities in the device.
@@ -234,17 +243,17 @@ Here is the explanation of the functions implemented for ``esp_lcd_panel_handle_
 
 For the majority of RGB LCDs, the commands and parameters of their driver IC are compatible with the implementation details mentioned above. Therefore, the porting process can be completed using the following steps:
 
-  #. Choose an RGB LCD driver component in the :ref:`LCD Driver Components <LCD_Driver_Component>` that is similar to the model you are working with.
-  #. Refer to the datasheet of the target LCD driver IC to confirm whether its commands and parameters used by various functions in the selected component are consistent. If not, modify the relevant code accordingly.
-  #. Even if the model of the LCD driver IC is the same, screens from different manufacturers often require configuration with their own set of initialization commands. Therefore, modify the commands and parameters sent in the ``init()`` function. These initialization commands are typically stored in a static array in a specific format. Additionally, ensure not to include commands controlled by the driver IC, such as ``LCD_CMD_COLMOD (3Ah)``, in the initialization commands to ensure successful initialization of the LCD device.
-  #. Use the search and replace function in your editor to replace the LCD driver IC name in the component with the target name. For example, replace ``gc9503`` with ``st7701``.
+#. Choose an RGB LCD driver component in the :ref:`LCD Driver Components <LCD_Driver_Component>` that is similar to the model you are working with.
+#. Refer to the datasheet of the target LCD driver IC to confirm whether its commands and parameters used by various functions in the selected component are consistent. If not, modify the relevant code accordingly.
+#. Even if the model of the LCD driver IC is the same, screens from different manufacturers often require configuration with their own set of initialization commands. Therefore, modify the commands and parameters sent in the ``init()`` function. These initialization commands are typically stored in a static array in a specific format. Additionally, ensure not to include commands controlled by the driver IC, such as ``LCD_CMD_COLMOD (3Ah)``, in the initialization commands to ensure successful initialization of the LCD device.
+#. Use the search and replace function in your editor to replace the LCD driver IC name in the component with the target name. For example, replace ``gc9503`` with ``st7701``.
 
 .. _rgb_initialize_lcd:
 
 Initialize LCD Device
 ---------------------------
 
-For LCDs using both 3-wire SPI and RGB interfaces, start by creating an LCD device and obtaining a handle of data type ``esp_lcd_panel_handle_t`` using the ``esp_lcd_new_rgb_panel()`` function from the `RGB Interface Driver <https://github.com/espressif/esp-idf/blob/release/v5.1/components/esp_lcd/src/esp_lcd_panel_rgb.c>`_. Then, use the `LCD General APIs <https://github.com/espressif/esp-idf/blob/release/v5.1/components/esp_lcd/include/esp_lcd_panel_ops.h>`_ to initialize the LCD device. Below is an example code explanation using the `rgb_panel <https://github.com/espressif/esp-idf/tree/release/v5.1/examples/peripherals/lcd/rgb_panel>`_ code from ESP-IDF release/v5.1:
+Below is an example code explanation using the `rgb_panel <https://github.com/espressif/esp-idf/tree/release/v5.1/examples/peripherals/lcd/rgb_panel>`_ code from ESP-IDF release/v5.1:
 
 .. code-block:: c
 
@@ -317,9 +326,11 @@ For LCDs using both 3-wire SPI and RGB interfaces, start by creating an LCD devi
     // ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_handle, true));    // Control the on/off of LCD display through the `disp_gpio_num` pin,
                                                                           // only available when the pin is set and not equal to `-1`, otherwise an error will be reported
 
+For LCDs using both 3-wire SPI and RGB interfaces, start by creating an LCD device and obtaining a handle of data type ``esp_lcd_panel_handle_t`` using the ``esp_lcd_new_rgb_panel()`` function from the `RGB Interface Driver <https://github.com/espressif/esp-idf/blob/release/v5.1/components/esp_lcd/src/esp_lcd_panel_rgb.c>`_. Then, use the `LCD General APIs <https://github.com/espressif/esp-idf/blob/release/v5.1/components/esp_lcd/include/esp_lcd_panel_ops.h>`_ to initialize the LCD device.
+
 For configuration parameters and explanations of certain functions related to the ``RGB`` interface, please refer to :ref:`RGB Configuration Parameters and Function Descriptions <rgb_parameter_configuration_and_functions>`.
 
-For LCDs using both 3-wire SPI and RGB interfaces, start by creating an LCD device using the ported driver component and obtaining a handle of data type ``esp_lcd_panel_handle_t``. Then, use the `LCD General APIs <https://github.com/espressif/esp-idf/blob/release/v5.1/components/esp_lcd/include/esp_lcd_panel_ops.h>`_ to initialize the LCD device. Below is an example code explanation using the `ST7701S <https://components.espressif.com/components/espressif/esp_lcd_st7701>`_ driver component:
+Below is an example code explanation using the `ST7701S <https://components.espressif.com/components/espressif/esp_lcd_st7701>`_ driver component:
 
 .. code-block:: c
 
@@ -426,6 +437,8 @@ For LCDs using both 3-wire SPI and RGB interfaces, start by creating an LCD devi
     // ESP_ERROR_CHECK(esp_lcd_panel_set_gap(panel_handle, 0, 0));
     // ESP_ERROR_CHECK(esp_lcd_panel_disp_on_off(panel_handle, true));
 
+For LCDs using both 3-wire SPI and RGB interfaces, start by creating an LCD device using the ported driver component and obtaining a handle of data type ``esp_lcd_panel_handle_t``. Then, use the `LCD General APIs <https://github.com/espressif/esp-idf/blob/release/v5.1/components/esp_lcd/include/esp_lcd_panel_ops.h>`_ to initialize the LCD device.
+
 .. _rgb_parameter_configuration_and_functions:
 
 For more detailed information on the configuration parameters for the ``RGB`` interface, please refer to the `ESP-IDF Programming Guide <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/lcd.html#rgb-interfaced-lcd>`_. Below are some instructions on using the ``esp_lcd_panel_draw_bitmap()`` function to refresh RGB LCD images: