battered 0.9.0

Make the most of your laptop's battery life with custom actions and informative desktop notifications.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

# battered

[![crates.io](https://img.shields.io/crates/v/battered?logo=rust)](https://crates.io/crates/battered)
![AUR Version](https://img.shields.io/aur/version/battered)
[![codecov](https://codecov.io/gh/t4k1t/battered/graph/badge.svg?token=CIMW9ARSPC)](https://codecov.io/gh/t4k1t/battered)
![Crates.io License](https://img.shields.io/crates/l/battered)

<img height="64" alt="battered Icon" src="https://raw.githubusercontent.com/t4k1t/battered/main/assets/icon/battered-icon.svg" align="left">

Make the most of your battery life with custom actions and informative desktop notifications.

Written in Rust, `battered` uses minimal system resources.

-----

[Features](#features) • [Usage](#usage) • [Installation](#installation) • [Configuration](#configuration) • [Logging](#logging) • [License](#license)

## Features

- Unlimited custom actions
- Customizable desktop notifications with placeholder values
- Optional action and notification on connecting power supply
- Configurable poll interval
- Cross-platform: Mac OS and Linux

## Usage

First, make sure you've [configured](#configuration) some actions. Then simply run `battered`:

```bash
battered
```

## Installation

`battered` is available on [crates.io](https://crates.io/crates/battered) and can be installed from there:

```bash
cargo install battered
```

If you're using Arch Linux you can also install it from the AUR using your favorite AUR helper (e.g. `paru`):

```bash
paru -Syu battered
```

## Configuration

battered looks for a configuration file in the following places:
1. `$XDG_CONFIG_HOME/battered/config.toml`
2. `$HOME/.config/battered/config.toml`
3. `/.config/battered/config.toml` if `$HOME` is not set

The `summary` and `body` fields of the `[action.notify]` table support optional placeholders which will be replaced with calculated values. The following placeholders are available:

| Placeholder | Description |
| --- | --- |
| `$percentage` | Current battery level in percent |
| `$state` | Current battery state, e.g. "discharging" |
| `$energy_rate` | Amount of energy drained from the battery in Watts |

By default `battered` will monitor the first battery it finds. Use the `serial_number` config value to pick a specific battery instead.
One way to find the serial number is through sysfs. E.g. find the serial number of `BAT0`:
```bash
cat /sys/class/power_supply/BAT0/serial_number
```

Example config:
```toml
interval = 60           # Battery level check interval in seconds; optional; defaults to 60; integer
serial_number = "31415" # Serial number of battery; optional; defaults to first battery; string

[[action]]
percentage = 0.25                 # Run action below this threshold; required; decimal
command = "./powersave.sh enable" # CLI command to run; optional; string
[action.notify] # Notification settings; optional; table
summary = "Battery low!"             # Notification summary; required within action.notify table; string
body = "Battery below $percentage%!" # Notification body; optional; string
urgency = "Critical"                 # Notfication urgency; optional; defaults to `Normal`; enum[ Low | Normal | Critical ]
icon = "battery-caution"             # Notification icon; optional; defaults to "battery-discharging"; string
timeout = 0                          # Notification timeout in ms; optional; defaults to desktop default; integer; `0` means no timeout

# There can be as many `action` entries as desired, and order doesn't matter
[[action]]
percentage = 0.95
[action.notify]
summary = "Battery discharging"

# Special action to run after connecting to AC
# Options are the same as for regular actions
[on_ac]
percentage = 0.10                  # Only run if battery level above this threshold; optional; decimal
command = "./powersave.sh disable"
[on_ac.notify]
summary = "Battery charging"
urgency = "Low"
icon = "battery-good-charging"
timeout = 300
```

### Notifications on Mac OS

On Mac OS there are some limitations to notifications. Only the `body` and `summary` options have an effect. The `urgency`, `timeout`, and `icon` options can be set, but will be ignored.

## Logging

Logging is configured via the `RUST_LOG` env variable. The provided systemd unit example sets the log level to `WARN` by default.

## License

`battered` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.