124 lines
5.4 KiB
Markdown
Executable file
124 lines
5.4 KiB
Markdown
Executable file
# install-battery-tooltip.sh — design notes
|
||
|
||
Notes to travel with the script when copying it to another machine for
|
||
the omarchy PR.
|
||
|
||
## What it does
|
||
|
||
Enriches Omarchy's stock waybar battery tooltip from a minimal
|
||
`5W↓ 69%` into a full readout:
|
||
|
||
Battery 69% · 03h:49m left · ↓10.3W/57Wh
|
||
|
||
Wrapped in an accent-colored border that matches the active theme.
|
||
|
||
Two files are patched:
|
||
|
||
| File | What changes |
|
||
| --------------------------------- | --------------------------------------------------- |
|
||
| `~/.config/waybar/config.jsonc` | 5 keys in the `"battery"` block |
|
||
| `~/.config/waybar/style.css` | `@import` of walker.css + tooltip rules (markered) |
|
||
|
||
## Design decisions
|
||
|
||
1. **Laptop detection (layered, skip cleanly on desktops):**
|
||
- `hostnamectl chassis` (primary — systemd's DMI + heuristics)
|
||
- `/sys/class/dmi/id/chassis_type` (SMBIOS fallback)
|
||
- Battery presence (last resort)
|
||
- `--force` to override
|
||
|
||
2. **Idempotent by construction:**
|
||
- `config.jsonc`: Python regex + brace-depth parser finds the
|
||
`"battery"` block, replaces known keys in-place, inserts missing
|
||
ones. Safe on stock omarchy AND on already-patched systems.
|
||
- `style.css`: `/* >>> battery-tooltip */` marker block — any re-run
|
||
replaces between markers instead of accumulating. The walker.css
|
||
`@import` is only added if not already present.
|
||
|
||
3. **Capacity modes:**
|
||
- Default `design` — rated spec from `energy_full_design`
|
||
(or `charge_full_design × voltage_min_design` if only mAh files exist).
|
||
Never changes, never needs refreshing.
|
||
- `--current` — uses `energy_full` / `charge_full`, reflects battery
|
||
degradation. Drifts over time; user re-runs when they want a
|
||
refreshed number.
|
||
|
||
4. **Theme following:**
|
||
- Border color uses `@selected-text` from the theme's walker.css.
|
||
`omarchy-theme-set` swaps the `~/.config/omarchy/current/theme`
|
||
symlink → border updates automatically on next waybar reload.
|
||
- Font follows because `omarchy-font-set` rewrites both waybar's
|
||
`style.css` font-family AND fontconfig's `monospace` alias, which
|
||
our `<span face='monospace'>` wrapper picks up.
|
||
|
||
5. **Zero-padded time (`03h:49m` not ` 3h 49m`):**
|
||
- `format-time: "{H:02}h:{M:02}m"` keeps the tooltip a constant width
|
||
with no leading-space that would compound with template spacing.
|
||
|
||
6. **Monospace wrapper forces stable width:**
|
||
- `<span face='monospace'>...</span>` around the dynamic fields so
|
||
digit-count transitions (5W → 10W, etc.) don't rewidth the tooltip.
|
||
`<tt>` was unreliable in GTK tooltips; `face='monospace'` is honored
|
||
consistently.
|
||
|
||
## Output matrix
|
||
|
||
| Scenario | Result | Exit |
|
||
| ------------------------------ | ------------------------- | ---- |
|
||
| Laptop | Installs | 0 |
|
||
| Desktop / VM / server | Skips with info message | 0 |
|
||
| Desktop with `--force` | Installs anyway | 0 |
|
||
| `--current` | Uses degraded capacity | 0 |
|
||
| `--help` | Prints header comment | 0 |
|
||
| Missing waybar / no python3 | Errors with hint | 1 |
|
||
| Laptop but unreadable sysfs | Errors with path | 1 |
|
||
| Laptop but no `"battery"` block| Errors with hint | 1 |
|
||
|
||
## Dependencies
|
||
|
||
- `bash`, `awk`, `find`, `python3` — all in omarchy's base install.
|
||
- `omarchy-restart-waybar` — optional; if present, waybar is restarted
|
||
automatically. If absent, the installer just reports completion.
|
||
|
||
## Tested on
|
||
|
||
- Acer laptop, BAT1 (charge-based sysfs, Li-ion, ~57Wh design, 18 cycles).
|
||
- Fresh stock omarchy configs (both config.jsonc and style.css).
|
||
- Re-runs (3× identical checksums → idempotent).
|
||
- Simulated desktop via `hostnamectl` override.
|
||
- Unknown-flag and missing-battery paths.
|
||
|
||
## PR suggestions for the omarchy distro
|
||
|
||
- If adding to the install flow, call the installer non-interactively.
|
||
It handles "not a laptop" internally as a zero-exit skip, so no guards
|
||
needed at the caller.
|
||
- If omarchy adds a global install-time hook mechanism, this could live
|
||
there. Otherwise place it in the laptop-specific install path.
|
||
- Backup files (`*.bak.<timestamp>`) accumulate on each re-run.
|
||
Consider adding the installer to a path where backups are either
|
||
swept, or add a `--no-backup` flag if the install flow doesn't want
|
||
them.
|
||
|
||
## Caveats / known edge cases
|
||
|
||
- Capacity padding `{capacity:>3}` means `Battery 5%` at single-digit
|
||
%, `Battery100%` at 100%. Width stays constant; visible gap varies.
|
||
Zero-padding (`005%`) was rejected as uglier.
|
||
- Similarly `↓{power:>4.1f}` shows `↓ 5.2W` vs `↓10.3W`.
|
||
- Full/plugged tooltips don't have `{time}` available so they use a
|
||
simpler format without the monospace span.
|
||
- `{icon}` is NOT supported in `tooltip-format-*` for the battery
|
||
module (waybar errors "argument not found"). We use static state
|
||
glyphs instead — still theme-consistent since all omarchy-managed
|
||
fonts are Nerd Fonts.
|
||
|
||
## File layout after install
|
||
|
||
```
|
||
~/.config/waybar/
|
||
├── config.jsonc # battery block patched
|
||
├── config.jsonc.bak.<ts> # timestamped backup per run
|
||
├── style.css # walker.css import + marker block
|
||
└── style.css.bak.<ts> # timestamped backup per run
|
||
```
|