initial commit: geekworm x1208 ups prometheus exporter

2026-04-17 20:30:34 +02:00
commit aae6cee886
11 changed files with 389 additions and 0 deletions
@@ -0,0 +1,49 @@
+# x1208-exporter
+
+One-shot Prometheus textfile exporter for the Geekworm X1208 UPS HAT on Raspberry Pi 5.
+
+Reads:
+
+- GPIO 6 (PLD) — `1` = AC plugged in, `0` = on battery.
+- I2C `0x36` (MAX17040 fuel gauge) — battery voltage and state of charge.
+
+Writes `/var/lib/node-exporter/textfiles/x1208.prom` atomically. node-exporter's
+textfile collector serves it at scrape time.
+
+## Metrics
+
+| Name                            | Type  | Description                                  |
+| ------------------------------- | ----- | -------------------------------------------- |
+| `rpi_ups_ac_power`              | gauge | `1` = AC present, `0` = on battery           |
+| `rpi_ups_voltage_volts`         | gauge | Battery cell voltage                         |
+| `rpi_ups_battery_percent`       | gauge | State of charge (0–100)                      |
+| `rpi_ups_last_update_seconds`   | gauge | Unix timestamp of last exporter run         |
+
+## Deploy
+
+```bash
+just deploy
+```
+
+Builds the arm64 binary, scps to `rpi`, installs systemd units, starts the timer.
+
+## Verify
+
+```bash
+just run-once   # forces one read, prints the prom file
+just logs       # journalctl tail
+```
+
+## How node-exporter picks it up
+
+The `monitoring` compose stack on the Pi must mount the textfile dir and pass
+the flag to node-exporter:
+
+```yaml
+node-exporter:
+  volumes:
+    - /var/lib/node-exporter/textfiles:/textfiles:ro
+  command:
+    - '--collector.textfile.directory=/textfiles'
+    # ...existing flags
+```