docs/nut-hal.txt

   1 Desc: NUT integration with FreeDesktop HAL - Hardware Abstraction Layer
   2 File: nut-hal.txt
   3 Date: 05 March 2008
   4 Auth: Arnaud Quette <aquette.dev@gmail.com>
   5
   6 This document introduces NUT integration with FreeDesktop HAL
   7 (Hardware Abstraction Layer), also called Integrated Power Management (IPM).
   8
   9 Introduction
  10 ------------
  11
  12 This feature, also known as the Common Power Management integration,
  13 allows NUT drivers to feed the HAL system, which will itself feeds
  14 applications such as the Gnome Power Manager, in charge of the
  15 system protection and notification.
  16
  17 This allows a better integration with the HAL supported systems
  18 (Linux, *BSD and Solaris), and to reuse applications that have
  19 been written to support laptop batteries. This also means that
  20 we avoid the code / application redundancy by not using the upsd
  21 and upsmon / NUT Client layer.
  22
  23 Since the NUT driver subset is limited to USB only, at least for
  24 the moment, this should allow this feature to be shipped with a
  25 base system.
  26
  27 From a user point of view, since all the needed components are
  28 present on the system, we can achieve a full plug and play system.
  29 That is to say when you plug your USB UPS, the needed driver is
  30 automatically loaded and the according application (ie GPM) is
  31 made available (displayed) at runtime without having to install
  32 anything else than the base system. Nothing more to install,
  33 nothing more to configure...
  34
  35 Detailed usage
  36 ---------------
  37
  38 Since this feature is still a work in progress, the below information
  39 details how to get, install and test it.
  40
  41 Note that the minimum HAL version required is 0.5.8
  42
  43 * install libhal-dev and its dependencies (libdbus-dev)
  44 or equivalent packages for your system.
  45
  46 * "./configure --with-hal && make" from within the nut dir
  47
  48 * either do a "make install" or simply copy the file
  49 drivers/hald-addon* to the HAL addons directory (ie
  50 /usr/lib/hal/ on Debian) or equivalent dir.
  51
  52 * copy the scripts/hal/20-ups-nut-device.fdi file to
  53 $datadir/hal/fdi/information/20thirdparty
  54 for example on Debian: /usr/share/hal/fdi/information/20thirdparty/
  55
  56 * create the (nut user and) group for the udev rule:
  57 addgroup --quiet --system nut
  58
  59 * add the hal user (ex: haldaemon) to the nut group using:
  60 adduser --quiet haldaemon nut
  61
  62 * restart HAL (ie using "/etc/init.d/dbus restart").
  63 I've personaly used "killall hal" and restarted it using
  64 "hald --daemon=no --verbose=yes" to see the verbose logs
  65
  66 * plug your UPS' USB cord into your computer
  67
  68 * you should now see the UPS using:
  69 - [kde-]hal-device-manager,
  70 - gnome power manager (standard applet for battery management), which
  71 will pop up and state that there is an UPS
  72 - ...
  73
  74 Packaging information
  75 ---------------------
  76
  77 The HAL support in NUT must currently be packaged separatly (ie in a
  78 specific nut-hal package) and must conflict with the classic nut packages.
  79 This is in order to:
  80 - allow shipping of the HAL support only in the base system,
  81 without including all the NUT drivers and software,
  82 - prevent the NUT HAL addons to get an exclusive
  83 and automatic access on a device, when a user only want to use the
  84 USB support with a classic NUT installation.
  85
  86 This will be addressed when the new NUT configuration framework
  87 will be merged in the main code branch.
  88
  89 Developing information
  90 ----------------------
  91
  92 As of NUT 2.2.2, the HAL integration also provide a DBus interface to
  93 allow the calling of two method:
  94 - Shutdown
  95 - SetBeeper (boolean)
  96
  97 Example:
  98 dbus-send --system --print-reply --dest=org.freedesktop.Hal \
  99         /org/freedesktop/Hal/devices/usb_device_463_ffff_1H2E300AH \
 100         org.freedesktop.Hal.Device.UPS.Shutdown
 101
 102 For development purposes, you might want to set the environment variable
 103 "NUT_HAL_DEBUG" to something between "1" and "5". This matches the NUT debug
 104 levels (-DDDDD).
 105
 106 Credits
 107 -------
 108
 109 Thanks to the following people who made this possible:
 110 - David Zeuthen, HAL Project Leader,
 111 - Richard Hughes, Gnome Power Manager Developer.
 112
 113 References
 114 ----------
 115
 116 * FreeDesktop HAL: http://freedesktop.org/wiki/Software_2fhal
 117 * Gnome Power Manager: http://www.gnome.org/projects/gnome-power-manager/
 118