# lvgl-upy-examples

A collection of [LVGL 9.0](https://lvgl.io/) example projects using [Micropython](https://micropython.org/). This repository primarily supports the ESP32-S3 DevKitC-1 board. Micropython uses the esp-idf 5.2.x version. I will endeavor to provide the most detailed instructions possible for achieving the results demonstrated in these examples.

To use this repository, create a python virtual environment and install the dependencies:

```shell
python3 -m venv env
source env/bin/activate
pip install -r requirements.txt
```

The `esptool` package will be used for flashing the binary to your board. The `mpremote` package will be used for transferring files and accessing the REPL.

## Building / Flashing the ESP32-S3

The binaries used for these examples were compiled using https://github.com/lvgl-micropython/lvgl_micropython by Kevin Schlosser. This project seeks to make it easier to get LVGL working for Micropython.

I have copies of the binary builds used for these examples in the `./builds` directory. Feel free to use one of these builds if it matches your board and screen. Otherwise you will need to build a binary for your target board and supported display/touch sensor documented in the `lvgl_micropython/README.md`. 

### Building LVGL + Micropython for the ESP32-S3 with ILI9341 Display

In another terminal clone the lvgl_micropython repo
```shell
git clone https://github.com/lvgl-micropython/lvgl_micropython.git
cd lvgl_micropython
```

Install any of the [build requirements](https://github.com/lvgl-micropython/lvgl_micropython?tab=readme-ov-file#requirements) listed in the README.md for your target OS.

Using the provided `make.py` script provide the necessary parameters for your target board. I am personally using a [ESP32-S3-DevKitC-1-N32R8V dev board](https://docs.espressif.com/projects/esp-idf/en/stable/esp32s3/hw-reference/esp32s3/user-guide-devkitc-1.html#) with a `ESP32-S3-WROOM-2-N32R8V` integrated module. This means my board has 32MB of Octal SPI flash. I am using an ILI9341 TFT display with an integrated XPT2046 touch sensor. So below is what my `make.py` parameters looked like. 

```shell
python3 make.py esp32 clean mpy_cross BOARD=ESP32_GENERIC_S3 BOARD_VARIANT=SPIRAM_OCT DISPLAY=ili9341 INDEV=xpt2046 --octal-flash --flash-size 32
```

This will trigger the build process, which will download the necessary submodules, and pass the appropriate parameters to each subsystem build. When complete you should have a built `*.bin` binary in `./lvgl_micropython/build/`. The above `make.py` command produced `lvgl_micropython/build/lvgl_micropy_ESP32_GENERIC_S3-SPIRAM_OCT-32_OCTFLASH.bin`. I have renamed this `lvgl_9p0_micropy_1p23_ili9341_ESP32_GENERIC_S3-SPIRAM_OCT-32_OCTFLASH.bin` to denote that it used the LVGL 9.0 Library and Micropython 1.23 with the ili93241 display driver.

### Flashing ESP32-S3

Plug in your development board and identify the tty port using `mpremote devs`. In my case (macOS) this resolves to `/dev/tty.usbserial-14410`. Export this port as an environment variable. 

```shell
export PORT=/dev/tty.usbserial-14410
```

Conveniently the above build step produced an "almost" working esptool command. I have used the below to flash my device.

```shell
python -m esptool --chip esp32s3 -p ${PORT} -b 115200 --before default_reset --after hard_reset write_flash --flash_mode dout --flash_size 32MB --flash_freq 80m --erase-all 0x0 ./builds/lvgl_9p0_micropy_1p23_ili9341_ESP32_GENERIC_S3-SPIRAM_OCT-32_OCTFLASH.bin
```

If your board has a smaller flash size be sure to adjust accordingly.

## Projects

This repository is organized as a series of example projects. It is designed to progressively explore the LVGL framework in Micropython on the ESP32-S3, but feel free skip ahead, copy adapt, etc. This repository is MIT Licensed, to save space on your micropython device I have forgone including the license text within the examples. If you copy the code to your projects please include a copy of the `./LICENSE` with the program. 

- Project 1: [Interactive LVGL in REPL](./project1/README.md)
- Project 2: [Helloworld LVGL as main.py](./project2/README.md)