From fccf54e64b3eb8999955bff20d0f010245cb8a89 Mon Sep 17 00:00:00 2001
From: thomasabishop <thomasabishop@tuta.com>
Date: Tue, 27 Jan 2026 18:24:04 +0000
Subject: [PATCH] update readme

---
 README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5e74413
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+## Pre-requisites
+
+### ESP-IDF SDK
+
+The ESP-IDF is the SDK, provided by Expressif, for programming the ESP32 with
+C and C++.
+
+Install (on Arch):
+
+```sh
+yay -Sy esp-idf
+```
+
+### User permissions
+
+Ensure you are a member of the `uucp` group, to enable access to serial ports:
+
+```sh
+usermod -a -G uucp $USER
+```
+
+## Check ESP32 serial connection
+
+### List USB devices
+
+```sh
+lsusb
+```
+
+You should see the ESP32 listed and named something like `Silicon Labs CP210x` -
+this is the USB-to-serial chip on the ESP32 board.
+
+Can also run:
+
+```sh
+ls /dev/ttyUSB*
+```
+
+Which should reveal:
+
+```
+crw-rw---- 1 root uucp 188, 0 Dec 15 17:57 /dev/ttyUSB0
+```
+
+## Initialise ESP-IDF local environment in terminal
+
+`cd` into sub-project and run
+
+```sh
+. /opt/esp-idf/export.sh
+```
+
+This gives you access to the ESP-IDF Python CLI.
+
+Then initialise the project:
+
+```sh
+idf.py set-target esp32
+```
+
+## Compile program
+
+```sh
+
+idf.py build
+```
+
+## Flash to device
+
+```sh
+idf.py flash
+```
+
+## Monitor program execution
+
+```sh
+idf.py -p /dev/ttyUSB0 monitor
+```
+
+## Clean the build cache
+
+```sh
+idf.py fullclean
+```