DRIVERS talk to the EQUIPMENT and receive updates. For most hardware this is polled (DRIVER asks EQUIPMENT about a variable), but forced updates are also possible. The exact method is not important, as it is abstracted by the driver.

The core of all DRIVERS maintains internal storage for every variable that is known along with the auxiliary data for those variables. It sends updates to this data to any process which connects to the Unix domain socket.

The DRIVERS will also provide a full atomic copy of their internal knowledge upon receiving the "DUMPALL" command on the socket. The dump is in the same format as updates, and is followed by "DUMPDONE". When "DUMPDONE" has been received, the view is complete.

The SERVER will connect to the socket of each DRIVER and will request a dump at that time. It retains this data in local storage for later use. It continues to listen on the socket for additional updates.

This protocol is documented in sock-protocol.txt.

The SERVER’s internal storage maintains a complete copy of the data which is in the DRIVER, so it is capable of answering any request immediately. When a request for data arrives from a CLIENT, the SERVER looks through the internal storage for that UPS and returns the requested data if it is available.

The format for requests from the CLIENT is documented in protocol.txt.

Service manifests include references to documentation for the tools they wrap, including published pages under the NUT_WEBSITE_BASE for the development or historic variants of the NUT website.

Use snprintf(). It’s even provided with a compatibility module if the target system doesn’t have it natively.

If you use snprintf() to load some value into a buffer, make sure you provide the format string. Don’t use user-provided format strings without delicate verification, since that’s an easy way to open yourself up to an exploit.

Don’t use strcat(). We have a neat wrapper for snprintf() called snprintfcat() that allows you to append to char * with a format string and all the usual string length checking of snprintf() routine.

Don’t call syslog() directly. Use upslog_with_errno() and upslogx(). They may also write to the syslog, stderr, or both as appropriate. This means you don’t have to worry about whether you’re running in the background or not.

The upslog_with_errno() routine prints your message plus the string expansion of current errno value. The upslogx() just prints the message.

fatal_with_errno() and fatalx() work the same way, but they also exit(arg) afterwards, where arg is the first argument of the fatal*() method — typically EXIT_FAILURE or EXIT_SUCCESS. In most cases, you should not call exit() directly.

The upsdebug_with_errno(), upsdebugx(), upsdebug_hex() and upsdebug_ascii() routines use the global nut_debug_level, so you don’t have to mess around with printf()'s and if's yourself. Use them.

xmalloc(), xcalloc(), xrealloc() and xstrdup() all check the results of the base calls before continuing, so you don’t have to. Don’t use the raw calls directly.

The configuration parser, called parseconf, is now up to its fourth major version. It has multiple entry points, and can handle many different jobs. It’s usually used for parsing files, but it can also take input a line at a time or even a character at a time.

You must initialize a context buffer with pconf_init() before using any other parseconf function. pconf_encode() is the only exception, since it operates on a buffer you supply and is an auxiliary function.

Escaping special characters and quoting multiple-word elements is all handled by the state machine. Using the same code for all config files avoids code duplication.

Drivers may have their own data files, such as lists of hardware, mapping tables, or similar. The difference between a data file and a config file is that users should never be expected to edit a data file under normal circumstances. This technique might be used to add more hardware support to a driver without recompiling.

This is already handled by autoconf, so just #include "timehead.h" and you will get the right headers on every system.

There are still older systems out there that don’t do C++ style comments.

/* Comments look like this. */
// Not like this.

Newer versions of gcc allow you to declare a variable inside a function after code, somewhat like the way C++ operates, like this:

function do_stuff(void)
{
        check_something();

        int a;

        a = do_something_else();
}

While this will compile and run on these newer versions, it will fail miserably for anyone on an older system. That means you must not use it.

Note that gcc only warns about this with -pedantic flag, and clang with a -Weverything (possibly -Wextra) flag, which can be enabled by developers with configure --enable-warnings=... option values (and made fatal with configure --enable-Werror), to ensure non-regression of code quality. It was reported that clang-16 with such options does complain about non-portability to older C language revisions even if explicitly building for a newer revision.

Please note that for the purposes of legacy-compatible variable declarations (on top of their scopes), a NUT_UNUSED_VARIABLE(varname) counts as code and should be used just below the declarations. Initial assignments to variables (also as return values of methods) may generally happen as part of their declarations.

You can use scoping (e.g. do { ... } while (0);) where it makes sense to constrain visibility of temporary variables, such as in switch/case blocks.

Another feature that does not work on some compilers (e.g. conforming to "ANSI C"/C89/C90 standard) is initial variable declaration inside a for loop block, like this:

function do_stuff(void)
{
        /* This should declare "int i;" first, then use it in "for" loop: */
        for (int i = 0; i < INT_MAX; ++i) { ... }

        /* Additional loops cause also an error about re-declaring a variable: */
        for (int i = 10; i < 15; ++i) { ... }
}

The NUT codebase may build in a mode without warnings made fatal on C89 (GNU89), but the emitted warnings indicate that those binaries may crash. By the end of 2021, NUT codebase has been revised to pass GNU and strict-C mode builds with C89 standard with the GCC toolkit (and on systems that do have the newer features in libraries, just hide them in standard headers); however CLANG toolkit is more restrictive about the C99+ syntax used. That said, some systems refuse to expose methods or types available in their system headers and binary libraries if strict-C mode is used alone, without extra system-specific defines to enable more than the baseline.

It was also seen that cross-builds (e.g. NUT for Windows using mingw on Linux) may be unable to define WIN32 and/or find symbols for linking when using a strict-C language standard.

The C++ support expects C+11 or newer (not really configured or tested for older C+98 or C+03), modulo features that were deprecated in later language revisions (C+14 onwards) as highlighted by warnings from newer compilers.

Note also that the NUT codebase currently relies on certain features, such as the printf format modifiers for (s)size_t, use of long long, some nuances about structure/array initializers, variadic macros for debugging, etc. that a pedantic C90 mode compilation warns is not part of the standard but a GNU extension (and part of C99 and newer standard revisions). Many of the "offences" against the older standard actually come from system and third-party header files.

That said, the NUT CI farm does run non-regression builds with GNU C89 and "strict" C89 standard revisions and minimal passing warnings level, to ensure that codebase is and remains at least basically compliant. We try to cover a few distributions from early 2000’s for this, either in regular CI builds or one-off local builds for community members with a zoo of old systems.

If somebody in the community actually requires to build and run NUT on systems that old, where newer compilers are not available, pull requests to fix the offending coding issues in some way that does not break other use-cases are welcome.

Another thing to notice is that the indenting happens with tabs instead of spaces. This lets everyone have their personal tab-width setting without inflicting much pain on other developers. If you use a space, then you’ve fixed the spacing in stone and have really annoyed half of the people out there.

Note that tabs apply only to indenting. Alignment of text after any non-tab character has appeared on the line must be done by spaces in order for it to remain at the same alignment when someone views tabs at a different widths.

One common example for this is multi-line if condition:

        if (something &&
            something_else) {

which may be written without mixing tabs and spaces to indent, as:

        if (something
        &&  something_else
        ) {

Another example is tables of definitions that are better aligned with (non-leading) spaces at least between names and values not too many characters wide; it still helps to align the columns with spaces at offsets divisible by 4 or 8 (consistently for the whole table):

#define SHORT_MACRO                         1   /* flag comment */
#define SOMETHING_WITH_A_VERY_LONG_NAME     255 /* flag comment */

While at it, we encourage indentation of nested preprocessor macros and pragmas, by adding a single space character for each inner level, as well as commenting the #else and #endif parts (especially if they are far away from their opening #if/#ifdef/#ifndef statement) to help visual navigation in the source code base. Please take care to keep the hash # character of the preprocessor lines in the left-most column, since some implementations of cpp parser used for analysis default to "traditional" (pre-C89) syntax shared with other languages, and then ignore lines which do not start with the hash character (or worse, ignore only some of them but not others).

#ifdef WITH_SSL
# ifdef WITH_NSS
        /* some code for NSS */
# endif /* WITH_NSS */
# ifdef WITH_OPENSSL
#  ifndef WIN32
        /* some code for OpenSSL on POSIX systems */
#  else /* not WIN32 */
        /* some code for OpenSSL on Windows */
#  endif        /* not WIN32 */
# endif /* WITH_OPENSSL */
#else   /* not WITH_SSL */
        /* report that crypto support is not built */
#endif  /* WITH_SSL */

If you write something that uses leading spaces, you may get away with it in a driver that’s relatively secluded. However, if we have to work on that code, expect it to get reformatted according to the above.

Patches to existing code that don’t conform to the coding style being used in that file will probably be dropped. If it’s something we really need, it will be grudgingly reformatted before being included.

When in doubt, have a look at Linus’s take on this topic in the Linux kernel — Documentation/CodingStyle. He’s done a far better job of explaining this.

It is better to have lines that are longer than 80 characters than to wrap lines in random places. This makes it easier to work with tools such as grep, and it also lets each developer choose their own window size and tab setting without being stuck to one particular choice.

Of course, this does not mean that lines should be made unnecessarily long when there is a better alternative (see the note on pretentiousVariableNamingSchemes above). Certainly there should not be more than one statement per line. Please do not use

if (condition) break;

but use the following:

if (condition) {
        break;
}

Whenever a function needs to satisfy a particular API, it can end up taking arguments that are not used in practice (think a too-trivial signal handler). While some compilers offer the facility of decorations like __attribute__(unused), this proved not to be a portable solution. Also the abilities of newer C/C++ standard revisions are of no help to the vast range of existing systems that run NUT today and expect to be able to do so tomorrow (hence the required C99+ support noted above).

In NUT codebase we prefer to mark un-used variables explicitly in the body of the function (or an #ifdef branch of its code) using the NUT_UNUSED_VARIABLE(varname) as a routine call inside a function body, referring to the macro defined in common.h.

Please note that for the purposes of legacy-compatible variable declarations (on top of their scopes), NUT_UNUSED_VARIABLE(varname) counts as code and should happen below the declarations.

To display in a rough example:

        static void signal_X_handler(int signal_X) {
                NUT_UNUSED_VARIABLE(signal_X);
                /* We have explicitly got nothing to do if we catch signal X */
                return;
        }

All this having been said, we do detect and use the support for pragmas to quiesce the complaints about such situations, but limit their use to processing of certain third-party header files.

We like code that uses const and static liberally. If you don’t need to expose a function or global variable to the outside world, static is your friend. If nobody should edit the contents of some buffer that’s behind a pointer, const keeps them honest.

We always compile with -Wall, so things like const and static help you find implementation flaws. Functions that attempt to modify a constant or access something outside their scope will throw a warning or even fail to compile in some cases. This is what we want.

NUT codebase often uses the switch/case/case.../default construct to handle conditional situations expressed by discrete numeric values (the case value: labels). Different compilers and their different warning settings require different rules to be satisfied, and those are sometimes at odds:

Ultimately, some cases require the wall of pragma directives below against warnings at this spot, and we use the default label handling to be sure, as the least-worst solution (ultra-long lines wrapped for readability in this document):

#if (defined HAVE_PRAGMA_GCC_DIAGNOSTIC_PUSH_POP) \
 && ( (defined HAVE_PRAGMA_GCC_DIAGNOSTIC_IGNORED_COVERED_SWITCH_DEFAULT) \
   || (defined HAVE_PRAGMA_GCC_DIAGNOSTIC_IGNORED_UNREACHABLE_CODE) )
# pragma GCC diagnostic push
#endif
#ifdef HAVE_PRAGMA_GCC_DIAGNOSTIC_IGNORED_COVERED_SWITCH_DEFAULT
# pragma GCC diagnostic ignored "-Wcovered-switch-default"
#endif
#ifdef HAVE_PRAGMA_GCC_DIAGNOSTIC_IGNORED_UNREACHABLE_CODE
# pragma GCC diagnostic ignored "-Wunreachable-code"
#endif
/* Older CLANG (e.g. clang-3.4) seems to not support the GCC pragmas above */
#ifdef __clang__
# pragma clang diagnostic push
# pragma clang diagnostic ignored "-Wunreachable-code"
# pragma clang diagnostic ignored "-Wcovered-switch-default"
#endif
                /* All enum cases defined as of the time of coding
                 * have been covered above. Handle later definitions,
                 * memory corruptions and buggy inputs below...
                 */
                default:
                        fatalx(EXIT_FAILURE, "no suitable definition found!");
#ifdef __clang__
# pragma clang diagnostic pop
#endif
#if (defined HAVE_PRAGMA_GCC_DIAGNOSTIC_PUSH_POP) \
 && ( (defined HAVE_PRAGMA_GCC_DIAGNOSTIC_IGNORED_COVERED_SWITCH_DEFAULT) \
   || (defined HAVE_PRAGMA_GCC_DIAGNOSTIC_IGNORED_UNREACHABLE_CODE) )
# pragma GCC diagnostic pop
#endif

While C standards allow to write switch statements to "fall through" from handling one case into another, modern compilers frown upon that practice and spew warnings which complicate detecting real bugs in the code (and also looking back at some of the cases written decades ago, it is not trivial to state whether the fall-through was intentional or really is a bug).

Compilers which detect such problem usually offer ways to decorate the code with comments or attributes to keep it quiet it in cases where the jump is intentional; also C++17 introduces special keywords for that in the standard. NUT aiming to be portable and independent of compilers as much as possible, prefers the arguably clearer and standards-based way of using goto into the next intended operation, even though it is a couple of lines away, e.g.:

int uppercase = 0;
switch (char_opt) {
        case 'U':
                uppercase = 1;
                goto fallthrough_case_u_option;
        case 'u':
        fallthrough_case_u_option:
                process_u_option(uppercase);
                break;
}

In trivial cases, like falling through to default which just returns, it may be clearer and more maintainable (adding other option cases in the future) to just return same_result in the code block that would fall through otherwise and avoid goto statements altogether.

If you use a goto that jumps over long distances (see "Switch case fall-through" section above), expect us to drop it when our head stops spinning. It gives us flashbacks to the very old code we wrote. We’ve tried to clean up our act, and you should make the effort as well.

We’re not making a blanket statement about gotos, since everything probably has at least one good use. There are a few cases where a goto is more efficient than any other approach, but you probably won’t encounter them very often in this software.

There are parts of the source tree that do not yet conform to these specs. Part of this is due to the fact that the coding style has been evolving slightly over the course of the project. Some of the code you see in these directories is 5 years old, and things have gotten cleaner since then. Don’t worry — it’ll get cleaned up the next time something in the vicinity gets a visit.

We can’t say enough good things about valgrind.

If you do anything with dynamic memory in your code, you need to use this. Just compile with gcc -g and start the program inside valgrind. Run it through the suspected area and then exit cleanly. Then valgrind will tell you if you’ve done anything dodgy like freeing regions twice, leaving files open, reading uninitialized memory, or if you’ve leaked memory anywhere.

For NUT, there are prepared integrations like configure --with-valgrind. See also scripts/valgrind in NUT sources for a helper tool and resource files to suppress common third-party problems.

For more information, refer to the Valgrind project.

The summary: please be kind to our eyes. There’s a lot of stuff in here, and many people have put a lot of time and energy to improve it.

Anonymous Git checkouts are possible:

:; git clone git://github.com/networkupstools/nut.git

or

:; git clone https://github.com/networkupstools/nut.git

if it is necessary to get around a pesky firewall that blocks the native Git protocol.

For a quicker checkout (when you don’t need the entire repository history), you can limit the depth of the clone:

:; git clone --depth 1 git://github.com/networkupstools/nut.git

OPTIONALLY you can then fetch known git tags, so semantic versions look better (based off a recent release, see NUT Versioning (or docs/nut-versioning.adoc in NUT sources for up-to-date information) for more details):

:; cd nut
:; git fetch --tags --all

There are those who prefer the simplicity and self-consistency of the Mercurial SCM client over the hodgepodge of unique commands which make up Git. Rather than debate the merits of each system, we will gently guide you towards the hg-git project which would theoretically be a transparent bridge between the central Git repository, and your local Mercurial working copy.

Other tools for hg/git interoperability are sure to exist. We would welcome any feedback about this process on the nut-upsdev mailing list.

If you prefer to check out the NUT source code using an SVN client, GitHub has a SVN interface to Git repositories hosted on their servers. You can fork a copy of the NUT repository and commit to your fork with SVN.

Be aware that the examples in the GitHub blog post might result in a checkout that includes all of the current branches, as well as the trunk. You are most likely interested in a command line similar to the following:

:; svn co https://github.com/networkupstools/nut/trunk nut-trunk-svn

This structure tracks several description information about the driver:

This information is currently used for the startup banner printing and tests.

Open the port (device_path) and do any low-level things that it may need to start using that port. If you have to set DTR or RTS on a serial port, do it here.

Don’t do any sort of hardware detection here, since you may be going into upsdrv_shutdown next.

Try to detect what kind of UPS is out there, if any, assuming that’s possible for your hardware. If there is a way to detect that hardware and it doesn’t appear to be connected, display an error and exit. This is the last time your driver is allowed to bail out.

This is usually a good place to create variables like ups.mfr, ups.model, ups.serial, determine and declare supported instant commands (maybe model-dependent, typically for all devices supported by the driver), and other "one time only" items.

Poll the hardware, and update any variables that you care about monitoring. Use dstate_setinfo() to store the new values.

Do at most one pass of the variables. You MUST return from this function or upsd will be unable to read data from your driver. main will call this function at regular intervals.

Don’t spent more than a couple of seconds in this function. Typically five (5) seconds is the maximum time allowed before you risk that the server declares the driver stale. If your UPS hardware requires a timeout period of several seconds before it answers, consider returning from this function after sending a command immediately and read the answer the next time it is called.

You must never abort from upsdrv_updateinfo(), even when the UPS doesn’t seem to be attached anymore. If the connection with the UPS is lost, the driver should retry to re-establish communication for as long as it is running. Calling exit() or any of the fatal*() functions is specifically not allowed anymore.

Do whatever you can to make the UPS power off the load but also return after the power comes back on. You may use a different command that keeps the UPS off if the user has requested that with a configuration setting.

You should attempt the UPS shutdown command even if the UPS detection fails. If the UPS does not shut down the load, then the user is vulnerable to a race if the power comes back on during the shutdown process.

This method should not directly exit() the driver program (neither should it call fatalx() nor fatal_with_errno() methods). It can upslogx(LOG_ERR, ...) or upslog_with_errno(LOG_ERR, ...), and then set_exit_flag(N) if required, using values EF_EXIT_FAILURE (-1) for eventual exit(EXIT_FAILURE) and EF_EXIT_SUCCESS (-2) for exit(EXIT_SUCCESS), which would be handled in the standard driver loop or in forceshutdown() method of main.c.

dstate_setinfo("ups.model", "Mega-Zapper 1500");

Many of these functions take format strings, so you can build the new values right there:

dstate_setinfo("ups.model", "Mega-Zapper %d", rating);

Some variables have special properties. They can be writable, and some are strings. The ST_FLAG_* values can be used to tell upsd more about what it can do.

dstate_setflags("input.transfer.high", ST_FLAG_RW);

UPS status flags like on line (OL) and on battery (OB) live in ups.status. Don’t manipulate this by hand. There are functions which will do this for you.

status_init()   -- before doing anything else (clear internal buffers,
                   etc.)

status_get(val) -- optionally check if a status word had been set
                   since the most-recent status_init()

status_set(val) -- add a status word (OB, OL, etc)

status_commit() -- push out the update

Possible values for status_set:

OL      -- On line (mains is present)
OB      -- On battery (mains is not present)
LB      -- Low battery
HB      -- High battery
RB      -- The battery needs to be replaced
CHRG    -- The battery is charging
DISCHRG -- The battery is discharging (inverter is providing load power)
BYPASS  -- UPS bypass circuit is active -- no battery protection is available
CAL     -- UPS is currently performing runtime calibration (on battery)
OFF     -- UPS is offline and is not supplying power to the load
OVER    -- UPS is overloaded
TRIM    -- UPS is trimming incoming voltage (called "buck" in some hardware)
BOOST   -- UPS is boosting incoming voltage
FSD     -- Forced Shutdown (restricted use, see the note below)

Internally, an ALARM value would be added (typically as first in the list) if the ups.alarm is currently not empty. For more details, see below in alarm_set() description.

Anything else will not be recognized by the usual clients expecting a particular NUT standard release. New tokens may appear over time, but driver developers should coordinate with the nut-upsdev list before creating something new, since there will be duplication and ugliness otherwise. It is possible that eventually, due to hardware and software design evolution, some concepts would be superseded by others. Fundamental meanings of the flags listed above should not change (but these flags may become no longer issued by the current NUT drivers; then may still be used e.g. in forks or older packaged builds).

Clients however MUST accept any space-separated tokens in ups.status without error or crash, and MUST treat those defined above with the ascribed meanings, but MAY ignore unidentified tokens (quietly by default, or acknowledge the skip with a debug log message).

Similar functionality can be supported for experimental.ups.mode.buzzwords, where it is tracked dynamically (e.g. due to ECO/ESS/HE/Smart or similar marketing buzzword modes supported by the device), using the following methods in the processing loop:

buzzmode_init()   -- before doing anything else (clear internal buffers,
                     etc.)

buzzmode_get(val) -- optionally check if an UPS mode buzzword had been
                     set since the most-recent buzzmode_init()

buzzmode_set(val) -- add an UPS mode buzzword (vendor:eaton:ECO, etc.)

buzzmode_commit() -- push out the update

You should use the usb_device_id_t structure, and the USB_DEVICE macro to declare the supported devices. This allows the automatic extraction of USB information, to generate the Hotplug, udev and UPower support files.

The structure allows to convey uint16_t values of VendorID and ProductID, and an optional matching-function callback to interrogate the device in more detail (constrain known supported firmware versions, OEM brands, etc.)

For example:

/* SomeVendor name */
#define SOMEVENDOR_VENDORID             0xXXXX

/* USB IDs device table */
static usb_device_id_t sv_usb_device_table [] = {
        /* some models 1 */
        { USB_DEVICE(SOMEVENDOR_VENDORID, 0xYYYY), NULL },

        /* various models */
        { USB_DEVICE(SOMEVENDOR_VENDORID, 0xZZZZ), NULL },
        { USB_DEVICE(SOMEVENDOR_VENDORID, 0xAAAA), NULL },

        /* Terminating entry */
        { 0, 0, NULL }
};

If your driver’s function for handling variable set events is called my_ups_set(), then you’d do this to add the pointer:

upsh.setvar = my_ups_set;

my_ups_set() will receive two parameters:

const char * -- the variable being changed
const char * -- the new value

You should return either STAT_SET_HANDLED if your driver recognizes the command, or STAT_SET_UNKNOWN if it doesn’t. Other possibilities will be added at some point in the future.

This works just like the set process, with slightly different values arriving from the server.

upsh.instcmd = my_ups_cmd;

Your function will receive two args:

const char * -- the command name
const char * -- (reserved)

You should return either STAT_INSTCMD_HANDLED or STAT_INSTCMD_UNKNOWN depending on whether your driver can handle the requested command.

Use strcasecmp. The command names arriving from upsd should be treated without regards to case.

Drivers will eventually be expected to send responses to commands. Right now, there is no channel to get these back through upsd to the client, so this is not implemented.

This will probably be implemented with a polling scheme in the clients.

"Contact closure" refers to a situation where one line is connected to another inside UPS hardware to indicate some sort of situation. These can be relays, or some other form of switching electronics. The generic idea is that you either have a signal on a line, or you don’t. Think binary.

Usually, the source for a signal is the host PC. It provides a high (logic level 1) from one of its outgoing lines, and the UPS returns it on one or more lines to communicate. The rest of the time, the UPS either lets it float or connects it to the ground to indicate a 0.

Other equipment generates the high and low signals internally, and does not require cable power. These signals just appear on the right lines without any special configuration on the PC side.

Some evil cabling and UPS equipment uses the transmit or receive lines as their reference points for these signals. This is not sufficient to register as a high signal on many serial ports. If you have problems reading certain signals on your system, make sure your UPS isn’t trying to do this.

Unlike their smarter cousins, this kind of UPS can only give you very simple yes/no answers. Due to the limited number of serial port lines that can be used for this purpose, you typically get two pieces of data:

That’s it. Some equipment actually swaps the second one for a notification about whether the battery needs to be replaced, which makes life interesting for those users.

Most hardware also supports an outgoing signal from the PC which means "shut down the load immediately". This is generally implemented in such a way that it only works when running on battery. Most hardware or cabling will ignore the shutdown signal when running on line power.

If none of the existing types in the genericups driver work completely, make a note of which ones (if any) manage to work partially. This can save you some work when creating support for your hardware.

Use that information to create a list of where the signals from your UPS appear on the serial port at the PC end, and whether they are active high or active low. You also need to know what outgoing lines, if any, need to be raised in order to supply power to the contacts. This is known as cable power. Finally, if your UPS can shut down the load, that line must also be identified.

There are only 4 incoming and 2 outgoing lines, so not many combinations are left. The other lines on a typical 9 pin port are transmit, receive, and the ground. Anything trying to do a high/low signal on those three is beyond the scope of the genericups driver. The only exception is an outgoing BREAK, which we already support.

When editing the genericups.h, the values have the following meanings:

Outgoing lines:

Incoming lines:

This may seem a bit confusing to have two variables per value that we want to read, but here’s how it works. If you set line_ol to TIOCM_RNG, then the value of TIOCM_RNG (0x080 on my box) will be anded with the value of the serial port whenever a poll occurs. If that flag exists, then the result of the and will be 0x80. If it does not exist, the result will be 0.

So, if line_ol = foo, then val_ol can only be foo or 0.

As a general case, if line_ol == val_ol, then the value you’re reading is active high. Otherwise, it’s active low. Check out the guts of upsdrv_updateinfo() to see how it really works.

Late in the 1.3 cycle, a feature was merged which allows you to create custom monitoring settings without editing the model table. Just set upstype to something close, then use settings in ups.conf to adjust the rest. See the genericups(8) man page for more details.

USB (Universal Serial Port) devices can be divided into several different classes (audio, imaging, mass storage etc). Almost all UPS devices belong to the "HID" class, which means "Human Interface Device", and also includes things like keyboards and mice. What HID devices have in common is a particular (and very flexible) interface for reading and writing information (such as X/Y coordinates and button states, in the case of a mouse, or voltages and status information, in the case of a UPS).

The NUT "usbhid-ups" driver is a meta-driver that handles all HID UPS devices. It consists of a core driver that handles most of the work of talking to the USB hardware, and several sub-drivers to handle specific UPS manufacturers (MGE, APC, and Belkin are currently supported). Adding support for a new HID UPS device is easy, because it requires only the creation of a new sub-driver.

There are a few USB UPS devices that are not true HID devices. These devices typically implement some version of the manufacturer’s serial protocol over USB (which is a really dumb idea, by the way). An example is the original Tripplite USB interface (USB idProduct = 0001). Its HID descriptor is only 52 bytes long (compared to several hundred bytes for a true PDC HID UPS). Such devices are not supported by the usbhid-ups driver, and are not covered in this document. If you need to add support for such a device, read new-drivers.txt and see the "tripplite_usb" driver for inspiration.

From the point of view of writing a HID subdriver, a HID device consists of a bunch of variables. Some variables (such as the current input voltage) are read-only, whereas other variables (such as the beeper enabled/disabled/muted status) can be read and written. These variables are usually grouped together and arranged in a hierarchical tree shape, similar to directories in a file system. This tree is called the "usage" tree. For example, here is part of the usage tree for a typical APC device. Variable components are separated by .. Typical values for each variable are also shown for illustrative purposes.

As you can see, variables that describe the battery status might be grouped together under "Battery", variables that describe the input power might be grouped together under "Input", and variables that describe the current UPS status might be grouped together under "PresentStatus". All of these variables are grouped together under "UPS".

This hierarchical organization of data has the advantage of being very flexible; for example, if some device has more than one battery, then similar information about each battery could be grouped under "Battery1", "Battery2" and so forth. If your UPS can also be used as a toaster, then information about the toaster function might be grouped under "Toaster", rather than "UPS".

However, the disadvantage is that each manufacturer will have their own idea about how the usage tree should be organized, and usbhid-ups needs to know about all of them. This is why manufacturer specific subdrivers are needed.

To make matters more complicated, usage tree components (such as "UPS", "Battery", or "Voltage") are internally represented not as strings, but as numbers (called "usages" in HID terminology). These numbers are defined in the "HID Usage Tables", available from http://www.usb.org/developers/hidpage/. The standard usages for UPS devices are defined in a document called "Usage Tables for HID Power Devices" (the Power Device Class [PDC] specification).

For example:

 0x00840010 = UPS
 0x00840012 = Battery
 0x00840030 = Voltage
 0x00840040 = ConfigVoltage
 0x0084001a = Input
 0x0084005a = AudibleAlarmControl
 0x00840002 = PresentStatus
 0x00850044 = Charging
 0x00850045 = Discharging
 0x008500d0 = ACPresent

Thus, the above usage tree is internally represented as:

 00840010.00840012.00840030
 00840010.00840012.00840040
 00840010.0084001a.00840030
 00840010.0084001a.00840040
 00840010.0084005a
 00840010.00840002.00850044
 00840010.00840002.00850045
 00840010.00840002.008500d0

To make matters worse, most manufacturers define their own additional usages, even in cases where standard usages could have been used. for example Belkin defines 00860040 = ConfigVoltage (which is incidentally a violation of the USB PDC specification, as 00860040 is reserved for future use).

Thus, subdrivers generally need to provide:

Moreover, subdrivers might have to provide additional functionality, such as custom implementations of specific instant commands (load.off, shutdown.restart), and conversions of manufacturer specific data formats.

The drivers/hidtypes.h header provides a number of macro names for entries in the standard usage tables for Power Device USAGE_POW_<SOMETHING> and Battery System USAGE_BAT_<SOMETHING> data pages.

If NUT codebase would ever need to refresh those macros, here is some background information (based on NUT issue #1189 and PR #1290):

These data were parsed from (a very slightly updated version of) https://github.com/abend0c1/hidrdd/blob/master/rd.conf file, which incorporates the complete USB-IF usage definitions for Power Device and Battery System pages (among many others), so we didn’t have to extract the names and values from the USB-IF standards documents (did check it all by eye though).

The file was processed with the following chain of commands:

:; grep -e '^0084' -e '^0085' rd.conf \
   | sed 's/,.*$//;s/ *$//' \
   | sed 's/ /_/g;s/_/ /' \
   | tr '[:lower:]' '[:upper:]' \
   | sed 's/\(0085.... \)/\1USAGE_BAT_/;s/\(0084.... \)/\1USAGE_POW_/;s/\([A-Z_]*\)_PAGE/PAGE_\1/' \
   | awk '{print "#define "$2" 0x"$1}'

In preparation for writing a subdriver for a device that is currently unsupported, run usbhid-ups with the following command line:

drivers/usbhid-ups -DD -u root -x explore -x vendorid=XXXX \
        -x port=auto -s ups

(substitute your device’s 4-digit VendorID instead of "XXXX"). This will produce a bunch of debugging information, including a number of lines starting with "Path:" that describe the device’s usage tree. This information forms the initial basis for a new subdriver.

You should save this information to a file, e.g.:

drivers/usbhid-ups -DD -u root -x explore -x vendorid=XXXX \
        -x port=auto -s ups -d1 2>&1 | tee /tmp/info

You can now create an initial "stub" subdriver for your device by using helper script scripts/subdriver/gen-usbhid-subdriver.sh.

Use the script as follows:

scripts/subdriver/gen-usbhid-subdriver.sh < /tmp/info

where /tmp/info is the file where you previously saved the debugging information.

This script prompts you for a name for the subdriver; use only letters and digits, and use natural capitalization such as "Belkin" (not "belkin" or "BELKIN"). The script may prompt you for additional information.

You should put the generated files into the drivers/ subdirectory, and update usbhid-ups.c by adding the appropriate #include line and by updating the definition of subdriver_list in usbhid-ups.c. You must also add the subdriver to USBHID_UPS_SUBDRIVERS in drivers/Makefile.am and call autoreconf and/or ./configure from the top-level NUT directory. You can then recompile usbhid-ups, and start experimenting with the new subdriver.

You may have a device from vendor (and maybe model) whose support usbhid-ups already claims. However, you may feel that the driver does not represent all data points that your device serves. This may be possible, as vendors tend to use the same identifiers for unrelated products, as well as produce revisions of devices with same marketed name but different internals (due to chip and other components availability, cost optimization, etc.) Even without sinister implications, UPS firmwares evolve and so bugs and features can get added, fixed and removed over time with truly the same hardware being involved.

In this case you should follow the same instructions as above for "Writing a subdriver", but specify the same subdriver name as the one which supports your device family already.

Then compare the generated source file with the one already committed to NUT codebase, paying close attention to ..._hid2nut[] table which maps "usage" names to NUT data points. There may be several "usage" values served by different device models or firmware versions, that provide same information for a NUT data point, such as input.voltage. For the hid2nut mapping tables, first hit wins (so you may e.g. prefer to check values with better precision first).

Using a GUI tool with partial-line difference matching and highlighting, such as Meld or WinMerge, is recommended for this endeavour.

For new data points in hid2nut tables be sure to not invent new names, but use standard ones from docs/nut-names.txt file. Temporarily, the experimental.* namespace may be used. If you need to standardize a name for some concept not addressed yet, please do so via nut-upsdev mailing list discussion.

The initially generated subdriver code is only a stub, and will not implement any useful functionality (in particular, it will be unable to shut down the UPS). In the beginning, it simply attempts to monitor some UPS variables. To make this driver useful, you must examine the NUT variables of the form "unmapped.*" in the hid_info_t data structure, and map them to actual NUT variables and instant commands. There are currently no step-by-step instructions for how to do this. Please look at the files to see how the currently implemented subdrivers are written:

It is a fact of life that fellow developers make mistakes, and firmware authors do too. In some cases there are inconsistencies about bytes seen on the wire vs. their logical values, such value range and signedness if interpreting them according to standard.

NUT drivers now include a way to detect and fix up known issues in such flawed USB report descriptors, side-stepping the standard similarly where deemed needed. A pointer to such hook method is part of the subdriver_t structure detailing each usbhid-ups subdriver nuances, defaulting to a fix_report_desc() trivial implementation.

For some practical examples, see e.g. apc_fix_report_desc() method in the drivers/apc-hid.c file, and cps_fix_report_desc() in drivers/cps-hid.c file.

Finally note that such fix-ups may be not applicable to all devices or firmware versions for what they assume their target audience is. If you suspect that the fix-up method is actually causing problems, you can quickly disable it with disable_fix_report_desc driver option for usbhid-ups. If the problem does dissipate, please find a way to identify your "fixed" hardware/firmware vs. those models where existing fix-up method should be applied, and post a pull request so the NUT driver would handle both cases.

Beside looking for problems with report descriptor processing in NUT code, it is important to make sure what data the device actually serves on the wire, and if it is logically consistent with the protocol requirements.

While here, keep in mind that USB protocol on the wire has a specified order of bytes involved, while processing on your computer may lay them out differently due to bitness and endianness of the current binary build. General NUT codebase (libhid.c, hidparser.c) aims to abstract this, so application code like drivers can deal with their native numeric data types, but when troubleshooting, do not rule out possibility of flaws there as well. And certainly do not code any assumptions about ordered multiple-byte ranges in a protocol buffer.

For a deep dive into the byte stream, you will need additional tools:

Typical troubleshooting of suspected firmware/protocol issues goes like this:

   3.670755     [D3] Report Descriptor: (909 bytes) => 05 84 09 04 a1 01 ...

:; rexx rd.rex -d --hex 05 84 09 04 a1 01 85 01 09 18 ... 55 b1 02 c0 c0 c0

//--------------------------------------------------------------------------------
// Decoded Application Collection
//--------------------------------------------------------------------------------

/*
05 84        (GLOBAL) USAGE_PAGE         0x0084 Power Device Page
09 04        (LOCAL)  USAGE              0x00840004 UPS (Application Collection)
A1 01        (MAIN)   COLLECTION         0x01 Application (Usage=0x00840004: Page=Power Device Page, Usage=UPS, Type=Application Collection)
85 01          (GLOBAL) REPORT_ID          0x01 (1)
09 18          (LOCAL)  USAGE              0x00840018 Outlet System (Physical Collection)
...
*/

// All structure fields should be byte-aligned...
#pragma pack(push,1)

//--------------------------------------------------------------------------------
// Power Device Page featureReport 01 (Device <-> Host)
//--------------------------------------------------------------------------------

typedef struct
{
  uint8_t  reportId;                                 // Report ID = 0x01 (1)
                                                     // Collection: CA:UPS CP:OutletSystem CP:Outlet
  int8_t   POW_UPSOutletSystemOutletSwitchable;      // Usage 0x0084006C: Switchable, Value =  to
  int8_t   POW_UPSOutletSystemOutletDelayBeforeStartup; // Usage 0x00840056: Delay Before Startup, Value = -1 to 60
  int8_t   POW_UPSOutletSystemOutletDelayBeforeShutdown; // Usage 0x00840057: Delay Before Shutdown, Value = -1 to 60
  int8_t   POW_UPSOutletSystemOutletDelayBeforeReboot; // Usage 0x00840055: Delay Before Reboot, Value = -1 to 60
  int8_t   POW_UPSOutletSystemOutletSwitchable_1;    // Usage 0x0084006C: Switchable, Value = -1 to 60
  int8_t   POW_UPSOutletSystemOutletDelayBeforeStartup_1; // Usage 0x00840056: Delay Before Startup, Value = -1 to 60
  int8_t   POW_UPSOutletSystemOutletDelayBeforeShutdown_1; // Usage 0x00840057: Delay Before Shutdown, Value = -1 to 60
  int8_t   POW_UPSOutletSystemOutletDelayBeforeReboot_1; // Usage 0x00840055: Delay Before Reboot, Value = -1 to 60
} featureReport01_t;

#pragma pack(pop)

It is desirable to support shutting down the UPS. Usually (for devices that follow the HID Power Device Class specification), this requires sending the UPS two commands. One for shutting down the UPS (with an offdelay) and one for restarting it (with an ondelay), where offdelay < ondelay. The two NUT commands for which this is relevant, are shutdown.return and shutdown.stayoff.

Since the one-to-one mapping above doesn’t allow sending two HID commands to the UPS in response to sending one NUT command to the driver, this is handled by the driver. In order to make this work, you need to define the following four NUT values:

ups.delay.start    (variable, R/W)
ups.delay.shutdown (variable, R/W)
load.off.delay     (command)
load.on.delay      (command)

If the UPS supports it, the following variables can be used to show the countdown to start/shutdown:

ups.timer.start    (variable, R/O)
ups.timer.shutdown (variable, R/O)

The load.on and load.off commands will be defined implicitly by the driver (using a delay value of 0). Define these commands yourself, if your UPS requires a different value to switch on/off the load without delay.

Note that the driver expects the load.off.delay and load.on.delay to follow the HID Power Device Class specification, which means that the load.on.delay command should NOT switch on the load in the absence of mains power. If your UPS switches on the load regardless of the mains status, DO NOT define this command. You probably want to define the shutdown.return and/or shutdown.stayoff commands in that case. Commands defined in the subdriver will take precedence over the ones that are composed in the driver.

When running the driver with the -k flag, it will first attempt to send a shutdown.return command and if that fails, will fallback to shutdown.reboot.

The SNMP protocol allow for a common way to interact with devices over the network.

The NUT "snmp-ups" driver is a meta-driver that handles many SNMP devices, such as UPS and PDU. It consists of a core driver that handles most of the work of talking to the SNMP agent, and several sub-drivers to handle specific device manufacturers. Adding support for a new SNMP device is easy, because it requires only the creation of a new sub-driver.

From the point of view of writing an SNMP subdriver, an SNMP device consists of a bunch of variables, called OIDs (for Object IDentifiers). Some OIDs (such as the current input voltage) are read-only, whereas others (such as the beeper enabled/disabled/muted status) can be read and written. OID are grouped together and arranged in a hierarchical tree shape, similar to directories in a file system. OID components are separated by ".", and can be expressed in numeric or textual form. For example:

.iso.org.dod.internet.mgmt.mib-2.system.sysObjectID

is equivalent to:

.1.3.6.1.2.1.1.2.0

Here is an excerpt tree, showing only two OIDs, sysDescr and sysObjectID:

.iso
        .org
                .dod
                        .internet
                                .mgmt
                                        .mib-2
                                                .system
                                                        .sysDescr.0 = STRING: Dell UPS Tower 1920W HV
                                                        .sysObjectID.0 = OID: .iso.org.dod.internet.private.enterprises.674.10902.2
                                                        (...)
                                                .upsMIB
                                                        .upsObjects
                                                                .upsIdent
                                                                        .upsIdentModel = STRING: "Dell UPS Tower 1920W HV"
                                                                        (...)
                                .private
                                        .enterprises
                                                .674
                                                        .10902
                                                                .2
                                                                        .100
                                                                                .1.0 = STRING: "Dell UPS Tower 1920W HV"
                                                                                (...)

As you can see in the above example, the device name is exposed three times, through three different MIBs:

But only the two last can serve useful data for NUT.

An highly interesting OID is sysObjectID: its value is an OID that refers to the main MIB of the device. In the above example, the device points us at the Dell UPS MIB. sysObjectID, also called "sysOID" is used by snmp-ups to find the right mapping structure.

For more information on SNMP, refer to the Wikipedia article, or browse the Internet.

To be able to convert values, NUT SNMP subdrivers need to provide:

Moreover, subdrivers might have to provide additional functionality, such as custom implementations of specific instant commands (load.off, shutdown.restart), and conversions of manufacturer specific data formats. At the time of writing this document, snmp-ups doesn’t provide such mechanisms (only formatting ones), but it is planned in a future release.

In order to create a subdriver, you will need the following:

You can create an initial "stub" subdriver for your device by using the helper script scripts/subdriver/gen-snmp-subdriver.sh. Note that this only creates a "stub" which MUST be customized to be useful (see CUSTOMIZATION below).

You have two options to run gen-snmp-subdriver.sh:

$ gen-snmp-subdriver.sh -H W.X.Y.Z -c foobar -n <MIB name>.mib

$ gen-snmp-subdriver.sh -s <sysOID value> <numeric SNMP walk> <string SNMP walk>

$ gen-snmp-subdriver.sh -s .1.3.6.1.4.1.705.1 snmpwalk-On.log snmpwalk-Os.log

/* upsMIB.upsObjects.upsIdent.upsIdentModel = STRING: "Dell UPS Tower 1920W HV" */
snmp_info_default("ups.model", ST_FLAG_STRING, SU_INFOSIZE,
    ".1.3.6.1.4.1.2254.2.4.1.1.0", NULL, SU_FLAG_OK, NULL),

The NUT "nutdrv_qx" driver is a meta-driver that handles Q* UPS devices.

It consists of a core driver that handles most of the work of talking to the hardware, and several sub-drivers to handle specific UPS manufacturers.

Adding support for a new UPS device is easy, because it requires only the creation of a new sub-driver.

In order to develop a new subdriver for a specific UPS you have to know the "idiom" (dialect of the protocol) spoken by that device.

This kind of devices speaks idioms that can be summed up as follows:

To be supported by this driver the idiom spoken by the UPS must comply to these conditions.

You have to fill the subdriver_t structure:

typedef struct {
        const char      *name;
        int             (*claim)(void);
        item_t          *qx2nut;
        void            (*initups)(void);
        void            (*initinfo)(void);
        void            (*makevartable)(void);
        const char      *accepted;
        const char      *rejected;
#ifdef TESTING
        testing_t       *testing;
#endif  /* TESTING */
} subdriver_t;

Where:

If you understand the idiom spoken by your device, you can easily map it to NUT variables and instant commands, filling qx2nut with an array of item_t data structure:

typedef struct item_t {
        const char      *info_type;
        const int       info_flags;
        info_rw_t       *info_rw;
        const char      *command;
        char            answer[SMALLBUF];
        const int       answer_len;
        const char      leading;
        char            value[SMALLBUF];
        const int       from;
        const int       to;
        const char      *dfl;
        unsigned long   qxflags;
        int             (*preprocess_command)(struct item_t *item, char *command, const size_t commandlen);
        int             (*preprocess_answer)(struct item_t *item, const int len);
        int             (*preprocess)(struct item_t *item, char *value, const size_t valuelen);
} item_t;

Where:

The following examples are from the voltronic subdriver.

> [QGS\r]
< [(234.9 50.0 229.8 50.0 000.0 000 369.1 ---.- 026.5 ---.- 018.8 100000000001\r]
   0123456789012345678901234567890123456789012345678901234567890123456789012345
   0         1         2         3         4         5         6         7

{ "output.voltage", 0, NULL, "QGS\r", "", 76, '(', "", 12, 16, "%.1f", 0, NULL, NULL, NULL },

> [QGS\r]
< [(234.9 50.0 229.8 50.0 000.0 000 369.1 ---.- 026.5 ---.- 018.8 100000000001\r]
   0123456789012345678901234567890123456789012345678901234567890123456789012345
   0         1         2         3         4         5         6         7

{ "ups.status", 0, NULL, "QGS\r", "", 76, '(', "", 71, 71, "%s", QX_FLAG_QUICK_POLL, NULL, NULL, voltronic_status },

> [QBT\r]
< [(01\r]       <- 00="Li", 01="Flooded" or 02="AGM"
   0123
   0

{ "battery.type", ST_FLAG_RW, voltronic_e_batt_type, "QBT\r", "", 4, '(', "", 1, 2, "%s",
  QX_FLAG_SEMI_STATIC | QX_FLAG_ENUM, NULL, NULL, voltronic_p31b },

> [PBTnn\r]             nn = 00/01/02
< [(ACK\r]
   01234
   0

{ "battery.type", 0, voltronic_e_batt_type, "PBT%02.0f\r", "", 5, '(', "", 1, 4, NULL,
  QX_FLAG_SETVAR | QX_FLAG_ENUM, NULL, NULL, voltronic_p31b_set },

> [Tnn\r]
< [(ACK\r]
   01234
   0

{ "test.battery.start", 0, NULL, "T%s\r", "", 5, '(', "", 1, 4, NULL, QX_FLAG_CMD, NULL, NULL, voltronic_process_command },

{ "ups.delay.start", ST_FLAG_RW, voltronic_r_ondelay, NULL, "", 0, 0, "", 0, 0, "180",
  QX_FLAG_ABSENT | QX_FLAG_SETVAR | QX_FLAG_RANGE, NULL, NULL, voltronic_process_setvar },

> [QPD\r]
< [(000 120\r]  <- Input Phase Angle -- Output Phase Angle
   012345678
   0

{ "input_phase_angle", 0, NULL, "QPD\r", "", 9, '(', "", 1, 3, "%03.0f",
  QX_FLAG_STATIC | QX_FLAG_NONUT, NULL, NULL, voltronic_phase },

{ "output_phase_angle", ST_FLAG_RW, voltronic_e_phase, "QPD\r", "", 9, '(', "", 5, 7, "%03.0f",
  QX_FLAG_SEMI_STATIC | QX_FLAG_ENUM | QX_FLAG_NONUT, NULL, NULL, voltronic_phase },

> [PPDn\r]              n = (000, 120, 180 or 240)
< [(ACK\r]
   01234
   0

{ "output_phase_angle", 0, voltronic_e_phase, "PPD%03.0f\r", "", 5, '(', "", 1, 4, NULL,
  QX_FLAG_SETVAR | QX_FLAG_ENUM | QX_FLAG_NONUT, NULL, NULL, voltronic_phase_set },

You are already given the following functions:

Armac subdriver is based on reverse engineering of Power Manager II software by Richcomm Technologies written in 2005 that is still (as of 2023) being distributed as a valid software for freshly sold UPS of various manufacturers. It uses commands as defined for Megatec protocol - but has a different communication mechanism.

It uses two types of USB interrupt transfers: - 4 bytes to send a command (usually single transfer). - 6 byte chunk to read a reply (multiple transfers).

Transfers are similar to those of the richcomm nut driver, but the transferred data is not short binary commands. Instead, serial text data is overlaid in these transfers in a way that creates a badly made USB serial interface. UPS reply looks similar to this:

 0  1  2  3  4  5
HL 00 00 00 00 00

HL is a control byte. Its high nibble meaning is unknown. It changes between two possible values during transmission. Low nibble encodes number of bytes that have a meaning in the transaction. For example there are 5 bytes that might contain ASCII serial data, but only some might be valid, and other might be random, stale buffer data, etc.

What follows is set of observed transmissions by various UPSes gathered from Github issues.

419.987514     [D4] armac command Q1
419.988307     [D4] armac cleanup ret i=0 ret=6 ctrl=c0
420.119402     [D4] read: ret 6 buf 81: 28 30 31 30 30  >(0100<
420.130383     [D4] read: ret 6 buf c1: 32 30 31 30 30  >20100<
420.141408     [D4] read: ret 6 buf 82: 33 33 31 30 30  >33100<
420.152201     [D4] read: ret 6 buf c3: 2e 30 20 30 30  >.0 00<
420.153237     [D4] read: ret 6 buf 82: 30 30 20 30 30  >00 00<
420.164299     [D4] read: ret 6 buf c1: 30 30 20 30 30  >00 00<
420.175293     [D4] read: ret 6 buf 82: 2e 30 20 30 30  >.0 00<
420.186358     [D4] read: ret 6 buf c3: 20 32 33 30 30  > 2300<
420.190322     [D4] read: ret 6 buf 83: 33 2e 30 30 30  >3.000<
420.194323     [D4] read: ret 6 buf c1: 20 2e 30 30 30  > .000<
420.205358     [D4] read: ret 6 buf 81: 30 2e 30 30 30  >0.000<
420.216318     [D4] read: ret 6 buf c2: 31 34 30 30 30  >14000<
420.227445     [D4] read: ret 6 buf 83: 20 34 39 30 30  > 4900<
420.228334     [D4] read: ret 6 buf c2: 2e 30 39 30 30  >.0900<
420.239461     [D4] read: ret 6 buf 81: 20 30 39 30 30  > 0900<
420.250411     [D4] read: ret 6 buf c2: 32 37 39 30 30  >27900<
420.261405     [D4] read: ret 6 buf 83: 2e 30 20 30 30  >.0 00<
420.265468     [D4] read: ret 6 buf c3: 32 30 2e 30 30  >20.00<
420.269465     [D4] read: ret 6 buf 81: 38 30 2e 30 30  >80.00<
420.280322     [D4] read: ret 6 buf c1: 20 30 2e 30 30  > 0.00<
420.291469     [D4] read: ret 6 buf 82: 30 30 2e 30 30  >00.00<
420.302465     [D4] read: ret 6 buf c3: 30 30 31 30 30  >00100<
420.303511     [D4] read: ret 6 buf 82: 00 30 31 30 30  >          <- This has 0x00 and '0', will be read as "00"
420.303515     [D3] found null byte in status bits at 43 byte, assuming 0.
420.314425     [D4] read: ret 6 buf c1: 31 30 31 30 30  >10100<    <- this has '1'
420.325432     [D4] read: ret 6 buf 81: 0d 30 31 30 30  >.0100<    <- and this finishes with `\r`.
420.325442     [D3] armac command Q1 response read: '(233.0 000.0 233.0 014 49.0 27.0 20.8 00001001'

1.185164     [D4] armac command ID
1.316257     [D4] read: ret 6 buf c1: 23 31 00 30 30  >#1
1.327309     [D4] read: ret 6 buf 81: 20 31 00 30 30  > 1
1.338264     [D4] read: ret 6 buf c2: 20 20 00 30 30  >
1.349151     [D4] read: ret 6 buf 83: 20 20 20 30 30  >   00<
1.360277     [D4] read: ret 6 buf c2: 20 20 20 30 30  >   00<
1.371322     [D4] read: ret 6 buf 83: 20 20 20 30 30  >   00<
1.382265     [D4] read: ret 6 buf c3: 20 20 20 30 30  >   00<
1.393156     [D4] read: ret 6 buf 82: 20 20 20 30 30  >   00<
1.404324     [D4] read: ret 6 buf c3: 20 20 20 30 30  >   00<
1.415342     [D4] read: ret 6 buf 83: 20 20 20 30 30  >   00<
1.426292     [D4] read: ret 6 buf c2: 20 20 20 30 30  >   00<
1.437203     [D4] read: ret 6 buf 83: 20 20 20 30 30  >   00<
1.448328     [D4] read: ret 6 buf c3: 56 34 2e 30 30  >V4.00<
1.459293     [D4] read: ret 6 buf 82: 31 30 2e 30 30  >10.00<
1.470274     [D4] read: ret 6 buf c3: 20 20 20 30 30  >   00<
1.481208     [D4] read: ret 6 buf 82: 20 20 20 30 30  >   00<
1.492261     [D4] read: ret 6 buf c1: 0d 20 20 30 30  >
1.492270     [D3] armac command ID response read: '#                           V4.10     '

4.749667     [D4] armac command F
4.876638     [D4] read: ret 6 buf 81: 23 31 00 30 30  >#1
4.887614     [D4] read: ret 6 buf c1: 32 31 00 30 30  >21
4.898644     [D4] read: ret 6 buf 82: 32 30 00 30 30  >20
4.909595     [D4] read: ret 6 buf c3: 2e 30 20 30 30  >.0 00<
4.920648     [D4] read: ret 6 buf 82: 30 30 20 30 30  >00 00<
4.931629     [D4] read: ret 6 buf c3: 35 20 32 30 30  >5 200<
4.942601     [D4] read: ret 6 buf 83: 34 2e 30 30 30  >4.000<
4.953666     [D4] read: ret 6 buf c2: 30 20 30 30 30  >0 000<
4.964535     [D4] read: ret 6 buf 83: 35 30 2e 30 30  >50.00<
4.975540     [D4] read: ret 6 buf c2: 30 0d 2e 30 30  >0
4.975546     [D3] armac command F response read: '#220.0 005 24.00 50.0'

112.966856     [D4] armac command Q1
112.968197     [D4] armac cleanup ret i=0 ret=6 ctrl=c0         <- Cleanups required.
113.091193     [D4] read: ret 6 buf 81: 28 30 0d 2e 30  >(0     <- Usually 1-3 bytes available in transfer.
113.103211     [D4] read: ret 6 buf c1: 30 30 0d 2e 30  >00
113.115180     [D4] read: ret 6 buf 82: 30 30 0d 2e 30  >00
113.117144     [D4] read: ret 6 buf c3: 2e 30 20 2e 30  >.0 .0<
113.120150     [D4] read: ret 6 buf 81: 31 30 20 2e 30  >10 .0<
113.132178     [D4] read: ret 6 buf c1: 34 30 20 2e 30  >40 .0<
113.144159     [D4] read: ret 6 buf 82: 30 2e 20 2e 30  >0. .0<
113.146149     [D4] read: ret 6 buf c3: 30 20 32 2e 30  >0 2.0<
113.149173     [D4] read: ret 6 buf 81: 32 20 32 2e 30  >2 2.0<
113.161167     [D4] read: ret 6 buf c1: 37 20 32 2e 30  >7 2.0<
113.173159     [D4] read: ret 6 buf 82: 2e 30 32 2e 30  >.02.0<
113.175157     [D4] read: ret 6 buf c3: 20 30 30 2e 30  > 00.0<
113.178158     [D4] read: ret 6 buf 81: 32 30 30 2e 30  >200.0<
113.190157     [D4] read: ret 6 buf c1: 20 30 30 2e 30  > 00.0<
113.202161     [D4] read: ret 6 buf 82: 30 30 30 2e 30  >000.0<
113.204154     [D4] read: ret 6 buf c3: 2e 30 20 2e 30  >.0 .0<
113.207150     [D4] read: ret 6 buf 81: 34 30 20 2e 30  >40 .0<
113.219174     [D4] read: ret 6 buf c1: 36 30 20 2e 30  >60 .0<
113.231165     [D4] read: ret 6 buf 82: 2e 38 20 2e 30  >.8 .0<
113.233157     [D4] read: ret 6 buf c3: 20 35 36 2e 30  > 56.0<
113.237149     [D4] read: ret 6 buf 81: 2e 35 36 2e 30  >.56.0<
113.249168     [D4] read: ret 6 buf c1: 30 35 36 2e 30  >056.0<
113.261155     [D4] read: ret 6 buf 83: 20 31 30 2e 30  > 10.0<
113.263151     [D4] read: ret 6 buf c2: 30 30 30 2e 30  >000.0<
113.266152     [D4] read: ret 6 buf 81: 31 30 30 2e 30  >100.0<
113.278161     [D4] read: ret 6 buf c1: 30 30 30 2e 30  >000.0<  <- No Null bytes.
113.290155     [D4] read: ret 6 buf 82: 30 30 30 2e 30  >000.0<
113.292159     [D4] read: ret 6 buf c1: 0d 30 30 2e 30  >
113.292169     [D3] armac command Q1 response read: '(000.0 140.0 227.0 002 00.0 46.8 56.0 10001000'

0.083301     [D4] armac command Q1
0.164847     [D4] read: ret 6 buf a6: 28 32 34 31 2e  >(241.<
0.184839     [D4] read: ret 6 buf 86: 35 20 30 30 30  >5 000<
0.205851     [D4] read: ret 6 buf a6: 2e 30 20 32 33  >.0 23<
0.226849     [D4] read: ret 6 buf 86: 30 2e 33 20 30  >0.3 0<
0.247859     [D4] read: ret 6 buf a6: 30 30 20 34 39  >00 49<
0.268862     [D4] read: ret 6 buf 86: 2e 39 20 32 2e  >.9 2.<
0.289857     [D4] read: ret 6 buf a6: 32 35 20 34 38  >25 48<
0.309866     [D4] read: ret 6 buf 86: 2e 30 20 30 30  >.0 00<
0.330863     [D4] read: ret 6 buf a6: 30 30 30 30 30  >00000<
0.827913     [D4] read: ret 6 buf 83: 31 0d 30 30 30  >1 000<
0.827927     [D3] armac command Q1 response read: '(241.5 000.0 230.3 000 49.9 2.25 48.0 00000001'
0.827954     [D4] armac command ID
1.394985     [D4] read: ret 6 buf a5: 4e 41 4b 0d 30  >NAK  <
1.395001     [D3] armac command ID response read: 'NAK'

You must put the generated files into the drivers/ subdirectory, with the name of your subdriver preceded by nutdrv_qx_, and update nutdrv_qx.c by adding the appropriate #include line and by updating the definition of subdriver_list.

Please, make sure to add your driver in that list in a smart way: if your device supports also the basic commands used by the other subdrivers to claim a device, add something that is unique (i.e. not supported by the other subdrivers) to your device in your claim function and then add it on top of the slightly supported ones in that list.

You must also add the subdriver to NUTDRV_QX_SUBDRIVERS list variable in the drivers/Makefile.am and call "autoreconf" and/or "./configure" from the top level NUT directory.

You can then recompile nutdrv_qx, and start experimenting with the new subdriver.

For more details, have a look at the currently available subdrivers:

SETINFO <varname> "<value>"

SETINFO ups.status "OB LB"

There is no "ADDINFO" — if a given variable does not exist, it is created upon receiving the first SETINFO command.

DELINFO <varname>

DELINFO ups.temperature

ADDENUM <varname> "<value>"

ADDENUM input.transfer.low "95"

DELENUM <varname> "<value>"

DELENUM input.transfer.low "98"

ADDRANGE <varname> <minvalue> <maxvalue>

ADDRANGE input.transfer.low 95 100

DELRANGE <varname> <minvalue> <maxvalue>

DELRANGE input.transfer.low 95 100

SETAUX <varname> <numeric value>

SETAUX ups.id 8

This overrides any previous value. The auxiliary value is presently used as a length byte for read-write variables that are strings.

SETFLAGS <varname> <flag>...

SETFLAGS ups.id RW STRING

Note that this command takes a variable number of arguments, as multiple flags are supported. Also note that they are not crammed together in "" quotes, since "RW STRING" would mean something completely different.

This also replaces any previous flags for a given variable.

Currently supported flags include RW, STRING and NUMBER (detailed in the NUT Network Protocol documentation); unrecognized values are quietly ignored.

ADDCMD <cmdname>

ADDCMD load.off

DELCMD <cmdname>

DELCMD load.on

PID <id>

PID 12345

PID "StrangeOS process identifier"

Response to GETPID query, where we serve platform-specific process identifier. On POSIX and many other platforms this would be a numeric value, but most generally it should be treated as an opaque string.

DUMPDONE

This is only used to tell the server that every possible item has been transmitted in response to its DUMPALL request. Once this has been received by the server, it can be sure that it knows everything that the driver does.

PONG

This is sent in response to a PING from the server. It is only used as a sanity check to make sure that the driver has not gotten stuck somewhere.

OK Goodbye

This is sent in response to a LOGOUT from the server (or more likely from a sibling driver or upsdrvctl program).

DATAOK

This means that the driver is able to communicate with the UPS, and the data should be treated as usable. It is always sent at the end of the dump if the data is not stale. It may also be sent at other times.

DATASTALE

This is sent by the driver to inform any listeners that the data is no longer usable. This usually means that the driver is unable to get any sort of meaningful response from the UPS. You must not rely on any status information once this has been sent.

This will be sent in the beginning of a dump if the data is stale, and may be repeated. It is cleared by DATAOK.

TRACKING <id> <value>

This is sent in response to an INSTCMD or SET VAR that includes a TRACKING, upon completion of request execution by the driver. <value> is the integer return value from the driver handlers instcmd and setvar (see drivers/upshandler.h). The server is in charge of translating these codes into strings, as per docs/net-protocol.txt GET TRACKING.

PING

This is sent to check on the health of a driver. The server should only send this when it hasn’t heard anything valid from a driver recently. Some drivers have very little to say in terms of updates, and this may be the only communications they have with the server on a normal basis.

If a driver does not respond with the PONG within a few seconds at the most, it should be treated as dead/unavailable. Data stored in the server must not be passed on to the clients when this happens.

INSTCMD <cmdname> [<cmdparam>] [TRACKING <id>]

INSTCMD panel.test.start
INSTCMD load.off 10
INSTCMD load.on 10 TRACKING 1bd31808-cb49-4aec-9d75-d056e6f018d2

NOTE:

SET <varname> "<value>" [TRACKING <id>]

SET ups.id "Data room"
SET ups.id "Data room" TRACKING 2dedb58a-3b91-4fab-831f-c8af4b90760a

NOTE:

The server (or sibling driver instances, or upsdrvctl tool) can use this to request the platform-specific process identifier of the driver process. On POSIX and many other platforms this would be a numeric value, but most generally it should be treated as an opaque string.

DUMPALL

The server uses this to request a complete copy of everything the driver knows. This is returned in the form of the same commands (SETINFO, etc.) that would be used if they were being updated normally. As a result, the same parsing happens either way.

The server can tell when it has a full copy of the data by waiting for DUMPDONE. That special response from the driver is sent once the entire set has been transmitted.

DUMPVALUE <varname>

DUMPVALUE driver.version

Only request the value of specified variable name (and its additional metadata in other lines), same as when DUMPALL iterates all such names.

The NUT data server or other socket-protocol client should parse the response line by line, looking for the SETINFO line to get the value; if a DUMPDONE is seen first, the value was not available in the driver.

DUMPSTATUS

Effectively an alias to DUMPVALUE ups.status.

This connection does not want to receive broadcast messages (implemented by send_to_all() method in dstate.c). Default is to receive everything.

This connection specified whether it wants to receive broadcast messages (implemented by send_to_all() method in dstate.c), and by default enables that — unless disabled by providing an optional zero or negative numeric argument. Note that initial default is to receive everything, so this command may be useful for connections that disabled broadcasts at some point.

Primarily used by communications between driver processes and/or upsdrvctl, this command allows clients to gracefully close connection to the NUT driver which acts as the server on the socket/pipe, avoiding noisy logs about sudden disconnection.

LOGOUT
OK Goodbye

There is no way to request just one variable. This was done on purpose to limit the complexity of the drivers. Their job is to send out updates and handle a few simple requests. DUMPALL is provided to give the server a known foundation.

To track a limited set of variables, a server just needs to do DUMPALL, then only have handlers that remember values for the variables that matter. Anything else should be ignored.

There are no access controls in the drivers. Anything that can connect to their sockets can make requests, including SET and INSTCMD if supported by the driver and hardware. These sockets must be kept secure. If your operating system does not honor permissions or modes on sockets, then you must store them in a directory with suitable permissions to limit access.

As parseconf is used to handle decoding and chunking of the data, there are some limits on what may be used. These default to 32 arguments of 512 characters each, which should be more than enough for everything which is currently needed by the software.

These limits are strictly for sanity purposes, and may be raised if necessary. parseconf itself can handle vast numbers of arguments and characters, with some speed penalty as things get really big.

If the server loses its connection to the driver and later reconnects, it must flush any local storage and start again with DUMPALL. The driver may have changed the internal state considerably during that time, and any other approach could leave old elements behind.

Having Augeas installed. You will need at least version 0.5.1 (prior versions may work too, reports are welcome).

As an example, on Debian and derivatives, do the following:

:; apt-get install augeas-lenses augeas-tools

And optionally:

:; apt-get install libaugeas0 libaugeas-dev python-augeas

On RedHat and derivatives, you have to install the packages augeas and augeas-libs.

These are the *.aug files in the present directory.

You can either install the files to the right location on your system, generally in /usr/share/augeas/lenses/, or use these from NUT source directory (nut/scripts/augeas). The latter is to be preferred for the time being.

Start an augeas shell using:

:; augtool -b

From there, you can perform different actions like:

C ~

A library is available for C programs, along with pkg-config support.

You can get the compilation and link flags using the following code in your program’s configure script or Makefile:

CFLAGS="`pkg-config --silence-errors --cflags augeas`"
LDFLAGS="`pkg-config --silence-errors --libs augeas`"

Here is a code sample using this library for NUT configuration:

augeas *a = aug_init(NULL, NULL, AUG_NONE);
ret = aug_match(a, "/files/etc/nut/*", &matches_p);
ret = aug_set(a, "/files/etc/nut/ups.conf/augtest/driver", "dummy-ups");
ret = aug_set(a, "/files/etc/nut/ups.conf/augtest/port", "auto");
ret = aug_save(a);

The augeas class abstracts access to the configuration files.

$ python
Python 2.5.1 (r251:54863, Apr  8 2008, 01:19:33)
[GCC 4.3.0 20080404 (Red Hat 4.3.0-6)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import augeas
>>> a = augeas.augeas()
>>> a.match("/files/etc/nut/*")
['/files/etc/nut/upsd.users', '/files/etc/nut/upsmon.conf', '/files/etc/nut/ups.conf', '/files/etc/nut/upsd.conf']
>>> a.set("/files/etc/nut/ups.conf/augtest/driver", "dummy-ups")
True
>>> a.set("/files/etc/nut/ups.conf/augtest/port", "auto")
True
>>> a.save()
True
>>>

$ grep -A 2 augtest /etc/nut/ups.conf
[augtest]
driver=dummy-ups
port=auto

The Perl binding is available through CPAN and packages.

use Config::Augeas;

my $aug = Config::Augeas->new( root => $aug_root ) ;

my @a = $aug->match("/files/etc/nut/*") ;
my $nb = $aug->count_match("/files/etc/nut/*") ;

$aug->set("/files/etc/nut/ups.conf/augtest/driver", "dummy-ups") ;
$aug->set("/files/etc/nut/ups.conf/augtest/port", "auto") ;

$aug->save ;

Existing configuration files can be tested for conformity. To do so, use:

$ augparse -I ./ ./test_nut.aug

The nutscan library can be linked into other programs to give access to NUT discovery. Both static and shared versions are provided.

nut-scanner(8) is provided as an example of how to use the nutscan functions.

Here is a simple example that scans for USB devices, and use its own iteration function to display results:

Scanning and reporting example. 

        #include <stdlib.h>
        #include <unistd.h>
        #include <string.h>

        /* Only enable USB scan */
        #define HAVE_USB_H

        #include "nut-scan.h"

        int main()
        {
                nutscan_options_t * opt;
                nutscan_device_t *device;
                nutscan_usb_t usb_scanopts;

                nutscan-init();

                if ((device = nutscan_scan_usb(&usb_scanopts)) == NULL) {
                        printf("No device found\n");
                        exit(EXIT_FAILURE);
                }

                /* Rewind the list */
                while(device->prev != NULL) {
                        device = device->prev;
                }

                /* Print results */
                do {
                        printf("USB device found\n\tdriver: \"%s\"\n\tport: \"%s\"\n",
                                device->driver, device->port);

                        /* process options (serial number, bus, ...) */
                        opt = &(device->opt);
                        do {
                                if( opt->option != NULL ) {
                                        printf("\t%s",opt->option);
                                        if( opt->value != NULL ) {
                                                printf(": \"%s\"", opt->value);
                                        }
                                        printf("\n");
                                }
                                opt = opt->next;
                        } while( opt != NULL );

                        device = device->next;
                }
                while( device != NULL );

                exit(EXIT_SUCCESS);
        }

This library file and the associated header files are not installed by default. You must ./configure --with-dev 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 nutscan(3), manual page and the various nutscan_*(3) functions documentation referenced in the same file.

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.

libupsclient and libnutclient libraries can be linked into other programs to give access to upsd and UPS status information. Both static and shared versions are provided.

These library files and associated header files are not installed by default. You must ./configure --with-dev 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.

  #include <iostream>
  #include <unistd.h>
  #include <stdlib.h>

  #include <nutclient.h>

  using namespace nut;
  using namespace std;

  /* argv[1] is the mandatory NUT device name (@localhost),
   *    used to list variables from
   * argv[2] is an optional command. When provided, it will be
   *    executed and possibly with status tracking enabled
   */
  int main(int argc, char **argv)
  {
    Client *client;
    try
    {
      // Connection
      client = new TcpClient("localhost", 3493);

      if (argc >= 2)
      {
        // Reading data from device
        Device mydev = client->getDevice(argv[1]);
        cout << "Description: " << mydev.getDescription() << endl;
        Variable var = mydev.getVariable("device.model");
        cout << "Model: " <<  var.getValue()[0] << endl;

        if (argc >= 3)
        {
          // Authenticate to NUT server
          const char *user = getenv("NUT_USER");
          const char *password = getenv("NUT_PASSWD");
          client->authenticate(user ? user : "", password ? password : "");

          // Enable command tracking, if available
          if (client->hasFeature(Client::TRACKING))
          {
            cout << "Server can do command tracking" << std::endl;
            client->setFeature(Client::TRACKING, true);
          }
          else
          {
            std::cout << "Server can't do command tracking" << std::endl;
          }

          // Perform an asynchronous command
          TrackingID id = mydev.executeCommand(argv[2]);
          TrackingResult result;
          do
          {
            sleep(1);
            result = client->getTrackingResult(id);
          }
          while (result == PENDING);

          // Display result of command
          const char *output = "<UNRECOGNIZED>";
          switch (result)
          {
            case SUCCESS: output = "SUCCESS"; break;
            case FAILURE: output = "FAILURE"; break;
            case UNKNOWN: output = "UNKNOWN"; break;
          }
          cout << "Command sent, result=" << output << endl;
        }
      }
    }
    catch (NutException &ex)
    {
      cerr << "Unexpected problem : " << ex.str() << endl;
    }
    delete client;
    return 0;
  }

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.

Form:

GET NUMLOGINS <upsname>
GET NUMLOGINS su700

Response:

NUMLOGINS <upsname> <value>
NUMLOGINS su700 1

<value> is the number of clients which have done LOGIN for this UPS. This is used by the upsmon in primary mode to determine how many clients are still connected when starting the shutdown process.

This replaces the old "REQ NUMLOGINS" command.

Form:

GET UPSDESC <upsname>
GET UPSDESC su700

Response:

UPSDESC <upsname> "<description>"
UPSDESC su700 "Development box"

<description> is the value of "desc=" from ups.conf for this UPS. If it is not set, upsd will return "Unavailable".

This can be used to provide human-readable descriptions instead of a cryptic "upsname@hostname" string.

Form:

GET VAR <upsname> <varname>
GET VAR su700 ups.status

Response:

VAR <upsname> <varname> "<value>"
VAR su700 ups.status "OL"

This replaces the old "REQ" command.

Form:

GET TYPE <upsname> <varname>
GET TYPE su700 input.transfer.low

Response:

TYPE <upsname> <varname> <type>...
TYPE su700 input.transfer.low ENUM

<type> can be several values, and multiple words may be returned:

ENUM, STRING and RANGE are usually associated with RW, but not always. The default <type>, when omitted, is numeric, so either integer or float. Each driver is then responsible for handling values as either integer or float.

Note that float values are expressed using decimal (base 10) english-based representation, so using a dot, in non-scientific notation. So hexadecimal, exponents, and comma for thousands separator are forbidden. For example: "1200.20" is valid, while "1,200.20" and "1200,20" and "1.2e4" are invalid.

This replaces the old "VARTYPE" command.

Form:

GET DESC <upsname> <varname>
GET DESC su700 ups.status

Response:

DESC <upsname> <varname> "<description>"
DESC su700 ups.status "UPS status"

<description> is a string that gives a brief explanation of the named variable. upsd may return "Unavailable" if the file which provides this description is not installed.

Different versions of this file may be used in some situations to provide for localization and internationalization.

This replaces the old "VARDESC" command.

Form:

GET CMDDESC <upsname> <cmdname>
GET CMDDESC su700 load.on

Response:

CMDDESC <upsname> <cmdname> "<description>"
CMDDESC su700 load.on "Turn on the load immediately"

This is like DESC above, but it applies to the instant commands.

This replaces the old "INSTCMDDESC" command.

Form:

GET TRACKING      (activation status of TRACKING)
GET TRACKING <id> (execution status of a command / setvar)
GET TRACKING 1bd31808-cb49-4aec-9d75-d056e6f018d2

Response:

ON                   (TRACKING feature is enabled)
OFF                  (TRACKING feature is disabled)
PENDING              (command execution is pending)
SUCCESS              (command was successfully executed)
ERR UNKNOWN          (command execution failed with unknown error)
ERR INVALID-ARGUMENT (command execution failed due to missing or invalid argument)
ERR FAILED           (command execution failed)

Form:

LIST UPS

Response:

BEGIN LIST UPS
UPS <upsname> "<description>"
...
END LIST UPS

BEGIN LIST UPS
UPS su700 "Development box"
END LIST UPS

<upsname> is a name from ups.conf, and <description> is the value of desc= from ups.conf, if available. It will be set to "Unavailable" otherwise.

This can be used to determine what values of <upsname> are valid before calling other functions on the server. This is also a good way to handle situations where a single upsd supports multiple drivers.

Clients which perform a UPS discovery process may find this useful.

Form:

LIST VAR <upsname>
LIST VAR su700

Response:

BEGIN LIST VAR <upsname>
VAR <upsname> <varname> "<value>"
...
END LIST VAR <upsname>

BEGIN LIST VAR su700
VAR su700 ups.mfr "APC"
VAR su700 ups.mfr.date "10/17/96"
...
END LIST VAR su700

This replaces the old "LISTVARS" command.

Form:

LIST RW <upsname>
LIST RW su700

Response:

BEGIN LIST RW <upsname>
RW <upsname> <varname> "<value>"
...
END LIST RW <upsname>

BEGIN LIST RW su700
RW su700 output.voltage.nominal "115"
RW su700 ups.delay.shutdown "020"
...
END LIST RW su700

This replaces the old "LISTRW" command.

Form:

LIST CMD <upsname>
LIST CMD su700

Response:

BEGIN LIST CMD <upsname>
CMD <upsname> <cmdname>
...
END LIST CMD <cmdname>

BEGIN LIST CMD su700
CMD su700 load.on
CMD su700 test.panel.start
...
END LIST CMD su700

This replaces the old "LISTINSTCMD" command.

Form:

LIST ENUM <upsname> <varname>
LIST ENUM su700 input.transfer.low

Response:

BEGIN LIST ENUM <upsname> <varname>
ENUM <upsname> <varname> "<value>"
...
END LIST ENUM <upsname> <varname>

BEGIN LIST ENUM su700 input.transfer.low
ENUM su700 input.transfer.low "103"
ENUM su700 input.transfer.low "100"
...
END LIST ENUM su700 input.transfer.low

This replaces the old "ENUM" command.

Form:

LIST RANGE <upsname> <varname>
LIST RANGE su700 input.transfer.low

Response:

BEGIN LIST RANGE <upsname> <varname>
RANGE <upsname> <varname> "<min>" "<max>"
...
END LIST RANGE <upsname> <varname>

BEGIN LIST RANGE su700 input.transfer.low
RANGE su700 input.transfer.low "90" "100"
RANGE su700 input.transfer.low "102" "105"
...
END LIST RANGE su700 input.transfer.low

Form:

LIST CLIENT <device_name>
LIST CLIENT ups1

Response:

BEGIN LIST CLIENT <device_name>
CLIENT <device name> <client IP address>
...
END LIST CLIENT <device_name>

BEGIN LIST CLIENT ups1
CLIENT ups1 ::1
CLIENT ups1 192.168.1.2
END LIST CLIENT ups1

Form:

SET VAR <upsname> <varname> "<value>"
SET VAR su700 ups.id "My UPS"

Response:

OK                         (if TRACKING is not enabled)
OK TRACKING <id>           (if TRACKING is enabled)
ERR <message> [<extra>...] (see Error responses)

Form:

SET TRACKING <value>
SET TRACKING ON
SET TRACKING OFF

Response:

OK
ERR INVALID-ARGUMENT  (if <value> is not "ON" or "OFF")
ERR USERNAME-REQUIRED (if not yet authenticated)
ERR PASSWORD-REQUIRED (if not yet authenticated)

The LIST commands may be given the ability to handle options some day. For example, LIST VARS <ups> +DESC would return the current value like now, but it would also append the description of that variable.

Allow to request only a subtree, which can be a collection, or a sub collection.

Some systems don’t want a daemon listening to the network. This can be for security reasons, or perhaps because the system has been squashed down and doesn’t have TCP/IP available. For these situations you could run a driver and program that sits on top of the driver socket to do local monitoring.

This also makes monitoring extremely easy to automate - you don’t need to worry about usernames, passwords or firewalling. Just start a driver and drop this program on top of it.

upsmon currently retains root in a forked process so it can call the shutdown command. The only reason it needs root on most systems is that only privileged users can signal init or send a message on /dev/initctl.

In the case of systems running sysvinit (Slackware, others?), upsmon could just open /dev/initctl while it has root and then drop it completely. When it’s time to shut down, fire a control structure at init across the lingering socket and tell it to enter runlevel 0.

This has been shown to work in local tests, but it’s not portable. It could only be offered as an option for those systems which run that flavor of init. It also needs to be tested to see what happens to the lingering fd over time, such as when init restarts after an upgrade.

For other systems, there is always the possibility of having a suid program which does nothing but prod init into starting a shutdown. Lock down the group access so only upsmon’s unprivileged user can access it, and make that your SHUTDOWNCMD. Then it could drop root completely.

upsmon could run the network monitoring part in a chroot jail if it had a pipe to another process running outside for NOTIFY dispatches. Such a pipe would have to be constructed extremely carefully so an attacker could not compromise it from the jailed process.

A state machine with a tightly defined sequence could do this safely. All it has to do is dispatch the UPS name and event type.

[start] [type] [length] <name> [stop]

Once in awhile, I get requests for a way to shut down based on the UPS temperature, or ambient humidity, or at a certain battery charge level, or any number of things other than an "OB LB" status. It should be obvious that adding a way to monitor all of that in upsmon would bloat upsmon for all those people who really don’t need anything like that.

A separate program that interprets a list of rules and uses it to monitor the UPS equipment is the way to solve this. If you have a condition that needs to be tested, add a rule.

Some of the tools that such a language would need include simple greater-than/less-than testing (if battery.charge < 20), equivalence testing (if ups.model = "SMART-UPS 700"), and some way to set and clear timers.

Due to the expected size and limited audience for such a program, it might have to be distributed separately.