www.voj-tech.net


vt-battery-checker

Synopsis

vt-battery-checker is a Bash script which uses desktop notifications to inform the user about the laptop battery state and whether the power cord is plugged in or not.

Motivation

The script comes in handy when your desktop environment does not provide the functionality already or it does but in a somewhat inconvenient manner (in my case this was LXDE).

Installation

Prerequisites

The script requires vt-bash-utils 0.9.0 or later. In particular it calls the functions vtbu_send_desktop_notification and vtbu_single_instance_running. Please download the library from the project page and install it following the instructions provided.

Moreover it is required that your environment features reasonably new versions of:

  • UPower
  • grep
  • the GNU core utilities
  • an implementation of AWK
  • Bash

It should be noted that the script has been tested using UPower 0.99.5, grep 3.1, coreutils 8.27, Gawk 4.1.4 and Bash 4.4.12 on Fedora 26 running on a Lenovo ThinkPad T420 laptop.

Installation Steps

It is currently required to perform a simple manual installation. To do so follow these steps:

  1. Download a ZIP file with the required version of the script from this page. Most likely you want the latest version.

  2. Unpack the downloaded file.

    unzip vt-battery-checker-0.8.1.zip && cd vt-battery-checker-0.8.1
    
  3. If the vt-bash-utils library was installed to a directory other than the /usr/local/share directory modify the vt-battery-checker.sh script on the line where the variable bash_utils_path is assigned a value to specifying the correct directory.

  4. Copy the script to a directory which is in your PATH environment variable and which is your preferred location to install third-party software to. This might be the /usr/local/bin directory for example. Make sure this is done as a user account allowed to write to the destination directory.

    cp vt-battery-checker.sh /usr/local/bin
    
  5. Add the execute mode bit to the script file mode bits. Again, make sure that this is done as the appropriate user account.

    chmod +x /usr/local/bin/vt-battery-checker.sh
    
  6. A common way to enable an application to autostart upon login to a desktop environment is to create a desktop entry for it in one of the directories /usr/xdg/autostart and ~/.config/autostart.

    cat > ~/.config/autostart/vt-battery-checker.sh.desktop <<'EOF'
    [Desktop Entry]
    Type=Application
    Exec=vt-battery-checker.sh
    Hidden=false
    Name=vt-battery-checker.sh
    Comment=
    EOF
    

Reference

Usage

vt-battery-checker.sh

Start vt-battery-checker.

The intention is to configure the desktop environment to do this upon login (see above).

The script currently does not understand any command line options or other arguments.

Description

The script listens for UPower events which signal that a power source has been added, removed or changed. When any such event occurs the script retrieves the value of the Online property of the /org/freedesktop/UPower/devices/line_power_AC object meaning that it checks whether power is currently being provided through line power. If this has changed since the last time it has been checked the script sends a desktop notification signalling the same. If the power is not currently being provided through line power the script retrieves the value of the TimeToEmpty property of the /org/freedesktop/UPower/devices/battery_BAT0 object meaning that it checks how much longer until the battery is empty. The script evaluates the state of the battery based on the estimated time left until it is empty. The state is an integer and it is 0 if the time left is at most 2 minutes, 1 if the time left is at most 6 minutes, 2 if the time left is at most 11 minutes, 3 if the time left is at most 31 minutes and finally 4 if the time left is more than 31 minutes. If the battery state is lower than the last time this has been checked or the power has just stopped being provided through line power the script retrieves the value of the Percentage property of the /org/freedesktop/UPower/devices/battery_BAT0 object meaning that it checks what the amount of energy left in the battery is, expressed as a percentage, and sends a desktop notification stating the estimated time left until the battery is empty and the amount of energy left in the battery.

Currently the script prevents running multiple instances of itself at the same time. Therefore it does not fully support a system shared among multiple users.

Bugs

Suggestions and bug reports are more than welcome at voj-tech@voj-tech.net.