


asapm(1)                                                 asapm(1)


NAME
       asapm - the AfterStep APM monitor

SYNOPSIS
       asapm [-h] [-H] [-V]
               [-rc resource file]
               [-iconic] [-withdrawn] [-standout]
               [-position [+|-]x[+|-]y]
               [-syslevels|nosyslevels]
               [-systime|nosystime]
               [-dev device] [-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 Manage-
       ment 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.

       - 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.



Version 2.13             30 October 2002                        1





asapm(1)                                                 asapm(1)


       Not  all APM systems support the estimation of the lifetime of the bat-
       tery. 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  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  over-
       ride  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  com-
       mand 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 spec-
              ified,  the  default location is parsed first, then the defaults
              are restored for everything except the reactions and the  alter-
              native 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



Version 2.13             30 October 2002                        2





asapm(1)                                                 asapm(1)


              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 run-
              ning low and not only when the APM daemon  starts  wall'ing  you
              about it.  On my machine I get beeps, the hardware battery indi-
              cator starts flashing and APM daemon sends messages to all  win-
              dows  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 esti-
              mation  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



Version 2.13             30 October 2002                        3





asapm(1)                                                 asapm(1)


              internally with the -nosystime option.

       -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.

       -fail
              By  default asapm does not quit if an error happens during read-
              ing 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 indi-
              cates the battery charge left. The  indicator  is  the  battery-
              shaped image on the left. The default is a kind of blue.





Version 2.13             30 October 2002                        4





asapm(1)                                                 asapm(1)


       -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.

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.  Equiva-
              lent 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 remain-
              ing 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.





Version 2.13             30 October 2002                        5





asapm(1)                                                 asapm(1)


       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  exe-
              cuted  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  bat-
              tery  strength.   The  equivalent  of the "-status" command line
              option.

       Green <color>
              The color for the battery symbol when the power level is reason-
              ably  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 criti-
              cal.  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



Version 2.13             30 October 2002                        6





asapm(1)                                                 asapm(1)


       the command line:

            user@host[1]% asapm -u 2 -left green -right yellow &

       Another way to call asapm is from the window manager:

            *Wharf "asapm" nil Swallow "asapm" /usr/local/bin/asapm -fail &

       This line, when placed in the wharf file in the users Afterstep config-
       uration directory will cause asapm to be a button on the Wharf (1) but-
       ton 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, dis-
       play 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

SEE ALSO
       apm(1),apmd(8)

COPYRIGHTS
       Copyright (c) 1998-2002  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.







Version 2.13             30 October 2002                        7


