docs/new-clients.txt

   1 Creating new client
   2 ===================
   3
   4 NUT provides bindings for several common languages that are
   5 presented below. All these are released under the same license as
   6 NUT (the GNU General Public License).
   7
   8 If none of these suits you for technical or legal reasons, you can
   9 implement one easily using the <<net-protocol,Network protocol information>>.
  10
  11 The latter approach has been used to create the Python 'PyNUT' module, the
  12 Nagios 'check_ups' plugin (and probably others), which can serve as a
  13 reference.
  14
  15 C / C++
  16 -------
  17
  18 Client access library
  19 ~~~~~~~~~~~~~~~~~~~~~
  20
  21 `libupsclient` and `libnutclient` libraries can be linked into other programs
  22 to give access to upsd and UPS status information.
  23 Both static and shared versions are provided.
  24
  25 These library files and associated header files are not installed by
  26 default.  You must `./configure --with-lib` to enable building and
  27 installing these files. The libraries can then be built and installed
  28 with `make` and `make install` as usual. This must be done before
  29 building other (non-NUT) programs which depend on them.
  30
  31 Low-level library: libupsclient
  32 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  33
  34 `libupsclient` provides a low-level interface to directly dialog with upsd.
  35 It is a wrapper around the NUT network protocol.
  36
  37 For more information, refer to the linkman:upsclient[3],
  38 manual page and the various link:../man/index.html#devclient[upscli_*(3)]
  39 functions documentation referenced in the same file.
  40
  41 Clients like upsc are provided as examples of how to retrieve data using the
  42 upsclient functions.
  43 link:http://www.networkupstools.org/projects.html[Other programs] not included
  44 in this package may also use this library, such as wmnut.
  45
  46 High level library: libnutclient
  47 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  48
  49 `libnutclient` provides a high-level interface representing devices, variables
  50 and commands with an object-oriented API in C++ and C.
  51
  52 For more information, refer to the linkman:libnutclient[3] manual page.
  53
  54   #include <iostream>
  55   #include <nutclient.h>
  56   using namespace nut;
  57   using namespace std;
  58
  59   int main(int argc, char** argv)
  60   {
  61     try
  62     {
  63       // Connection
  64       Client* client = new TcpClient("localhost", 3493);
  65       Device mydev = client->getDevice("myups");
  66       cout << mydev.getDescription() << endl;
  67       Variable var = mydev.getVariable("device.model");
  68       cout << var.getValue()[0] << endl;
  69     }
  70     catch(NutException& ex)
  71     {
  72       cerr << "Unexpected problem : " << ex.str() << endl;
  73     }
  74     return 0;
  75   }
  76
  77 Configuration helpers
  78 ~~~~~~~~~~~~~~~~~~~~~
  79
  80 NUT provides helper scripts to ease the configuration step of your program, by
  81 detecting the right compilation and link flags.
  82
  83 For more information, refer to a
  84 <<lib-info,Appendix B: NUT libraries complementary information>>.
  85
  86 Python
  87 ------
  88
  89 The PyNUT module, contributed by David Goncalves, can be used for connecting a
  90 Python script to `upsd`. Note that this code (and the accompanying NUT-Monitor
  91 application) is licensed under the GPL v3.
  92
  93 The `PyNUTClient` class abstracts the connection to the server. In order to
  94 list the status variables for `ups1` on the local `upsd`, the following
  95 commands could be used:
  96
  97   $ cd scripts/python/module
  98   $ python
  99   ...
 100   >>> import PyNUT
 101   >>> from pprint import pprint
 102   >>> client = PyNUT.PyNUTClient()
 103   >>> vars = client.GetUPSVars('ups1')
 104   >>> pprint(vars)
 105   {'battery.charge': '90',
 106    'battery.charge.low': '30',
 107    'battery.runtime': '3690',
 108    'battery.voltage': '230.0',
 109   ...
 110
 111 Further examples are given in the `test_nutclient.py` file. To see the entire
 112 API, you can run `pydoc` from the `module` directory.
 113
 114 If you wish to make the module available to everyone on the system, you will
 115 probably want to install it in the `site-packages` directory for your Python
 116 interpreter. (This is usually one of the last items in `sys.path`.)
 117
 118 Perl
 119 ----
 120
 121 The old Perl bindings from CPAN have recently been updated and merged into the
 122 NUT source code. These operate in a similar fashion to the Python bindings,
 123 with the addition of access to single variables, and additional interpretation
 124 of the results. The Perl class instance encapsulates a single UPS, where the
 125 Python class instance represents a connection to the server (which may service
 126 multiple UPS units).
 127
 128  use UPS::Nut;
 129
 130  $ups = new UPS::Nut( NAME => "myups",
 131                       HOST => "somemachine.somewhere.com",
 132                       PORT => "3493",
 133                       USERNAME => "upsuser",
 134                       PASSWORD => "upspasswd",
 135                       TIMEOUT => 30,
 136                       DEBUG => 1,
 137                       DEBUGOUT => "/some/file/somewhere",
 138                     );
 139  if ($ups->Status() =~ /OB/) {
 140     print "Oh, no!  Power failure!\n";
 141  }
 142
 143  tie %other_ups, 'UPS::Nut',
 144      NAME => "myups",
 145      HOST => "somemachine.somewhere.com",
 146      ... # same options as new();
 147  ;
 148
 149  print $other_ups{MFR}, " ", $other_ups{MODEL}, "\n";
 150
 151 Java
 152 ----
 153
 154 The NUT java support have been externalized.
 155 It is available at https://github.com/networkupstools/jnut
 156