Skip to content

Commit cade7b4

Browse files
kdschlosserkdschlosser
committed
updating docs.
1 parent 4ce7f79 commit cade7b4

File tree

11 files changed

+329
-72
lines changed

11 files changed

+329
-72
lines changed

‎README.md

+4-42
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,8 @@ used to be.
8787
- [*Model/Variant*](#model/variant)
8888
- [*Model/Variant specific options*](#model/variant-specific-options)
8989
- [*ESP32 options*](#esp32-options)
90+
- [*Custom Boards*](https://github.com/lvgl-micropython/lvgl_micropython/tree/main/custom_board_and_toml_examples/README.md#custom-boards)
91+
- [*TOML Example*](https://github.com/lvgl-micropython/lvgl_micropython/tree/main/custom_board_and_toml_examples/README.md#toml-example)
9092
- [*Global Options (optional)*](#global-options-(optional))
9193
- [*Input/Output*](#input/output)
9294
- [*Other global options*](#other-global-options)
@@ -586,49 +588,9 @@ Options specific to the ESP32-S2, ESP32-S3, ESP32-C3 and ESP32-C6 processors:
586588
* `--enable-cdc-repl={y/n}`: Enable/disable REPL output over CDC on the USB pins
587589
* `--enable-jtag-repl={y/n}`: Enable/disable REPL output over JTAG on the USB pins
588590

591+
* `--custom-board-path={path to custom board}`: [Custom Board](https://github.com/lvgl-micropython/lvgl_micropython/tree/main/custom_board_and_toml_examples/README.md#custom-boards)
592+
* `--toml={path to .toml file}`: [TOML Example](https://github.com/lvgl-micropython/lvgl_micropython/tree/main/custom_board_and_toml_examples/README.md#toml-example)
589593

590-
This next option is abailable for all ESP32 series MCU's I placed it here instead of above
591-
because it is going to need some in depth explaining. This is for advanced users.
592-
593-
* `--custom-board-path`
594-
595-
I added the ability to provide a path to a custom board. There are a few requirememnts for
596-
this to work properly. The path needs to point to the folder that holds the board specification
597-
files. Here is a list of required files.
598-
599-
* `board.json`: This file outlines what the board is. At a minimum the file needs to contain the following.
600-
```
601-
{
602-
"mcu": "{MCU}"
603-
}
604-
```
605-
where `{MCU}` is one of the follwing:
606-
607-
* esp32
608-
* esp32s2
609-
* exp32s3
610-
* exp32c3
611-
* exp32c6
612-
613-
* `sdkconfig.board`: This file contains all of the ESP-IDF specific config settings. If you don't know
614-
what needs to be set in here then please ask me for assistance.
615-
* `mpconfigboard.h`: MicroPython config settings. If you don't know what needs to be set in here then
616-
please ask me for assistance.
617-
* `mpconfigboard.cmake`: Build script. At a minimum the following should be in the build script.
618-
`{MCU}` is replaced with one of the options from the list of MCU's above.
619-
`{BOARD_CONATINING_FOLDER}` if the name of the folder these files are located in.
620-
```
621-
set(IDF_TARGET {MCU})
622-
623-
set(SDKCONFIG_DEFAULTS
624-
boards/sdkconfig.base
625-
${SDKCONFIG_IDF_VERSION_SPECIFIC}
626-
boards/{BOARD_CONATINING_FOLDER}/sdkconfig.board
627-
)
628-
```
629-
630-
* `partition.csv`: This file dictates what the partitions are supposed to be on the ESP32. As for assistance
631-
If you do not know how to create one of these.
632594

633595
<br>
634596

‎builder/esp32.py

-25
Original file line numberDiff line numberDiff line change
@@ -528,31 +528,6 @@ def esp32_args(extra_args):
528528

529529
def parse_args(extra_args, lv_cflags, brd):
530530
global board
531-
global custom_board_path
532-
533-
esp_argParser = ArgumentParser(prefix_chars='-')
534-
esp_argParser.add_argument(
535-
'--custom-board-path',
536-
dest='custom_board_path',
537-
default=None,
538-
action='store'
539-
)
540-
esp_args, extra_args = esp_argParser.parse_known_args(extra_args)
541-
542-
custom_board_path = esp_args.custom_board_path
543-
544-
if custom_board_path is not None:
545-
if not os.path.exists(custom_board_path):
546-
raise RuntimeError(
547-
'Supplied custom board path does not exist.'
548-
)
549-
parent_folder_name = os.path.split(custom_board_path)[-1]
550-
551-
dst_path = f'lib/micropython/ports/esp32/boards/{parent_folder_name}'
552-
shutil.copytree(custom_board_path, dst_path)
553-
554-
if brd is None:
555-
brd = parent_folder_name
556531

557532
if brd is None:
558533
brd = 'ESP32_GENERIC'

‎custom_board_and_toml_examples/MY_CUSTOM_BOARD/board.json

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"mcu": "esp32s3",
3+
"product": "Custom ESP32-S3 display board",
4+
"url": "https://www.come_manufacturer.com/board.html",
5+
"vendor": "Vendor name of board"
6+
}

‎custom_board_and_toml_examples/MY_CUSTOM_BOARD/mpconfigboard.cmake

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
set(IDF_TARGET esp32s3)
2+
3+
set(SDKCONFIG_DEFAULTS
4+
boards/sdkconfig.base
5+
${SDKCONFIG_IDF_VERSION_SPECIFIC}
6+
boards/sdkconfig.usb
7+
boards/sdkconfig.ble
8+
boards/sdkconfig.spiram_sx
9+
boards/sdkconfig.spiram_oct
10+
boards/sdkconfig.240mhz
11+
boards/MY_CUSTOM_BOARD/sdkconfig.board
12+
)
13+
14+
list(APPEND MICROPY_DEF_BOARD
15+
MICROPY_HW_BOARD_NAME="custom ESP32 board"
16+
)
17+

‎custom_board_and_toml_examples/MY_CUSTOM_BOARD/mpconfigboard.h

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#ifndef MICROPY_HW_BOARD_NAME
2+
// Can be set by mpconfigboard.cmake.
3+
#define MICROPY_HW_BOARD_NAME "Custom ESP32S3 board"
4+
#endif
5+
#define MICROPY_HW_MCU_NAME "ESP32S3"
6+
7+
// Enable UART REPL for modules that have an external USB-UART and don't use native USB.
8+
#define MICROPY_HW_ENABLE_UART_REPL (1)
9+
10+
#define MICROPY_HW_I2C0_SCL (9)
11+
#define MICROPY_HW_I2C0_SDA (8)

‎custom_board_and_toml_examples/MY_CUSTOM_BOARD/my_custom_board.toml

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
2+
[MCU.esp32]
3+
BOARD = "MY_CUSTOM_BOARD"
4+
5+
6+
[I80Bus.display_bus]
7+
data0 = 9
8+
data1 = 46
9+
data2 = 3
10+
data3 = 8
11+
data4 = 18
12+
data5 = 17
13+
data6 = 16
14+
data7 = 15
15+
dc = 0
16+
wr = 47
17+
cs = -1
18+
freq = 20000000
19+
20+
21+
[I2C.Bus.i2c_bus]
22+
host = 0
23+
scl = 5
24+
sda = 6
25+
freq = 100000
26+
27+
28+
[I2C.Device.indev_device]
29+
bus = "i2c_bus"
30+
dev_id = "ft6x36.I2C_ADDR"
31+
reg_bits = "ft6x36.BITS"
32+
33+
34+
[ST7796.display]
35+
data_bus = "display_bus"
36+
display_width = 320
37+
display_height = 480
38+
backlight_pin = 45
39+
color_byte_order = "st7789.BYTE_ORDER_BGR"
40+
color_space = "lv.COLOR_FORMAT.RGB565"
41+
rgb565_byte_swap = true
42+
43+
[ST7796.display.init]
44+
params = []
45+
46+
[FT6x36.indev]
47+
device = "indev_device"
48+
49+
[display.set_color_inversion]
50+
params = [true]
51+
52+
[display.set_rotation]
53+
params = ["lv.DISPLAY_ROTATION._90"]
54+
55+
[display.set_backlight]
56+
params = [100]
57+
58+
[task_handler.TaskHandler]
59+
params=[]

‎custom_board_and_toml_examples/MY_CUSTOM_BOARD/partitions.csv

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Notes: the offset of the partition table itself is set in
2+
# $IDF_PATH/components/partition_table/Kconfig.projbuild.
3+
# Name, Type, SubType, Offset, Size, Flags
4+
nvs, data, nvs, 0x9000, 0x6000,
5+
phy_init, data, phy, 0xf000, 0x1000,
6+
factory, app, factory, 0x10000, 0x2F0000,
7+
vfs, data, fat, 0x300000, 0x1D00000,

‎custom_board_and_toml_examples/MY_CUSTOM_BOARD/sdkconfig.board

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
CONFIG_IDF_EXPERIMENTAL_FEATURES=y
2+
3+
CONFIG_FREERTOS_HZ=1000
4+
CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y
5+
6+
CONFIG_ESPTOOLPY_FLASHMODE_QIO=y
7+
CONFIG_ESPTOOLPY_FLASHFREQ_120M=y
8+
CONFIG_ESPTOOLPY_FLASHSIZE_32MB=y
9+
10+
CONFIG_SPIRAM_SPEED_120M=y
11+
CONFIG_SPIRAM_IGNORE_NOTFOUND=n
12+
CONFIG_SPIRAM_RODATA=y
13+
CONFIG_SPIRAM_FETCH_INSTRUCTIONS=y
14+
15+
CONFIG_ESP32S3_DATA_CACHE_LINE_64B=y
16+
CONFIG_COMPILER_OPTIMIZATION_PERF=y
17+
18+
CONFIG_PARTITION_TABLE_CUSTOM=y
19+
CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="boards/MY_CUSTOM_BOARD/partitions.csv"
20+
21+
CONFIG_LWIP_LOCAL_HOSTNAME="my_custom_board"
22+
23+
CONFIG_TINYUSB_DESC_USE_ESPRESSIF_VID=n
24+
CONFIG_TINYUSB_DESC_USE_DEFAULT_PID=n
25+
CONFIG_TINYUSB_DESC_CUSTOM_VID=0x2341
26+
CONFIG_TINYUSB_DESC_CUSTOM_PID=0x056B
27+
CONFIG_TINYUSB_DESC_MANUFACTURER_STRING="MyCustomBoard"
28+
CONFIG_TINYUSB_DESC_PRODUCT_STRING="Custom ESP32"
29+

‎custom_board_and_toml_examples/README.md

+156
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
2+
3+
### *Custom Boards*
4+
___________________
5+
6+
7+
I added the ability to provide a path to a custom board. There are a few requirememnts for
8+
this to work properly. The best bet is to look at the files in the `custom_board_and_toml_examples/MY_CUSTOM_BOARD`
9+
folder to see what files are needed and to also get an idea of the kind of information that
10+
is in the files.
11+
12+
***NOTE***: There are only 2 options that get used when supplying a custom board. The first one
13+
is the build target and the second is the `--custom-board-path` command. ALL others
14+
are ignored. The reason they are ignored is because you have the ability to set things
15+
in the files for the custom board.
16+
17+
18+
The path needs to point to the folder that holds the board specification files. Here is a list of required files.
19+
20+
* `board.json`: This file outlines what the board is. At a minimum the file needs to contain the following.
21+
```
22+
{
23+
"mcu": "{MCU}"
24+
}
25+
```
26+
where `{MCU}` is one of the follwing:
27+
28+
* esp32
29+
* esp32s2
30+
* esp32s3
31+
* esp32c3
32+
* esp32c6
33+
34+
* `sdkconfig.board`: This file contains all of the ESP-IDF specific config settings. If you don't know
35+
what needs to be set in here then please ask me for assistance.
36+
* `mpconfigboard.h`: MicroPython config settings. If you don't know what needs to be set in here then
37+
please ask me for assistance.
38+
* `mpconfigboard.cmake`: Build script. At a minimum the following should be in the build script.
39+
`{MCU}` is replaced with one of the options from the list of MCU's above.
40+
`{BOARD_CONATINING_FOLDER}` if the name of the folder these files are located in.
41+
```
42+
set(IDF_TARGET {MCU})
43+
44+
set(SDKCONFIG_DEFAULTS
45+
boards/sdkconfig.base
46+
${SDKCONFIG_IDF_VERSION_SPECIFIC}
47+
boards/{BOARD_CONATINING_FOLDER}/sdkconfig.board
48+
)
49+
```
50+
51+
* `partition.csv`: This file dictates what the partitions are supposed to be on the ESP32. As for assistance
52+
If you do not know how to create one of these.
53+
54+
***NOTE***: The `.toml` file in the custom board example is NOT a requirement. I do strongly suggest using it
55+
since it will tie everything together. You can specify all of the display and indev bits and pieces.
56+
see [TOML Example](#toml-example) for further information.
57+
58+
59+
### *TOML Example*
60+
__________________
61+
62+
Here is an example of what you would put inside of the `.toml` file.
63+
I will go over each section below.
64+
65+
[MCU.esp32]
66+
BOARD = "ESP32_GENERIC_S3"
67+
BOARD_VARIANT = "SPIRAM_OCT"
68+
octal_flash = true
69+
flash_size = 16
70+
enable_jtag_repl = 'n'
71+
enable_cdc_repl = 'n'
72+
enable_uart_repl = 'y'
73+
uart_repl_bitrate = 115200
74+
75+
[I80Bus.display_bus]
76+
data0 = 9
77+
data1 = 46
78+
data2 = 3
79+
data3 = 8
80+
data4 = 18
81+
data5 = 17
82+
data6 = 16
83+
data7 = 15
84+
dc = 0
85+
wr = 47
86+
cs = -1
87+
freq = 20000000
88+
89+
[I2C.Bus.i2c_bus]
90+
host = 0
91+
scl = 5
92+
sda = 6
93+
freq = 100000
94+
95+
[I2C.Device.indev_device]
96+
bus = "i2c_bus"
97+
dev_id = "ft6x36.I2C_ADDR"
98+
reg_bits = "ft6x36.BITS"
99+
100+
[ST7796.display]
101+
data_bus = "display_bus"
102+
display_width = 320
103+
display_height = 480
104+
backlight_pin = 45
105+
color_byte_order = "st7789.BYTE_ORDER_BGR"
106+
color_space = "lv.COLOR_FORMAT.RGB565"
107+
rgb565_byte_swap = true
108+
109+
[ST7796.display.init]
110+
params = []
111+
112+
[FT6x36.indev]
113+
device = "indev_device"
114+
115+
[display.set_color_inversion]
116+
params = [true]
117+
118+
[display.set_rotation]
119+
params = ["lv.DISPLAY_ROTATION._90"]
120+
121+
[display.set_backlight]
122+
params = [100]
123+
124+
[task_handler.TaskHandler]
125+
params=[]
126+
127+
128+
129+
* `[MCU.{target}]`: `{target}` is the build target you want to use. In the example above we are using `esp32`
130+
The parameters that immediatly follow are almost the same as what you would use for build commands
131+
when entering them from the command line. There are a few rules for how those commands get enetered.
132+
133+
* options that star with `--` need to have the `--` removed and all `-`'s in the name need to be change to `_`.
134+
* options are cas esensitive
135+
* options that take a string value need to be wrapped in double quotes (`"value"`)
136+
* options that do not take any value *MUST* have the value set to `true`
137+
* options like `DISPLAY` and `INDEV` which are able to be repeated cannot be repeated (yet). That means you can onmly
138+
supply a single display or indev. You only need to supply the `DISPLAY` and `INDEV` if you are not wanting to automatically
139+
build the startup script.
140+
141+
142+
[MCU.esp32]
143+
BOARD = "ESP32_GENERIC_S3"
144+
BOARD_VARIANT = "SPIRAM_OCT"
145+
octal_flash = true
146+
flash_size = 16
147+
enable_jtag_repl = 'n'
148+
enable_cdc_repl = 'n'
149+
enable_uart_repl = 'y'
150+
uart_repl_bitrate = 115200
151+
152+
* `[{display bus}.{variable name}]`: `[I80Bus.display_bus]`, That heading section gets turnmed into `display_bus = lcd_bus.I80Bus(...)`.
153+
The variable name you will use when passing the display bus instance to the display driver. I will
154+
go into that more later on. The list of options below this heading are the parameters that get passed.
155+
These options MUST match the names of the parameters for the class being used.
156+
* `[I2C.Bus.{variable name}]` and `[I2C.Device.{variable_name}]`

‎example_build_toml.toml renamed to ‎custom_board_and_toml_examples/toml_example/example_build_toml.toml

File renamed without changes.

0 commit comments

Comments
 (0)