Skip to content

Commit 2128a6e

Browse files
Lzw655Lzw655
committed
Merge branch 'feat/add_micropython_docs' into 'master'
Closes #190 See merge request ae_group/ESP32_Display_Panel!15
2 parents 31771b3 + 1469299 commit 2128a6e

9 files changed

+398
-4
lines changed

‎.github/workflows/pre-commit.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,4 @@ jobs:
1111
steps:
1212
- uses: actions/checkout@v2
1313
- uses: actions/setup-python@v2
14-
- uses: pre-commit/action@v2.0.3
14+
- uses: pre-commit/action@v3.0.1

‎CHANGELOG.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# ChangeLog
22

3+
## v1.0.3 - 2025-04-27
4+
5+
### Enhancements:
6+
7+
* feat(docs): provides an example of how to integrate this library into micropython by @tsteinruecken (#190)
8+
39
## v1.0.2 - 2025-04-23
410

511
### Enhancements:

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ The functional block diagram is shown below:
4545
* [ESP-IDF](./docs/envs/use_with_idf.md)
4646
* [Arduino IDE](./docs/envs/use_with_arduino.md)
4747
* [PlatformIO](./examples/platformio/lvgl_v8_port/README.md)
48+
* [Micropython](./docs/envs/use_with_micropython.md)
4849

4950
## Supported Boards
5051

‎README_CN.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ ESP32_Display_Panel 的主要特性如下：
4545
* [ESP-IDF](./docs/envs/use_with_idf_cn.md)
4646
* [Arduino IDE](./docs/envs/use_with_arduino_cn.md)
4747
* [PlatformIO](./examples/platformio/lvgl_v8_port/README.md)
48+
* [Micropython](./docs/envs/use_with_micropython_cn.md)
4849

4950
## 支持的开发板
5051

‎docs/envs/use_with_micropython.md

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Using with micropython
2+
3+
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.
4+
5+
## Step-by-Step instructions
6+
7+
1. Install IDF and micropython
8+
9+
```bash
10+
mkdir ~/esp32build
11+
pushd ~/esp32build
12+
git clone -b v5.2.2 --recursive https://github.com/espressif/esp-idf.git
13+
pushd esp-idf
14+
./install.sh esp32
15+
source export.sh
16+
popd
17+
git clone https://github.com/micropython/micropython.git
18+
pushd micropython
19+
git submodule update --init --recursive
20+
pushd mpy-cross
21+
make
22+
popd
23+
```
24+
25+
2. Ensure, you can build a working firmware
26+
27+
```bash
28+
make BOARD=ESP32_GENERIC_S3 BOARD_VARIANT=SPIRAM_OCT -C ports/esp32
29+
pushd ports/esp32
30+
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
31+
popd
32+
popd
33+
```
34+
Now, test the board and ensure your build of micropython works.
35+
36+
3. Download ESP32_Display_Panel and it's dependencies
37+
38+
```bash
39+
git clone https://github.com/esp-arduino-libs/ESP32_Display_Panel.git
40+
git clone https://github.com/esp-arduino-libs/esp-lib-utils.git
41+
git clone https://github.com/esp-arduino-libs/ESP32_IO_Expander.git
42+
```
43+
44+
4. Create a custom user-module definition
45+
46+
```bash
47+
cat > micropython.cmake << EOF
48+
include(~/esp32build/ESP32_Display_Panel/micropython.cmake)
49+
include(~/esp32build/esp-lib-utils/micropython.cmake)
50+
include(~/esp32build/ESP32_IO_Expander/micropython.cmake)
51+
EOF
52+
```
53+
54+
5. Copy some header-files
55+
56+
```bash
57+
cp esp-idf/components/esp_lcd/include/esp_lcd_panel_commands.h ESP32_Display_Panel/mpy_support/
58+
cp esp-idf/components/esp_lcd/interface/esp_lcd_panel_interface.h ESP32_Display_Panel/mpy_support/
59+
cp esp-idf/components/esp_lcd/include/esp_lcd_panel_io.h ESP32_Display_Panel/mpy_support/
60+
cp esp-idf/components/esp_lcd/interface/esp_lcd_panel_io_interface.h ESP32_Display_Panel/mpy_support/
61+
cp esp-idf/components/esp_lcd/include/esp_lcd_panel_ops.h ESP32_Display_Panel/mpy_support/
62+
cp esp-idf/components/esp_lcd/include/esp_lcd_panel_rgb.h ESP32_Display_Panel/mpy_support/
63+
cp esp-idf/components/esp_lcd/include/esp_lcd_panel_vendor.h ESP32_Display_Panel/mpy_support/
64+
cp esp-idf/components/esp_lcd/include/esp_lcd_types.h ESP32_Display_Panel/mpy_support/
65+
```
66+
67+
6. Rebuild micropython to include the new modules
68+
69+
```bash
70+
pushd micropython
71+
make BOARD=ESP32_GENERIC_S3 BOARD_VARIANT=SPIRAM_OCT USER_C_MODULES=~/esp32build/micropython.cmake -C ports/esp32
72+
pushd ports/esp32
73+
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
74+
popd
75+
popd
76+
```
77+
78+
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:
79+
80+
```csv
81+
factory, app, factory, 0x10000, 0x1F0000,
82+
vfs, data, fat, 0x200000, 0x200000,
83+
```
84+
85+
to
86+
87+
```csv
88+
factory, app, factory, 0x10000, 0x2F0000,
89+
vfs, data, fat, 0x300000, 0x100000,
90+
```
91+
92+
7. Test the module
93+
94+
Connect to your board and run:
95+
96+
```python
97+
from esp_panel import Board
98+
board = Board()
99+
board.init()
100+
```
101+
102+
`board.init()` should return False, as we yet have to define a board.
103+
104+
8. Define your Board
105+
106+
Edit *ESP32_Display_Panel/mpy_support/esp_panel_mp_board.cpp*. Add a Board definition:
107+
108+
```c++
109+
const BoardConfig BOARD_EXTERNAL_CONFIG = {
110+
/* General */
111+
.name = "ESP_PANEL_BOARD_NAME",
112+
.lcd = BoardConfig::LCD_Config{
113+
.bus_config = esp_panel::drivers::BusSPI::Config{
114+
.host_id = 1,
115+
// Host
116+
.host = esp_panel::drivers::BusSPI::HostPartialConfig{
117+
.mosi_io_num = 6, //ESP_PANEL_BOARD_LCD_SPI_IO_MOSI,
118+
.miso_io_num = 8, //ESP_PANEL_BOARD_LCD_SPI_IO_MISO,
119+
.sclk_io_num = 7, //ESP_PANEL_BOARD_LCD_SPI_IO_SCK,
120+
},
121+
// Control Panel
122+
.control_panel = esp_panel::drivers::BusSPI::ControlPanelPartialConfig{
123+
.cs_gpio_num = 5, //ESP_PANEL_BOARD_LCD_SPI_IO_CS,
124+
.dc_gpio_num = 4, //ESP_PANEL_BOARD_LCD_SPI_IO_DC,
125+
.spi_mode = 0, //ESP_PANEL_BOARD_LCD_SPI_MODE,
126+
.pclk_hz = 40 * 1000 * 1000, //ESP_PANEL_BOARD_LCD_SPI_CLK_HZ,
127+
.lcd_cmd_bits = 8, //ESP_PANEL_BOARD_LCD_SPI_CMD_BITS,
128+
.lcd_param_bits = 8, //ESP_PANEL_BOARD_LCD_SPI_PARAM_BITS,
129+
},
130+
},
131+
.device_name = "ILI9341",
132+
.device_config = {
133+
// Device
134+
.device = esp_panel::drivers::LCD::DevicePartialConfig{
135+
.reset_gpio_num = 48, //ESP_PANEL_BOARD_LCD_RST_IO,
136+
.rgb_ele_order = 0, //ESP_PANEL_BOARD_LCD_COLOR_BGR_ORDER,
137+
.bits_per_pixel = 18, //ESP_PANEL_BOARD_LCD_COLOR_BITS, 16/18/24
138+
.flags_reset_active_high = 0, //ESP_PANEL_BOARD_LCD_RST_LEVEL,
139+
},
140+
// Vendor
141+
.vendor = esp_panel::drivers::LCD::VendorPartialConfig{
142+
.hor_res = 320, //ESP_PANEL_BOARD_WIDTH,
143+
.ver_res = 480, //ESP_PANEL_BOARD_HEIGHT,
144+
},
145+
},
146+
.pre_process = {
147+
.invert_color = 0, //ESP_PANEL_BOARD_LCD_COLOR_INEVRT_BIT,
148+
},
149+
},
150+
};
151+
```
152+
153+
Then replace the constructor
154+
155+
```c++
156+
self->board = utils::make_shared<Board>()
157+
```
158+
159+
with
160+
161+
```c++
162+
self->board = utils::make_shared<Board>(BOARD_EXTERNAL_CONFIG);
163+
```
164+
165+
9. Edit esp_panel_drivers_conf.h
166+
167+
Edit *ESP32_Display_Panel/esp_panel_drivers_conf.h* and ensure, the drivers referenced in your board config are being
168+
build. **Warning**: `ESP_PANEL_DRIVERS_BUS_USE_ALL` does not seem to work. Set to 0 and manually include the bus driver
169+
you need. Same goes for `ESP_PANEL_DRIVERS_BUS_COMPILE_UNUSED_DRIVERS`.
170+
171+
10. Repeat **Step 6** to rebuild micropython
172+
173+
11. Test your display
174+
175+
Connect to your board and run:
176+
177+
```python
178+
from esp_panel import Board
179+
board = Board()
180+
board.init()
181+
board.begin()
182+
board.color_bar_test()
183+
```
184+
185+
12. Profit! :)
186+
187+
To include touch support, see *ESP32_Display_Panel/examples/arduino/board/board_dynamic_config/board_external_config.cpp* for an example touch definition.
188+
189+
## Known Pitfalls
190+
191+
1. When `board.init()` returns false, likely your driver-definition in *esp_panel_drivers_conf.h* does not match.
192+
2. `board.begin()` crashes, if you rely on `ESP_PANEL_DRIVERS_BUS_USE_ALL`
193+
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.

0 commit comments

Comments
 (0)