apcupsd-usb.txt

   1 AUTHOR:         Bryan Mason <bmason@bmason.com>
   2
   3 DATE:           2004-05-24
   4
   5 LICENSE:        GNU Free Documentation License Version 1.2
   6                 Copyright (c) 2003-2004, Bryan Mason.
   7                 Permission is granted to copy, distribute and/or modify
   8                 this document under the terms of the GNU Free
   9                 Documentation License, Version 1.2 or any later version
  10                 published by the Free Software Foundation. A copy of the
  11                 license can be found at
  12                 http://www.gnu.org/copyleft/fdl.html.
  13
  14 SYNOPSIS:       APCUPSD Power Protection from an APC UPS Connected via USB
  15
  16 ATTACHMENTS:    Init script for starting apcupsd:
  17                 http://www.bmason.com/LFS/apcupsd/apcupsd
  18
  19 DESCRIPTION:    This hint describes how to install some of the new
  20                 Uninterruptable Power Supplies (UPS's) from American
  21                 Power Conversion (APC) that use a Universal Serial Bus
  22                 (USB) interface to connect to the host.
  23
  24 PREREQUISITES:  This hint assumes that you have already a working system
  25                 and are comfortable with configuring and re-compiling
  26                 the Linux kernel.  Although this hint was written based
  27                 on LFS 3.3, it should work equally well on newer LFS
  28                 installations as well, although they have not been
  29                 fully tested.
  30
  31 HINT:
  32
  33 Contents
  34 ========
  35
  36     1. Introduction
  37     2. Configuring the LFS Kernel for USB and HID Support
  38     3. Installing apcupsd with USB Support
  39     4. Configuring Apcupsd
  40     5. Testing the Installation
  41     6. Creating Scripts
  42     7. Advanced Testing
  43     8. Tested Configurations
  44     9. Troubleshooting
  45
  46
  47 1. Introduction
  48 ===============
  49
  50     John McSwain's hint, "Apcupsd power protection for your LFS
  51     connected to an APC UPS via serial port" describes how to install an
  52     Uninterruptable Power Supply (UPS) made by American Power Conversion
  53     (APC) using apcupsd as the software interface between the UPS and
  54     the LFS system.  Apcupsd monitors the UPS and informs the system
  55     when a power loss has occurred and can subsequently shutdown the
  56     system if power is not restored within a predetermined time.
  57
  58     John's hint works fine for those UPS's that use a serial cable to
  59     interface to the host computer, but many of APC's new UPS's use a
  60     Universal Serial Bus (USB) hardware interface to connect to the
  61     system that is being provided power by the UPS.  Versions 3.9.4 and
  62     later of apcupsd provide direct support for USB UPS's.  This hint is
  63     based on version 3.10.13 of apcupsd, the latest stable version of
  64     apcupsd available at the time of writing.
  65
  66     Installation of a USB UPS consists of the following basic steps,
  67     which are described in more detail below:
  68     1) Configuring the LFS Kernel for USB and HID support
  69     2) Installing apcupsd with USB support
  70     3) Configuring apcupsd
  71     3) Testing the installation
  72     4) Creating scripts
  73
  74     If you have any comments or corrections to be made to this document,
  75     please send an e-mail message to the author at <bmason@bmason.com>.
  76
  77
  78 2. Configuring the LFS Kernel for USB and HID Support
  79 =====================================================
  80
  81     To enable the use of a USB UPS in Linux, not only USB support is
  82     required, but also support for Human Interface Devices (HIDs). The
  83     documentation on the apcupsd Web site states that Alan Cox's patch
  84     are required to enable HID support.  This may have been true on
  85     older kernels, but HID support now seems to be an integral part of
  86     kernel version 2.4.18 which was the version used in creating this
  87     hint.
  88
  89     To enable USB and HID, make sure that the following items are
  90     enabled either as a module or as part of the kernel.  Generally it's
  91     easier to install these as part of the kernel; otherwise the modules
  92     will have to be loaded in the boot script and a delay will need to
  93     be made so that the USB drivers can recognize the UPS.
  94
  95     Kernel options to be enabled:
  96
  97     - "Input Core Support" (CONFIG_INPUT)
  98     - "Support for USB" (CONFIG_USB)
  99     - "Preliminary USB File System" (CONFIG_USB_DEVICEFS)
 100     - "USB Human Interface Device (full HID) support" (CONFIG_USB_HID)
 101     - "/dev/hiddev raw HID device support" (CONFIG_USB_HIDDEV)
 102     - One of:
 103         "UHCI (Intel PIIX4, VIA, ...) support" (CONFIG_USB_UHCI)
 104         or "UHCI Alternate Driver (JE) support" (CONFIG_USB_UHCI_ALT)
 105         or "OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support"
 106            (CONFIG_USB_OHCI)
 107       Which one of these last options is enabled will depend on the chip
 108       set used in the system on which LFS is running.  See your
 109       motherboard documentation and the help system within menuconfig
 110       for additional information.
 111
 112     After the kernel is configured, proceed with the normal process of
 113     building and installing a new Linux kernel (make bzImage, make
 114     modules, make modules_install, copy the bzImage file, etc.)
 115
 116     Strictly speaking, the "Preliminary USB File System" support isn't
 117     required, but it should make debugging easier if there are problems.
 118
 119
 120 3. Installing apcupsd with USB Support
 121 ======================================
 122
 123     3.1 Review Existing Documentation
 124
 125     Before you install apcupsd, it might be a good idea to review the
 126     documentation for the latest version of apcupsd on the apcupsd Web
 127     site (<http://www.apcupsd.com/>). Specifically, the following
 128     sections might be useful:
 129     - Quick Start for Beginners
 130     - Compiling and Installing
 131     - Using Apcupsd with a USB UPS
 132
 133     Also, reviewing John McSwain's apcupsd hint is also probably a good
 134     idea.
 135
 136     Much of what follows is based on the documentation listed above --
 137     I've just put it in a convenient, easy to swallow format (I hope).
 138
 139
 140     3.2 Download and Unpack Apcupsd
 141
 142     The source tarballs for apcupsd are located on SourceForge at
 143     <http://sourceforge.net/projects/apcupsd/>
 144
 145
 146     3.3 Create the HID Devices
 147
 148     After the source has been unpacked, use the "make-hiddev" script in
 149     the "examples" directory of the apcupsd source tree to make the HID
 150     devices.  Make-hiddev performs the following commands:
 151
 152         #!/bin/sh
 153         mkdir -p /dev/usb/hid
 154         mknod /dev/usb/hid/hiddev0 c 180 96
 155         mknod /dev/usb/hid/hiddev1 c 180 97
 156         mknod /dev/usb/hid/hiddev2 c 180 98
 157         mknod /dev/usb/hid/hiddev3 c 180 99
 158         mknod /dev/usb/hid/hiddev4 c 180 100
 159         mknod /dev/usb/hid/hiddev5 c 180 101
 160         mknod /dev/usb/hid/hiddev6 c 180 102
 161         mknod /dev/usb/hid/hiddev7 c 180 103
 162         mknod /dev/usb/hid/hiddev8 c 180 104
 163         mknod /dev/usb/hid/hiddev9 c 180 105
 164         mknod /dev/usb/hid/hiddev10 c 180 106
 165         mknod /dev/usb/hid/hiddev11 c 180 107
 166         mknod /dev/usb/hid/hiddev12 c 180 108
 167         mknod /dev/usb/hid/hiddev13 c 180 109
 168         mknod /dev/usb/hid/hiddev14 c 180 110
 169         mknod /dev/usb/hid/hiddev15 c 180 111
 170
 171     After running make-hiddev, connect your UPS to your LFS system, and
 172     then build and run the "hid-ups" test program to test the connection
 173     between your system and the UPS.
 174
 175     If you compiled USB and/or HID support into modules, make sure that
 176     you have loaded the modules before running hid-ups.  The following
 177     modules should be loaded:
 178     - "hid"
 179     - "input"
 180     - "usbcore"
 181     - "usb-uhci" (or "usb-ohci" or whatever module you created)
 182
 183     To compile and execute hid-ups, execute the following commands
 184     (substituting "<apcupsd-src>" with the directory to which you
 185     unpacked the apcupsd source tarballs.
 186
 187         cd <apcupsd-src>/examples
 188         make hid-ups
 189         ./hid-ups
 190
 191     If hid-ups is successful, the tail of the output from hid-ups should
 192     look similar to the following:
 193
 194         FeatureReport 121
 195           Field 0, app UPS, phys ---
 196             Usage 0, APCPanelTest = 0
 197
 198         FeatureReport 120
 199           Field 0, app UPS, phys ---
 200             Usage 0, AudibleAlarmControl = 2
 201
 202         FeatureReport 117
 203           Field 0, app UPS, phys ---
 204             Usage 0, APC860029_?????? = 34
 205
 206         FeatureReport 116
 207           Field 0, app UPS, phys ---
 208             Usage 0, APC86002A_?????? = 0
 209
 210         Waiting for events ... (interrupt to exit)
 211         Event: Voltage = 122
 212         Event: CommunicationLost = 0
 213
 214     Press Ctrl-C to exit hid-ups.
 215
 216
 217     3.4 Install Apcupsd
 218
 219     Now configure, compile, and install apcupsd by running the following
 220     commands from the top of the source code tree:
 221
 222         ./configure --prefix=/usr --sbindir=/sbin \
 223             --with-serial-dev=/dev/usb/hid/hiddev[0-9] \
 224             --with-upstype=usb --with-upscable=usb --enable-usb \
 225             --enable-pthreads --enable-powerflute &&
 226         make &&
 227         make install
 228
 229     Below are descriptions of the options passed to the configure
 230     script:
 231
 232     --with-serial-dev=/dev/usb/hid/hiddev[0-9]: This is not a typo, and
 233     should be entered exactly as shown.  This syntax allows apcupsd to
 234     search all the USB devices to find the UPS.
 235
 236     --with-upstype=usb: This tells apcupsd to default to a USB UPS. This
 237     option can be changed at runtime by modifying apcupsd's
 238     configuration file.
 239
 240     --with-upscable=usb: This tells apcupsd to default to a USB cable.
 241     This option can be changed at runtime by modifying apcupsd's
 242     configuration file.
 243
 244     --enable-usb: This enables the USB support in apcupsd.
 245
 246     --enable-pthreads: This option enables pthreads support causing
 247     apcupsd to be built as a threaded program rather than forking to
 248     create separate processes. This should cause apcupsd to be more
 249     efficient with memory and resources.  This is not strictly needed
 250     for USB support, but is a good idea.
 251
 252     --enable-powerflute: This enables the building of powerflute, which
 253     is an ncurses-based program that can be used to monitor the UPS.
 254     This is not strictly need for USB support or even to build apcupsd,
 255     but it could be a useful program.
 256
 257     Additional information on features that can be enabled through use
 258     of the configure utility can be viewed by executing
 259
 260         ./configure --help
 261
 262     Executing these commands will put the following files in the
 263     following directories:
 264
 265         Executable Binaries
 266             Location:   /sbin
 267             Files:      powerflute
 268                         apcaccess
 269                         apcnisd
 270                         apcupsd
 271
 272         Configuration and Script Files
 273             Location:   /etc/apcupsd
 274             Files:      masterconnect
 275                         mastertimeout
 276                         apcupsd.conf
 277                         commfailure
 278                         apccontrol
 279                         mainsback
 280                         onbattery
 281                         changeme
 282                         commok
 283
 284         Help Files
 285             Location:   /usr/share/man/man8
 286             File:       apcupsd.8
 287
 288 4. Configuring Apcupsd
 289 ======================
 290
 291     The apcupsd configuration file is located by default at
 292     /etc/apcupsd/apcupsd.conf.  There shouldn't be much of a need to
 293     change anything in this file, since most of the important settings
 294     have already been specified during the compilation of apcupsd in
 295     Section 3.4 above.
 296
 297     The only thing that might be a good idea is to modify the behavior
 298     of apcupsd and syslogd so that apcupsd events are sent to their own
 299     file, /var/log/apcupsd.log. To do this, modify the following line in
 300     apcupsd.conf:
 301
 302     From:   #FACILITY local0
 303     To:     FACILITY local1
 304
 305     Then add the following lines to /etc/syslog.conf:
 306
 307         # Logging for apcupsd
 308         local1.*            -/var/log/apcupsd.log
 309
 310     If the "local1" facility is already being used by another program,
 311     then change "local1" in the examples above to "local2" or another
 312     free local facility.
 313
 314     After this is done, syslogd needs to be reloaded by executing the
 315     following command:
 316
 317         /etc/rc.d/init.d/sysklogd reload
 318
 319 5. Testing the Installation
 320 ===========================
 321
 322     5.1 Running apcupsd
 323
 324     The first step in testing is to run the apcupsd program itself.
 325     Load the USB modules (if not compiled directly into the kernel) by
 326     executing
 327
 328         modprobe hid
 329         modprobe usb-uhci
 330         apcupsd
 331
 332     (The last command may need to be "modprobe usb-ohci") if you've
 333     compiled kernel support for an OHCI compliant USB controller instead
 334     of UHCI compliant one.)
 335
 336     Wait for apcupsd to configure itself and establish contact with the
 337     UPS, and then execute
 338
 339         ps fax | grep apcupsd
 340
 341     The output should look something like
 342
 343         8525 ?        SN     0:00 /sbin/apcupsd
 344         8527 ?        SN     0:00  \_ /sbin/apcupsd
 345         8528 ?        SN     0:00      \_ /sbin/apcupsd
 346         8529 ?        SN     0:00      \_ /sbin/apcupsd
 347
 348     or
 349
 350         4492 ?        S      0:00 apcmain
 351         4496 ?        S      0:00  \_ apcser
 352         4497 ?        S      0:00  \_ apcnis
 353
 354     if you did not use the "--enable-pthreads" option in configure.
 355
 356     Next, take a look at the contents of the apcupsd log file by
 357     executing
 358
 359         tail /var/log/apcupsd.log
 360
 361     The result should be something similar to the following:
 362
 363         May 24 13:49:56 linux apcupsd[8217]: apcupsd 3.10.13 \
 364             (16 April 2004) unknown startup succeeded
 365
 366     If apcupsd generates an error code and then exits, see the
 367     "Troubleshooting Your Installation" section of the apcupsd
 368     documentation on the apcupsd Web site (<http://www.apcupsd.com/>)
 369     for information on possible sources of problems.
 370
 371
 372     5.2 Getting UPS status
 373
 374     Once apcupsd is successfully loaded, the next step is to get status
 375     from the UPS.  To do this, execute
 376
 377         apcaccess status
 378
 379     The result should be similar to the following:
 380
 381         APC      : 001,035,0853
 382         DATE     : Mon May 24 13:50:28 PDT 2004
 383         HOSTNAME : linux
 384         RELEASE  : 3.10.13
 385         VERSION  : 3.10.13 (16 April 2004) unknown
 386         UPSNAME  : linux
 387         CABLE    : USB Cable
 388         MODEL    : Back-UPS RS 1000
 389         UPSMODE  : Net Master
 390         STARTTIME: Mon May 24 13:49:50 PDT 2004
 391         SHARE    : NetworkUPS
 392         STATUS   : ONLINE
 393         LINEV    : 122.0 Volts
 394         LOADPCT  :  18.0 Percent Load Capacity
 395         BCHARGE  : 100.0 Percent
 396         TIMELEFT :  50.1 Minutes
 397         MBATTCHG : 10 Percent
 398         MINTIMEL : 10 Minutes
 399         MAXTIME  : 0 Seconds
 400         LOTRANS  : 097.0 Volts
 401         HITRANS  : 138.0 Volts
 402         ALARMDEL : Always
 403         BATTV    : 27.1 Volts
 404         NUMXFERS : 0
 405         TONBATT  : 0 seconds
 406         CUMONBATT: 0 seconds
 407         XOFFBATT : N/A
 408         SELFTEST : NO
 409         STATFLAG : 0x02000008 Status Flag
 410         MANDATE  : 2002-10-13
 411         SERIALNO : JB0241034799
 412         BATTDATE : 2001-09-25
 413         NOMBATTV :  24.0
 414         FIRMWARE : .g2 .D USB FW:g2
 415         APCMODEL : Back-UPS RS 1000
 416         END APC  : Mon May 24 13:50:55 PDT 2004
 417
 418
 419 6. Creating Scripts
 420 ===================
 421
 422     6.1 Creating the boot script
 423
 424     The following boot script will start, stop, restart, etc. apcupsd.
 425     It is based on the LFS boot script template
 426     (/etc/rc.d/init.d/template) and the file apcupsd in the
 427     platforms/unknown directory of the apcupsd source tree.
 428
 429     --------------------------------------------------------------------
 430     #!/bin/bash
 431     # Begin /etc/rc.d/init.d/apcupsd
 432
 433     # Based on sysklogd script from LFS-3.1 and earlier.
 434     # Rewritten by Gerard Beekmans  - gerard@linuxfromscratch.org
 435     # Apcupsd version written by Bryan Mason - bmason@bmason.com
 436
 437     source /etc/sysconfig/rc
 438     source $rc_functions
 439
 440     case "$1" in
 441         start)
 442     #       Comment the following lines if the USB and HID
 443     #       drivers were built into the kernel
 444     #       Use "modprobe usb-ohci" instead of "modprobe usb-uhci"
 445     #       if you have an OHCI compliant USB controller.
 446
 447             echo "Installing modules for USB and HID..."
 448             modprobe usb-uhci &&
 449             modprobe hid
 450             evaluate_retval
 451
 452             echo "Starting APC UPS Daemon (apcupsd)..."
 453             rm -f /etc/apcupsd/powerfail
 454             rm -f /etc/nologin
 455             loadproc /sbin/apcupsd
 456             ;;
 457
 458         stop)
 459             echo "Stopping APC UPS Daemon (apcupsd)..."
 460             killproc /sbin/apcupsd
 461
 462     #       Comment the following lines if the USB and HID
 463     #       drivers were built into the kernel
 464     #       Replace "usb-ohci" with "usb-uhci"
 465     #       if you have an OHCI compliant USB controller.
 466
 467             echo "Removing modules for USB and HID..."
 468             rmmod usb-uhci hid input usbcore
 469             evaluate_retval
 470
 471     #       Sometimes killproc can't kill apcupsd, which
 472     #       interrupts the shutdown process.
 473     #       That isn't good.  So lets make sure to always
 474     #       exit with a status of 0.
 475
 476             exit 0
 477             ;;
 478
 479         reload)
 480             echo "Reloading APC UPS Daemon (apcupsd)..."
 481             reloadproc /sbin/apcupsd
 482             ;;
 483
 484         restart)
 485             $0 stop
 486             sleep 1
 487             $0 start
 488             ;;
 489
 490         status)
 491             /sbin/apcaccess status
 492             statusproc /sbin/apcupsd
 493             ;;
 494
 495         *)
 496             echo "Usage: $0 {start|stop|reload|restart|status}"
 497             exit 1
 498             ;;
 499
 500      esac
 501
 502     # End /etc/rc.d/init.d/apcupsd
 503     --------------------------------------------------------------------
 504
 505     The commands to load the USB kernel modules in the script can
 506     probably be removed entirely if you're running hotplug.  I don't use
 507     hotplug, so I'm not sure about this.  If anybody would like to
 508     comment on this one way or another, please contact me and I'll add
 509     the information into this document.
 510
 511     This file can be made by copying /etc/rc.d/init.d/template to
 512     /etc/rc.d/init.d/apcupsd, made from scratch, or be downloaded from
 513     <http://www.bmason.com/LFS/apcupsd/apcupsd>.
 514
 515
 516     6.2 Creating the links for the boot script
 517
 518     Apcupsd should be started as soon as possible during the boot
 519     process, right after sysklogd is started.  Since sysklogd uses S10,
 520     apcupsd can be started at S15 or S20.  Apcupsd should also be one of
 521     the last things to be stopped, right before sysklogd is stopped.
 522     Create the symbolic links by executing the following commands:
 523
 524         cd /etc/rc.d &&
 525         cd rc0.d &&
 526         ln -s ../init.d/apcupsd K35apcupsd &&
 527         cd ../rc1.d &&
 528         ln -s ../init.d/apcupsd K75apcupsd &&
 529         cd ../rc2.d &&
 530         ln -s ../init.d/apcupsd S15apcupsd &&
 531         cd ../rc3.d &&
 532         ln -s ../init.d/apcupsd S15apcupsd &&
 533         cd ../rc4.d &&
 534         ln -s ../init.d/apcupsd S15apcupsd &&
 535         cd ../rc5.d &&
 536         ln -s ../init.d/apcupsd S15apcupsd &&
 537         cd ../rc6.d &&
 538         ln -s ../init.d/apcupsd K35apcupsd
 539
 540     Of course, if you've renumbered your boot scripts, then you'll need
 541     to link the apcupsd boot script accordingly.
 542
 543
 544     6.3 Creating the UPS Powerdown Script
 545
 546     Normally, the last thing that needs to happen before the system
 547     shuts down is to power off the UPS.  Unfortunately, one of the known
 548     limitations of apcupsd interfacing to a USB UPS is that the
 549     "--killpower" option to apcupsd doesn't work, which means that it is
 550     not possible to power off a USB UPS.  Although the apcupsd
 551     documentation states that the UPS should shut itself down one to two
 552     minutes after the system, I did not observe this in my testing.  In
 553     my case, the UPS continued to supply power to the computer until the
 554     batteries drained to a critically low level.  Of course, this wasn't
 555     a problem because the system had already been shut down.
 556
 557
 558 7. Advanced Testing
 559 ===================
 560
 561     Many tests that should be run on the system before the installation
 562     is considered complete and stable.  The "Testing Apcupsd" section of
 563     the documentation on the apcupsd Web site
 564     (<http://www.apcupsd.com/>) contains a list of such tests. The first
 565     three tests were performed in Section 6 above.  Briefly, the rest of
 566     the test sequence runs as follows:
 567
 568     - Remove the USB cable from the UPS to make sure communications
 569       are working
 570     - Modify some of the scripts used by apcupsd so that they are
 571       "safe" (i.e. they won't actually shut down the system) and
 572       disconnect the UPS from utility power.
 573     - Perform a full shutdown test, but do not allow the UPS to
 574       power down.
 575     - Perform a full shutdown test, allowing the UPS to cut power to
 576       the system.
 577
 578
 579 8. Tested Configurations
 580 ========================
 581
 582     The following configuration has been tested and is fully functional
 583     after following the instructions in this hint:
 584
 585     * APC Back-UPS XS 1000
 586       Note: Apcupsd reports this as a Back-UPS RS 1000
 587     * APC Back-UPS LS 700 on Slackware 9.1
 588     * APC Back-UPS RS 1000 on Slackware 9.1
 589     * APC Back-UPS XS 1000 on SuSE 8.2
 590
 591     If you have successfully installed another APC USB UPS on your LFS
 592     system, please send an e-mail message to <bmason@bmason.com> so I
 593     can add your model number to the above list.
 594
 595 9. Troubleshooting
 596 ==================
 597
 598     The installation of my USB UPS went very smoothly.  I didn't have to
 599     do much troubleshooting, so I don't have any troubleshooting steps
 600     to report.  If you experience problems with your installation and
 601     have a way to overcome them, please send an e-mail message to
 602     <bmason@bmason.com> with your experience, and I'll add it to this
 603     section.
 604
 605
 606 ACKNOWLEDGEMENTS:
 607     * John M. McSwain <jmcswain@infoave.net> for providing the original
 608       apcupsd hint.
 609     * Artur Kedzierski <Artur@Kedzierski.org> for providing information
 610       on the Back-UPS LS 700 and Back-UPS RS 1000.
 611     * Brett Delmage <Brett.Delmage@twobikes.ottawa.on.ca> for providing
 612       information on the Back-UPS XS 1000 running on SuSE 8.2.
 613
 614
 615 CHANGELOG:
 616     [2003-01-23]
 617     * Original Hint
 618     [2003-10-03]
 619     * Modified to conform to new hint format.  Updated some links.
 620     [2003-12-02]
 621     * Added information on Back-UPS LS 700 and RS 1000 on Slackware 9.1.
 622     [2004-05-24]
 623     * Updated for apcupsd version 3.10.13.
 624     * Added more detail on what files would be created and where they
 625       are placed.
 626     * Fixed a couple of mistakes and oversights.
 627     * Added information on Back-UPS XS 1000 on SuSE 8.2
 628
 629
 630