Initial instructions

.gitattributes

@@ -0,0 +1 @@
+builds/*.bin filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,3 +1,52 @@
 # lvgl-upy-examples
 
-A collection of LVGL examples
+A collection of LVGL examples using Micropython. This repository primarily supports the ESP32-S3 DevKitC-1 board. 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
+pip install -r requirements.txt
+```
+
+The `esptool` package will be used for flashing the binary to you 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 submodules 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.

requirements.in

@@ -0,0 +1,3 @@
+esptool
+mpremote
+pip-tools

requirements.txt

@@ -0,0 +1,52 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile requirements.in
+#
+bitarray==2.9.2
+    # via bitstring
+bitstring==4.2.3
+    # via esptool
+build==1.2.1
+    # via pip-tools
+cffi==1.17.0
+    # via cryptography
+click==8.1.7
+    # via pip-tools
+cryptography==43.0.0
+    # via esptool
+ecdsa==0.19.0
+    # via esptool
+esptool==4.7.0
+    # via -r requirements.in
+intelhex==2.3.0
+    # via esptool
+mpremote==1.23.0
+    # via -r requirements.in
+packaging==24.1
+    # via build
+pip-tools==7.4.1
+    # via -r requirements.in
+pycparser==2.22
+    # via cffi
+pyproject-hooks==1.1.0
+    # via
+    #   build
+    #   pip-tools
+pyserial==3.5
+    # via
+    #   esptool
+    #   mpremote
+pyyaml==6.0.2
+    # via esptool
+reedsolo==1.7.0
+    # via esptool
+six==1.16.0
+    # via ecdsa
+wheel==0.44.0
+    # via pip-tools
+
+# The following packages are considered to be unsafe in a requirements file:
+# pip
+# setuptools