diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml index 7111ea9..cc477db 100644 --- a/.github/workflows/pre-commit.yml +++ b/.github/workflows/pre-commit.yml @@ -11,4 +11,4 @@ jobs: steps: - uses: actions/checkout@v2 - uses: actions/setup-python@v2 - - uses: pre-commit/action@v2.0.3 + - uses: pre-commit/action@v3.0.1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 535e92e..14c7f5a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # ChangeLog +## v1.0.3 - 2025-04-27 + +### Enhancements: + +* feat(docs): provides an example of how to integrate this library into micropython by @tsteinruecken (#190) + ## v1.0.2 - 2025-04-23 ### Enhancements: diff --git a/README.md b/README.md index 8b6fb50..1e6defd 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,7 @@ The functional block diagram is shown below: * [ESP-IDF](./docs/envs/use_with_idf.md) * [Arduino IDE](./docs/envs/use_with_arduino.md) * [PlatformIO](./examples/platformio/lvgl_v8_port/README.md) +* [Micropython](./docs/envs/use_with_micropython.md) ## Supported Boards diff --git a/README_CN.md b/README_CN.md index 6a77b5b..08364cf 100644 --- a/README_CN.md +++ b/README_CN.md @@ -45,6 +45,7 @@ ESP32_Display_Panel 的主要特性如下: * [ESP-IDF](./docs/envs/use_with_idf_cn.md) * [Arduino IDE](./docs/envs/use_with_arduino_cn.md) * [PlatformIO](./examples/platformio/lvgl_v8_port/README.md) +* [Micropython](./docs/envs/use_with_micropython_cn.md) ## 支持的开发板 diff --git a/docs/envs/use_with_micropython.md b/docs/envs/use_with_micropython.md new file mode 100644 index 0000000..eaa64d2 --- /dev/null +++ b/docs/envs/use_with_micropython.md @@ -0,0 +1,193 @@ +# Using with micropython + +This is an example of how to integrate this library into micropython. It's written for an ESP32-S3, however it should be easy to adapt to different supported ESP-Chips. Please note, that you'll need at least 4mb of flash. + +## Step-by-Step instructions + +1. Install IDF and micropython + + ```bash + mkdir ~/esp32build + pushd ~/esp32build + git clone -b v5.2.2 --recursive https://github.com/espressif/esp-idf.git + pushd esp-idf + ./install.sh esp32 + source export.sh + popd + git clone https://github.com/micropython/micropython.git + pushd micropython + git submodule update --init --recursive + pushd mpy-cross + make + popd + ``` + +2. Ensure, you can build a working firmware + + ```bash + make BOARD=ESP32_GENERIC_S3 BOARD_VARIANT=SPIRAM_OCT -C ports/esp32 + pushd ports/esp32 + python -m esptool --port /dev/ttyACM0 --chip esp32s3 -b 460800 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size 4MB --flash_freq 80m 0x0 build-ESP32_GENERIC_S3-SPIRAM_OCT/bootloader/bootloader.bin 0x8000 build-ESP32_GENERIC_S3-SPIRAM_OCT/partition_table/partition-table.bin 0x10000 build-ESP32_GENERIC_S3-SPIRAM_OCT/micropython.bin + popd + popd + ``` + Now, test the board and ensure your build of micropython works. + +3. Download ESP32_Display_Panel and it's dependencies + + ```bash + git clone https://github.com/esp-arduino-libs/ESP32_Display_Panel.git + git clone https://github.com/esp-arduino-libs/esp-lib-utils.git + git clone https://github.com/esp-arduino-libs/ESP32_IO_Expander.git + ``` + +4. Create a custom user-module definition + + ```bash + cat > micropython.cmake << EOF + include(~/esp32build/ESP32_Display_Panel/micropython.cmake) + include(~/esp32build/esp-lib-utils/micropython.cmake) + include(~/esp32build/ESP32_IO_Expander/micropython.cmake) + EOF + ``` + +5. Copy some header-files + + ```bash + cp esp-idf/components/esp_lcd/include/esp_lcd_panel_commands.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/interface/esp_lcd_panel_interface.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/include/esp_lcd_panel_io.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/interface/esp_lcd_panel_io_interface.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/include/esp_lcd_panel_ops.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/include/esp_lcd_panel_rgb.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/include/esp_lcd_panel_vendor.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/include/esp_lcd_types.h ESP32_Display_Panel/mpy_support/ + ``` + +6. Rebuild micropython to include the new modules + + ```bash + pushd micropython + make BOARD=ESP32_GENERIC_S3 BOARD_VARIANT=SPIRAM_OCT USER_C_MODULES=~/esp32build/micropython.cmake -C ports/esp32 + pushd ports/esp32 + python -m esptool --port /dev/ttyACM0 --chip esp32s3 -b 460800 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size 4MB --flash_freq 80m 0x0 build-ESP32_GENERIC_S3-SPIRAM_OCT/bootloader/bootloader.bin 0x8000 build-ESP32_GENERIC_S3-SPIRAM_OCT/partition_table/partition-table.bin 0x10000 build-ESP32_GENERIC_S3-SPIRAM_OCT/micropython.bin + popd + popd + ``` + + This may fail if your chip has a small flash size, in this case you have to increase the size of the application partition. E.g. for a 4mb flash chip edit *micropython/ports/esp32/partitions-4MiB.csv* and change the last two lines from: + + ```csv + factory, app, factory, 0x10000, 0x1F0000, + vfs, data, fat, 0x200000, 0x200000, + ``` + + to + + ```csv + factory, app, factory, 0x10000, 0x2F0000, + vfs, data, fat, 0x300000, 0x100000, + ``` + +7. Test the module + + Connect to your board and run: + + ```python + from esp_panel import Board + board = Board() + board.init() + ``` + + `board.init()` should return False, as we yet have to define a board. + +8. Define your Board + + Edit *ESP32_Display_Panel/mpy_support/esp_panel_mp_board.cpp*. Add a Board definition: + + ```c++ + const BoardConfig BOARD_EXTERNAL_CONFIG = { + /* General */ + .name = "ESP_PANEL_BOARD_NAME", + .lcd = BoardConfig::LCD_Config{ + .bus_config = esp_panel::drivers::BusSPI::Config{ + .host_id = 1, + // Host + .host = esp_panel::drivers::BusSPI::HostPartialConfig{ + .mosi_io_num = 6, //ESP_PANEL_BOARD_LCD_SPI_IO_MOSI, + .miso_io_num = 8, //ESP_PANEL_BOARD_LCD_SPI_IO_MISO, + .sclk_io_num = 7, //ESP_PANEL_BOARD_LCD_SPI_IO_SCK, + }, + // Control Panel + .control_panel = esp_panel::drivers::BusSPI::ControlPanelPartialConfig{ + .cs_gpio_num = 5, //ESP_PANEL_BOARD_LCD_SPI_IO_CS, + .dc_gpio_num = 4, //ESP_PANEL_BOARD_LCD_SPI_IO_DC, + .spi_mode = 0, //ESP_PANEL_BOARD_LCD_SPI_MODE, + .pclk_hz = 40 * 1000 * 1000, //ESP_PANEL_BOARD_LCD_SPI_CLK_HZ, + .lcd_cmd_bits = 8, //ESP_PANEL_BOARD_LCD_SPI_CMD_BITS, + .lcd_param_bits = 8, //ESP_PANEL_BOARD_LCD_SPI_PARAM_BITS, + }, + }, + .device_name = "ILI9341", + .device_config = { + // Device + .device = esp_panel::drivers::LCD::DevicePartialConfig{ + .reset_gpio_num = 48, //ESP_PANEL_BOARD_LCD_RST_IO, + .rgb_ele_order = 0, //ESP_PANEL_BOARD_LCD_COLOR_BGR_ORDER, + .bits_per_pixel = 18, //ESP_PANEL_BOARD_LCD_COLOR_BITS, 16/18/24 + .flags_reset_active_high = 0, //ESP_PANEL_BOARD_LCD_RST_LEVEL, + }, + // Vendor + .vendor = esp_panel::drivers::LCD::VendorPartialConfig{ + .hor_res = 320, //ESP_PANEL_BOARD_WIDTH, + .ver_res = 480, //ESP_PANEL_BOARD_HEIGHT, + }, + }, + .pre_process = { + .invert_color = 0, //ESP_PANEL_BOARD_LCD_COLOR_INEVRT_BIT, + }, + }, + }; + ``` + + Then replace the constructor + + ```c++ + self->board = utils::make_shared() + ``` + + with + + ```c++ + self->board = utils::make_shared(BOARD_EXTERNAL_CONFIG); + ``` + +9. Edit esp_panel_drivers_conf.h + + Edit *ESP32_Display_Panel/esp_panel_drivers_conf.h* and ensure, the drivers referenced in your board config are being + build. **Warning**: `ESP_PANEL_DRIVERS_BUS_USE_ALL` does not seem to work. Set to 0 and manually include the bus driver + you need. Same goes for `ESP_PANEL_DRIVERS_BUS_COMPILE_UNUSED_DRIVERS`. + +10. Repeat **Step 6** to rebuild micropython + +11. Test your display + + Connect to your board and run: + + ```python + from esp_panel import Board + board = Board() + board.init() + board.begin() + board.color_bar_test() + ``` + +12. Profit! :) + + To include touch support, see *ESP32_Display_Panel/examples/arduino/board/board_dynamic_config/board_external_config.cpp* for an example touch definition. + +## Known Pitfalls + +1. When `board.init()` returns false, likely your driver-definition in *esp_panel_drivers_conf.h* does not match. +2. `board.begin()` crashes, if you rely on `ESP_PANEL_DRIVERS_BUS_USE_ALL` +3. If you edit *ESP32_Display_Panel/esp_panel_drivers_conf.h*, also modify *ESP32_Display_Panel/mpy_support/esp_panel_mp_board.cpp* (like add or remove an empty line). Otherwise, changes to *esp_panel_drivers_conf.h* will not be recognized. diff --git a/docs/envs/use_with_micropython_cn.md b/docs/envs/use_with_micropython_cn.md new file mode 100644 index 0000000..4e476f5 --- /dev/null +++ b/docs/envs/use_with_micropython_cn.md @@ -0,0 +1,193 @@ +# 在 micropython 中使用 + +这是一个如何将此库集成到 micropython 的示例。它是为 ESP32-S3 编写的,但应该很容易适应不同的受支持的 ESP 芯片。请注意,您至少需要 4MB 的闪存。 + +## 逐步说明 + +1. 安装 IDF 和 micropython + + ```bash + mkdir ~/esp32build + pushd ~/esp32build + git clone -b v5.2.2 --recursive https://github.com/espressif/esp-idf.git + pushd esp-idf + ./install.sh esp32 + source export.sh + popd + git clone https://github.com/micropython/micropython.git + pushd micropython + git submodule update --init --recursive + pushd mpy-cross + make + popd + ``` + +2. 确保您可以构建一个可工作的固件 + + ```bash + make BOARD=ESP32_GENERIC_S3 BOARD_VARIANT=SPIRAM_OCT -C ports/esp32 + pushd ports/esp32 + python -m esptool --port /dev/ttyACM0 --chip esp32s3 -b 460800 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size 4MB --flash_freq 80m 0x0 build-ESP32_GENERIC_S3-SPIRAM_OCT/bootloader/bootloader.bin 0x8000 build-ESP32_GENERIC_S3-SPIRAM_OCT/partition_table/partition-table.bin 0x10000 build-ESP32_GENERIC_S3-SPIRAM_OCT/micropython.bin + popd + popd + ``` + 现在,测试开发板并确保您构建的 micropython 可以正常工作。 + +3. 下载 ESP32_Display_Panel 及其依赖项 + + ```bash + git clone https://github.com/esp-arduino-libs/ESP32_Display_Panel.git + git clone https://github.com/esp-arduino-libs/esp-lib-utils.git + git clone https://github.com/esp-arduino-libs/ESP32_IO_Expander.git + ``` + +4. 创建自定义用户模块定义 + + ```bash + cat > micropython.cmake << EOF + include(~/esp32build/ESP32_Display_Panel/micropython.cmake) + include(~/esp32build/esp-lib-utils/micropython.cmake) + include(~/esp32build/ESP32_IO_Expander/micropython.cmake) + EOF + ``` + +5. 复制一些头文件 + + ```bash + cp esp-idf/components/esp_lcd/include/esp_lcd_panel_commands.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/interface/esp_lcd_panel_interface.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/include/esp_lcd_panel_io.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/interface/esp_lcd_panel_io_interface.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/include/esp_lcd_panel_ops.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/include/esp_lcd_panel_rgb.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/include/esp_lcd_panel_vendor.h ESP32_Display_Panel/mpy_support/ + cp esp-idf/components/esp_lcd/include/esp_lcd_types.h ESP32_Display_Panel/mpy_support/ + ``` + +6. 重新构建 micropython 以包含新模块 + + ```bash + pushd micropython + make BOARD=ESP32_GENERIC_S3 BOARD_VARIANT=SPIRAM_OCT USER_C_MODULES=~/esp32build/micropython.cmake -C ports/esp32 + pushd ports/esp32 + python -m esptool --port /dev/ttyACM0 --chip esp32s3 -b 460800 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size 4MB --flash_freq 80m 0x0 build-ESP32_GENERIC_S3-SPIRAM_OCT/bootloader/bootloader.bin 0x8000 build-ESP32_GENERIC_S3-SPIRAM_OCT/partition_table/partition-table.bin 0x10000 build-ESP32_GENERIC_S3-SPIRAM_OCT/micropython.bin + popd + popd + ``` + + 如果您的芯片闪存大小较小,这可能会失败,在这种情况下,您必须增加应用程序分区的大小。例如,对于 4MB 闪存芯片,编辑 *micropython/ports/esp32/partitions-4MiB.csv* 并将最后两行从: + + ```csv + factory, app, factory, 0x10000, 0x1F0000, + vfs, data, fat, 0x200000, 0x200000, + ``` + + 改为: + + ```csv + factory, app, factory, 0x10000, 0x2F0000, + vfs, data, fat, 0x300000, 0x100000, + ``` + +7. 测试模块 + + 连接到您的开发板并运行: + + ```python + from esp_panel import Board + board = Board() + board.init() + ``` + + `board.init()` 应该返回 False,因为我们还需要定义一个开发板。 + +8. 定义您的开发板 + + 编辑 *ESP32_Display_Panel/mpy_support/esp_panel_mp_board.cpp*。添加一个开发板定义: + + ```c++ + const BoardConfig BOARD_EXTERNAL_CONFIG = { + /* General */ + .name = "ESP_PANEL_BOARD_NAME", + .lcd = BoardConfig::LCD_Config{ + .bus_config = esp_panel::drivers::BusSPI::Config{ + .host_id = 1, + // Host + .host = esp_panel::drivers::BusSPI::HostPartialConfig{ + .mosi_io_num = 6, //ESP_PANEL_BOARD_LCD_SPI_IO_MOSI, + .miso_io_num = 8, //ESP_PANEL_BOARD_LCD_SPI_IO_MISO, + .sclk_io_num = 7, //ESP_PANEL_BOARD_LCD_SPI_IO_SCK, + }, + // Control Panel + .control_panel = esp_panel::drivers::BusSPI::ControlPanelPartialConfig{ + .cs_gpio_num = 5, //ESP_PANEL_BOARD_LCD_SPI_IO_CS, + .dc_gpio_num = 4, //ESP_PANEL_BOARD_LCD_SPI_IO_DC, + .spi_mode = 0, //ESP_PANEL_BOARD_LCD_SPI_MODE, + .pclk_hz = 40 * 1000 * 1000, //ESP_PANEL_BOARD_LCD_SPI_CLK_HZ, + .lcd_cmd_bits = 8, //ESP_PANEL_BOARD_LCD_SPI_CMD_BITS, + .lcd_param_bits = 8, //ESP_PANEL_BOARD_LCD_SPI_PARAM_BITS, + }, + }, + .device_name = "ILI9341", + .device_config = { + // Device + .device = esp_panel::drivers::LCD::DevicePartialConfig{ + .reset_gpio_num = 48, //ESP_PANEL_BOARD_LCD_RST_IO, + .rgb_ele_order = 0, //ESP_PANEL_BOARD_LCD_COLOR_BGR_ORDER, + .bits_per_pixel = 18, //ESP_PANEL_BOARD_LCD_COLOR_BITS, 16/18/24 + .flags_reset_active_high = 0, //ESP_PANEL_BOARD_LCD_RST_LEVEL, + }, + // Vendor + .vendor = esp_panel::drivers::LCD::VendorPartialConfig{ + .hor_res = 320, //ESP_PANEL_BOARD_WIDTH, + .ver_res = 480, //ESP_PANEL_BOARD_HEIGHT, + }, + }, + .pre_process = { + .invert_color = 0, //ESP_PANEL_BOARD_LCD_COLOR_INEVRT_BIT, + }, + }, + }; + ``` + + 然后替换构造函数 + + ```c++ + self->board = utils::make_shared() + ``` + + 为 + + ```c++ + self->board = utils::make_shared(BOARD_EXTERNAL_CONFIG); + ``` + +9. 编辑 esp_panel_drivers_conf.h + + 编辑 *ESP32_Display_Panel/esp_panel_drivers_conf.h* 并确保在您的开发板配置中引用的驱动程序被构建。 + **警告**:`ESP_PANEL_DRIVERS_BUS_USE_ALL` 似乎不起作用。设置为 0 并手动包含您需要的总线驱动程序。 + `ESP_PANEL_DRIVERS_BUS_COMPILE_UNUSED_DRIVERS` 也是如此。 + +10. 重复 **步骤 6** 重新构建 micropython + +11. 测试您的显示屏 + + 连接到您的开发板并运行: + + ```python + from esp_panel import Board + board = Board() + board.init() + board.begin() + board.color_bar_test() + ``` + +12. 大功告成!:) + + 要包含触摸支持,请参阅 *ESP32_Display_Panel/examples/arduino/board/board_dynamic_config/board_external_config.cpp* 获取触摸定义示例。 + +## 已知陷阱 + +1. 当 `board.init()` 返回 false 时,很可能是您在 *esp_panel_drivers_conf.h* 中的驱动程序定义不匹配。 +2. 如果您依赖 `ESP_PANEL_DRIVERS_BUS_USE_ALL`,`board.begin()` 会崩溃。 +3. 如果您编辑 *ESP32_Display_Panel/esp_panel_drivers_conf.h*,还需要修改 *ESP32_Display_Panel/mpy_support/esp_panel_mp_board.cpp*(比如添加或删除一个空行)。否则,对 *esp_panel_drivers_conf.h* 的更改将不会被识别。 diff --git a/idf_component.yml b/idf_component.yml index 0fd8af5..4e1f039 100644 --- a/idf_component.yml +++ b/idf_component.yml @@ -1,4 +1,4 @@ -version: "1.0.2" +version: "1.0.3" description: ESP32_Display_Panel is a display driver and GUI porting library designed by Espressif specifically for ESP series SoCs (ESP32, ESP32-S3, ESP32-P4, etc.) url: https://github.com/esp-arduino-libs/ESP32_Display_Panel repository: https://github.com/esp-arduino-libs/ESP32_Display_Panel.git diff --git a/library.properties b/library.properties index 8cb346a..7f9996d 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=ESP32_Display_Panel -version=1.0.2 +version=1.0.3 author=espressif maintainer=espressif sentence=ESP32_Display_Panel is a display driver and GUI porting library designed by Espressif specifically for ESP series SoCs (ESP32, ESP32-S3, ESP32-P4, etc.) diff --git a/src/esp_panel_versions.h b/src/esp_panel_versions.h index 81ff955..648505f 100644 --- a/src/esp_panel_versions.h +++ b/src/esp_panel_versions.h @@ -8,7 +8,7 @@ /* Library Version */ #define ESP_PANEL_VERSION_MAJOR 1 #define ESP_PANEL_VERSION_MINOR 0 -#define ESP_PANEL_VERSION_PATCH 2 +#define ESP_PANEL_VERSION_PATCH 3 /* File `esp_panel_drivers_conf.h` */ #define ESP_PANEL_DRIVERS_CONF_VERSION_MAJOR 1