Add software LiPo UV protection with energy-save boot.

Detect under-voltage on GPIO1/11, persist UV state in NVS, enter a minimal power mode without ESP-NOW, and recover after charge; expose LED mode 6 battery-low for host testing via goTool. Co-authored-by: Cursor <cursoragent@cursor.com>
Added LIPO 2 Reading
2026-06-23 18:22:52 +02:00 · 2026-06-23 17:54:18 +02:00
29 changed files with 498 additions and 96 deletions
@@ -52,7 +52,7 @@ Zielbild für den Host: Befehle an den Master senden; der Master steuert Slaves
 | BMA456 Interrupt | 10 | `bosch456.c` |
 | Taster | 12 | `board_input.c` |
 | LiPo ADC 1 | 1 | `board_input.c` |
-| LiPo ADC 2 | 12 | Entfällt wenn = Taster-GPIO |
+| LiPo ADC 2 | 11 | `board_input.c` |

 **UART (Host-Protokoll):** `UART_NUM_1`, **921600** Baud, 8N1, kein Flow-Control.

@@ -91,15 +91,17 @@ idf.py -p /dev/ttyUSB0 flash monitor
 ### 4.1 Initialisierungsreihenfolge (`powerpod.c`)

 1. `pod_settings_init()` — NVS
-2. DIP → `app_config.master`
-3. I2C + IO-Expander → `app_config.network` (1–8)
-4. `init_bma456()` — optional, bei Fehler weiter ohne Sensor
-5. `pod_settings_apply_accel_deadzone()` wenn Sensor da
-6. OTA-Partition → `app_config.running_partition`
-7. `board_input_init()`
-8. `esp_now_comm_init(&app_config)` — **immer** (Master + Slave)
-9. `led_ring_init()`
-10. **Nur Master:** `cmd_queue` → `init_cmdHandler` → `init_uart` → alle `cmd_*_register()`
+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–8)
+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` → alle `cmd_*_register()`

 ### 4.2 Master vs. Slave

@@ -397,6 +399,7 @@ Ohne Sensor: `bma456_is_ready() == false`, Firmware läuft weiter.
 - 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).

 ---

@@ -405,12 +408,26 @@ Ohne Sensor: `bma456_is_ready() == false`, Firmware läuft weiter.
 `board_input.c`:

 - **Taster** GPIO 12 — Logging bei Druck.
- **LiPo-ADC** GPIO 1 (und optional 2, wenn nicht Taster).
+- **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).
+
+| Zustand | ADC-Schwelle | Logik |
+|---------|--------------|-------|
+| UV | &lt; 2300 mV | Ein gültiger Kanal reicht |
+| Geladen | ≥ 3000 mV | Alle gültigen Kanäle |
+
+- NVS-Key `uv_latch` in `pod_settings.c`
+- Boot: ADC früh, bei UV nur LED + ADC-Poll (kein ESP-NOW/WiFi/UART/I2C/Button)
+- Runtime: `battery_uv_poll()` im LiPo-Monitor (2 Samples Debounce)
+- LED-Anzeige: Mode `6` battery-low (`led_ring_show_battery_low`)
+
 ---

 ## 12. Persistenz (NVS)
@@ -420,6 +437,7 @@ Spannungen in Millivolt in Registry und `BATTERY_STATUS`-UART.
 | Key | Inhalt |
 |-----|--------|
 | `accel_dz` | Accel-Deadzone LSB |
+| `uv_latch` | Software-UV-Zustand (`1` = Energiesparmodus) |

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

@@ -493,6 +511,7 @@ Includes in generierten `.pb.c` müssen `"uart_messages.pb.h"` heißen (nicht `m
 | `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 |
@@ -0,0 +1,2 @@
+win:
+	GOOS=windows GOARCH=386 go build .
@@ -33,7 +33,7 @@ go run . -port /dev/ttyUSB0 clients
 | `serve` | — | Web dashboard at `http://localhost:8080` (WebSocket live updates) |
 | `ota` | 16–19 | UART firmware upload to master; firmware then pushes to slaves via ESP-NOW |
 | `ota-progress` | 21 | Query per-slave ESP-NOW OTA progress on the master (`-client N`, default all) |
-| `led-ring` | 8 | LED ring: `-mode clear\|color\|progress\|digit\|blink\|find-me`, `-client`, `-all` |
+| `led-ring` | 8 | LED ring: `-mode clear\|color\|progress\|digit\|blink\|find-me\|battery-low`, `-client`, `-all` |
 | `find-me` | 22 | Locate pod (`-client 0` master, `>0` slave via ESP-NOW) |
 | `restart` | 23 | Reboot master or slave (`-client 0` / `>0`) |
 | `log-level` | `0x1f` | Get/set master ESP-IDF log level for tag `"*"` (`-set`, `-level` 0–5); output on UART0 debug, not host UART |
@@ -347,6 +347,8 @@ func ledRingModeValue(mode string) (uint32, error) {
 		return 3, nil
 	case "find_me", "findme":
 		return 4, nil
+	case "battery_low", "batterylow":
+		return 6, nil
 	case "color", "solid", "fill":
 		return 5, nil
 	default:
@@ -12,6 +12,7 @@ func TestLedRingModeValue(t *testing.T) {
 		{"digit", 2},
 		{"blink", 3},
 		{"find-me", 4},
+		{"battery-low", 6},
 	}
 	for _, tc := range tests {
 		got, err := ledRingModeValue(tc.mode)
@@ -9,7 +9,7 @@ import (

 func runLedRing(sp *serialPort, args []string) error {
 	fs := flag.NewFlagSet("led-ring", flag.ExitOnError)
-	mode := fs.String("mode", "progress", "clear, color, progress, digit, blink, or find-me")
+	mode := fs.String("mode", "progress", "clear, color, progress, digit, blink, find-me, or battery-low")
 	clientID := fs.Uint("client", 0, "0=master ring, >0=slave via ESP-NOW")
 	allClients := fs.Bool("all", false, "broadcast to all slaves")
 	slavesOnly := fs.Bool("slaves-only", false, "with -all: do not change master ring")
@@ -633,7 +633,7 @@ func runBatteryPoller(link *managedSerial, hub *wsHub, interval time.Duration, s
 		case <-stop:
 			return
 		case <-ticker.C:
-			if hub.clientCount() == 0 {
+			if !link.IsConnected() {
 				continue
 			}
 			bat, err := link.BatteryStatusPoll(&pb.BatteryStatusRequest{AllClients: true})
@@ -96,6 +96,7 @@ Body:
 | `digit` | `digit` 0–10 |
 | `blink` | `blink_ms`, `blink_count` |
 | `find-me` | Locate pod |
+| `battery-low` | First 4 LEDs red at ~10 % for 5 s (UV indicator test) |

 Use `client_id` (`0` = master) or `all_clients` (+ optional `slaves_only`) for broadcast.

@@ -214,11 +214,12 @@ Response `tap_notify_status`:
 | `digit`        | `digit` 0–10                |
 | `blink`        | `blink_ms`, `blink_count`   |
 | `find-me`      | Locate pod                  |
+| `battery-low`  | UV indicator (4 LEDs, 5 s)  |


 Target: `client_id` (`0` = master) or `all_clients` (+ optional `slaves_only`).

-Response `led_ring_status` — `mode` is numeric: 0=clear, 1=progress, 2=digit, 3=blink, 4=find-me, 5=color.
+Response `led_ring_status` — `mode` is numeric: 0=clear, 1=progress, 2=digit, 3=blink, 4=find-me, 5=color, 6=battery-low.

 ```json
 {"type":"led_ring_status","success":true,"mode":5,"client_id":16,"slaves_updated":1}
@@ -14,6 +14,7 @@ const (
 	ledRingModeBlink    = 3
 	ledRingModeFindMe   = 4
 	ledRingModeColor    = 5
+	ledRingModeBatteryLow = 6
 )

 type ledRingAPIRequest struct {
@@ -56,8 +57,10 @@ func ledRingModeFromString(s string) (uint32, error) {
 		return ledRingModeBlink, nil
 	case "find-me", "find_me", "findme":
 		return ledRingModeFindMe, nil
+	case "battery-low", "battery_low", "batterylow":
+		return ledRingModeBatteryLow, nil
 	default:
-		return 0, fmt.Errorf("unknown mode %q (clear, color, progress, digit, blink, find-me)", s)
+		return 0, fmt.Errorf("unknown mode %q (clear, color, progress, digit, blink, find-me, battery-low)", s)
 	}
 }

@@ -2526,7 +2526,7 @@ func (x *EspNowEchoPingResponse) GetEspRttUs() uint32 {
 }

 // Host → master: LED ring on master (client_id=0) and/or slaves via ESP-NOW.
-// mode: 0=clear, 1=progress (0–100 %), 2=digit (0–10), 3=blink, 4=find-me, 5=all LEDs solid color.
+// mode: 0=clear, 1=progress (0–100 %), 2=digit (0–10), 3=blink, 4=find-me, 5=all LEDs solid color, 6=battery-low.
 type LedRingProgressRequest struct {
 	state protoimpl.MessageState `protogen:"open.v1"`
 	Mode  uint32                 `protobuf:"varint,1,opt,name=mode,proto3" json:"mode,omitempty"`
@@ -44,7 +44,7 @@ Ordered steps: UART commands, delays, or esptool reset.
 **unicast_test** — `input`: `slave` or `client_id`, `seq`  
 `expect`: `success`, `seq`

-**led_ring** — `input`: `mode` (`clear`, `progress`, `digit`, `blink`, `find_me`), `progress`, `digit`, `r`/`g`/`b`, `intensity`, `blink_ms`, `blink_count`  
+**led_ring** — `input`: `mode` (`clear`, `progress`, `digit`, `blink`, `find_me`, `battery_low`), `progress`, `digit`, `r`/`g`/`b`, `intensity`, `blink_ms`, `blink_count`  
 `expect`: `success`, `mode`, `progress`, `digit`

 **find_me** — `input`: `client` / `client_id` or `slave` (`0` = master ring)  
@@ -471,7 +471,7 @@
          <div class="card-body">
            <p class="text-muted small mb-3">
              Modi: <code>clear</code>, <code>color</code> (ganzer Ring), <code>progress</code> (0–100&nbsp;%),
-              <code>digit</code> (0–10), <code>blink</code>, <code>find-me</code>.
+              <code>digit</code> (0–10), <code>blink</code>, <code>find-me</code>, <code>battery-low</code>.
              Ziel: Master (<code>client_id=0</code>), ein Slave oder alle Slaves (Broadcast).
            </p>
            <div class="row g-3 align-items-end">
@@ -484,6 +484,7 @@
                  <option value="digit">Ziffer/Symbol</option>
                  <option value="blink">Blink</option>
                  <option value="find-me">Find me</option>
+                  <option value="battery-low">Battery low</option>
                </select>
              </div>
              <div class="col-md-4">
@@ -769,21 +770,35 @@
        },
        applyBatterySamples(samples) {
          if (!samples?.length) return;
+          const master = { ...(this.state.master || {}) };
+          const clients = [...(this.state.clients || [])];
+          let masterChanged = false;
+          let clientsChanged = false;
          for (const s of samples) {
            if (s.client_id === 0) {
-              if (!this.state.master) this.state.master = {};
-              this.state.master.lipo1 = s.lipo1;
-              this.state.master.lipo2 = s.lipo2;
-              this.state.master.battery_age_ms = s.age_ms;
+              master.lipo1 = s.lipo1;
+              master.lipo2 = s.lipo2;
+              master.battery_age_ms = s.age_ms;
+              masterChanged = true;
              continue;
            }
-            const c = (this.state.clients || []).find((x) => x.id === s.client_id);
-            if (c) {
-              c.lipo1 = s.lipo1;
-              c.lipo2 = s.lipo2;
-              c.battery_age_ms = s.age_ms;
+            const idx = clients.findIndex((x) => x.id === s.client_id);
+            if (idx >= 0) {
+              clients[idx] = {
+                ...clients[idx],
+                lipo1: s.lipo1,
+                lipo2: s.lipo2,
+                battery_age_ms: s.age_ms,
+              };
+              clientsChanged = true;
            }
          }
+          if (!masterChanged && !clientsChanged) return;
+          this.state = {
+            ...this.state,
+            ...(masterChanged ? { master } : {}),
+            ...(clientsChanged ? { clients } : {}),
+          };
        },
        async refreshBattery() {
          if (!this.state?.uart_connected) return;
@@ -42,6 +42,7 @@ idf_component_register(
  "esp_now_proto.c"
  "bosch456.c"
  "board_input.c"
+  "battery_uv.c"
  "pod_settings.c"
  "proto/uart_messages.pb.c"
  "proto/esp_now_messages.pb.c"
@@ -68,3 +69,5 @@ idf_component_register(

 target_compile_definitions(${COMPONENT_LIB}
                           PRIVATE "POWERPOD_GIT_HASH=\"${POWERPOD_GIT_HASH}\"")
+# Optional: disable software UV protection
+# target_compile_definitions(${COMPONENT_LIB} PRIVATE POWERPOD_BATTERY_UV_ENABLE=0)
@@ -55,18 +55,20 @@ Pins (`powerpod.h`):
 | BMA456 INT | 10 |
 | Button (Taster) | 12 |
 | LiPo sense 1 (ADC) | 1 |
-| LiPo sense 2 (ADC) | 12 (skipped if same as button) |
+| LiPo sense 2 (ADC) | 11 |

 > **TODO:** GPIO assignments above are provisional; confirm pinning against the real board before release.

-Startup order:
+Startup order (normal path; UV energy-save skips I2C/BMA456/ESP-NOW/UART/button — see **Software UV protection**):

-1. Read DIP + IO expander → `app_config`
-2. **I2C bus** — IO expander `0x20`; optional **BMA456H** (`init_bma456`, same bus)
-3. `esp_now_comm_init(&app_config)` — WiFi + ESP-NOW
-4. `led_ring_init()`
-5. `board_input_init()` — button press logs, LiPo ADC logs every **10 s**
-6. **Master only:** command queue, UART, registered commands (e.g. VERSION)
+1. `pod_settings_init()` — NVS
+2. LiPo ADC init + optional UV boot check (`battery_uv.c`)
+3. Read DIP + IO expander → `app_config`
+4. **I2C bus** — IO expander `0x20`; optional **BMA456H** (`init_bma456`, same bus)
+5. `esp_now_comm_init(&app_config)` — WiFi + ESP-NOW
+6. `led_ring_init()`
+7. LiPo monitor task + button (`board_input.c`)
+8. **Master only:** command queue, UART, registered commands (e.g. VERSION)

 ## BMA456 accelerometer (`bosch456.c`)

@@ -440,6 +442,19 @@ Read **cached** LiPo ADC values on the **master** (master local + one entry per
 # Host / goTool: all_clients returns master (id 0) + slaves from cache
 ```

+### Software UV protection (LiPo)
+
+When `POWERPOD_BATTERY_UV_ENABLE` is `1` (default in `powerpod.h`, disable via CMake), the firmware monitors ADC pin voltages on GPIO 1 and 11:
+
+| Condition | ADC threshold | Action |
+|-----------|---------------|--------|
+| Under-voltage | any valid channel &lt; **2300 mV** (3.0 V pack) | NVS latch `uv_latch`, restart into energy-save mode |
+| Charged | all valid channels ≥ **3000 mV** (4.0 V pack) | Clear latch, restart into normal boot |
+
+**Energy-save boot:** LED mode `6` (first 4 LEDs red ~10 % for 5 s), then no WiFi/ESP-NOW, UART, I2C, BMA456, or button — only LiPo ADC polling every 30 s until charged.
+
+**Test LED pattern from host:** `led-ring -mode battery-low` (works even when UV feature is disabled).
+
 ### LED_RING command

 Control the 95-LED ring from the host. The firmware **does not** animate digits locally; only UART updates the display.
@@ -448,7 +463,7 @@ Control the 95-LED ring from the host. The firmware **does not** animate digits

 | Field | Meaning |
 |-------|---------|
-| `mode` | `0` = clear, `1` = progress, `2` = digit (0–10), `3` = blink, `4` = find-me, `5` = solid color (all LEDs) |
+| `mode` | `0` = clear, `1` = progress, `2` = digit (0–10), `3` = blink, `4` = find-me, `5` = solid color (all LEDs), `6` = battery-low (first 4 LEDs red ~10 % for 5 s) |
 | `progress` | 0–100 (% of ring lit, mode `1`) |
 | `digit` | 0–10 (mode `2`, segment maps in `led_ring.c`) |
 | `r`, `g`, `b` | Color 0–255 |
@@ -470,6 +485,7 @@ go run . -port /dev/ttyUSB0 led-ring -mode blink -g 255 -blink-count 2
 go run . -port /dev/ttyUSB0 find-me
 go run . -port /dev/ttyUSB0 find-me -client 16
 go run . -port /dev/ttyUSB0 led-ring -mode find-me
+go run . -port /dev/ttyUSB0 led-ring -mode battery-low -client 0
 go run . -port /dev/ttyUSB0 led-ring -mode color -r 255 -g 0 -b 0 -client 16
 go run . -port /dev/ttyUSB0 led-ring -mode digit -digit 5 -all
 ```
@@ -563,8 +579,9 @@ Target: ESP32-S3. Close serial monitor on the UART adapter port before running `
 | `bosch456.c/h` | BMA456H I2C driver, accel poll, on-demand read, tap INT, deadzone filter |
 | `cmd/cmd_tap_notify.c` | UART `TAP_NOTIFY` — ESP-NOW tap notify config |
 | `cmd/cmd_cache_status.c` | UART `CACHE_STATUS` — subscribed accel + tap cache poll |
-| `board_input.c/h` | Taster GPIO12, LiPo ADC on GPIO1 / GPIO12 |
-| `pod_settings.c/h` | NVS persistence (accel deadzone, …) |
+| `board_input.c/h` | Taster GPIO12, LiPo ADC on GPIO1 / GPIO11 |
+| `battery_uv.c/h` | Software LiPo UV latch, energy-save boot (`POWERPOD_BATTERY_UV_ENABLE`) |
+| `pod_settings.c/h` | NVS persistence (accel deadzone, UV latch, …) |
 | `led_ring.c/h` | LED ring (digit display, progress bar) |
 | `cmd/cmd_led_ring.c` | UART `LED_RING` progress command |
 | `cmd/cmd_set_log_level.c` | UART `SET_LOG_LEVEL` — runtime ESP-IDF log level |
@@ -0,0 +1,130 @@
+#include "battery_uv.h"
+
+#if POWERPOD_BATTERY_UV_ENABLE
+
+#include "led_ring.h"
+#include "pod_reboot.h"
+#include "pod_settings.h"
+#include "esp_log.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+static const char *TAG = "[BATTERY_UV]";
+
+#define UV_DEBOUNCE_SAMPLES 2u
+#define UV_POLL_INTERVAL_MS 30000u
+
+static uint8_t s_uv_streak;
+static uint8_t s_charge_streak;
+
+bool battery_uv_is_latched(void) { return pod_settings_is_uv_latched(); }
+
+bool battery_uv_reading_is_under(const board_lipo_reading_t *reading) {
+  if (reading == NULL) {
+    return false;
+  }
+
+  if (reading->lipo1_valid && reading->lipo1_mv < BATTERY_UV_ADC_MV) {
+    return true;
+  }
+  if (reading->lipo2_valid && reading->lipo2_mv < BATTERY_UV_ADC_MV) {
+    return true;
+  }
+  return false;
+}
+
+bool battery_uv_reading_is_charged(const board_lipo_reading_t *reading) {
+  if (reading == NULL) {
+    return false;
+  }
+
+  bool any_valid = false;
+  if (reading->lipo1_valid) {
+    any_valid = true;
+    if (reading->lipo1_mv < BATTERY_CHARGE_ADC_MV) {
+      return false;
+    }
+  }
+  if (reading->lipo2_valid) {
+    any_valid = true;
+    if (reading->lipo2_mv < BATTERY_CHARGE_ADC_MV) {
+      return false;
+    }
+  }
+  return any_valid;
+}
+
+bool battery_uv_evaluate_boot(void) {
+  board_lipo_reading_t reading;
+  board_input_read_lipo(&reading);
+
+  if (pod_settings_is_uv_latched() && battery_uv_reading_is_charged(&reading)) {
+    ESP_LOGI(TAG, "charged — clearing UV latch");
+    pod_settings_clear_uv_latched();
+    return false;
+  }
+
+  if (pod_settings_is_uv_latched() || battery_uv_reading_is_under(&reading)) {
+    if (!pod_settings_is_uv_latched()) {
+      ESP_LOGW(TAG, "under-voltage at boot — latching UV");
+    } else {
+      ESP_LOGW(TAG, "UV latched — energy-save boot");
+    }
+    pod_settings_set_uv_latched(true);
+    return true;
+  }
+
+  return false;
+}
+
+void battery_uv_poll(const board_lipo_reading_t *reading) {
+  if (reading == NULL || pod_settings_is_uv_latched()) {
+    return;
+  }
+
+  if (battery_uv_reading_is_under(reading)) {
+    s_uv_streak++;
+    ESP_LOGW(TAG, "under-voltage sample %u/%u", (unsigned)s_uv_streak,
+             (unsigned)UV_DEBOUNCE_SAMPLES);
+    if (s_uv_streak >= UV_DEBOUNCE_SAMPLES) {
+      ESP_LOGW(TAG, "UV confirmed — latching and restarting");
+      pod_settings_set_uv_latched(true);
+      pod_schedule_restart();
+    }
+    return;
+  }
+
+  s_uv_streak = 0;
+}
+
+void battery_uv_run_mode(void) {
+  s_charge_streak = 0;
+  s_uv_streak = 0;
+
+  led_ring_init();
+  led_ring_show_battery_low();
+
+  ESP_LOGW(TAG, "energy-save mode — ADC poll every %u ms", UV_POLL_INTERVAL_MS);
+
+  while (1) {
+    board_lipo_reading_t reading;
+    board_input_read_lipo(&reading);
+
+    if (battery_uv_reading_is_charged(&reading)) {
+      s_charge_streak++;
+      ESP_LOGI(TAG, "charge sample %u/%u", (unsigned)s_charge_streak,
+               (unsigned)UV_DEBOUNCE_SAMPLES);
+      if (s_charge_streak >= UV_DEBOUNCE_SAMPLES) {
+        ESP_LOGI(TAG, "charged — clearing UV latch and restarting");
+        pod_settings_clear_uv_latched();
+        pod_schedule_restart();
+      }
+    } else {
+      s_charge_streak = 0;
+    }
+
+    vTaskDelay(pdMS_TO_TICKS(UV_POLL_INTERVAL_MS));
+  }
+}
+
+#endif
@@ -0,0 +1,51 @@
+#ifndef BATTERY_UV_H
+#define BATTERY_UV_H
+
+#include "board_input.h"
+#include "powerpod.h"
+#include <stdbool.h>
+
+#if POWERPOD_BATTERY_UV_ENABLE
+
+/** ADC pin voltage (mV) below which UV is triggered (3.0 V pack via 33k/10k divider). */
+#define BATTERY_UV_ADC_MV 2300u
+/** ADC pin voltage (mV) at which charging is detected (4.0 V pack, rounded). */
+#define BATTERY_CHARGE_ADC_MV 3000u
+
+bool battery_uv_is_latched(void);
+bool battery_uv_reading_is_under(const board_lipo_reading_t *reading);
+bool battery_uv_reading_is_charged(const board_lipo_reading_t *reading);
+
+/** true → enter UV energy-save path (does not return). */
+bool battery_uv_evaluate_boot(void);
+
+void battery_uv_poll(const board_lipo_reading_t *reading);
+
+/** Blocks: LED indicator, then minimal ADC polling until charged. */
+void battery_uv_run_mode(void);
+
+#else
+
+static inline bool battery_uv_is_latched(void) { return false; }
+
+static inline bool battery_uv_reading_is_under(const board_lipo_reading_t *reading) {
+  (void)reading;
+  return false;
+}
+
+static inline bool battery_uv_reading_is_charged(const board_lipo_reading_t *reading) {
+  (void)reading;
+  return false;
+}
+
+static inline bool battery_uv_evaluate_boot(void) { return false; }
+
+static inline void battery_uv_poll(const board_lipo_reading_t *reading) {
+  (void)reading;
+}
+
+static inline void battery_uv_run_mode(void) {}
+
+#endif
+
+#endif
@@ -1,6 +1,10 @@
 #include "board_input.h"
 #include "powerpod.h"
+#include "client_registry.h"
 #include "driver/gpio.h"
+#if POWERPOD_BATTERY_UV_ENABLE
+#include "battery_uv.h"
+#endif
 #include "esp_adc/adc_oneshot.h"
 #include "esp_log.h"
 #include "freertos/FreeRTOS.h"
@@ -18,34 +22,51 @@ static const char *TAG_LIPO = "[LIPO]";
 #define LIPO_ADC_MAX_RAW 4095

 static QueueHandle_t s_button_queue;
-static adc_oneshot_unit_handle_t s_adc;
-static bool s_lipo1_ok;
-static bool s_lipo2_ok;
-static adc_channel_t s_lipo1_ch;
-static adc_channel_t s_lipo2_ch;

-static esp_err_t adc_init_channel(int gpio, adc_channel_t *out_ch, bool *out_ok) {
-  adc_unit_t unit;
-  esp_err_t err = adc_oneshot_io_to_channel(gpio, &unit, out_ch);
+typedef struct {
+  adc_oneshot_unit_handle_t unit;
+  adc_channel_t ch;
+  bool ok;
+} lipo_adc_t;
+
+static lipo_adc_t s_lipo1;
+static lipo_adc_t s_lipo2;
+
+static esp_err_t adc_init_gpio(int gpio, lipo_adc_t *out) {
+  out->unit = NULL;
+  out->ok = false;
+
+  adc_unit_t unit_id;
+  esp_err_t err = adc_oneshot_io_to_channel(gpio, &unit_id, &out->ch);
  if (err != ESP_OK) {
    ESP_LOGW(TAG_LIPO, "GPIO%d not an ADC channel: %s", gpio, esp_err_to_name(err));
-    *out_ok = false;
    return err;
  }
-  if (unit != ADC_UNIT_1) {
-    ESP_LOGW(TAG_LIPO, "GPIO%d on ADC unit %d (expected ADC1)", gpio, (int)unit);
+
+  adc_oneshot_unit_init_cfg_t init_cfg = {
+      .unit_id = unit_id,
+  };
+  err = adc_oneshot_new_unit(&init_cfg, &out->unit);
+  if (err != ESP_OK) {
+    ESP_LOGW(TAG_LIPO, "ADC unit %d init GPIO%d failed: %s", (int)unit_id, gpio,
+             esp_err_to_name(err));
+    return err;
  }
+
  adc_oneshot_chan_cfg_t chan_cfg = {
      .atten = ADC_ATTEN_DB_12,
      .bitwidth = ADC_BITWIDTH_DEFAULT,
  };
-  err = adc_oneshot_config_channel(s_adc, *out_ch, &chan_cfg);
+  err = adc_oneshot_config_channel(out->unit, out->ch, &chan_cfg);
  if (err != ESP_OK) {
    ESP_LOGW(TAG_LIPO, "ADC config GPIO%d failed: %s", gpio, esp_err_to_name(err));
-    *out_ok = false;
+    adc_oneshot_del_unit(out->unit);
+    out->unit = NULL;
    return err;
  }
-  *out_ok = true;
+
+  out->ok = true;
+  ESP_LOGI(TAG_LIPO, "GPIO%d ready (ADC unit %d)", gpio, (int)unit_id);
  return ESP_OK;
 }

@@ -56,15 +77,15 @@ static uint32_t raw_to_mv(int raw) {
  return (uint32_t)((raw * LIPO_ADC_FULL_SCALE_MV) / LIPO_ADC_MAX_RAW);
 }

-static void sample_one_channel(adc_channel_t ch, bool ok, uint32_t *mv_out,
+static void sample_one_channel(const lipo_adc_t *adc, uint32_t *mv_out,
                               bool *valid_out) {
  *valid_out = false;
  *mv_out = 0;
-  if (!ok || s_adc == NULL) {
+  if (adc == NULL || !adc->ok || adc->unit == NULL) {
    return;
  }
  int raw = 0;
-  if (adc_oneshot_read(s_adc, ch, &raw) == ESP_OK) {
+  if (adc_oneshot_read(adc->unit, adc->ch, &raw) == ESP_OK) {
    *valid_out = true;
    *mv_out = raw_to_mv(raw);
  }
@@ -75,8 +96,8 @@ void board_input_read_lipo(board_lipo_reading_t *out) {
    return;
  }
  memset(out, 0, sizeof(*out));
-  sample_one_channel(s_lipo1_ch, s_lipo1_ok, &out->lipo1_mv, &out->lipo1_valid);
-  sample_one_channel(s_lipo2_ch, s_lipo2_ok, &out->lipo2_mv, &out->lipo2_valid);
+  sample_one_channel(&s_lipo1, &out->lipo1_mv, &out->lipo1_valid);
+  sample_one_channel(&s_lipo2, &out->lipo2_mv, &out->lipo2_valid);
 }

 static void lipo_monitor_task(void *param) {
@@ -87,6 +108,7 @@ static void lipo_monitor_task(void *param) {
  while (1) {
    board_lipo_reading_t reading;
    board_input_read_lipo(&reading);
+    client_registry_set_master_battery(&reading);

    ESP_LOGI(TAG_LIPO,
             "LIPO1 GPIO%d %s %lu mV  LIPO2 GPIO%d %s %lu mV",
@@ -95,6 +117,10 @@ static void lipo_monitor_task(void *param) {
             reading.lipo2_valid ? "ok" : "n/a",
             (unsigned long)reading.lipo2_mv);

+#if POWERPOD_BATTERY_UV_ENABLE
+    battery_uv_poll(&reading);
+#endif
+
    vTaskDelay(pdMS_TO_TICKS(LIPO_SAMPLE_INTERVAL_MS));
  }
 }
@@ -165,29 +191,30 @@ static esp_err_t init_button(void) {
  return ESP_OK;
 }

-static esp_err_t init_lipo_adc(void) {
-  adc_oneshot_unit_init_cfg_t init_cfg = {
-      .unit_id = ADC_UNIT_1,
-  };
-  esp_err_t err = adc_oneshot_new_unit(&init_cfg, &s_adc);
-  if (err != ESP_OK) {
-    ESP_LOGW(TAG_LIPO, "ADC init failed: %s", esp_err_to_name(err));
-    return err;
-  }
+static esp_err_t init_lipo_adc_hw(void) {
+  memset(&s_lipo1, 0, sizeof(s_lipo1));
+  memset(&s_lipo2, 0, sizeof(s_lipo2));

-  adc_init_channel(V_LIPO_1_GPIO, &s_lipo1_ch, &s_lipo1_ok);
+  adc_init_gpio(V_LIPO_1_GPIO, &s_lipo1);

  if (V_LIPO_2_GPIO == TASTER_GPIO) {
    ESP_LOGW(TAG_LIPO, "LIPO2 on GPIO%d skipped (button uses same pin)",
             V_LIPO_2_GPIO);
-    s_lipo2_ok = false;
  } else {
-    adc_init_channel(V_LIPO_2_GPIO, &s_lipo2_ch, &s_lipo2_ok);
+    adc_init_gpio(V_LIPO_2_GPIO, &s_lipo2);
  }

-  if (!s_lipo1_ok && !s_lipo2_ok) {
-    adc_oneshot_del_unit(s_adc);
-    s_adc = NULL;
+  if (!s_lipo1.ok && !s_lipo2.ok) {
+    return ESP_FAIL;
+  }
+
+  return ESP_OK;
+}
+
+esp_err_t board_input_init_adc_only(void) { return init_lipo_adc_hw(); }
+
+esp_err_t board_input_start_lipo_monitor(void) {
+  if (!s_lipo1.ok && !s_lipo2.ok) {
    return ESP_FAIL;
  }

@@ -198,16 +225,23 @@ static esp_err_t init_lipo_adc(void) {
  return ESP_OK;
 }

+esp_err_t board_input_init_button(void) { return init_button(); }
+
 esp_err_t board_input_init(void) {
-  esp_err_t err = init_button();
+  esp_err_t err = board_input_init_adc_only();
+  if (err != ESP_OK) {
+    ESP_LOGW(TAG_LIPO, "ADC init failed: %s", esp_err_to_name(err));
+  } else {
+    err = board_input_start_lipo_monitor();
+    if (err != ESP_OK) {
+      ESP_LOGW(TAG_LIPO, "monitor task failed: %s", esp_err_to_name(err));
+    }
+  }
+
+  err = board_input_init_button();
  if (err != ESP_OK) {
    ESP_LOGW(TAG_BTN, "init failed: %s", esp_err_to_name(err));
  }

-  err = init_lipo_adc();
-  if (err != ESP_OK) {
-    ESP_LOGW(TAG_LIPO, "init failed: %s", esp_err_to_name(err));
-  }
-
  return ESP_OK;
 }
@@ -19,6 +19,15 @@ typedef struct {
 */
 esp_err_t board_input_init(void);

+/** LiPo ADC channels only (no button, no background task). */
+esp_err_t board_input_init_adc_only(void);
+
+/** Start 10 s LiPo monitor task (normal boot only). */
+esp_err_t board_input_start_lipo_monitor(void);
+
+/** Front-panel button debounce task. */
+esp_err_t board_input_init_button(void);
+
 /** On-demand ADC read of both LiPo sense inputs (if configured). */
 void board_input_read_lipo(board_lipo_reading_t *out);

@@ -33,18 +33,14 @@ static bool append_battery_sample(alox_BatteryStatusResponse *resp,
  return lipo1_valid || lipo2_valid;
 }

-static bool append_master_cached(alox_BatteryStatusResponse *resp) {
+static bool append_master_sample(alox_BatteryStatusResponse *resp) {
  board_lipo_reading_t reading;
-  uint32_t age_ms = 0;

-  if (!client_registry_get_master_battery(&reading, &age_ms)) {
-    board_input_read_lipo(&reading);
-    client_registry_set_master_battery(&reading);
-    age_ms = 0;
-  }
+  board_input_read_lipo(&reading);
+  client_registry_set_master_battery(&reading);

  return append_battery_sample(resp, 0, reading.lipo1_valid, reading.lipo1_mv,
-                               reading.lipo2_valid, reading.lipo2_mv, age_ms);
+                               reading.lipo2_valid, reading.lipo2_mv, 0);
 }

 static bool append_slave_cached(alox_BatteryStatusResponse *resp,
@@ -102,7 +98,7 @@ static void handle_battery_status(const uint8_t *data, size_t len) {
  bool any = false;

  if (req.all_clients) {
-    any |= append_master_cached(resp);
+    any |= append_master_sample(resp);
    for (size_t i = 0; i < client_registry_count(); i++) {
      const client_info_t *client = client_registry_at(i);
      if (client == NULL) {
@@ -113,7 +109,7 @@ static void handle_battery_status(const uint8_t *data, size_t len) {
    ESP_LOGI(TAG, "battery cache all_clients → %u samples",
             (unsigned)resp->samples_count);
  } else if (req.client_id == 0) {
-    any = append_master_cached(resp);
+    any = append_master_sample(resp);
    ESP_LOGI(TAG, "battery cache master");
  } else {
    const client_info_t *client = client_registry_find_by_id(req.client_id);
@@ -13,6 +13,7 @@ static const char *TAG = "[LED_RING_CMD]";
 #define LED_RING_MODE_BLINK    3
 #define LED_RING_MODE_FIND_ME  4
 #define LED_RING_MODE_COLOR    5
+#define LED_RING_MODE_BATTERY_LOW 6

 static uint8_t clamp_u8(uint32_t v) {
  if (v > 255) {
@@ -90,6 +91,10 @@ bool cmd_led_ring_apply(const alox_LedRingProgressRequest *req) {
    led_ring_find_me();
    return true;

+  case LED_RING_MODE_BATTERY_LOW:
+    led_ring_show_battery_low();
+    return true;
+
  case LED_RING_MODE_BLINK:
    cmd.mode = LED_CMD_BLINK;
    cmd.r = r;
@@ -5,6 +5,7 @@
 #include "esp_log.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
+#include "freertos/semphr.h"
 #include "led_strip.h"
 #include <stdint.h>

@@ -23,8 +24,12 @@ static led_strip_handle_t led_ring;
 #define LED_RING_FIND_ME_ON_MS 300
 #define LED_RING_FIND_ME_OFF_MS 150
 #define LED_RING_FIND_ME_BLINKS_PER_COLOR 3
+#define LED_RING_BATTERY_LOW_R 255
+#define LED_RING_BATTERY_LOW_G 0
+#define LED_RING_BATTERY_LOW_B 0

 static QueueHandle_t led_queue;
+static SemaphoreHandle_t s_battery_low_done;

 // Led Matrix Maps
 const uint8_t d0[] = {46, 47, 60, 61, 62, 75, 78, 79,
@@ -145,6 +150,22 @@ void vTaskLedRing(void *pvParameters) {
          }
        }
        continue;
+      } else if (cmd.mode == LED_CMD_BATTERY_LOW) {
+        uint8_t r = LED_RING_BATTERY_LOW_R;
+        uint8_t g = LED_RING_BATTERY_LOW_G;
+        uint8_t b = LED_RING_BATTERY_LOW_B;
+        led_ring_scale_rgb(&r, &g, &b, LED_RING_BATTERY_LOW_INTENSITY);
+        for (uint32_t i = 0; i < LED_RING_BATTERY_LOW_LEDS; i++) {
+          led_strip_set_pixel(led_ring, i, r, g, b);
+        }
+        led_strip_refresh(led_ring);
+        vTaskDelay(pdMS_TO_TICKS(LED_RING_BATTERY_LOW_HOLD_MS));
+        led_strip_clear(led_ring);
+        led_strip_refresh(led_ring);
+        if (s_battery_low_done != NULL) {
+          xSemaphoreGive(s_battery_low_done);
+        }
+        continue;
      }
      led_strip_refresh(led_ring);
    }
@@ -153,6 +174,7 @@ void vTaskLedRing(void *pvParameters) {

 void led_ring_init(void) {
  led_queue = xQueueCreate(10, sizeof(led_command_t));
+  s_battery_low_done = xSemaphoreCreateBinary();
  xTaskCreate(vTaskLedRing, "led_task", 4096, NULL, 5, NULL);
 }

@@ -224,3 +246,13 @@ void led_ring_find_me(void) {
  led_command_t cmd = {.mode = LED_CMD_FIND_ME};
  led_ring_send_command(&cmd);
 }
+
+void led_ring_show_battery_low(void) {
+  if (led_queue == NULL || s_battery_low_done == NULL) {
+    return;
+  }
+  (void)xSemaphoreTake(s_battery_low_done, 0);
+  led_command_t cmd = {.mode = LED_CMD_BATTERY_LOW};
+  led_ring_send_command(&cmd);
+  (void)xSemaphoreTake(s_battery_low_done, portMAX_DELAY);
+}
@@ -7,6 +7,10 @@
 #define LED_RING_DEFAULT_INTENSITY 13
 /** Full brightness for find-me and similar alerts. */
 #define LED_RING_FULL_INTENSITY 255
+/** ~10 % brightness for battery-low indicator. */
+#define LED_RING_BATTERY_LOW_INTENSITY 26
+#define LED_RING_BATTERY_LOW_LEDS 4
+#define LED_RING_BATTERY_LOW_HOLD_MS 5000

 typedef enum {
  LED_CMD_CLEAR,
@@ -14,7 +18,8 @@ typedef enum {
  LED_CMD_SET_COLOR,
  LED_CMD_PROGRESS,
  LED_CMD_BLINK,
-  LED_CMD_FIND_ME
+  LED_CMD_FIND_ME,
+  LED_CMD_BATTERY_LOW
 } led_mode_t;

 typedef struct {
@@ -45,4 +50,7 @@ void led_ring_ota_failed(void);
 /** Red / green / blue: 3 blinks each at full intensity. */
 void led_ring_find_me(void);

+/** First 4 LEDs red at ~10 % for 5 s, then off (blocking in LED task). */
+void led_ring_show_battery_low(void);
+
 #endif
@@ -7,6 +7,7 @@
 static const char *TAG = "[SETTINGS]";
 static const char *NS = "powerpod";
 static const char *KEY_ACCEL_DZ = "accel_dz";
+static const char *KEY_UV_LATCH = "uv_latch";

 #define ACCEL_DEADZONE_MAX 4095u

@@ -108,3 +109,53 @@ void pod_settings_apply_accel_deadzone(void) {
    bma456_set_accel_deadzone(deadzone);
  }
 }
+
+bool pod_settings_is_uv_latched(void) {
+  if (!s_nvs_ready) {
+    return false;
+  }
+
+  nvs_handle_t handle;
+  esp_err_t err = nvs_open(NS, NVS_READONLY, &handle);
+  if (err != ESP_OK) {
+    return false;
+  }
+
+  uint8_t value = 0;
+  err = nvs_get_u8(handle, KEY_UV_LATCH, &value);
+  nvs_close(handle);
+
+  return err == ESP_OK && value != 0;
+}
+
+esp_err_t pod_settings_set_uv_latched(bool latched) {
+  esp_err_t err = ensure_nvs();
+  if (err != ESP_OK) {
+    return err;
+  }
+
+  nvs_handle_t handle;
+  err = nvs_open(NS, NVS_READWRITE, &handle);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "nvs_open failed: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  err = nvs_set_u8(handle, KEY_UV_LATCH, latched ? 1u : 0u);
+  if (err == ESP_OK) {
+    err = nvs_commit(handle);
+  }
+  nvs_close(handle);
+
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "save uv_latch failed: %s", esp_err_to_name(err));
+    return err;
+  }
+
+  ESP_LOGI(TAG, "UV latch %s", latched ? "set" : "cleared");
+  return ESP_OK;
+}
+
+esp_err_t pod_settings_clear_uv_latched(void) {
+  return pod_settings_set_uv_latched(false);
+}
@@ -2,6 +2,7 @@
 #define POD_SETTINGS_H

 #include "esp_err.h"
+#include <stdbool.h>
 #include <stdint.h>

 /** Initialize NVS (idempotent) and log stored settings. Call once early in app_main. */
@@ -16,4 +17,9 @@ uint32_t pod_settings_load_accel_deadzone(void);
 /** Apply NVS deadzone to BMA456 when the sensor is present. */
 void pod_settings_apply_accel_deadzone(void);

+/** LiPo under-voltage latch persisted across reboot (software UV protection). */
+bool pod_settings_is_uv_latched(void);
+esp_err_t pod_settings_set_uv_latched(bool latched);
+esp_err_t pod_settings_clear_uv_latched(void);
+
 #endif
@@ -31,6 +31,7 @@
 #include "led_ring.h"
 #include "pod_settings.h"
 #include "uart.h"
+#include "battery_uv.h"
 #include <stdint.h>

 enum MASTER_STATES {
@@ -78,6 +79,16 @@ void app_main(void) {
    ESP_LOGW(TAG, "settings NVS init failed; using defaults");
  }

+  if (board_input_init_adc_only() != ESP_OK) {
+    ESP_LOGW(TAG, "LiPo ADC init failed");
+  }
+
+#if POWERPOD_BATTERY_UV_ENABLE
+  if (battery_uv_evaluate_boot()) {
+    battery_uv_run_mode();
+  }
+#endif
+
  // Get Master Mode Pin
  gpio_reset_pin(DIP_MASTER);
  gpio_set_direction(DIP_MASTER, GPIO_MODE_INPUT);
@@ -167,7 +178,8 @@ void app_main(void) {
  ESP_LOGI(TAG, "Running Partition: %s (OTA slot %d)",
           app_config.running_partition, ota_slot);

-  board_input_init();
+  board_input_start_lipo_monitor();
+  board_input_init_button();

  err = esp_now_comm_init(&app_config);
  if (err != ESP_OK) {
@@ -1,6 +1,11 @@
 #ifndef POWERPOD_H
 #define POWERPOD_H

+/** 1 = software LiPo UV latch + energy-save mode; 0 = disabled (LED mode 6 still works). */
+#ifndef POWERPOD_BATTERY_UV_ENABLE
+#define POWERPOD_BATTERY_UV_ENABLE 0
+#endif
+
 #define DIP_MASTER 4
 #define I2C_SCL 5
 #define I2C_SDA 6
@@ -11,9 +16,8 @@
 /** Front-panel button (active low, internal pull-up). */
 #define TASTER_GPIO 12

-/** LiPo voltage sense inputs (ADC1-capable GPIOs). */
+/** LiPo voltage sense inputs (ADC-capable GPIOs; GPIO11 = ADC2 on ESP32-S3). */
 #define V_LIPO_1_GPIO 1
-/** Shares GPIO with TASTER on current bench wiring; second ADC is skipped in board_input.c. */
-#define V_LIPO_2_GPIO 12
+#define V_LIPO_2_GPIO 11

 #endif
@@ -256,7 +256,7 @@ typedef struct _alox_EspNowEchoPingResponse {
 } alox_EspNowEchoPingResponse;

 /* Host → master: LED ring on master (client_id=0) and/or slaves via ESP-NOW.
- mode: 0=clear, 1=progress (0–100 %), 2=digit (0–10), 3=blink, 4=find-me, 5=all LEDs solid color. */
+ mode: 0=clear, 1=progress (0–100 %), 2=digit (0–10), 3=blink, 4=find-me, 5=all LEDs solid color, 6=battery-low. */
 typedef struct _alox_LedRingProgressRequest {
    uint32_t mode;
    /* * 0–100: fraction of ring LEDs to light (mode=progress) */
@@ -280,7 +280,7 @@ message EspNowEchoPingResponse {
 }

 // Host → master: LED ring on master (client_id=0) and/or slaves via ESP-NOW.
-// mode: 0=clear, 1=progress (0–100 %), 2=digit (0–10), 3=blink, 4=find-me, 5=all LEDs solid color.
+// mode: 0=clear, 1=progress (0–100 %), 2=digit (0–10), 3=blink, 4=find-me, 5=all LEDs solid color, 6=battery-low.
 message LedRingProgressRequest {
  uint32 mode = 1;
  /** 0–100: fraction of ring LEDs to light (mode=progress) */