batsignal1

Battery monitor daemon

Usage

batsignal [OPTIONS]

Overview

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'"