feat(example): add docs for PlatformIO

Author: Lzw655

CHANGELOG.md

@@ -7,6 +7,7 @@
 * feat(board): add add new board M5CORE2 by @MacChu0315-Espressif (#40)
 * feat(board): add add new board M5DIAL by @MacChu0315-Espressif (#41)
 * feat(board): add add new board M5CORES3 by @MacChu0315-Espressif (#45)
+* feat(example): add support for PlatformIO by @isthaison (#37)
 
 ### Bugfixes:
 

README.md

@@ -24,11 +24,13 @@ ESP32_Display_Panel encapsulates various components from the [Espressif Componen
       - [Using Supported Development Boards](#using-supported-development-boards)
       - [Using Custom Development Boards](#using-custom-development-boards)
     - [Usage Examples](#usage-examples)
-      - [LCD](#lcd)
-      - [Touch](#touch)
-      - [Panel](#panel)
-      - [LVGL v8](#lvgl-v8)
-      - [SquareLine](#squareline)
+      - [Arduino IDE](#arduino-ide)
+        - [LCD](#lcd)
+        - [Touch](#touch)
+        - [Panel](#panel)
+        - [LVGL v8](#lvgl-v8)
+        - [SquareLine](#squareline)
+      - [PlatformIO](#platformio)
   - [Other Relevant Instructions](#other-relevant-instructions)
     - [Configuring Supported Development Boards](#configuring-supported-development-boards)
     - [Configuring LVGL](#configuring-lvgl)
@@ -38,6 +40,7 @@ ESP32_Display_Panel encapsulates various components from the [Espressif Componen
     - [How to Install ESP32\_Display\_Panel in Arduino IDE?](#how-to-install-esp32_display_panel-in-arduino-ide)
     - [Where are the installation directory for arduino-esp32 and the SDK located?](#where-are-the-installation-directory-for-arduino-esp32-and-the-sdk-located)
     - [How to fix screen drift issue when driving RGB LCD with ESP32-S3?](#how-to-fix-screen-drift-issue-when-driving-rgb-lcd-with-esp32-s3)
+    - [How to Use ESP32\_Display\_Panel on PlatformIO?](#how-to-use-esp32_display_panel-on-platformio)
 
 ## Overview
 
@@ -256,9 +259,13 @@ Here is a snippet of the modified `ESP_Panel_Board_Custom.h` file:
 
 ### Usage Examples
 
-Below are some examples of using ESP32_Display_Panel. You can access them in the Arduino IDE by navigating to `File` > `Examples` > `ESP32_Display_Panel`. If you cannot find the `ESP32_Display_Panel` option, please check if the library has been installed correctly and ensure that an ESP development board is selected.
+The following are some examples of using ESP32_Display_Panel on different development platforms.
 
-#### LCD
+#### Arduino IDE
+
+You can access them in the Arduino IDE by navigating to `File` > `Examples` > `ESP32_Display_Panel`. If you cannot find the `ESP32_Display_Panel` option, please check if the library has been installed correctly and ensure that an ESP development board is selected.
+
+##### LCD
 
 The following examples demonstrate how to develop different interface and model LCDs using standalone drivers and test them by displaying color bars:
 
@@ -267,33 +274,37 @@ The following examples demonstrate how to develop different interface and model
 * [Single RGB](examples/LCD/RGB/)
 * [3-wire SPI + RGB](examples/LCD/3wireSPI_RGB/)
 
-#### Touch
+##### Touch
 
 The following example demonstrates how to develop touch screens of different interfaces and models using standalone drivers and test them by printing touch point coordinates:
 
 * [I2C](examples/Touch/I2C/)
 * [SPI](examples/Touch/SPI/)
 
-#### Panel
+##### Panel
 
 The following example demonstrates how to develop built-in or custom development boards using the `ESP_Panel` driver:
 
 * [Panel Test](examples/Panel/PanelTest/): This example tests by displaying color bars and printing touch point coordinates.
 
-#### LVGL v8
+##### LVGL v8
 
 For configuring LVGL (v8.3.x), please refer to [here](#configuring-lvgl) for more detailed information.
 
 * [Porting](examples/LVGL/v8/Porting/): This example demonstrates how to port LVGL (v8.3.x). And for RGB LCD, it can enable the avoid tearing fucntion.
 * [Rotation](examples/LVGL/v8/Rotation/): This example demonstrates how to use LVGL to rotate the display.
 
-#### SquareLine
+##### SquareLine
 
 To port the SquareLine project (v1.3.x), please refer to [here](#porting-squareline-project) for more detailed information.
 
 - [Porting](examples/SquareLine/v8/Porting/): This example demonstrates how to port the SquareLine project.
 - [WiFiClock](examples/SquareLine/v8/WiFiClock/): This example implements a simple Wi-Fi clock and can display weather information.
 
+#### PlatformIO
+
+- [PlatformIO](examples/PlatformIO/): This example demonstrates how to use ESP32_Display_Panel in PlatformIO. By default, it is suitable for the **ESP32-S3-LCD-EV-Board** and **ESP32-S3-LCD-EV-Board-2** development boards. Users need to modify the [boards/ESP-LCD.json](examples/PlatformIO/boards/ESP-LCD.json) file according to the actual situation.
+
 ## Other Relevant Instructions
 
 ### Configuring Supported Development Boards
@@ -446,3 +457,7 @@ When encountering screen drift issue when driving RGB LCD with ESP32-S3, you can
     lcd_bus->begin();
     ...
     ```
+
+### How to Use ESP32_Display_Panel on PlatformIO?
+
+You can refer to the example [PlatformIO](examples/PlatformIO/) to use the ESP32_Display_Panel library in PlatformIO. By default, it is suitable for the **ESP32-S3-LCD-EV-Board** and **ESP32-S3-LCD-EV-Board-2** development boards. You need to modify the [boards/ESP-LCD.json](examples/PlatformIO/boards/ESP-LCD.json) file according to the actual situation.

README_CN.md

@@ -24,11 +24,13 @@ ESP32_Display_Panel 封装了多种[乐鑫组件库](https://components.espressi
       - [使用支持的开发板](#使用支持的开发板)
       - [使用自定义开发板](#使用自定义开发板)
     - [示例说明](#示例说明)
-      - [LCD](#lcd)
-      - [Touch](#touch)
-      - [Panel](#panel)
-      - [LVGL v8](#lvgl-v8)
-      - [SquareLine](#squareline)
+      - [Arduino IDE](#arduino-ide)
+        - [LCD](#lcd)
+        - [Touch](#touch)
+        - [Panel](#panel)
+        - [LVGL v8](#lvgl-v8)
+        - [SquareLine](#squareline)
+      - [PlatformIO](#platformio)
   - [其他相关说明](#其他相关说明)
     - [配置支持的开发板](#配置支持的开发板)
     - [配置 LVGL](#配置-lvgl)
@@ -38,6 +40,7 @@ ESP32_Display_Panel 封装了多种[乐鑫组件库](https://components.espressi
     - [如何在 Arduino IDE 中安装 ESP32\_Display\_Panel？](#如何在-arduino-ide-中安装-esp32_display_panel)
     - [arduino-eps32 的安装目录以及 SDK 的目录在哪儿？](#arduino-eps32-的安装目录以及-sdk-的目录在哪儿)
     - [使用 ESP32-S3 驱动 RGB LCD 时出现画面漂移问题的解决方案](#使用-esp32-s3-驱动-rgb-lcd-时出现画面漂移问题的解决方案)
+    - [如何在 PlatformIO 上使用 ESP32\_Display\_Panel？](#如何在-platformio-上使用-esp32_display_panel)
 
 ## 概述
 
@@ -256,9 +259,13 @@ ESP32_Display_Panel 会根据 [ESP_Panel_Board_Custom.h](./ESP_Panel_Board_Custo
 
 ### 示例说明
 
-以下是使用 ESP32_Display_Panel 的一些示例，你可以在 Arduino IDE 中导航到 `File` > `Examples` > `ESP32_Display_Panel` 来访问它们。如果你找不到 `ESP32_Display_Panel` 选项，请检查库是否已正确安装，并确认选择了一个 ESP 开发板。
+以下是在不同开发平台下使用 ESP32_Display_Panel 的一些示例。
 
-#### LCD
+#### Arduino IDE
+
+你可以在 Arduino IDE 中导航到 `File` > `Examples` > `ESP32_Display_Panel` 来访问它们。如果你找不到 `ESP32_Display_Panel` 选项，请检查库是否已正确安装，并确认选择了一个 ESP 开发板。
+
+##### LCD
 
 以下示例演示了如何使用独立的驱动开发不同接口和不同型号的 LCD，并通过显示彩条进行测试：
 
@@ -267,33 +274,37 @@ ESP32_Display_Panel 会根据 [ESP_Panel_Board_Custom.h](./ESP_Panel_Board_Custo
 * [Single RGB](examples/LCD/RGB/)
 * [3-wire SPI + RGB](examples/LCD/3wireSPI_RGB/)
 
-#### Touch
+##### Touch
 
 以下示例演示了如何使用独立的驱动开发不同接口和不同型号的触摸屏，并通过打印触摸点坐标进行测试：
 
 * [I2C](examples/Touch/I2C/)
 * [SPI](examples/Touch/SPI/)
 
-#### Panel
+##### Panel
 
 以下示例演示了如何使用 `ESP_Panel` 驱动开发内置或自定义的开发板：
 
 * [Panel Test](examples/Panel/PanelTest/)：此示例通过显示彩条和打印触摸点坐标进行测试。
 
-#### LVGL v8
+##### LVGL v8
 
 关于如何配置 LVGL（v8.3.x），请参阅[此处](#配置-lvgl)以获取更多详细信息。
 
 * [Porting](examples/LVGL/v8/Porting/): 此示例演示了如何移植 LVGL（v8.3.x）。对于 RGB LCD，它还可以启用防撕裂功能。
 * [Rotation](examples/LVGL/v8/Rotation/): 此示例演示了如何使用 LVGL 来旋转显示屏。
 
-#### SquareLine
+##### SquareLine
 
 ​	要移植 Squarelina 项目（v1.3.x），请参阅[此处](#移植-SquareLine-工程)获取更多详细信息。
 
 - [Porting](examples/SquareLine/v8/Porting): 此示例演示了如何移植 SquareLine 项目。
 - [WiFiClock](examples/SquareLine/v8/WiFiClock): 此示例实现了一个简单的 Wi-Fi 时钟，并且可以显示天气信息。
 
+#### PlatformIO
+
+- [PlatformIO](examples/PlatformIO/): 此示例演示了如何在 PlatformIO 中使用 ESP32_Display_Panel。它默认情况下适用于 **ESP32-S3-LCD-EV-Board** and **ESP32-S3-LCD-EV-Board-2** 开发板，用户需要根据实际情况修改 [boards/ESP-LCD.json](examples/PlatformIO/boards/ESP-LCD.json) 文件。
+
 ## 其他相关说明
 
 ### 配置支持的开发板
@@ -446,3 +457,7 @@ arduino-esp32 v3.x.x 版本的 SDK 位于默认安装路径下的 `tools > esp32
     lcd_bus->begin();
     ...
     ```
+
+### 如何在 PlatformIO 上使用 ESP32_Display_Panel？
+
+您可以参考示例 [PlatformIO](examples/PlatformIO/) 在 PlatformIO 中使用 ESP32_Display_Panel 库，它默认情况下适用于 **ESP32-S3-LCD-EV-Board** and **ESP32-S3-LCD-EV-Board-2** 开发板，您需要根据实际情况修改 [boards/ESP-LCD.json](examples/PlatformIO/boards/ESP-LCD.json) 文件。

examples/platformio/.gitignore renamed to examples/PlatformIO/.gitignore

@@ -0,0 +1,41 @@
+# PlatformIO Example
+
+The example is used to guide how to use this library in PlatformIO. It also demonstrates how to port LVGL (v8.3.x). And for RGB LCD, it can enable the avoid tearing fucntion.
+
+It is by default suitable for **ESP32-S3-LCD-EV-Board** and **ESP32-S3-LCD-EV-Board-2** boards. Users should modify the [boards/ESP-LCD.json](boards/ESP-LCD.json) file as needed.
+
+## How to Use
+
+Follow the steps below to configure:
+
+1. For **ESP32_Display_Panel**:
+
+    - Follow the [steps](../../README.md#configuring-drivers) to configure drivers if needed.
+    - If using a supported development board, follow the [steps](../../README.md#using-supported-development-boards) to configure it.
+    - If using a custom board, follow the [steps](../../README.md#using-custom-development-boards) to configure it.
+
+2. For **lvgl**:
+
+    - Follow the [steps](../../README.md#configuring-lvgl) to add *lv_conf.h* file and change the configurations.
+    - Modify the macros in the [lvgl_port_v8.h](./lvgl_port_v8.h) file to configure the LVGL porting parameters.
+
+3. Navigate to the `Tools` menu in the Arduino IDE to choose a ESP board and configure its parameters. For supported boards, please refter to [Configuring Supported Development Boards](../../README.md#configuring-supported-development-boards)
+4. Verify and upload the example to your ESP board.
+
+## Serial Output
+
+```bash
+...
+LVGL porting example start
+Initialize panel device
+Initialize LVGL
+Create UI
+LVGL porting example end
+IDLE loop
+IDLE loop
+...
+```
+
+## Troubleshooting
+
+Please check the [FAQ](../../README.md#faq) first to see if the same question exists. If not, please create a [Github issue](https://github.com/esp-arduino-libs/ESP32_Display_Panel/issues). We will get back to you as soon as possible.

examples/PlatformIO/README.md

@@ -26,7 +26,7 @@
       "openocd_target": "esp32s3.cfg"
     },
     "frameworks": ["arduino", "espidf"],
-    "name": "ESP-LCD (16M Flash 8M OPI PSRAM )",
+    "name": "ESP-LCD (16M QIO Flash & OPI PSRAM)",
     "upload": {
       "flash_size": "16MB",
       "maximum_ram_size": 327680,

examples/platformio/boards/ESP-LCD.json renamed to examples/PlatformIO/boards/ESP-LCD.json

@@ -2,20 +2,20 @@
 platform = espressif32
 board = ESP-LCD
 framework = arduino
-platform_packages = 
+platform_packages =
 	platformio/framework-arduinoespressif32@https://github.com/espressif/arduino-esp32.git
 	platformio/framework-arduinoespressif32-libs@https://github.com/espressif/esp32-arduino-libs.git#idf-release/v5.1
 upload_speed = 921600
 monitor_speed = 115200
-build_flags = 
+build_flags =
 	-DBOARD_HAS_PSRAM
 	-DLV_CONF_INCLUDE_SIMPLE
 	-DDISABLE_ALL_LIBRARY_WARNINGS
 	-DARDUINO_USB_CDC_ON_BOOT=1
 	-DCORE_DEBUG_LEVEL=1
 	-DLV_LVGL_H_INCLUDE_SIMPLE
 	-I src
-lib_deps = 
+lib_deps =
 	https://github.com/esp-arduino-libs/ESP32_Display_Panel.git
 	https://github.com/esp-arduino-libs/ESP32_IO_Expander.git
     https://github.com/lvgl/lvgl.git#release/v8.3

examples/platformio/platformio.ini renamed to examples/PlatformIO/platformio.ini

@@ -214,7 +214,7 @@
  *      - CST816S
  *      - FT5x06
  *      - GT911, GT1151
- *      - ST7123
+ *      - ST1633, ST7123
  *      - TT21100
  *      - XPT2046
  */
@@ -362,7 +362,7 @@
  */
 #define ESP_PANEL_BOARD_CUSTOM_FILE_VERSION_MAJOR 0
 #define ESP_PANEL_BOARD_CUSTOM_FILE_VERSION_MINOR 1
-#define ESP_PANEL_BOARD_CUSTOM_FILE_VERSION_PATCH 0
+#define ESP_PANEL_BOARD_CUSTOM_FILE_VERSION_PATCH 1
 
 #endif /* ESP_PANEL_USE_CUSTOM_BOARD */
 

examples/platformio/src/ESP_Panel_Board_Custom.h renamed to examples/PlatformIO/src/ESP_Panel_Board_Custom.h

@@ -46,6 +46,17 @@
 // #define BOARD_ESP32_S3_LCD_EV_BOARD_2_V1_5
 // #define BOARD_ESP32_S3_USB_OTG
 
+/*
+ * M5Stack (https://m5stack.com/):
+ *
+ *  - M5STACK_M5CORE2: https://docs.m5stack.com/zh_CN/core/core2
+ *  - M5STACK_M5DIAL: https://docs.m5stack.com/zh_CN/core/M5Dial
+ *  - M5STACK_M5CORES3: https://docs.m5stack.com/zh_CN/core/CoreS3
+ */
+// #define BOARD_M5STACK_M5CORE2
+// #define BOARD_M5STACK_M5DIAL
+// #define BOARD_M5STACK_M5CORES3
+
 /*
  * Shenzhen Jingcai Intelligent Supported Boards (https://www.displaysmodule.com/):
  *
@@ -68,7 +79,7 @@
  *
  */
 #define ESP_PANEL_BOARD_SUPPORTED_FILE_VERSION_MAJOR 0
-#define ESP_PANEL_BOARD_SUPPORTED_FILE_VERSION_MINOR 1
+#define ESP_PANEL_BOARD_SUPPORTED_FILE_VERSION_MINOR 2
 #define ESP_PANEL_BOARD_SUPPORTED_FILE_VERSION_PATCH 0
 
 #endif

examples/platformio/src/ESP_Panel_Board_Supported.h renamed to examples/PlatformIO/src/ESP_Panel_Board_Supported.h

@@ -0,0 +1,77 @@
+/*
+ * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////// Debug Configurations /////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/* Set to 1 if assert on error. Otherwise print error message */
+#define ESP_PANEL_CHECK_RESULT_ASSERT       (0)         // 0/1
+
+/* Set to 1 if print log message for debug */
+#define ESP_PANEL_ENABLE_LOG                (0)         // 0/1
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////// Touch Driver Configurations //////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/* Maximum point number */
+#define ESP_PANEL_TOUCH_MAX_POINTS          (5)
+/* Maximum button number */
+#define ESP_PANEL_TOUCH_MAX_BUTTONS         (1)
+
+/**
+ * XPT2046 related
+ *
+ */
+#define ESP_PANEL_TOUCH_XPT2046_Z_THRESHOLD             (400)   // Minimum Z pressure threshold
+/**
+ * Enable Interrupt (PENIRQ) output, also called Full Power Mode.
+ * Enable this to configure the XPT2046 to output low on the PENIRQ output if a touch is detected.
+ * This mode uses more power when enabled. Note that this signal goes low normally when a read is active.
+ */
+#define ESP_PANEL_TOUCH_XPT2046_INTERRUPT_MODE          (0)     // 0/1
+/**
+ * Keep internal Vref enabled.
+ * Enable this to keep the internal Vref enabled between conversions. This uses slightly more power,
+ * but requires fewer transactions when reading the battery voltage, aux voltage and temperature.
+ *
+ */
+#define ESP_PANEL_TOUCH_XPT2046_VREF_ON_MODE            (0)     // 0/1
+/**
+ * Convert touch coordinates to screen coordinates.
+ * When this option is enabled the raw ADC values will be converted from 0-4096 to 0-{screen width} or 0-{screen height}.
+ * When this option is disabled the process_coordinates method will need to be used to convert the raw ADC values into a
+ * screen coordinate.
+ *
+ */
+#define ESP_PANEL_TOUCH_XPT2046_CONVERT_ADC_TO_COORDS   (1)     // 0/1
+/**
+ * Enable data structure locking.
+ * By enabling this option the XPT2046 driver will lock the touch position data structures when reading values from the
+ * XPT2046 and when reading position data via API.
+ * WARNING: enabling this option may result in unintended crashes.
+ *
+ */
+#define ESP_PANEL_TOUCH_XPT2046_ENABLE_LOCKING          (0)     // 0/1
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/////////////////////////////////////////////// File Version ///////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * Do not change the following versions, they are used to check if the configurations in this file are compatible with
+ * the current version of `ESP_Panel_Board_Custom.h` in the library. The detailed rules are as follows:
+ *
+ *   1. If the major version is not consistent, then the configurations in this file are incompatible with the library
+ *      and must be replaced with the file from the library.
+ *   2. If the minor version is not consistent, this file might be missing some new configurations, which will be set to
+ *      default values. It is recommended to replace it with the file from the library.
+ *   3. Even if the patch version is not consistent, it will not affect normal functionality.
+ *
+ */
+#define ESP_PANEL_CONF_FILE_VERSION_MAJOR 0
+#define ESP_PANEL_CONF_FILE_VERSION_MINOR 1
+#define ESP_PANEL_CONF_FILE_VERSION_PATCH 1