8. Creating new client

NUT provides bindings for several common languages that are presented below. All these are released under the same license as NUT (the GNU General Public License).

If none of these suits you for technical or legal reasons, you can implement one easily using the Network protocol information.

The latter approach has been used to create the Python PyNUT module, the Nagios check_ups plugin (and probably others), which can serve as a reference.

8.1. C / C++

Client access library

The upsclient library can be linked into other programs to give access to upsd and UPS status information. Both static and shared versions are provided.

Clients like upsc are provided as examples of how to retrieve data using the upsclient functions. Other programs not included in this package may also use this library, such as wmnut.

This library file and the associated header files are not installed by default. You must ./configure --with-lib to enable building and installing these files. The libraries can then be built and installed with make and make install as usual. This must be done before building other (non-NUT) programs which depend on them.

For more information, refer to the upsclient(3), manual page and the various upscli_*(3) functions documentation referenced in the same file.

Configuration helpers

NUT provides helper scripts to ease the configuration step of your program, by detecting the right compilation and link flags.

For more information, refer to a Appendix B: NUT libraries complementary information.

8.2. Python

The PyNUT module, contributed by David Goncalves, can be used for connecting a Python script to upsd. Note that this code (and the accompanying NUT-Monitor application) is licensed under the GPL v3.

The PyNUTClient class abstracts the connection to the server. In order to list the status variables for ups1 on the local upsd, the following commands could be used:

$ cd scripts/python/module
$ python
...
>>> import PyNUT
>>> from pprint import pprint
>>> client = PyNUT.PyNUTClient()
>>> vars = client.GetUPSVars('ups1')
>>> pprint(vars)
{'battery.charge': '90',
 'battery.charge.low': '30',
 'battery.runtime': '3690',
 'battery.voltage': '230.0',
...

Further examples are given in the test_nutclient.py file. To see the entire API, you can run pydoc from the module directory.

If you wish to make the module available to everyone on the system, you will probably want to install it in the site-packages directory for your Python interpreter. (This is usually one of the last items in sys.path.)

8.3. Perl

The old Perl bindings from CPAN have recently been updated and merged into the NUT source code. These operate in a similar fashion to the Python bindings, with the addition of access to single variables, and additional interpretation of the results. The Perl class instance encapsulates a single UPS, where the Python class instance represents a connection to the server (which may service multiple UPS units).

use UPS::Nut;
$ups = new UPS::Nut( NAME => "myups",
                     HOST => "somemachine.somewhere.com",
                     PORT => "3493",
                     USERNAME => "upsuser",
                     PASSWORD => "upspasswd",
                     TIMEOUT => 30,
                     DEBUG => 1,
                     DEBUGOUT => "/some/file/somewhere",
                   );
if ($ups->Status() =~ /OB/) {
   print "Oh, no!  Power failure!\n";
}
tie %other_ups, 'UPS::Nut',
    NAME => "myups",
    HOST => "somemachine.somewhere.com",
    ... # same options as new();
;
print $other_ups{MFR}, " ", $other_ups{MODEL}, "\n";

8.4. Java

This chapter presents the new Java support for NUT, called jNut.

Java NUT Client files

This directory contains various NUT Client related java source files, written by Emilien Kia, sponsored by Eaton, and released under GPL v2.

  • "jNut": this directory contains maven project and source files for jNut, which is a Java abstraction bundle to access NUT server(s). You can use it in Java programs to access NUT’s upsd data server in a simple way, without having to know the NUT protocol.
  • "jNutList": this directory contains maven project and source files for jNutList, a simple Java example program using jNut which connect to an UPSD, lists its ups and their variables and commands.
  • "jNutWebAPI": this directory contains maven project and source files for jNutWebAPI, a simple Java web archive to access nut informations via REST web services.

jNut library

This directory contains source files for the jNut library, which is a Java abstraction bundle to access NUT server(s). You can use it in Java programs to access NUT’s upsd data server in a simple way, without having to know the NUT protocol.

jNut building requirements

jNut requires to be build : - A Java JDK 6 correctly set in environment (ie bin folder in path) - A Maven 3 installation set in environment (ie bin folder in path) with sufficient configuration (internet connection, local repository) to let maven get all plugins to make processes.

jNut is written in Java SE 1.4 and is tuned to be compiled to Java 1.4 code level so most of environment can use it.

jNut building

Once JDK and Maven installed and configured, just go into the jNut directory and type:

mvn install

The produced package called jNut-x.x-xxx.jar is located in target subdirectory.

jNut javadoc

You can generate jNut javadoc by typing:

mvn javadoc:javadoc

Documentation will be generated in target/site/apidocs subdirectory and its entry point is located at target/site/apidocs/index.html.

Workspace cleaning

The jNut workspace can be cleaned by removing the target subdirectory or by typing:

mvn clean
Unit test notes

jNut sources embed some unit tests in the src/test/java subdirectory. These tests are based on JUnit and are executed between compilation and packaging phases at each build.

Implementation notes

Currently, jNut is not thread safe. It is not protected against concurrent queries but queries to different clients can be done in parallel as there are done on different sockets.

Moreover, jNut have no connection preservation system so servers can break down connections due to timeout. Application using retrieved data must forget them when a disconnection occurs. If the application want to maintain the connection, it must implement a ping-pong mecanism itself.

At present time, jNut do not support SSL connection. It is planned for near future.

Changelog
  • "0.2": Add nut-scanner.
  • "0.1": Initial version with basic dialog with UPSD.

jNutList example application

This directory contains source files for the jNutList application. It allows to connect to an UPSD then retrieve devices and their variables. It is a little example application to show how to use jNut.

jNutList building

As jNut, jNutList is a maven project so a maven environment must be set. Please reffer to jNut building notes.

jNutList running

jNutList can be run launching it in a console:

java -jar jNutList-x.x-xxx-jar-with-dependencies.jar

Some parameters can be passed :

java -jar jNutList-x.x-jar-with-dependencies.jar host port login password

For example:

java -jar jNutList-x.x-jar-with-dependencies.jar localhost 3493 admin passwd

By default, host is localhost, port is 3493 and login and password are not specified.