| 1 |
How to write applications which use the hwmon drivers |
| 2 |
===================================================== |
| 3 |
|
| 4 |
You have several choices in accessing sensor devices using the hwmon drivers. |
| 5 |
This document will briefly describe these methods, their advantages and |
| 6 |
disadvantages, and provide examples. |
| 7 |
|
| 8 |
From lowest-level to the highest-level, the access methods are: |
| 9 |
|
| 10 |
1. sysfs access |
| 11 |
2. libsensors library |
| 12 |
3. sensors program |
| 13 |
|
| 14 |
|
| 15 |
Details: |
| 16 |
|
| 17 |
1. sysfs access |
| 18 |
--------------- |
| 19 |
Hwmon drivers create subdirectories in the sysfs filesystem (usually /sys) |
| 20 |
which can be accessed directly by applications. |
| 21 |
Naming and content standards for the entries in these subdirectories |
| 22 |
are documented in the file Documentation/hwmon/sysfs-interface in the 2.6 |
| 23 |
kernel source tree. sysfs is the lowest-level access to sensor values. |
| 24 |
|
| 25 |
Note that most drivers provide only raw sensor readings via /sys; |
| 26 |
many readings must be scaled or adjusted, and these adjustments |
| 27 |
must often be changed by the user. An application using /sys must |
| 28 |
generally provide adjustment facilities and the requirements |
| 29 |
of the adjustments can be quite complex. For this reason, this |
| 30 |
approach isn't recommended. Instead, consider the libsensors library, |
| 31 |
which offers a higher-level interface on top of sysfs (see below.) |
| 32 |
|
| 33 |
Still, this method may work well for shell and perl scripts written to |
| 34 |
access a specific device. |
| 35 |
|
| 36 |
For an example of a program using /sys accesses, see gkrellm (though |
| 37 |
recent versions use libsensors instead.) See also lib/sysfs.c. |
| 38 |
|
| 39 |
2. libsensors library |
| 40 |
--------------------- |
| 41 |
The libsensors library provides standardized access to all chip drivers. |
| 42 |
It also provides a translation layer with settings in /etc/sensors.conf |
| 43 |
so that your application sees adjusted (scaled) values using settings |
| 44 |
provided by the user. Other facilities are sensor labelling, limit setting, |
| 45 |
and ignoring individual sensors. This is the recommended way to access |
| 46 |
the sensor chips. |
| 47 |
|
| 48 |
The library API is documented in the libsensors(3) manual page. The |
| 49 |
configuration file format is documented in the sensors.conf(5) manual |
| 50 |
page. |
| 51 |
|
| 52 |
Note that since version 3.2.0, libsensors falls under the LGPL, not the |
| 53 |
GPL as it used to. In more human language, that means it is now ALLOWED |
| 54 |
to link any application to the library, even to the shared version, |
| 55 |
regardless of the application's license. |
| 56 |
|
| 57 |
For examples of programs using libsensors accesses, see prog/sensors and |
| 58 |
prog/sensord. |
| 59 |
|
| 60 |
3. sensors program |
| 61 |
------------------ |
| 62 |
The 'sensors' program is a text-based application that uses libsensors. |
| 63 |
The output is fairly standardized; therefore this output could be |
| 64 |
used by other applications. |
| 65 |
One simple method is 'sensors|grep ALARM'. |
| 66 |
Note though that there is no guarantee that the output format won't change |
| 67 |
in the future, so be careful. We might improve the command-line interface |
| 68 |
of 'sensors' someday to make it more convenient for external programs to |
| 69 |
use it as a back-end. |