From 4f635ae18fe0649c6dfa513d5061b518f6124091 Mon Sep 17 00:00:00 2001
From: Serge Bazanski <q3k@q3k.org>
Date: Sat, 13 May 2023 16:39:28 +0200
Subject: [PATCH] *: add developer breadcrumbs

---
 README.md                    | 19 +++++++++++++++----
 components/badge23/README.md |  6 ++++++
 main/README.md               |  6 ++++++
 usermodule/README.md         |  3 +++
 usermodule/micropython.cmake |  4 ++++
 5 files changed, 34 insertions(+), 4 deletions(-)
 create mode 100644 components/badge23/README.md
 create mode 100644 main/README.md
 create mode 100644 usermodule/README.md

diff --git a/README.md b/README.md
index 8679ad1b2c..f34a693c7f 100644
--- a/README.md
+++ b/README.md
@@ -107,15 +107,26 @@ There's `flash/monitor` targets, too (but no openocd/gdb...). To pick what port
 
 ## How to modify
 
+### Structure
+
+```
+main/               - main module, starts micropython on core1 and continues
+                      executing components/badge23/.
+usermodule/         - `hardware`, `synth`, ... C modules exposed to micropython.
+components/badge23/ - main ESP-IDF `app_main`, runs on core 0 after micropython
+                      gets started on core1.
+components/gc9a01/  - low-level LCD driver.
+```
+
 ### General info
 
-Global + micropython entry point: app\_main() in micropython/ports/esp32/main.c (includes badge23/espan.h).
+Global + micropython entry point: `app_main()` in `micropython/ports/esp32/main.c`, compiled into `main/` component.
 
-C entry point, called by^: os\_app\_main() in badge23/espan.c
+C entry point, called by^: `os_app_main()` in components/badge23/espan.c
 
-Register new c files for compilation: add to set(BADGE23\_SOURCE) in main/CMakelists.txt
+Register new C files for compilation: add to components/badge23/CMakelists.txt
 
-Change output volume in the set\_global\_vol\_dB(int8\_t) call; -90 for mute
+Change output volume in the `set_global_vol_dB(int8_t)` call; -90 for mute
 
 ### Debugging
 
diff --git a/components/badge23/README.md b/components/badge23/README.md
new file mode 100644
index 0000000000..990eb72c4b
--- /dev/null
+++ b/components/badge23/README.md
@@ -0,0 +1,6 @@
+badge23/espan
+===
+
+Transitional component containing all custom C code for badge23, including drivers for peripherals and 'espan' application leftovers.
+
+This will be likely split up into sub-components.
diff --git a/main/README.md b/main/README.md
new file mode 100644
index 0000000000..8deec1e0bd
--- /dev/null
+++ b/main/README.md
@@ -0,0 +1,6 @@
+micropython shim module
+===
+
+This is the 'main' module from ESP-IDF, and its job is to just start
+micropython and continue executing `app_main` from
+`components/badge23/espan.c`.
diff --git a/usermodule/README.md b/usermodule/README.md
new file mode 100644
index 0000000000..ac5f07b672
--- /dev/null
+++ b/usermodule/README.md
@@ -0,0 +1,3 @@
+micropython C modules
+===
+
diff --git a/usermodule/micropython.cmake b/usermodule/micropython.cmake
index fbc5ed9b56..d647bb687c 100644
--- a/usermodule/micropython.cmake
+++ b/usermodule/micropython.cmake
@@ -1,3 +1,7 @@
+# If you want to add dependencies on other ESP-IDF modules, add them to
+# IDF_COMPONENTS in main/CMakeLists, as main/ is the component that the
+# usermodules are actually part of.
+
 add_library(usermod_badge23 INTERFACE)
 
 target_sources(usermod_badge23 INTERFACE
-- 
GitLab