rusty-battery

Logo

CLI tool which notifies you when laptop battery reaches a threshold.

View the Project on GitHub kucera-lukas/rusty-battery

rusty-battery

crates.io pages-build-deployment Continuous Integration

CLI tool which notifies you when laptop battery reaches a threshold.

Why should you use rusty-battery?

If you aren’t able to set start/stop charge threshold (for example via TLP) but would still like to make sure that your battery won’t exceed your preferred threshold. rusty-battery can let you know when your battery reached the threshold by showing a desktop notification and optionally pinging your KDE Connect devices.

Features

notify

Notify whenever battery percentage exceeds the given threshold

Usage: rusty-battery notify [OPTIONS]

Options:

-t, --threshold <THRESHOLD>
        Battery charge threshold

        Whenever the chosen battery device reaches this charge threshold and will be charging, notifications will be sent, alerting that the charger should be unplugged.

        [minimum: 0] [maximum: 100]

        [default: 80]

-v, --verbose...
        More output per occurrence

-m, --model <MODEL>
        Battery model name

        If this value is omitted and only battery device is found for the current device, that one will be used.

        Otherwise, please use the `batteries` subcommand to get a list of all battery devices to get the model of the wanted battery device which should be monitored.

-q, --quiet...
        Less output per occurrence

    --refresh-secs <REFRESH_SECS>
        Number of seconds to wait before refreshing battery device data

        After every battery device refresh, its data will be checked. Notifications will be sent everytime they should be, based on the new refreshed battery device data.

        [default: 30]

    --summary <SUMMARY>
        Notification summary

        Supported variables: THRESHOLD, CHARGE_STATE, MODEL, REFRESH_SECS

        Reference these variables in your summary like shell environment variables with the '$' prefix.

        [default: "Charge limit warning"]

    --body <BODY>
        Notification body

        Supported variables: THRESHOLD, CHARGE_STATE, MODEL, REFRESH_SECS

        Reference these variables in your body like shell environment variables with the '$' prefix.

        [default: "Battery percentage reached the $THRESHOLD% threshold, please unplug your charger"]

    --kde-connect [<KDE_CONNECT_NAMES>...]
        KDE Connect device names

        If this value is not present, KDE Connect will not be used.

        If this value is empty, all of the KDE Connect devices will be pinged.

    --disable-desktop
        Disable desktop notifications

        Specify this flag if you don't want desktop notifications to be shown whenever the chosen battery percentage exceeds the given threshold.

-h, --help
        Print help information (use `-h` for a summary)

-V, --version
        Print version information

batteries

List all available batteries of the current device

Usage: rusty-battery batteries [OPTIONS]

Options:

-h, --help       Print help information
-q, --quiet      Less output per occurrence
-v, --verbose    More output per occurrence
-V, --version    Print version information

kde-connect-devices

List all available KDE Connect devices

Usage: rusty-battery kde-connect-devices [OPTIONS]

Options:

-h, --help       Print help information
-q, --quiet      Less output per occurrence
-v, --verbose    More output per occurrence
-V, --version    Print version information

Installation

From crates.io

cargo install rusty-battery

From source

  1. Clone the repository
git clone git@github.com:kucera-lukas/rusty-battery.git
  1. Change directory
cd rusty-battery
  1. Install with cargo
cargo install --path .

From release page

Download a binary of the latest release and move it to a directory which is in your $PATH. You may need to change the binary’s permissions by running:

chmod +x rusty-battery

If there are any problems with the pre-compiled binaries, file an issue.

Usage tips

rusty-battery is best used when set up to start running in the background when the system boots.

Systemd service configuration

Creating a systemd service is probably the easiest way to setup rusty-battery.

  1. Create the file ~/.config/systemd/user/rusty-battery.service

    This will create a user specific service. You can learn more on the ArchWiki.

  2. You can use the example service in examples/systemd and put it into the service file.

    Depending on the way how you installed rusty-battery you might need to modify the ExecStart value in the Service section. It should point to the location of the rusty-battery binary.

    If you don’t know where is rusty-battery installed but it’s on your path, you can run which rusty-battery.

  3. Modify the rest of the CLI options

  4. Reload the systemd manager configuration

    systemctl --user daemon-reload

  5. Start the systemd service

    systemctl --user start rusty-battery

  6. Check the rusty-battery service status

    systemctl --user status rusty-battery

  7. Enable the rusty-battery service to run on each boot

    systemctl --user enable rusty-battery

Setup with cron

  1. Open crontab
crontab -e
  1. Paste in @reboot rusty-battery notify [YOUR OPTIONS]
  2. Save and exit the text editor, you should see crontab: installing new crontab in your terminal
  3. Reboot the system
reboot

Logging

  1. Choose the log verbosity via the number of occurences of the -v or --verbose flag
  2. Append it to the rusty-battery command
  3. Redirect output via >> /path/to/log/file 2>&1
  4. Check all logs via
less /path/to/log/file

tail -f /path/to/log/file

Debugging

ps aux | grep -e rusty-battery

kill $PID

Device support

Tested on: