NUTController

NUTController is a (client) interface to a Network UPS Tools (NUT) server. Each UPS system published by the NUT server is represented by an entity in Reactor, and its variables and states are presented as attributes on those entities. Using NUTController, you can have Reactor rules react to changes in UPS status and behavior.

Requirements

NUTController requires Reactor build/version 22145 or higher to operate. A NUT server running on a network-accessible host system is also required.

Installation

NUTController is not included in base Reactor distributions. It must be installed separately by downloading the package from the extras subdirectory of the Reactor download server.

Once the package file (a ZIP or Gzip'd tar archive) is downloaded:

Create, if it does not already exist, a subdirectory called ext in your Reactor install directory (so it should be at the same level as config, storage, etc.).
```
cd /path/to/reactor
mkdir ext
```
If you are running Reactor in a docker container, the ext directory must be created in your data directory, where your config and storage directories live as indicated above.
Change directory into the new ext directory:
```
cd ext
```

Unpack the archive (use whichever command is correct for the type of archive downloaded):

tar xzvf /path/to/NUTController-XXXXX.tar.gz    # or...
unzip /path/to/NUTController-XXXXX.zip

Run the install script. If you are using a "bare metal" install (not a docker container):
```
cd NUTController
./install.sh
```
If you are running Reactor in a docker container, we will open a container shell in which to do the install (the Reactor container must be up and running):
```
docker exec -it <container-name> /bin/sh
cd /var/reactor/ext/NUTController
./install.sh
exit
```

In future, if you upgrade to a newer available version of NUTController, just re-run steps 2-4 (inclusive) after downloading the newer package archive file.

From here, continue to Configuration below.

Configuration

One instance of NUTController is needed for each NUT server you want to connect to. To configure an instance of NUTController:

Make sure your NUT server is running. Also make sure it is configured in netserver mode (in nut.conf), and its LISTEN directive(s) (in upsd.conf) list the IP address of the NUT server host system (i.e. not just localhost, unless Reactor and NUT are running on the same system, in which case localhost is fine). If you're not sure, LISTEN 0.0.0.0 will have the NUT server listen on all host interfaces.
Open your reactor.yaml configuration file on your Reactor host.

In the controllers section, add the following template, substituting your server's IP address:

controllers:
  - id: nut
    implementation: NUTController
    enabled: true
    config:
      server: 127.0.0.1        # modify the IP address as needed
      #port: 3493              # optional, default shown
      #username: "myuser"      # optional, no user auth if not set (see callout, below)
      #password: "mypassword"  # optional, must be specified if username is used

The configuration lines beginning # are commented out; if you need to use them, remove the # and provide your correct value.

Restart Reactor.
Connect to the Reactor UI using a browser.
In the Entities page, use the controller filter to select your NUT controller instance and display its entities. Each NUT-connected UPS should be shown as a an entity.

Username and Password

It appears that, at the moment, you do not need to set the username and password for NUTController to get UPS states — the NUT server does not require authentication for those queries. There are no operations NUTController can perform at this time that require authentication, so you can safely leave username and password out of your configuration.

Capabilities and Attributes

NUTController UPS entities show the following attributes:

Attribute	Type	Description
power_source.source	string (enum)	`utility` when on mains/utility power, `battery` when mains/utility has failed and the UPS is supplying power from its battery
battery_power.level	real (0.0-1.0)	Battery power level (0=empty, 1=full)
battery_power.since	timestamp	Time when battery power was last reported
battery_maintenance.charging	boolean	true if the battery is being charged, false otherwise
battery_maintenance.replace	boolean	true if battery needs to be replaced (depends on UPS functionality and NUT driver for that device; not available on all UPS devices)

In addition, all variables published by NUT are offered as extended attributes on the entity.

The NUTController system entity's sys_system.state attribute is true when the instance has a valid connection to the NUT server, and false when a connection cannot be established. Attributes on UPS entities are not modified by loss of communication (they simply maintain their last known state/value until communication is restored).

Updated: 2023-Jul-29