# fluxBattery

A Window Maker style battery / UPS monitor dockapp for the Fluxbox slit.
Displays charge as a thick donut arc that shrinks clockwise from 12 o'clock
as the battery discharges: at 50% it looks like a C, at 100% it is a full O.
A `+` shows in the hole while charging, `-` while discharging, and the hole is
blank when the battery is full and not discharging. A small `BAT 87%` /
`UPS 87%` label sits below the donut.

Part of the [Flux Dock Apps Suite](https://www.chrisspackman.com/software/flux-dock-apps/).

## Screenshot

```
┌──────────────┐
│    ▄█████▄   │
│   ██     ██  │  ← donut arc (full at 100%)
│  ██   +   ██ │  ← + charging, - discharging, blank full
│   ██     ██  │
│    ▀█████▀   │
│──────────────│
│    BAT 87%   │  ← source label + percentage
└──────────────┘
```

## Installation

Requires Rust and a working X11 environment. For UPS monitoring you also need
[Network UPS Tools](https://networkupstools.org/) configured and running, with
the `upsc` command available in `$PATH`.

```sh
cargo build --release
cp target/release/fluxBattery ~/.local/bin/
```

The release build is stripped and LTO-optimized. No runtime dependencies beyond
libc and libX11 (plus `upsc` if you monitor a UPS).

## Usage

```
fluxBattery [OPTIONS]
```

Add `fluxBattery` to your Fluxbox startup to embed it in the slit.

### Options

| Flag | Description |
|---|---|
| `--size SIZE` | Window size: 64, 96 (default), or 128 pixels |
| `--font PATH` | Path to a TTF/OTF font file |
| `--interval SECS` | Update interval in seconds (minimum 1, default 5) |
| `--source MODE` | Data source: `auto`, `battery`, or `ups` |
| `--battery NAME` | Use sysfs battery NAME (e.g. `BAT0`) |
| `--ups NAME` | Use NUT UPS NAME (e.g. `myups` or `myups@host`) |
| `--theme THEME` | Color theme (`zenburn`) |
| `--background`, `--bg` | Run in background |
| `--write-config [PATH]` | Write annotated config file and exit |
| `--configure` | Interactive configuration wizard |
| `--help` | Show help message |

### Click behavior

| Button | Action |
|---|---|
| Left click | Toggle the detail popup (or run `left_click` command) |
| Middle click | Reload config (or run `middle_click` command) |
| Right click (content) | Run `right_click` command |
| Right click (border) | Fluxbox slit menu |

### Popup info

**Battery (sysfs):** status, charge %, energy (Wh) or charge (Ah),
health vs design capacity, instantaneous power draw, time remaining
or time to full, voltage, cycle count, technology, model and
manufacturer.

**UPS (NUT):** decoded status (Online, On Battery, Charging, ...),
charge %, estimated runtime, battery voltage vs nominal, input
voltage vs nominal, output voltage, load %, real power draw, input
line frequency, battery type, and model/manufacturer.

## Data sources

- `/sys/class/power_supply/<name>/capacity` — charge percentage
- `/sys/class/power_supply/<name>/status` — charging state
- `/sys/class/power_supply/<name>/energy_now`, `energy_full`,
  `power_now` (or `charge_now`, `charge_full`, `current_now`)
- `upsc <ups_name>` — NUT client; see `upsc(8)`.

## Configuration

Config file: `~/.config/fluxBattery/config`

Generate an annotated config:

```sh
fluxBattery --write-config
```

Or use the interactive wizard (auto-detects available sources):

```sh
fluxBattery --configure
```

### Config options

```ini
# auto | battery | ups
source = auto

# For sysfs: use a specific battery directory (default: first found)
battery_name = BAT0

# For NUT: UPS name (see `upsc -l`); may include @host
ups_name = myups

interval = 5
size = 96
color = 0, 255, 0
dim_color = 0, 200, 0

# Left click default: toggle popup
left_click =
middle_click =
right_click =
```

## License

[CC0 1.0](LICENSE) — Public Domain