Consolidate flash/debug tooling on espresso.py; remove stale scripts

.cursor/rules/general.mdc

@@ -15,7 +15,7 @@ alwaysApply: true
 ```bash
 python build.py           # Build for ESP32
 python build.py esp32s3   # Build for ESP32-S3
-python flash.py           # Flash to device
+python espresso.py flash  # Flash to device
 python monitor.py         # Serial monitor
 ./gen_parser.sh           # Regenerate parser from language.owl
 ```

.cursor/rules/python-tools.mdc

@@ -19,11 +19,9 @@ Python scripts in this project are **build/flash/monitor tools**, not the main a
 | Script           | Purpose                                         |
 | ---------------- | ----------------------------------------------- |
 | `build.py`       | Build for ESP32/ESP32-S3 (wraps `idf.py build`) |
-| `flash.py`       | Flash firmware to device                        |
 | `monitor.py`     | Serial monitor                                  |
-| `espresso.py`    | Deployment tool                                 |
+| `espresso.py`    | Flash & control ESP32 (flash/erase/enable/reset/coredump; `--host` for remote) |
 | `configure.py`   | Project configuration                           |
-| `core_dumper.py` | Analyze core dumps                              |
 
 ## Pattern
 

.github/zip_content.txt

@@ -2,13 +2,10 @@ build/bootloader/bootloader.bin
 build/partition_table/partition-table.bin
 build/lizard.elf
 build/lizard.bin
-backtrace.sh
 configure.py
-core_dumper.py
-esp.py
 espresso.py
-flash.py
 monitor.py
+upload_ssh.py
 README.md
 requirements.txt
 LICENSE

AGENTS.md

@@ -99,7 +99,7 @@ lizard/
 ├── docs/                   # MkDocs documentation
 ├── examples/               # Usage examples (ROS integration, trajectories)
 ├── build.py               # Build script (wraps idf.py)
-├── flash.py               # Flash script
+├── espresso.py            # Flash & control script (ESP32 / ESP32-S3)
 ├── monitor.py             # Serial monitor
 ├── language.owl           # Lizard grammar definition (Owl parser generator)
 └── gen_parser.sh          # Regenerates parser.c from language.owl
@@ -135,8 +135,8 @@ python build.py esp32s3 --clean
 ### Flash & Monitor
 
 ```bash
-# Flash to connected device
-python flash.py
+# Flash to connected device (add --device <port> if not auto-detected)
+python espresso.py flash
 
 # Monitor serial output
 python monitor.py
@@ -427,10 +427,10 @@ idf.py monitor
 
 ### Core Dumps
 
-If the device crashes, use `core_dumper.py` to analyze:
+If the device crashes, use `espresso.py coredump` to analyze:
 
 ```bash
-python core_dumper.py
+python espresso.py coredump
 ```
 
 ### Common Debug Techniques

docs/getting_started.md

@@ -4,7 +4,7 @@
 
 1. Download and unpack the zip file of the [latest release](https://github.com/zauberzeug/lizard/releases).
 2. Attach an Espressif ESP32 microcontroller via serial to your computer.
-3. Run `sudo ./espresso.py flash /dev/<serial device name>` to install Lizard on the ESP32.
+3. Run `sudo ./espresso.py flash --device /dev/<serial device name>` to install Lizard on the ESP32.
 
 ## Try Out
 

docs/tools.md

@@ -7,7 +7,7 @@
 To install Lizard on your ESP32 run
 
 ```bash
-sudo ./espresso.py flash <device_path>
+sudo ./espresso.py flash --device <device_path>
 ```
 
 Note that flashing may require root access (hence the sudo).
@@ -21,6 +21,18 @@ On boards with a native USB-Serial-JTAG port (e.g. ESP32-S3), prefer that port o
 
 The `espresso.py` script can also upload firmware on a [Robot Brain](https://www.zauberzeug.com/product-robot-brain.html)
 where the microcontroller is connected to the pin header of an NVIDIA Jetson computer.
+This requires a Jetson Orin (L4T 35 or 36);
+for Nano/Xavier Robot Brains use release 0.12.x or earlier, which still ships `flash.py`.
+
+To flash a Robot Brain over the network from a development machine, pass `--host`.
+This rsyncs the binaries and `espresso.py` to the target and runs the command there over SSH:
+
+```bash
+./espresso.py flash --host user@robot-brain[:path]
+```
+
+`--host` works for every command (`flash`, `erase`, `enable`, `disable`, `reset`, `release_pins`, `coredump`),
+so e.g. `./espresso.py erase --host user@robot-brain` performs a remote recovery erase.
 
 ## Interaction
 
@@ -158,13 +170,35 @@ To upload the compiled firmware you can use the `./espresso.py` command describe
 
 ### Backtrace
 
-In case Lizard terminates with a backtrace printed to the serial terminal, you can use the following script to print corresponding source code lines.
+In case Lizard terminates with a backtrace printed to the serial terminal,
+you can translate the addresses to source code lines with the `addr2line` tool from the ESP-IDF toolchain.
+Make sure the toolchain is on your `PATH` (e.g. by sourcing `. $IDF_PATH/export.sh`)
+and that a compiled ELF file is located at `build/lizard.elf`.
+Use the `addr2line` that matches the active ESP-IDF toolchain.
+On ESP-IDF 5.2 and newer, the unified Xtensa binary below covers both ESP32 and ESP32-S3.
+
+```bash
+xtensa-esp-elf-addr2line -e build/lizard.elf <addresses>
+```
+
+### Core Dumps
+
+If Lizard crashes, the ESP32 can store a core dump that you read back over the serial device:
 
 ```bash
-./backtrace.sh <addresses>
+./espresso.py coredump            # print core dump info
+./espresso.py coredump --debug    # start a GDB debug session, then return to the shell
 ```
 
-Note that the script assumes Espressif IDF tools being installed at `~/esp/esp-tools_4.4/` and a compiled ELF file being located at `build/lizard.elf`.
+This needs a compiled ELF at `build/lizard.elf` and, on the machine reading the dump,
+a sourced ESP-IDF environment: `esp_coredump` looks up the core dump partition via
+`$IDF_PATH/components/partition_table/parttool.py` and symbolizes with the matching GDB
+(`xtensa-esp32-elf-gdb`/`xtensa-esp32s3-elf-gdb`), so the pip package alone is not enough
+and it must be importable by `python3` (not just a CLI on the `PATH`).
+Add `--host user@robot-brain` to pull a core dump off a Robot Brain without logging in;
+the requirements above then apply to the Robot Brain itself, which reads the dump.
+Unlike flashing, the remote core dump runs without sudo,
+so the SSH user needs access to the serial device (e.g. membership in the `dialout` group).
 
 ### Releasing