battery-stats

CLI commands

Fish function at ~/.config/fish/functions/battery-stats.fish. All read-only against ~/Documents/battery-stats/battery.duckdb unless noted.

The display surface interactive

PowerTop manual sudo

Maintenance non-display

How poll.sh works every 5 min

Single sysfs sample + Wayland screen-state probe → one row in battery_samples. Triggered by battery-stats-poll.timer.

What's read from sysfs

Screen state — the honest "is the user actually here" check

Two signals combined:

• loginctl show-session $XDG_SESSION_ID -p IdleHint → true means the desktop session has been idle past the threshold (locked or auto-locked)
• gdbus call --session --dest org.gnome.ScreenSaver --method org.gnome.ScreenSaver.GetActive → true when the GNOME lock screen is up
• screen_active = NOT idle_hint AND NOT screensaver_active

The aggregator-after-each-poll trick

# Refresh derived tables so dashboard reflects every poll.
# Use flock so concurrent runs (e.g. manual + timer) don't collide on the DB.
LOCK="/tmp/battery-stats-aggregate.lock"
flock -n "$LOCK" -c "$HOME/Documents/battery-stats/bin/aggregate-daily.sh >/dev/null 2>&1" || true

Each poll re-runs the aggregator under flock -n (non-blocking). That means battery-stats dashboard always shows fresh data, not yesterday's nightly rollup. The flock prevents two concurrent aggregator runs from corrupting the DB.

How aggregate-daily.sh works nightly + after every poll

Wipes and rebuilds two derived tables from the raw battery_samples: discharge_sessions (one row per AC-off → AC-on) and daily_battery (per-day rollup in IST).

Session detection

1. Sort all samples by timestamp
2. Tag each row with new_session = 1 when on_ac goes true → false (the unplug moment)
3. session_id = SUM(new_session) OVER (ORDER BY ts) — running count
4. Filter to on_ac = false samples only
5. Group by session_id → MIN/MAX timestamps, capacity start/end, energy used

SOT integration

For each sample, compute interval_seconds = time-to-next-sample, capped at 600s. The cap handles laptop suspends (gap of hours appears as one 10-minute interval, not 4 hours of fictitious drain). SOT is the sum of intervals where screen_active = true.

LEAST(
    COALESCE(EXTRACT(EPOCH FROM (LEAD(ts) OVER (ORDER BY ts) - ts)), 300),
    600
) AS interval_seconds

Phantom session filter

Sessions with duration ≤ 60s OR energy_delta ≤ 0.05 Wh are dropped via HAVING. This eliminates flicker sessions (briefly unplug-and-replug) that would otherwise dominate the dashboard's "worst sessions" panel with bogus 0Wh / infinite-runtime entries.

IST date bucketing for daily_battery

DATE_TRUNC('day', (start_ts AT TIME ZONE 'UTC') AT TIME ZONE 'Asia/Kolkata')::DATE AS date

The double AT TIME ZONE matters — see Timezone gotcha.

Health backfill

After daily rollup, a second UPDATE pulls end-of-day cycle count and energy_full_wh from the raw samples (FIRST() ORDER BY ts DESC), and computes health_pct = energy_full / energy_full_design × 100. Tracks battery decay over time.

How ingest-upower.sh works one-time backfill

UPower (the Linux battery daemon) keeps its own historical TSV files at /var/lib/upower/history-*.dat. We bulk-import them once at install so the dashboard has data going back weeks/months even before our own poller starts.

File detection

UPower names files history-{rate,charge}-{MODEL}-{SERIAL}.dat. We auto-detect the model:

BATTERY_MODEL="${BATTERY_MODEL:-$(cat /sys/class/power_supply/BAT0/model_name | tr -d '[:space:]')}"
RATE_FILE=$(ls "$HIST_DIR"/history-rate-"$BATTERY_MODEL"-*.dat | head -1)
CHARGE_FILE=$(ls "$HIST_DIR"/history-charge-"$BATTERY_MODEL"-*.dat | head -1)

Override with BATTERY_MODEL=<tag> env var if your distro names files differently. Don't hardcode a serial — moves between laptops break.

TSV format

Each line is epoch \t value \t state. value is watts for the rate file, percentage for charge. state is charging/discharging/fully-charged/etc.

Pipeline

How powertop-capture.sh works manual

On-demand snapshot of the OS-level top energy consumers (processes, devices, tunables). Needs root, so it routes through the SUDO_ASKPASS + zenity popup defined in ~/.local/bin/sudo-askpass.

Why python parses, not jq

powertop's CSV is hostile — semicolon-delimited with multi-row section headers like ______; ; ;. The parser scans for the "Top 10 Power Consumers" line, then collects rows until it hits an underline or blank. For each row it heuristically picks:

• description = longest text field
• pw_estimate_w = first field matching ^[\d.]+\s*W$
• wakeups_per_sec = first plain numeric field

Imperfect, but good enough to spot "this Discord build is burning 4W idle." For deeper analysis, run powertop directly (interactive mode) and use this snapshot as a historical anchor.

Schema

Six tables. Source-of-truth at ~/Documents/pulse/battery-stats/schema.sql.

battery_samples populated by poll.sh, every 5 min

discharge_sessions derived from battery_samples

daily_battery per-IST-day rollup

upower_rate, upower_charge UPower bulk import

powertop_runs, powertop_top_processes