johnpacino · johnpacino · Aug 15, 2026 · Aug 15, 2026 · Aug 16, 2026 · Aug 16, 2026
diff --git a/README.md b/README.md
@@ -112,6 +112,9 @@ scripts/start-kiosk.sh --swing-speed
 
 # Development mode (no hardware)
 scripts/start-kiosk.sh --mock
+
+# With Geekworm X1202/X1206 battery monitoring
+scripts/start-kiosk.sh --battery geekworm
 ```
 
 The IWR6843 example values are not universal. Measure the geometry from the
@@ -303,6 +306,8 @@ uv run pytest tests/ -v
 - **[Parts List](docs/PARTS.md)** — What to buy
 - **[Sound Trigger Wiring](docs/sound-trigger-wiring.md)** — How to wire the sound trigger
 - **[Raspberry Pi Setup](docs/raspberry-pi-setup.md)** — Full setup guide
+- **[Battery Monitoring](docs/battery/README.md)** — Provider architecture, UI states, and shared Pi support
+- **[Geekworm X1202/X1206 Operator Guide](docs/battery/geekworm.md)** — Batteries, Pi setup, native telemetry, and warnings
 - **[IWR6843 Operator Guide](docs/iwr6843/README.md)** — Wire, flash, mount, aim, and calibrate the angle radar
 - **[LIS3DH Inclinometer Setup](docs/inclinometer/README.md)**: Add enclosure-level compensation to IWR6843 tilt
 - **[OPS243 USB → GPIO UART Migration](docs/ops243-uart-migration.md)** — Required before adding the IWR6843

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -8,6 +8,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **Battery and external-power status for Raspberry Pi UPS boards.** OpenFlight
+  can now display charging state and battery percentage, issue dismissible 20%
+  and 10% warnings while discharging, and record throttled power telemetry in
+  session logs. Enable the initial Geekworm X1202/X1206 provider with
+  `--battery geekworm`; monitoring remains disabled when no provider is
+  selected. The accompanying Pi setup installs native Linux power-supply
+  telemetry and optional taskbar capacity support without enabling automatic
+  shutdown or charging control. See [Battery Monitoring](battery/README.md).
 - **System Prerequisites:** Documented missing binary dependencies (`swig`, `liblgpio-dev`, `python3-dev`) required prior to executing `./scripts/setup/setup.sh`.
 - **Environment Reload Guidance:** Added instructions for reloading terminal environment variables (`source ~/.bashrc`) when installed dependencies or scripts (`setup.sh`, `start-kiosk.sh`) are not recognized in the current terminal session.
 - **Configurable IWR6843 capture compression.** One firmware image can now

diff --git a/docs/PARTS.md b/docs/PARTS.md
@@ -139,7 +139,8 @@ One unit is mounted vertically (launch angle), one horizontally (club path / aim
 | Part | Description | Link | ~Price |
 |------|-------------|------|--------|
 | Tripod Mount | For positioning the unit | 1/4"-20 mount | $10 |
-| **Geekworm X1202 UPS HAT** | Rechargeable Pi 5 power using four compatible 18650 Li-ion cells. Cells are not included; follow the manufacturer's cell requirements | [Amazon](https://www.amazon.com/dp/B0CRZ4ZXQW?ref=ppx_yo2ov_dt_b_fed_asin_title) | ~$48 + ~$25 for cells |
+| **Geekworm X1202 UPS HAT** | Rechargeable Pi 5 power using four matching flat-top 18650 Li-ion cells. Cells are not included | [Geekworm](https://geekworm.com/products/x1202) | ~$48 + cells |
+| **Geekworm X1206 UPS HAT** | Larger rechargeable Pi 5 power option using four matching 21700 Li-ion cells, advertised up to 20,000mAh total. Cells are not included | [Geekworm](https://geekworm.com/products/x1206) | Varies + cells |
 | **InnoMaker OV9281 global-shutter camera** | High-speed monochrome camera for experimental vision work. Camera software is not enabled in the production kiosk path | [Amazon](https://www.amazon.com/dp/B09WTP5GZH?th=1) | ~$30 |
 
 See [Camera and YOLO Experiments](yolo-performance-tuning.md) before buying the

diff --git a/docs/battery/README.md b/docs/battery/README.md
@@ -0,0 +1,108 @@
+# Battery Monitoring
+
+OpenFlight can display battery percentage, external-power state, and low-battery
+warnings when a supported UPS provider is selected. Monitoring is disabled by
+default and is read-only: OpenFlight does not change charging behavior or shut
+down Linux automatically.
+
+## Supported Providers
+
+| Provider | CLI value | Hardware | Setup guide |
+|---|---|---|---|
+| Geekworm | `geekworm` | X1202 and X1206 | [Geekworm X1202/X1206](geekworm.md) |
+
+Start OpenFlight with an installed provider:
+
+```bash
+scripts/start-kiosk.sh --battery geekworm
+```
+
+The `--battery` argument is intentionally explicit. When it is absent,
+OpenFlight does not probe UPS hardware and does not show the battery UI.
+
+## Implementation
+
+Battery support is split into generic monitoring and hardware providers:
+
+```text
+CLI provider selection
+        |
+        v
+PowerReader factory --> Linux power_supply reader
+        |                       |
+        | unavailable           | PowerSample
+        v                       v
+Provider reader ----------> PowerMonitor --> WebSocket UI
+                                      `--> session JSONL
+```
+
+Every provider implements the `PowerReader` contract and returns the common
+`PowerSample` fields:
+
+- Battery percentage
+- Battery voltage
+- External-power availability
+
+The factory first uses standard Linux devices under `/sys/class/power_supply`
+when the installed kernel driver exposes both a battery and mains supply. It
+falls back to the selected provider's direct hardware reader when native Linux
+telemetry is unavailable.
+
+The generic `PowerMonitor` owns polling, retry, state classification, UI
+publication, and throttled session logging. Hardware readers do not implement
+warnings or shutdown policy.
+
+## UI And Logging
+
+The UI reports plugged-in, on-battery, low, critical, and unavailable states.
+Warnings at 20% and 10% are dismissible and appear only while discharging.
+
+![OpenFlight showing a plugged-in battery at 78%](images/openflight-battery-status.jpg)
+
+### Indicator States
+
+| Plugged in | On battery | Low | Critical | Unavailable |
+|---|---|---|---|---|
+| ![Plugged in at 78%](images/battery-icon-plugged-in.jpg) | ![On battery at 64%](images/battery-icon-on-battery.jpg) | ![Low battery at 20%](images/battery-icon-low.jpg) | ![Critical battery at 10%](images/battery-icon-critical.jpg) | ![Battery telemetry unavailable](images/battery-icon-unavailable.jpg) |
+
+### Warning Dialogs
+
+| Low battery | Critically low battery |
+|---|---|
+| ![Dismissible low-battery warning at 20%](images/battery-alert-low.jpg) | ![Dismissible critical-battery warning at 10%](images/battery-alert-critical.jpg) |
+
+Session logs contain `power_status` records with the provider, percentage,
+voltage, external-power state, availability, timestamp, and any read error.
+The session-start configuration also records the selected provider.
+
+## Raspberry Pi Taskbar Compatibility
+
+Raspberry Pi's `wfplug-batt` panel normally calculates percentage from charge
+or energy counters. Some standard Linux battery drivers expose an already
+calculated `capacity` value instead. OpenFlight's shared taskbar patch adds
+support for that standard property and clamps full-charge overshoot to 100%.
+
+![Raspberry Pi desktop showing the taskbar battery indicator](images/raspberry-pi-taskbar.png)
+
+The shared ARM64 Raspberry Pi OS Trixie package and source patch are stored at:
+
+```text
+scripts/battery/packages/
+scripts/battery/patches/
+```
+
+This compatibility package is not Geekworm-specific. A provider setup script
+may install it when that provider's Linux driver needs capacity-only support.
+It affects only the Raspberry Pi desktop panel; OpenFlight's UI reads the same
+Linux telemetry directly and does not require the panel package.
+
+## Adding A Provider
+
+Add hardware integrations under `src/openflight/power/providers/`, register the
+provider name and reader in `src/openflight/power/factory.py`, and add focused
+reader and factory tests. Provider-specific Pi provisioning belongs under
+`scripts/battery/<provider>/`, with its operator guide under `docs/battery/`.
+
+Keep provider readers read-only. Any future controlled shutdown behavior must
+remain a separate policy that first stops OpenFlight cleanly, asks Linux to
+halt, and only then allows the UPS to remove Pi power.