diff --git a/README.md b/README.md
index 155de829553d919211a16517b693909fc67f5208..c764c55cc3b1bdc42b61ea40d9d5d10618c535f9 100644
--- a/README.md
+++ b/README.md
@@ -84,11 +84,10 @@ $ idf.py -p /dev/ttyACM0 flash
The following targets are available for flashing:
-| Target | Flashes |
-|--------------------|-------------------------------------------------|
-| `idf.py flash` | Bootloader, C code, Python Code / FAT partition |
-| `idf.py app-flash` | C code |
-| `idf.py vfs-flash` | Python Code / FAT partition |
+| Target | Flashes |
+|--------------------|-------------------------------------|
+| `idf.py flash` | Bootloader, partition table, C code |
+| `idf.py app-flash` | C code |
You can skip `-p /dev/ttyACM0` if you set the environment variable `ESPPORT=/dev/ttyACM0`. This environment variable is also set by default when using Nix.
@@ -135,31 +134,31 @@ There's `flash/monitor` targets, too (but no openocd/gdb...). To pick what port
### 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.
+components/flow3r_bsp/ - Board Support Package, ie. low-level drivers
+components/st3m/ - Core C software (C-st3m)
+python_payload/st3m/ - Core Python software (Py-st3m)
+components/micropython/usermodule/ - Bindings between C-st3m and Py-st3m.
+components/micropython/vendor/ - Micrpython fork.
```
### General info
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 components/badge23/espan.c
+C entry point, called by above: `st3m_board_init()` in `components/st3m/st3m_board_init.c`
-Register new C files for compilation: add to components/badge23/CMakelists.txt
+After C-st3m initializes, it returns and lets Micropython run. Micropython then will stay in a loop which attempts to run main.py, otherwise runs the REPL.
### Debugging
-The badge is currently configured to run in HW USB UART/JTAG mode (vs. using TinyUSB and 'software' CDC/whatever using the generic OTG peripheral).
+The badge starts with a UART/JTAG bridge, but then after boot switches to a custom USB stack based on TinyUSB. This stack will bring up a serial-based console that will run the Micropython REPL.
-What this means:
+The serial console will carry any C printf() you throw in, and any active `ESP_LOGx` call (see: ESP logging levels in sdkconfig). It will also carry anything that micropython prints.
+
+However, if the badge crashes, you will not see any output on the console. You are also not able to run OpenOCD/gdb. If you wish to perform these actions, you will have to modify `st3m_board_init.c` to disable USB console startup. You can also switch the default console to UART0 and use the UART0 peripheral over USB-C sideband pins.
+
+See [tracking issue](https://git.card10.badge.events.ccc.de/badge23/firmware/-/issues/23).
-1. You can use the MicroPython REPL over a USB console,
-2. The MicroPython REPL will also print ESP-IDF logs, including panics,
-3. You can use OpenOCD/GDB.
#### printf() debugging and logging in C-land
@@ -179,6 +178,8 @@ If you want to only log errors or just add temporary logs, use `ESP_LOGE` instea
#### Running OpenOCD+GDB
+(currently broken, see [tracking issue](https://git.card10.badge.events.ccc.de/badge23/firmware/-/issues/23).
+
First, make sure your badge is running in application mode (not bootloader mode! that will stay in bootloader mode).
Then, start OpenOCD:
@@ -222,50 +223,6 @@ defconfig by using 'D'. The resulting `build/defconfig` file can then be copied
into `sdkconfig` to change the defaults for a given generation (be sure to
remove FLOW3R_* options that are usually generated by `idf_ext.py`).
-### Badge link
-
-Badge link lets you have UART between badges or other devices using a 3.5mm
-audio cable.
-
-Baud rates up to 5mbit are supported in theory, but data corruption is likely
-with higher rates.
-
-Use baud rate 31250 for MIDI.
-
-Note that `badge_link.enable()` will refuse to enable line out if the cable is
-not connected. Connect it first. Connecting headphones with badge link enabled
-is not recommended, especially not when wearing them.
-
-Example usage:
-
-On both badges:
-
-```
-import badge_link
-from machine import UART
-badge_link.enable(badge_link.PIN_MASK_ALL)
-```
-
-On badge 1, connect the cable to line out, and configure uart with tx on tip
-(as an example)
-
-```
-uart = UART(1, baudrate=115200, tx=badge_link.PIN_INDEX_LINE_OUT_TIP, rx=badge_link.PIN_INDEX_LINE_OUT_RING)
-```
-
-On badge 2, connect the cable to line in, and configure uart with tx on ring:
-
-```
-uart = UART(1, baudrate=115200, tx=badge_link.PIN_INDEX_LINE_IN_RING, rx=badge_link.PIN_INDEX_LINE_IN_TIP)
-```
-
-Then write and read from each side:
-
-```
-uart.write("hiiii")
-uart.read(5)
-```
-
### Documentation
Automatically updated on CI runs of the main branch and lives under https://docs.flow3r.garden