NUT (Network UPS Tools)

The NUT component publishes uninterruptible power supply (UPS) telemetry read from a Network UPS Tools upsd daemon to the DroneDeploy Robotics Portal. It is a telemetry-only (upstream) component: it exposes one telemetry topic per UPS, carrying that UPS's NUT variables.

The component connects to an upsd daemon as a regular NUT client; it does not talk to UPS hardware directly. upsd (and the appropriate NUT driver for your UPS) must already be running and reachable from the Agent, whether that's on the same host or elsewhere on the network.

Configuration

To use the nut component, your agent will need a section in its agent-settings.json file which enables the nut component, as shown below. For more information on how to configure the agent plugins, see Agent Configuration.

...
"components": [
...
  {
    "enabled": true,
    "id": "nut",
    "settings": {
      "host": "127.0.0.1",
      "port": 3493,
      "upsNames": [],
      "interval": "5s",
      "useAuth": false
    }
  },
...
]

Name	Description	Default	Unit
host	The hostname or IP address of the upsd daemon to connect to.	127.0.0.1
port	The TCP port that upsd is listening on.	3493
upsNames	The names of the UPS devices to publish telemetry for, as known to upsd. If left empty, the component instead discovers UPS names automatically (see below).	[]
interval	How often each UPS's telemetry topic is polled. Values below 1s are floored to 1s.	5s	duration (e.g. 1s)
useAuth	Whether to authenticate with upsd using a username and password (see Credentials below).	false

UPS discovery

If upsNames is left empty, the component asks upsd for its list of known UPS devices on startup, and continues to poll for newly-added ones for as long as it runs — this covers a UPS being added to upsd's configuration, or its driver coming up, after the Agent has started. The polling delay backs off (up to a maximum of 5 minutes) while no new UPS devices are found, and resets whenever a new one appears.

If upsNames is populated, it is instead treated as the complete set of UPS devices to publish telemetry for, and no discovery is performed.

Credentials

Some upsd configurations require clients to authenticate. If useAuth is set to true, the component logs in to upsd using a username and password, which must be provided via the credentials configured for the nut component under the upsd system: the credential's ID is sent as the username, and its Key as the password. If useAuth is true but no credentials are available, the component will report an error.

Data Model

The component advertises one telemetry topic per UPS, at /nut/<upsName>, where <upsName> is the UPS's name as known to upsd.

Each message is an open map of that UPS's NUT variables to their string values, with the dotted NUT variable names preserved verbatim, for example:

{
  "ups.status": "OL",
  "battery.charge": "100",
  "battery.runtime": "1800",
  "input.voltage": "230.0"
}

The set of variables present depends on the UPS and driver in use. See the Network UPS Tools documentation for the meaning of individual variables.

If upsd reports the UPS's data as stale, or its driver as not connected, the tick is skipped (no message is published) rather than publishing incomplete data; polling resumes on the next interval.