feat(docs): support micropython

Author: Lzw655

.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

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:

README.md

@@ -45,7 +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](./mpy_support/README.md)
+* [Micropython](./docs/envs/use_with_micropython.md)
 
 ## Supported Boards
 

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)
 
 ## 支持的开发板
 

mpy_support/README.md renamed to docs/envs/use_with_micropython.md

@@ -1,8 +1,6 @@
 # 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.
-
+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
 
@@ -25,33 +23,36 @@ it should be easy to adapt to different supported ESP-Chips. Please note, that y
     ```
 
 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 
+    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/
@@ -64,40 +65,46 @@ it should be easy to adapt to different supported ESP-Chips. Please note, that y
     ```
 
 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 
+    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 
+    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,
+    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,
+
+    to
+
+    ```csv
+    factory,  app,  factory, 0x10000, 0x2F0000,
+    vfs,      data, fat,     0x300000, 0x100000,
     ```
 
 7. Test the module
-   Connect to your board and run:
+
+    Connect to your board and run:
+
     ```python
-   from esp_panel import Board
-   board = Board()
-   board.init()
+    from esp_panel import Board
+    board = Board()
+    board.init()
     ```
-   board.init() should return False, as we yet have to define a board.
+
+    `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:
+
+   Edit *ESP32_Display_Panel/mpy_support/esp_panel_mp_board.cpp*. Add a Board definition:
+
     ```c++
     const BoardConfig BOARD_EXTERNAL_CONFIG = {
         /* General */
@@ -142,40 +149,45 @@ it should be easy to adapt to different supported ESP-Chips. Please note, that y
         },
     };
     ```
-   Then replace the constructor
-   ```c++
-   self->board = utils::make_shared<Board>()
+
+    Then replace the constructor
+
+    ```c++
+    self->board = utils::make_shared<Board>()
     ```
-   with
-   ```c++
-   self->board = utils::make_shared<Board>(BOARD_EXTERNAL_CONFIG);
+
+    with
+
+    ```c++
+    self->board = utils::make_shared<Board>(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
+    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.
-       
+    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.
+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.