BATSIGNAL(1)

NAME
batsignal - battery monitor daemon

SYNOPSIS
batsignal [OPTIONS]

DESCRIPTION
batsignal is a lightweight battery daemon written in C that notifies the user about battery states. It is intended for minimal window managers, but can be used in any environment that supports desktop notifications via libnotify.

OPTIONS

-h  Display help

-v  Display version information

-b  Run batsignal as background daemon

-o  Check battery once and exit

-i  Ignore missing battery errors

-e  Cause notifications to expire

-N  Disable desktop notifications

-w LEVEL
    Battery warning LEVEL (default 15). 0 disables this level

-c LEVEL
    Critical battery LEVEL (default 5). 0 disables this level

-d LEVEL
    Battery danger LEVEL (default 2). 0 disables this level

-f LEVEL
    Battery full LEVEL (default 0). 0 disables this level

-p  Show a message when the battery begins charging or discharging

-W MESSAGE
    Show MESSAGE when battery is at warning level

-C MESSAGE
    Show MESSAGE when battery is at critical level

-D COMMAND
    Run COMMAND when battery is at danger level

-F MESSAGE
    Show MESSAGE when battery is at full level

-P MESSAGE
    Show MESSAGE when battery is charging, if -p option is set

-U MESSAGE
    Show MESSAGE when battery is discharging, if -p option is set

-M COMMAND
    Send each message using COMMAND

-n NAME
    Battery device NAME - multiple batteries may be separated by commas (default BAT0)

-m SECONDS
    Minimum number of SECONDS (default 60) to wait between battery checks. Settings SECONDS to 0 disables polling and waits for the USR1 signal before checking battery level. Prefixing SECONDS with a + (ex: -m +10) will force a check at SECONDS intervals, regardless of battery level.

-a APP_NAME
    App name used in notifications (default: batsignal)

-I ICON
    Display specified ICON in notifications

CONFIGURATION
Options can be passed to batsignal as command arguments or placed in a configuration file. Options from the configuration file will be applied first and then may be overridden by command line as arguments.

The configuration file should include option arguments as documented above, one argument per line. Lines beginning with # and empty lines are ignored. For example, to specify a warning level of 30 and run as a background daemon, the following configuration file could be used:

    # Run in background
    -b
    # Use warning level of 30
    -w
    30

The following paths are checked in sequence for a configuration file:

•   BATSIGNAL_CONFIG environment variable (if present)

•   $HOME/.config/batsignal (or the config base specificed in XDG_CONFIG_HOME)

•   $HOME/.batsignal

•   /usr/local/etc/batsignal

•   /etc/batsignal

ENVIRONMENT

BATSIGNAL_CONFIG
    Sets the option configuration file path.

XDG_CONFIG_HOME
    The base path for the XDG config directory. Used in the option file search.

SIGNALS
batsignal responds to the following signals:

SIGUSR1
    Sending the process SIGUSR1 will cause an immediate battery check to be performed.

NOTES
In most cases, batsignal will perform fewer battery state checks while the battery is discharging and the level of charge is not near a warning level. This frequency is affected by the multiplier (-m) option and is never less than <multiplier> seconds. If the "full" level (-f) is set or charge/discharge messages are enabled (-p), batsignal will instead check the battery state every <multiplier> seconds regardless of level of charge.

If the "full" level (-f) is set, the battery full notification will be triggered at the given level of charge or when the battery status changes to full, whichever occurs first.

The message COMMAND passed with -M is a C printf-style format string. It can use two string placeholders (%s) that will be replaced by the message text and the current battery level. Be sure to test the command - invalid format strings may cause batsignal to crash.
Ex: -M "wall 'Battery warning: %s - Level is %s'"

COPYRIGHT
Copyright 2018-2024 Corey Hinshaw
Copyright 2016-2017 Aaron Marcher
License: ISC License