Imported Upstream version 2.6.0

2011-01-26 10:35:08 +01:00 · 2011-01-26 10:35:08 +01:00 · 459aaf9392
commit 459aaf9392
parent 26fb71b504
510 changed files with 40508 additions and 18859 deletions
--- a/docs/new-clients.txt
+++ b/docs/new-clients.txt
@ -0,0 +1,125 @@
+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 <<net-protocol,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.
+
+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.
+link:http://www.networkupstools.org/projects.html[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 linkman:upsclient[3],
+manual page and the various
+link:man/index.html#Developer_man[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:
+
+- one for platforms providing pkg-config,
+- and the other (libupsclient-config) for platforms not providing pkg-config.
+
+If you have pkg-config installed, and you need to find the location of the NUT
+client include files, add the output of the following command to your build
+system (which can be combined with other pkg-config invocations):
+
+   pkg-config libupsclient --cflags
+
+If you don't have pkg-config, use this:
+
+   libupsclient-config --cflags
+
+Reference: linkman:libupsclient-config[1]
+
+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`.)
+
+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";
+