powerpods/docs/DOCUMENTATION.md

# Powerpod ESP-Firmware — Dokumentation

Vollständige Referenz für das ESP-IDF-Projekt unter `main/` und `components/`. Diese Doku beschreibt **nur die Firmware** — kein goTool, keine Host-Implementierung.

- **Architektur & Datenflüsse:** [`ARCHITECTURE.md`](ARCHITECTURE.md)  
- **Neues Feature end-to-end:** [`adding-a-feature.md`](adding-a-feature.md)

---

## Inhaltsverzeichnis

1. [Projektziel](#1-projektziel)
2. [Hardware und Pins](#2-hardware-und-pins)
3. [Build und Flash](#3-build-und-flash)
4. [Boot-Konfiguration](#4-boot-konfiguration)
5. [UART-Protokoll](#5-uart-protokoll)
6. [ESP-NOW-Protokoll](#6-esp-now-protokoll)
7. [Befehlsreferenz (UART)](#7-befehlsreferenz-uart)
8. [OTA](#8-ota)
9. [BMA456 Beschleunigungssensor](#9-bma456-beschleunigungssensor)
10. [LED-Ring](#10-led-ring)
11. [Board-Input und Batterie](#11-board-input-und-batterie)
12. [Persistenz (NVS)](#12-persistenz-nvs)
13. [Protobuf und Code-Generierung](#13-protobuf-und-code-generierung)
14. [Modulreferenz](#14-modulreferenz)
15. [Logging-Tags](#15-logging-tags)

---

## 1. Projektziel

**Powerpod** ist Firmware für ESP32-S3-Knoten in einem verteilten System:

- Ein **Master** spricht per **UART** mit einem externen Host und verwaltet bis zu **16 Slaves** über **ESP-NOW**.
- **Slaves** haben keinen UART-Befehlspfad; sie joinen über periodisches **Discover**, senden Heartbeats und liefern Sensor-/Statusdaten.
- Master und Slave nutzen **identisches Firmware-Image**; Rolle und Funknetz werden beim Boot erkannt.

Zielbild für den Host: Befehle an den Master senden; der Master steuert Slaves und **cached** deren Telemetrie (`client_registry`) für schnelle UART-Abfragen.

---

## 2. Hardware und Pins

> Pinbelegung ist in `powerpod.h` als vorläufig markiert — mit Schaltplan abgleichen.

| Signal | GPIO | Datei / Modul |
|--------|------|----------------|
| DIP Master/Slave | 4 | `powerpod.h` — Low = Master |
| I2C SCL / SDA | 5 / 6 | IO-Expander `0x20`, BMA456 `0x18` |
| Expander DIP-Bank (8) | PCF/TCA @ `0x20` | DIP1–7 = Netzwerk 1–7 (one-hot); **DIP8 ON = BLE host**, OFF = UART. High-Nibble auf PCB vertauscht → `reverse_high_nibble_lut`. Wechsel nur nach Reboot. |
| UART1 TX / RX | **2 / 3** | `uart.h` (Adapter: ESP-TX → Host-RX); nur wenn DIP8 = UART |
| LED-Ring (WS2812) | 7 | `led_ring.c` |
| BMA456 Interrupt | 10 | `bosch456.c` |
| Taster | 12 | `board_input.c` |
| LiPo ADC 1 | 1 | `board_input.c` |
| LiPo ADC 2 | 11 | `board_input.c` |

**Host-Protokoll (UART oder BLE):** Gleiches Framing (`0xAA`…`0xCC`) + nanopb. **UART:** `UART_NUM_1`, **921600** Baud, 8N1. **BLE:** Gerät `Powerpod`, NUS-UUIDs `6e400001`/`6e400002` (Write=RX, Notify=TX). goTool CLI: `-port …` oder `-ble` / `-ble-name Powerpod`. **`gotool serve`** startet ohne Pflicht-Gerät; Dashboard/REST/WS verbinden UART oder BLE dynamisch (`-port`/`-ble` nur optionale Vorbelegung). **OTA** über UART oder BLE (DIP8); BLE braucht ATT MTU ≥ ~219 für 200-B-Chunks. Bei BLE + Accel-Stream: periodische `BLE_STREAM_TICK`-Notifies (`period_ms` 10–16; während OTA pausiert).

**ESP-IDF-Log (Debug):** `esp_log_*` geht auf **UART0** (Standard-Konsole, typisch USB am Dev-Board, **115200** Baud, `CONFIG_ESP_CONSOLE_UART_NUM=0`). Das ist **getrennt** vom Host-UART1 — goTool liest keine `esp_log`-Ausgabe. Ohne angeschlossenes Debug-Kabel werden aktivierte Logs trotzdem formatiert und an UART0 gesendet (CPU-Overhead bleibt); nur `ESP_LOG_NONE` / Level-Filter vermeiden die Arbeit.

**I2C:** 100 kHz, interne Pull-ups, gemeinsamer Bus für Expander und BMA456H.

---

## 3. Build und Flash

**Ziel-Chip:** ESP32-S3 (ESP-IDF).

```bash
source ~/esp/esp-idf/export.sh   # oder export.fish
cd /pfad/zu/powerpod
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor
```

- **Git-Hash** wird beim Build in `POWERPOD_GIT_HASH` eingebettet (`main/CMakeLists.txt`).
- **Firmware-Version:** `POWERPOD_FW_VERSION` (Default `1` in `esp_now_comm.c` / `cmd_version.c`).

**Komponenten:**

| Pfad | Inhalt |
|------|--------|
| `main/` | Anwendungslogik |
| `components/bma456/` | Bosch BMA456H-Treiber (Vendor) |
| `libs/nanopb/` | Protobuf-Codec für Embedded |

---

## 4. Boot-Konfiguration

### 4.1 Initialisierungsreihenfolge (`powerpod.c`)

1. `pod_settings_init()` — NVS
2. `board_input_init_adc_only()` — LiPo-ADC
3. Bei `POWERPOD_BATTERY_UV_ENABLE`: `battery_uv_evaluate_boot()` → ggf. Energiesparmodus (nur LED + ADC, **kein** weiterer Init)
4. DIP → `app_config.master`
5. I2C + IO-Expander → `app_config.network` (1–7) + `app_config.host_ble` (DIP8)
6. `init_bma456()` — optional, bei Fehler weiter ohne Sensor
7. `pod_settings_apply_accel_deadzone()` wenn Sensor da
8. OTA-Partition → `app_config.running_partition`
9. `board_input_start_lipo_monitor()` + `board_input_init_button()`
10. `esp_now_comm_init(&app_config)` — **normaler Pfad** (Master + Slave)
11. `led_ring_init()`
12. **Nur Master:** `cmd_queue` → `init_cmdHandler` → `init_uart` **oder** `init_ble_host` → alle `cmd_*_register()`

### 4.2 Master vs. Slave

| Funktion | Master | Slave |
|----------|--------|-------|
| Host Command-Handler (UART oder BLE) | Ja | Nein |
| ESP-NOW Discover senden | Ja (Broadcast) | Nein |
| ESP-NOW auf Discover reagieren | Nein | Ja |
| `client_registry` für Fremdknoten | Ja | Nein (nur eigener Join-State) |

---

## 5. UART-Protokoll

*(Transport + Anwendung — Datenfluss-Diagramme in [`ARCHITECTURE.md`](ARCHITECTURE.md) §4–5.)*

### 5.1 Rahmen

| Byte | Inhalt |
|------|--------|
| 0 | `0xAA` Start |
| 1–2 | Länge N little-endian (1–1024) |
| 3…N+2 | Payload |
| N+3 | XOR-Checksum über Payload |
| N+4 | `0xCC` Stopp |

Implementierung: `uart.c` — `parse_uart_byte()`, `uart_send_framed()`.

### 5.2 Anwendungs-Payload

| Offset | Bedeutung |
|--------|-----------|
| 0 | `MessageType` (siehe Enum in `uart_messages.proto`) |
| 1… | nanopb `UartMessage` (ohne separates type-Feld im protobuf-Teil) |

**Antworten** nutzen dieselbe Struktur: Byte 0 = Response-Typ, Rest = kodierte `UartMessage`.

### 5.3 Handler-Pipeline

1. `uart_read_task` parst Frames → `uart_enqueue_packet`
2. `generic_msg_t` → `cmd_queue`
3. `vCmdDispatcherTask` → registrierter `msg_callback_t`
4. Handler: `uart_cmd_decode(data, len, &msg)` — `data` ist **nur** protobuf-Teil; bei `len > 0` strikt (Decode/`which_payload`-Fehler → Fehlerantwort)
5. `ota_session_uart_cmd_allowed()` — während OTA nur OTA-Befehle
6. Antwort: `uart_cmd_init_response()` + Felder setzen + `uart_cmd_send()`

Hilfsmakro für Request-Felder:

```c
UART_CMD_REQ(&uart_msg, alox_UartMessage_accel_deadzone_request_tag, accel_deadzone_request)
```

---

## 6. ESP-NOW-Protokoll

*(Join, Tasks, Registry — [`ARCHITECTURE.md`](ARCHITECTURE.md) §6.)*

### 6.1 Grundlagen

- WiFi **STA**, keine AP-Verbindung.
- **Kanal** = `app_config.network` (1–13).
- Payload = ein `EspNowMessage` (nanopb), max. `ESP_NOW_MAX_DATA_LEN`.
- Schema: `main/proto/esp_now_messages.proto`.

### 6.2 Nachrichtentypen

| Type | Richtung | Payload | Zweck |
|------|----------|---------|--------|
| `ESPNOW_DISCOVER` | M→Broadcast | `discover.network` | Slaves finden Master |
| `ESPNOW_SLAVE_INFO` | S→M | `slave_info` | Erste Registrierung |
| `ESPNOW_HEARTBEAT` | S→M | `heartbeat` | Keepalive 1 s |
| `ESPNOW_SET_ACCEL_DEADZONE` | M→S | `accel_deadzone` | Deadzone LSB |
| `ESPNOW_SET_TAP_CONFIG` | M→S | `tap_config` | Multitap-Parameter + NVS |
| `ESPNOW_SET_ACCEL_STREAM` | M→S | `accel_stream` | Stream poll ~10 ms, TX on deadzone change |
| `ESPNOW_ACCEL_SAMPLE` | S→M | `accel_sample` | x/y/z Roh-LSB |
| `ESPNOW_SET_TAP_NOTIFY` | M→S | `tap_notify` | Tap-Arten filtern |
| `ESPNOW_TAP_EVENT` | S→M | `tap_event` | kind 1/2/3 |
| `ESPNOW_BATTERY_QUERY` | M→S | `battery_query` | On-demand |
| `ESPNOW_BATTERY_REPORT` | S→M | `battery_report` | mV LiPo 1/2 |
| `ESPNOW_LED_RING` | M→S | `led_ring` | Wie UART LED_RING |
| `ESPNOW_FIND_ME` | M→S | `find_me` | LED-Locate |
| `ESPNOW_RESTART` | M→S | `restart` | Reboot Slave |
| `ESPNOW_UNICAST_TEST` | M→S | `unicast_test` | Link-Test |
| `ESPNOW_ECHO_PING` | M→S | `echo_ping` | Latenztest (Host-Timestamp + `master_time_us`) |
| `ESPNOW_ECHO_PONG` | S→M | `echo_pong` | Echo unverändert zurück zum Master |
| `ESPNOW_OTA_*` | M↔S | `ota_*` | Firmware-Verteilung |

### 6.3 Zeitkonstanten (`esp_now_comm.c`)

| Konstante | Wert |
|-----------|------|
| Discover-Intervall | 500 ms |
| Heartbeat | 1000 ms |
| Client-Timeout (Master) | 3 × Heartbeat = 3 s → `available=false` |
| Master-Verlust (Slave) | 5 s ohne Discover |
| Accel-Stream | Poll 10 ms; TX nur bei Deadzone-Änderung (best-effort) |
| Batterie-Report | 30 s (+ einmal 150 ms nach Join) |
| Echo-Ping Timeout (Master) | 500 ms (`ESPNOW_ECHO_PING_TIMEOUT_MS`) |

### 6.4 `EspNowSlavePresence`

Felder: `network`, `mac` (6 B), `version`, `slave_id`, `available`, `used`.

- `slave_id` = letztes Oktett der STA-MAC.
- Registry auf dem Master indexiert über **Sender-MAC** der ESP-NOW-Callback.

---

## 7. Befehlsreferenz (UART)

Nur auf dem **Master** registriert (`powerpod.c`). IDs aus `MessageType` in `uart_messages.proto`.

| ID | Name | Modul | Kurzbeschreibung |
|----|------|-------|------------------|
| 1 | ACK | — | Reserviert |
| 2 | ECHO | — | Reserviert |
| 3 | VERSION | `cmd_version.c` | FW-Version, Git-Hash, OTA-Partition |
| 4 | CLIENT_INFO | `cmd_client_info.c` | Liste `client_registry` |
| 5 | CLIENT_INPUT | — | Geplant |
| 6 | ACCEL_DEADZONE | `cmd_accel_deadzone.c` | Get/Set Deadzone lokal + ESP-NOW |
| 7 | ESPNOW_UNICAST_TEST | `cmd_espnow_unicast_test.c` | Link-Test zu Slave |
| 8 | LED_RING | `cmd_led_ring.c` | Ring lokal / ESP-NOW |
| 16 | OTA_START | `cmd_ota.c` | Host-OTA beginnen (UART oder BLE) |
| 17 | OTA_PAYLOAD | `cmd_ota.c` | Chunk ≤200 B |
| 18 | OTA_END | `cmd_ota.c` | Abschluss + ESP-NOW-Verteilung |
| 19 | OTA_STATUS | `cmd_ota.c` | Gerät → Host Status |
| 20 | OTA_START_ESPNOW | `cmd_ota.c` | Nur ESP-NOW aus Staging |
| 21 | OTA_SLAVE_PROGRESS | `cmd_ota_slave_progress.c` | Fortschritt pro Slave |
| 22 | FIND_ME | `cmd_espnow_find_me.c` | LED Locate |
| 23 | RESTART | `cmd_restart.c` | Master oder Slave reboot |
| 25 | ACCEL_STREAM | `cmd_accel_stream.c` | ESP-NOW Accel-Stream an/aus (+ `period_ms` für BLE-Push) |
| 26 | BATTERY_STATUS | `cmd_battery.c` | Cache LiPo Master + Slaves |
| 27 | TAP_NOTIFY | `cmd_tap_notify.c` | Tap-Weiterleitung konfigurieren |
| 29 | CACHE_STATUS | `cmd_cache_status.c` | Accel + Tap Cache (ein Round-Trip) |
| 33 | BLE_STREAM_TICK | `ble_stream.c` | Master→Host Notify (nur BLE): Snapshot + `esp_timestamp_us` |
| 30 | ESPNOW_ECHO_PING | `cmd_espnow_echo_ping.c` | Timestamp-Echo über ESP-NOW (Latenztest) |
| 31 | SET_LOG_LEVEL | `cmd_set_log_level.c` | ESP-IDF-Log-Level global (`"*"`) lesen/setzen |
| 32 | TAP_CONFIG | `cmd_tap_config.c` | BMA456 Multitap-Parameter + NVS |

### 7.1 VERSION (3)

- **Request:** nur Typ-Byte `0x03` oder leerer protobuf-Body.
- **Response:** `version`, `git_hash`, `running_partition`.

### 7.2 CLIENT_INFO (4)

- **Response:** wiederholtes `ClientInfo` pro Registry-Eintrag: `id`, `mac`, `version`, `available`, `used`, `last_ping`, `last_success_ping`, Tap-/Stream-Flags.

### 7.3 ACCEL_DEADZONE (6)

- **Request:** `write`, `deadzone`, `client_id` (0=lokal), `all_clients`.
- **Write Master:** Registry + `esp_now_comm_send_accel_deadzone` pro Slave; lokal `bma456` + NVS.
- **Slave-Empfang:** `handle_slave_accel_deadzone` in `esp_now_comm.c`.

### 7.4 ACCEL_STREAM (25)

- Optional `period_ms` (10–16): BLE-Host-Push-Intervall für `BLE_STREAM_TICK` (UART ignoriert; Default 10).
- Master setzt `client_registry_set_accel_stream` und sendet `ESPNOW_SET_ACCEL_STREAM`.
- Slave-Task `accel_stream_task` pollt alle 10 ms; sendet `ESPNOW_ACCEL_SAMPLE` nur wenn eine Achse die Accel-Deadzone seit dem letzten gesendeten Sample überschreitet (best-effort / `send_best_effort`; Baseline-Reset beim Stream-Enable).

### 7.5 TAP_NOTIFY (27)

- Konfiguriert auf Slave welche Tap-Arten `ESPNOW_TAP_EVENT` auslösen.
- Tap-Quelle: BMA456-Interrupt → `on_bma456_tap` in `esp_now_comm.c`.

### 7.5a TAP_CONFIG (32)

- **Request:** `write`, `client_id` (0=lokal), `all_clients`, Multitap-Felder (`tap_sens_thres` … `enable_triple`).
- **Write:** `bma456_set_tap_config` + NVS `tap_cfg` lokal; Slaves via `ESPNOW_SET_TAP_CONFIG`.
- Boot: `pod_settings_apply_tap_config()` nach `init_bma456()`.

### 7.6 CACHE_STATUS (29)

- **Request:** leer.
- **Response:** pro Slave mit Stream und/oder Tap-Notify: gecachte Accel-Werte (`age_ms`) und konsumierte Tap-Events (`client_registry_take_tap`).

### 7.7 BATTERY_STATUS (26)

- Liest **nur Cache** — keine ESP-NOW-Roundtrip-Pflicht pro Abfrage.
- Master-Batterie: `client_registry_set_master_battery` (Monitor-Task).

### 7.8 LED_RING (8)

| mode | Bedeutung |
|------|-----------|
| 0 | Clear |
| 1 | Progress 0–100 % |
| 2 | Digit 0–10 |
| 3 | Blink |
| 4 | Find-me (RGB-Sequenz) |
| 5 | Solid color |

`client_id=0` nur Master-Ring; `>0` ESP-NOW; `all_clients` Broadcast über Registry.

### 7.9 FIND_ME (22) / RESTART (23)

- `client_id=0`: lokaler Master (`led_ring_find_me` / `pod_schedule_restart`).
- `client_id>0`: ESP-NOW Unicast zum Slave.

### 7.10 ESPNOW_UNICAST_TEST (7)

Minimaler Master→Slave-Ping; Slave loggt `UNICAST TEST OK`.

### 7.11 ESPNOW_ECHO_PING (30)

Round-Trip-Latenztest zu einem **Slave** (`client_id` > 0, muss in der Registry sein).

**Ablauf:**

1. Host (goTool) setzt `timestamp_us` (Unix-µs) und sendet `EspNowEchoPingRequest` per UART.
2. Master (`cmd_espnow_echo_ping.c`) löst MAC aus Registry auf, ruft `esp_now_comm_echo_ping()` auf.
3. Master sendet `ESPNOW_ECHO_PING` mit `host_timestamp_us` und `master_time_us` (`esp_timer_get_time()` kurz vor Send).
4. Slave (`handle_echo_ping`) antwortet mit `ESPNOW_ECHO_PONG` (Felder unverändert).
5. Master empfängt Pong, berechnet `esp_rtt_us = esp_timer_get_time() - master_time_us`, antwortet per UART.

**Request:** `client_id`, `timestamp_us` (vom Host gesetzt).

**Response:** `success`, `client_id`, `timestamp_us` (echoed), `esp_rtt_us` (nur bei Erfolg).

| Feld | Quelle | Bedeutung |
|------|--------|-----------|
| `timestamp_us` | Host → Slave → Host | Korrelations-ID; muss mit Request übereinstimmen |
| `esp_rtt_us` | Master | Rohe µs-Differenz von `esp_timer_get_time()` (Ping-Send → Pong-Empfang im `recv_cb`) |

**Implementierung:** `main/cmd/cmd_espnow_echo_ping.c`, `esp_now_comm_echo_ping()` in `esp_now_master.c`, Slave `handle_echo_ping` in `esp_now_slave.c`.

**Host-seitig (goTool):** `rtt_ms` = volle UART-Kette (Send bis Response-Empfang); unabhängig von `esp_rtt_us`.

### 7.12 SET_LOG_LEVEL (31)

Laufzeit-Steuerung des **globalen** ESP-IDF-Log-Levels auf dem Master (`esp_log_level_set("*", …)`). Kein ESP-NOW, kein NVS — nur Master.

**Request:** `write`, `level` (`esp_log_level_t`: 0=NONE, 1=ERROR, 2=WARN, 3=INFO, 4=DEBUG, 5=VERBOSE).

| `write` | Verhalten |
|---------|-----------|
| `false` / leer | Aktuelles Level lesen (`esp_log_level_get("*")`) |
| `true` | Level setzen; ungültige Werte (>5) → `success=false` |

**Response:** `success`, `level` (aktuell bzw. gesetzt).

**Boot-Default:** `CONFIG_LOG_DEFAULT_LEVEL` in `sdkconfig` (aktuell **INFO** = 3). Kann per UART/Web-UI zur Laufzeit geändert werden; nach Reboot gilt wieder der sdkconfig-Wert.

**Ausgabe:** Logs erscheinen auf **UART0** (Debug-USB), nicht auf dem Host-UART1 (goTool).

```bash
go run . -port /dev/ttyUSB0 log-level
go run . -port /dev/ttyUSB0 log-level -set -level 3
```

---

## 8. OTA

### 8.1 Host-OTA (nur Master, UART oder BLE)

Implementierung: `ota_uart.c`, Steuerung `cmd/cmd_ota.c`. Gleiches Protokoll über DIP8-Host (UART oder BLE NUS).

| Phase | Host → Master | Master → Host |
|-------|---------------|---------------|
| Start | `OTA_START` + `total_size` | `OTA_STATUS` preparing → ready |
| Daten | `OTA_PAYLOAD` ≤200 B, `seq` | `block_ack` je 4096 B Flash |
| Ende | `OTA_END` | success/failed; startet ESP-NOW-Verteilung |

- Inaktive Partition: `esp_ota_get_next_update_partition()`.
- LED-Ring zeigt Fortschritt (blau Schreiben, grün Verteilung).
- BLE: ATT MTU ≥ ~219 (preferred 517); große Antworten werden über mehrere Notifies gestückelt; `BLE_STREAM_TICK` pausiert während `ota_session_busy()`.
- **BLE+ESP-NOW Coex:** Tag `wifi` auf `ESP_LOG_NONE` (WiFi-Task-Stack + Error-Logs → Overflow/Panic); während ESP-NOW-Dist `OTA_STATUS` DISTRIBUTING max. ~4/s und kürzere BLE-Notify-Retries.
- **App-Rollback** (`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE`): neues Image bootet als `PENDING_VERIFY`. `ota_confirm` markiert nach ~8 s stabilem Lauf `mark_app_valid`; Crash/Reset davor → Bootloader rollt auf die vorherige App zurück. Während `PENDING_VERIFY` ist ein neues `OTA_START` blockiert.

### 8.2 ESP-NOW-OTA (Master → Slaves)

`ota_espnow.c` — gleiche Status-Codes wie Host-OTA.

1. `ESPNOW_OTA_START` + `total_size` → Slave `ota_espnow_slave_on_start`
2. `ESPNOW_OTA_PAYLOAD` bis 200 B → 4 KiB Buffer auf Slave
3. `ESPNOW_OTA_END` → Boot-Partition setzen + automatischer Reboot
4. Slave antwortet `ESPNOW_OTA_STATUS` (mit `send_message_ex` + Semaphore auf Master)

Während Distribution: keine Client-Timeouts in der Registry (Heartbeats werden im recv_cb verworfen). Nach Erfolg: Master und Slaves starten automatisch neu (Rollback-Confirm siehe 8.1).

### 8.3 OTA_SLAVE_PROGRESS (21)

Abfrage laufender oder letzter ESP-NOW-Verteilung: pro Slave `bytes_written`, `status`, `error`.

---

## 9. BMA456 Beschleunigungssensor

| Thema | Detail |
|-------|--------|
| Wrapper | `bosch456.c` / `bosch456.h` |
| Chip-Variante | BMA456**H** (`bma456h.c` im Component) |
| I2C | Adresse 0x18, 100 kHz |
| Polling | Task ~10 Hz |
| Interrupt GPIO 10 | Single/Double/Triple Tap |
| Deadzone | Software-Filter für Logs/Stream (Default 100 LSB) |
| API | `bma456_read_accel`, `bma456_set_accel_deadzone`, `bma456_set_tap_handler` |

Ohne Sensor: `bma456_is_ready() == false`, Firmware läuft weiter.

---

## 10. LED-Ring

- **95 LEDs**, WS2812 über RMT (`led_ring.c`).
- Segment-Karten für Ziffern 0–10 in `digit_lookup[]`.
- **Kein** lokaler Demo-Loop — Anzeige nur über UART (`cmd_led_ring.c`) oder ESP-NOW `ESPNOW_LED_RING`.
- Helligkeit: `intensity` 0 → Default ~5 % (`LED_RING_DEFAULT_INTENSITY`).
- Modi: `0` clear … `5` color, `6` **battery-low** (erste 4 LEDs rot ~10 %, 5 s).

---

## 11. Board-Input und Batterie

`board_input.c`:

- **Taster** GPIO 12 — Logging bei Druck.
- **LiPo-ADC** GPIO 1 und GPIO 11 (Pin-Spannung in mV).
- Master: `master_monitor_task` aktualisiert Master-Batterie alle 30 s.
- Slave: `slave_send_battery_report_to_master` nach Join, Heartbeat und Query.

Spannungen in Millivolt in Registry und `BATTERY_STATUS`-UART.

### Software-UV-Schutz (`battery_uv.c`)

Aktivierbar mit `POWERPOD_BATTERY_UV_ENABLE` in `powerpod.h` (CMake-Override möglich). Runtime zusätzlich NVS `uv_en` (Default **aus**) — UART `BATTERY_UV` / Dashboard / ESP-NOW `ESPNOW_SET_BATTERY_UV`.

| Zustand | ADC-Schwelle | Logik |
|---------|--------------|-------|
| Extern / kein Pack | < 100 mV | Alle gültigen Kanäle → normaler Boot |
| UV | 100…2299 mV | Ein gültiger Kanal reicht |
| Geladen | ≥ 3000 mV | Alle nicht-absent gültigen Kanäle |

- NVS-Keys `uv_latch`, `uv_en` in `pod_settings.c`
- Boot: ADC früh, bei UV nur LED + ADC-Poll (kein ESP-NOW/WiFi/UART/I2C/Button); übersprungen wenn `uv_en=0`
- Runtime: `battery_uv_poll()` im LiPo-Monitor (2 Samples Debounce), gated by `uv_en`
- UART `BATTERY_UV`: `client_id` / `all_clients`; Disable cleart Latch
- LED-Anzeige: Mode `6` battery-low (`led_ring_show_battery_low`)

---

## 12. Persistenz (NVS)

`pod_settings.c` — Namespace `powerpod`:

| Key | Inhalt |
|-----|--------|
| `accel_dz` | Accel-Deadzone LSB |
| `tap_cfg` | BMA456 Multitap-Config (Blob) |
| `uv_latch` | Software-UV-Zustand (`1` = Energiesparmodus) |
| `uv_en` | Runtime-Enable UV-Schutz (`0`/`1`, fehlend = aus) |

Gespeichert bei lokalem Set (UART `client_id=0`, ESP-NOW auf Slave). Geladen nach `init_bma456()`.

---

## 13. Protobuf und Code-Generierung

```bash
make proto_generate        # beide Schemas
make proto_generate_uart   # nur uart_messages.proto
make proto_generate_espnow # nur esp_now_messages.proto
```

**Ausgabe:** `main/proto/*.pb.c`, `*.pb.h`  
**Optionen:** `main/proto/uart_messages.options` (nanopb max_size etc.)

Includes in generierten `.pb.c` müssen `"uart_messages.pb.h"` heißen (nicht `main/proto/...`).

**Paketname protobuf:** `alox` → C-Prefix `alox_`.

---

## 14. Modulreferenz

### 14.1 Kern

| Datei | Rolle |
|-------|--------|
| `powerpod.c` | `app_main`, Init, Master-Register |
| `app_config.h` | Laufzeit-Konfiguration |
| `cmd_handler.c` | Queue + Dispatcher |
| `uart.c` | Framing |
| `uart_proto.c` | UartMessage send |
| `uart_cmd.c` | Handler-Hilfen |

### 14.2 Kommunikation

| Datei | Rolle |
|-------|--------|
| `esp_now_comm.c` | Init, recv-Router |
| `esp_now_core.c` | WiFi, Peer, gemeinsamer Send |
| `esp_now_master.c` | Master-Tasks, Registry, Unicast send |
| `esp_now_slave.c` | Join, Heartbeat, Accel/Tap send |
| `esp_now_proto.c` | nanopb für EspNowMessage |
| `client_registry.c` | Slave-Tabelle + Telemetrie-Cache |

### 14.3 Befehle (`main/cmd/`)

| Datei | UART-Typ |
|-------|----------|
| `cmd_version.c` | VERSION |
| `cmd_client_info.c` | CLIENT_INFO |
| `cmd_accel_deadzone.c` | ACCEL_DEADZONE |
| `cmd_accel_stream.c` | ACCEL_STREAM |
| `cmd_tap_config.c` | TAP_CONFIG |
| `cmd_tap_notify.c` | TAP_NOTIFY |
| `cmd_cache_status.c` | CACHE_STATUS |
| `cmd_battery.c` | BATTERY_STATUS |
| `cmd_led_ring.c` | LED_RING |
| `cmd_espnow_find_me.c` | FIND_ME |
| `cmd_restart.c` | RESTART |
| `cmd_espnow_unicast_test.c` | ESPNOW_UNICAST_TEST |
| `cmd_espnow_echo_ping.c` | ESPNOW_ECHO_PING |
| `cmd_set_log_level.c` | SET_LOG_LEVEL |
| `cmd_ota.c` | OTA_* |
| `cmd_ota_slave_progress.c` | OTA_SLAVE_PROGRESS |

### 14.4 Domäne

| Datei | Rolle |
|-------|--------|
| `bosch456.c` | Accelerometer + Tap |
| `led_ring.c` | LED-Anzeige |
| `board_input.c` | Taster, ADC |
| `battery_uv.c` | Software-UV-Schutz, Energiesparmodus |
| `pod_settings.c` | NVS |
| `pod_reboot.c` | Verzögerter Restart |
| `ota_uart.c` | Flash-Puffer UART-OTA |
| `ota_espnow.c` | OTA Master/Slave; Slave-Work-Queue |
| `ota_session.c` | OTA-Sperre für UART-Dispatcher |

### 14.5 Protobuf

| Datei | Rolle |
|-------|--------|
| `proto/uart_messages.proto` | UART-Vertrag |
| `proto/esp_now_messages.proto` | ESP-NOW-Vertrag |
| `proto/pb_encode.c`, `pb_decode.c`, `pb_common.c` | nanopb Runtime |

---

## 15. Logging-Tags

**Level zur Laufzeit:** UART `SET_LOG_LEVEL` (31) oder Dashboard „ESP Log-Level“ — steuert nur die Konsolen-Ausgabe auf UART0, nicht das Host-Protokoll.

| Tag | Modul |
|-----|--------|
| `[Main]` | powerpod.c |
| `[LOG_LVL]` | cmd_set_log_level.c |
| `[UART]` | uart.c |
| `[CMDH]` | cmd_handler.c |
| `[UART_CMD]` | uart_cmd.c |
| `[ESPNOW]` | esp_now_comm.c |
| `[CLIENTS]` | client_registry.c |
| `[BMA456]` | bosch456.c |
| `[VERSION]` etc. | jeweiliger cmd_* |

Typischer Ablauf bei UART-Befehl:

```
[UART] received message cmd=0x06 len=…
[CMDH] trigger command ACCEL_DEADZONE (0x06)
[ACCEL_DZ] …
```

---

## Anhang: Neues UART-Kommando hinzufügen

1. `uart_messages.proto` erweitern → `make proto_generate_uart`
2. `cmd/cmd_neu.c` mit `handle_*` + `uart_cmd_register()`
3. In `powerpod.c` `cmd_neu_register()` aufrufen (nur Master-Zweig)
4. Bei Slave-Bedarf: `esp_now_messages.proto` + `esp_now_comm_send_*` + Slave-Zweig in `espnow_recv_cb`

Siehe [`adding-a-feature.md`](adding-a-feature.md) für ein vollständiges Beispiel (Find Me).