Imported Upstream version 2.4.3

docs/nut-hal.txt

@@ -0,0 +1,118 @@
+Desc: NUT integration with FreeDesktop HAL - Hardware Abstraction Layer
+File: nut-hal.txt
+Date: 05 March 2008
+Auth: Arnaud Quette <aquette.dev@gmail.com>
+
+This document introduces NUT integration with FreeDesktop HAL
+(Hardware Abstraction Layer), also called Integrated Power Management (IPM).
+
+Introduction
+------------
+
+This feature, also known as the Common Power Management integration,
+allows NUT drivers to feed the HAL system, which will itself feeds
+applications such as the Gnome Power Manager, in charge of the
+system protection and notification.
+
+This allows a better integration with the HAL supported systems
+(Linux, *BSD and Solaris), and to reuse applications that have
+been written to support laptop batteries. This also means that
+we avoid the code / application redundancy by not using the upsd
+and upsmon / NUT Client layer.
+
+Since the NUT driver subset is limited to USB only, at least for
+the moment, this should allow this feature to be shipped with a
+base system.
+
+From a user point of view, since all the needed components are
+present on the system, we can achieve a full plug and play system.
+That is to say when you plug your USB UPS, the needed driver is
+automatically loaded and the according application (ie GPM) is
+made available (displayed) at runtime without having to install
+anything else than the base system. Nothing more to install,
+nothing more to configure...
+
+Detailed usage
+---------------
+
+Since this feature is still a work in progress, the below information
+details how to get, install and test it.
+
+Note that the minimum HAL version required is 0.5.8
+
+* install libhal-dev and its dependencies (libdbus-dev)
+or equivalent packages for your system.
+
+* "./configure --with-hal && make" from within the nut dir
+
+* either do a "make install" or simply copy the file
+drivers/hald-addon* to the HAL addons directory (ie
+/usr/lib/hal/ on Debian) or equivalent dir.
+
+* copy the scripts/hal/20-ups-nut-device.fdi file to
+$datadir/hal/fdi/information/20thirdparty
+for example on Debian: /usr/share/hal/fdi/information/20thirdparty/
+
+* create the (nut user and) group for the udev rule:
+addgroup --quiet --system nut
+
+* add the hal user (ex: haldaemon) to the nut group using:
+adduser --quiet haldaemon nut
+
+* restart HAL (ie using "/etc/init.d/dbus restart").
+I've personaly used "killall hal" and restarted it using
+"hald --daemon=no --verbose=yes" to see the verbose logs
+
+* plug your UPS' USB cord into your computer
+
+* you should now see the UPS using:
+- [kde-]hal-device-manager,
+- gnome power manager (standard applet for battery management), which
+will pop up and state that there is an UPS
+- ...
+
+Packaging information
+---------------------
+
+The HAL support in NUT must currently be packaged separatly (ie in a
+specific nut-hal package) and must conflict with the classic nut packages.
+This is in order to:
+- allow shipping of the HAL support only in the base system,
+without including all the NUT drivers and software,
+- prevent the NUT HAL addons to get an exclusive
+and automatic access on a device, when a user only want to use the
+USB support with a classic NUT installation.
+
+This will be addressed when the new NUT configuration framework
+will be merged in the main code branch.
+
+Developing information
+----------------------
+
+As of NUT 2.2.2, the HAL integration also provide a DBus interface to
+allow the calling of two method:
+- Shutdown
+- SetBeeper (boolean)
+
+Example:
+dbus-send --system --print-reply --dest=org.freedesktop.Hal \
+	/org/freedesktop/Hal/devices/usb_device_463_ffff_1H2E300AH \
+	org.freedesktop.Hal.Device.UPS.Shutdown
+
+For development purposes, you might want to set the environment variable
+"NUT_HAL_DEBUG" to something between "1" and "5". This matches the NUT debug
+levels (-DDDDD).
+
+Credits
+-------
+
+Thanks to the following people who made this possible:
+- David Zeuthen, HAL Project Leader,
+- Richard Hughes, Gnome Power Manager Developer.
+
+References
+----------
+
+* FreeDesktop HAL: http://freedesktop.org/wiki/Software_2fhal
+* Gnome Power Manager: http://www.gnome.org/projects/gnome-power-manager/
+