Saving write up

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) <year> <copyright holders>
+Copyright (c) 2024 Drew Bednar
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

README.md

@@ -1,15 +1,16 @@
 # lvgl-upy-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.
+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 you board. The `mpremote` package will be used for transferring files and accessing the REPL.
+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
 
@@ -50,3 +51,10 @@ python -m esptool --chip esp32s3 -p ${PORT} -b 115200 --before default_reset --a
 ```
 
 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)

project1/README.md

@@ -0,0 +1,25 @@
+# Project 1 Interactive Hello World
+
+This project picks up directly from the flashing instructions in the root `README.md`. In this project we will be manually creating all LVGL objects within the REPL. We do this to progressively learn how an LVGL interface is built from a set of parent<->child relationships.
+
+The code within the example assumes an ESP32-S3 DevKitC-1, [pin out diagram is available here](https://docs.espressif.com/projects/esp-idf/en/v5.2.2/esp32s3/hw-reference/esp32s3/user-guide-devkitc-1.html#pin-layout). 
+
+The code also assumes an ili9341 TFT Display with an xpt2046 touch sensor. These boards are inexpensive and available on Amazon or Aliexpress from many distributors.
+
+##  Our pin mapping
+
+The ili9341/xpt2046 uses the Serial Peripheral Interface(SPI) for communication with our board. You should [review the terminology](https://docs.espressif.com/projects/esp-idf/en/v5.2.2/esp32s3/api-reference/peripherals/spi_master.html#terminology) section of the documentation before continuing. The ESP32-S3 has multiple SPI buses (or in Espressif terms 'hosts') some of which are already in use for flash and PSRAM on the devkit. SPI buses 1 and 2 will be used here for our example, each of which will be connected to the ili9341 and xpt2046, with different configured speeds.
+
+### The GPIO Matrix and IO_MUX 
+
+If you are combing through the ESP-IDF documentation you will find references to SPI buses connected to specific GPIO pins. The ESP32-S3 has a flexible I/O system that allows for mapping internal peripherals (e.g. SPI) to GPIO pins. This is achieved via the I/O Multiplexer(IO_MUX) and the GPIO Matrix.
+
+The IO_MUX is a hardware-level multiplexer that connects the chip's internal peripherals to the physical pins. Each GPIO pin has a default peripheral function, which is directly connected through the IO_MUX. Using the IO_MUX provides the fastest and most efficient connection between a peripheral and a pin. This is why you will see in the pin out diagram reference SPI functions like FSPICS0(Chip select) to GPIO pin 10. 
+
+The GPIO Matrix is a programmable routing system that sits between the IO_MUX and the chip's peripherals. It allows almost any internal signal to be routed to almost any GPIO pin. In short it allows us to map the Chip select functionality mentioned above to another pin.
+
+This project makes generous use of the flexible pin assignment capability provided by the GPIO Matrix. Be aware that technically the IO_MUX default pins will provide better performance. Also in Micropython the SPI numbers does not directly map 
+
+## Access the REPL
+
+Assuming no other Micropython serial devices are connected to your PC. Plug your board in and type the command `mpremote`. This should automatically connect to the first device. 

project2/README.md

@@ -0,0 +1,4 @@
+# Helloworld LVGL as main.py
+
+In this project we will upload the finished LVGL file from [project1](../project1/README.md) to the ESP32-S3 as the main.py program. On boot the device display will show the finished `project1` example.
+