asapm(1)

NAME
asapm - the AfterStep APM / ACPI monitor

SYNOPSIS
asapm [-h] [-H] [-V]
        [-rc resource file]
        [-iconic] [-withdrawn] [-standout]
        [-position [+|-]x[+|-]y]
        [-syslevels|nosyslevels]
        [-systime|nosystime]
        [-name window name]
        [-dev device]
        [-bat name]
        [-acpi] [-apm]
        [-fail]
        [-u update rate]
        [-display display]
        [-status color]
        [-green color]
        [-yellow color]
        [-red color]
        [-lower color]
        [-upper color]

DESCRIPTION
The asapm is a X11 application that acts as an Advanced Power Management (APM) system or ACPI system monitor for laptop and notebook PCs running Linux, FreeBSD, or NetBSD. The asapm provides a distinctive Afterstep window manager look and feel and features multiple options to allow the customization. Basically, the tool shows you the following:

- The bar-like indicator of the charge left in the battery
  which appears on the left side and is battery-shaped.
  The bottom part shows the charge left in the battery.
  The colors may be customized.

- The top line works as a pair of indicators. You see
  there a battery outline which is "green" when the
  battery status is high, "yellow" when the battery status
  is low, and "red" when the battery status is critical.
  The colors may be customized. The definition of the
  high, low, critical status may be mine :-) or APM
  daemon's - you can choose. The AC plug outline is black
  while you run the computer on the battery and it turns
  "green" when your computer is connected to the mains.
  The plug will turn red while the battery is charging
  and return back to green when the battery is full.

- The second line is the charge left in the battery in
  percent. If the APM daemon does not return a good value
  for it, the display is disabled. Note that when using
  ACPI, the value may never reach 100% - that's how it
  works, that's not a bug.

- The third line is the estimate of the time left before
  the complete discharge of the battery. This estimate is
  either provided by the APM daemon or is calculated by
  this tool itself. When there is no estimate available
  the display is disabled. While using ACPI, the rate
  of charging may be also available; if that's the case,
  you will see also the time to full charge while the
  battery is charging. Not all APM systems support the estimation of the lifetime of the battery. If it is supported it is shown. Otherwise the asapm tool will try to do its best to estimate the time by itself. This will work only when the computer is running on the battery. If the computer is connected to the mains the display is disabled. When the asapm starts in such a situation, it will disable the display for the time until the first change in the battery charge is detected. Then the tool will calculate the elapsed time and try to predict how long it will take before the battery goes flat. The value displayed is not precise so don't rely too much on this. And if you do not like it you can switch it off with the -systime option. The ACPI system works different from APM but the tool will provide all the same information and work the same way if the battery information is provided by the ACPI system. ACPI distinguishes between batteries and you may have multiple batteries in the system without any obvious limits. To avoid complicating things, since ACPI reports each battery status separately, asapm works with a single battery under ACPI. The idea is that you may want to watch particular batteries and not watch others (like when one of them is broken). So, you will start separate instances of asapm to monitor each battery with its own instance of the tool. By default, the first battery detected with the status "present" is monitored, which is what most of us have. The resource files may specify some of the command-line options. The logic of asapm is simple: first it parses the resource file at the default location (~/.asapmrc) if it exists and then goes to parse the command line parsing. Therefore any options on the command line override the corresponding options in the resource file. Unfortunately there is no complete correspondence between what you can specify on the command line and in the configuration file. When one of the parameters on the command line is -rc which specifies an alternative location for the resource file, asapm resets all options and goes to parse that resource file. After parsing it, asapm returns and re-parses the command line.

CONFIGURATION OPTIONS

-h or -H
    prints a short description and usage message.

-V
    Version control. Prints out the version of the program.

-rc resource file
    Specifies the alternative location for the resource file. The default location is ~/.asapmrc. If the alternative file is specified, the default location is parsed first, then the defaults are restored for everything except the reactions and the alternative file is read. I know this is weird - care to change?

-position [+|-]x[+|-]y
    Displays the window at the specified location on the screen. This works as standard X Windows geometry option.

-iconic
    Starts the asapm application in the iconized mode. The icon has the same appearance with the main window. When this option is given, the -position refers to the position of the icon window as well as the main window.

-withdrawn
    Starts the asapm application in the withdrawn mode. This option is necessary to be able to dock the asapm in the WindowMaker dock. When this option is given, the -position refers to the position of the icon window as well as the main window. asapm ignores the -iconic option when started in withdrawn mode.

-standout
    This changes the appearance of the asapm display from "pushed-in" to "popped-out". The first is the default look. The "popped-out" look is also a bit darker then the "pushed-in" and according to some looks much better in WindowMaker's dock. Give it a try in any case.

-syslevels|nosyslevels
    This will make asapm to pay attention to what the APM daemon says about high/low/critical state of the battery and reflect those levels by changing the labels to the appropriate color. By default, asapm would consider levels of power below 40% as low and below 20% as critical because I personally like it that way :-). I want to notice well in advance that the power is running low and not only when the APM daemon starts wall'ing you about it. On my machine I get beeps, the hardware battery indicator starts flashing and APM daemon sends messages to all windows when the power status changes to "low". You know, all the bells and whistles are on and now you want the tool to change the indicator to yellow. What's the point? Anyway, if you really want it - this is the option. There is a good application to this option though. When APM reports the status of the battery being something inconsistent with the percent charge reported you may use it to get a better picture of what is going on. I can imagine that by some glitch APM reports the charge of the battery 100% but the battery state being critical. Then this option will allow asapm to reflect this status. It may be possible that your APM does not report the charge percentage but does report the status of the battery too. This option allows you to see the status of the battery again.

-systime|nosystime
    Some APM daemons/BIOSes do not supply the time left until the complete discharge of the battery. Mine is one of those. By default, asapm detects that the APM daemon does not return a good value and tries to estimate the time itself. It is an estimation based on the time that passed between the two last changes of the power status. You can use this option to make asapm use the time only if it is supplied by the daemon and not attempt any calculations itself. The display for the time left will be disabled all the time if the feature is not supported by the daemon then. The option -systime does not change the behaviour of asapm if the APM daemon and BIOS support the notion of time left until the complete discharge of the battery. However, if your BIOS reports the time left until the complete discharge but reports incorrectly, you can force asapm to calculate this time internally with the -nosystime option.

-acpi
    This is the switch to force the use of ACPI. In effect, it simply disables the part that deals with APM. The last of "-acpi" or "-apm" on the command line takes the effect.

-apm
    This is the switch to force the use of APM In effect, it simply disables the part that deals with ACPI. The last of "-acpi" or "-apm" on the command line takes the effect.

-dev <device>
    Using this option you can specify the location of the file that serves the APM information on your system. The default location of the APM device on Linux systems is /proc/apm and on FreeBSD and NetBSD systems it is /dev/apm device. This same option specifies the location of your ACPI information files in the filesystem. By default, this is /proc/acpi and you can use this switch to point ACPI in a different place. Mind you, the place is the directory where sub-dir "battery" is, not the pointer to inside the sub-dir "battery. In other words, the default location is /proc/acpi and not the /proc/acpi/battery. The effect of this option is that asapm will try to detect both APM and ACPI in the same location. This is ok because only one of them is used anyway. However, it is advisable to use either -acpi or -apm to avoid seeing irrelevant error messages.

-bat <name>
    This option specifies what battery name will be monitored by the asapm. The idea is that you can start multiple instances of this applet each monitoring a separate battery (of course, if you have more than one). asapm will make its best effort to determine the battery name to use automagically. It will list all batteries under the specified directory (see -dev <device>). The first battery that has its state as "present" will be used by default. If you do not want the default battery, use the switch to specify the one you want. For example, the output of "ls /proc/acpi/battery" may look like this:
    	C170  C171
    In this case you can run two instances of asapm like this:
    	asapm -name "battery 1" -bat C170 &
    	asapm -name "battery 2" -bat C171 &
    This option is only useful if you have ACPI and has no effect when APM is used.

-fail
    By default asapm does not quit if an error happens during reading the APM device file. It prints a warning and continues. Most of the time all display parts will be disabled too. This option tells asapm to quit immediately if an error was encountered. I recommend specifying this option when you run from AfterStep Wharf because the output of asapm can fill up your log file if troubles happen and you probably want notice it. However, if you experience occasional glitches in the working of APM daemon (unheard of) or you want to see what APM looks like while not having APM on your machine this option will help.

-u <update rate>
    Changes the polling rate for accessing the APM data. The update rate is specified in seconds. The value of 1 is the minimum. Default value is 1 second.

-status <color>
    Changes the color of the time-left and percentile indicators for asapm. The default color is also LightSeaGreen.

-green <color>
    Changes the color of the "green" image of the battery and power plug when those are in "green" condition. By default the "green" condition is when the charge of the battery is above 40%. The default color is LightSeaGreen.

-yellow <color>
    Changes the color of the "yellow" image of the battery. The "yellow" image corresponds to low charge left state and by default is when the charge of the battery is above 20% but below 40%. The default is DarkGold.

-red <color>
    Changes the color of the "red" image of the battery. The "red" image corresponds to critical battery charge state and by default is when the charge of the battery is below 20%. The default is a kind of red.

-lower <color>
    Changes the color of the bottom side of the indicator that indicates the battery charge left. The indicator is the battery-shaped image on the left. The default is a kind of blue.

-upper <color>
    Changes the color of the top side of the battery indicator that indicates, well, you know, the used up part of the battery charge. The default is a kind of red.

-display <name>
    The name of the display to start the window in. It works just as X Windows display option.

-name <window name>
    The name of the application window will be set to the specified window name. This is useful for swallowing multiple instances of asapm in Wharf.

RESOURCE FILE SYNTAX

fail
    Force the tool to quit when an error is detected while accessing the APM device. Equivalent to the command line "-fail" option.

nofail
    The opposite of "fail". This is the default behaviour.

device <name>
    Use the alternative APM device to read the information. Equivalent to the "-dev" command-line option.

SysLevels
    Use the information the APM daemon provides concerning the level of the power being high/low/critical. Equivalent to the "-syslevels" command line option.

NoSysLevels
    Use my own definition of the low/critical levels of power as being less or equal to 40%/20% respectively.

SysTime
    Don't attempt to calculate the time to live for the battery even if the APM daemon does not supply any value. Equivalent to the -systime command line option.

NoSysTime
    Opposite of "SysTime". Calculate our own values for the remaining time on the battery power when APM daemon does not supply any value.

ColorDepth 8/16
    Force the given color depth. Specify 16 or 8. asapm does automagically detect the display's color depth and will run in the correct mode but this is handy if you want to force it run with different look than the default for your color depth. asapm uses more than 32 colors in 16bpp and around 12 in 8bpp. This is the equivalent of the command line "-bpp" option.

ACOn <command>
    Execute the given command when the APM daemon reports the AC power being switched on. You may want to execute here things that make your computer consume more power.

ACOff <command>
    Execute the specified command when the APM daemon says the AC was switched off (= we are running on some kind of battery). You may want to execute commands here that make your computer more power-conscious and save some power.

PowerDown <command>
    This command is executed every time the battery power level decreases. Nothing really useful.

PowerUp <command>
    This command is executed every time the battery power level increases. Not really useful.

DownTo <percent> <command>
    Execute the given command when the power level drops to the given level. The level must be exact, the command is not executed on the "lower or equal" basis. This is the option I wanted. I make it suspend my computer when the power drops to 10%. Now I can forget to switch it off ;-) These commands may be given multiple times in the rc file.

UpTo <percent> <command>
    Executes the command when the power level reaches up to the given level. I cannot think of any useful application for this. These commands may be given multiple times in the rc file.

Status <color>
    The color for the time-left and percentile indicators for battery strength. The equivalent of the "-status" command line option.

Green <color>
    The color for the battery symbol when the power level is reasonably high. The equivalent of the "-green" command line option.

Yellow <color>
    The color for the battery symbol when the power level is low. The equivalent of the "-yellow" command line option.

Red <color>
    The color for the battery symbol when the power level is critical. The equivalent of the "-red" command line option.

Lower <color>
    The color for the power left indicator. This is the equivalent of the "-lower" command line option.

Upper <color>
    The color for the "empty" part of the battery indicator. This is the equivalent for the "-upper" command line option.

INVOCATION
asapm can be called in different ways. The most common invocation is the command line:
	user@host[1]% asapm -u 2 -lower green -upper yellow &
Another way to call asapm is from the window manager:
	*Wharf "asapm" nil Swallow "asapm" /usr/local/bin/asapm -bat 1 &
This line, when placed in the wharf file in the users Afterstep configuration directory will cause asapm to be a button on the Wharf (1) button bar under the afterstep (1) window manager. If you run WindowMaker then you should use the "-withdrawn" option:
	user@host[1]% asapm -withdrawn -standout &
and then drag the icon to the dock.

BUGS
My programs do not have bugs, they just develop random features ;-)

Well, there are limitations. All the strings for the color names, display name, and the geometry have the length limit of 50 characters (terminating zero included). The string copying routine cuts the names that are longer. The limit on the APM device name is 256 characters.

The number of hours I can show for the lifetime of the battery left is limited by the space. The maximum is 99:59 and that is what it shows when the time left is even more. I doubt that you have a battery that survives longer though :-)

The total number of reactions specified with the "UpTo" and "DownTo" resource file switches is limited to ten.

FILES
/proc/apm /dev/apm /proc/acpi/battery/*

SEE ALSO
apm(1),apmd(8),acpi(1)

COPYRIGHTS
Copyright (c) 1998-2005 Albert Dorofeev <albert@tigr.net> Distributed under GNU General Public License v2 ; see LICENSE file for more informations.

AUTHORS
Albert "Tigr" Dorofeev <albert@tigr.net> See the README file for credits.