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/

