node-red-contrib-nut

Node-RED nodes to integrate Network UPS Tools (NUT) UPS status and events into your flows.

npm install node-red-contrib-nut

✨ Features

• Connects to any NUT server (TCP, default port 3493)
• Username/password authentication and optional TLS
• Separate config node for the NUT server
• UPS node with two modes:
  • Polling: query UPS status in a fixed interval
  • Events (monitor): subscribe to NUT events/variable changes
• Optional fetch on deploy and auto-refresh
• Option to send messages only if payload changed
• Normalised status flags: onBattery, lowBattery, online
• Full NUT variable map (e.g. battery.charge, ups.load, …)
• Fully i18n-enabled (English / German, including help text and status messages)

Install

From your Node-RED user directory (typically ~/.node-red):

npm install node-red-contrib-nut

Or via the Node-RED Palette Manager:

1. Open the Node-RED editor
2. Menu → Manage palette
3. Tab Install
4. Search for node-red-contrib-nut
5. Click Install

Nodes

nut-server (config node)

Represents a single NUT server instance.
Multiple nut-ups nodes can share the same server configuration.

nut-ups

Queries or monitors a specific UPS connected to the configured NUT server and outputs structured status messages.

Configuration

Common options

Name

Optional display name for the node.
If left empty, a default label is used.

nut-server options

Host

Hostname or IP address of the NUT server (e.g. 10.24.0.100).

Port

TCP port of the NUT server.
Default: 3493.

Username / Password

NUT user credentials, e.g. a dedicated user like nodered that has at least read permissions for the configured UPS.

Note: Credentials are stored by Node-RED’s credential mechanism and are not exported with flows.

Use TLS

If enabled, the node connects using TLS instead of plain TCP.
Make sure your NUT server is configured accordingly.

nut-ups options

NUT Server

Reference to a nut-server config node.

UPS Name

The UPS name as configured on the NUT server, e.g. apc-1.

You can list available UPS devices on the server with:

upsc -l <host>

Mode

• Polling – actively queries the UPS in a fixed interval.
• Events (monitor) – subscribes to events and variable changes from the NUT server.

Auto-refresh (sec)

Additional auto-refresh interval in seconds.

• 0 → disabled
• > 0 → in polling mode, this is the interval between two queries
  (in monitor mode it can be used as a safety refresh).

Fetch on deploy

If enabled, the node performs an initial fetch shortly after the flow is deployed.

Only send on change

If enabled, the node only emits a message when the payload differs from the last emitted payload.

Inputs

Any incoming message to the nut-ups node acts as a trigger:

• In Polling mode, the node immediately queries the UPS status.
• In Events mode, the node performs a refresh but will also emit messages on NUT events.

The content of the incoming message is not evaluated in this version.

Outputs

The node outputs a message with a structured payload.
A typical message looks like:

{
  "topic": "nut/apc-1/status",
  "payload": {
    "ups": "apc-1",
    "status": "OL",
    "onBattery": false,
    "lowBattery": false,
    "online": true,
    "variables": {
      "battery.charge": "100",
      "battery.charge.low": "10",
      "battery.runtime": "1068",
      "battery.type": "PbAc",
      "input.voltage": "234.0",
      "ups.load": "25",
      "ups.model": "Back-UPS BX950MI ",
      "ups.status": "OL",
      "...": "..."
    },
    "event": null,
    "timestamp": "2025-12-01T17:34:30.887Z"
  }
}

• topic – by default set to nut/<ups-name>/status
• payload.ups – UPS name
• payload.status – raw NUT status string, e.g. OL, OB, LB
• payload.onBattery – boolean flag
• payload.lowBattery – boolean flag
• payload.online – boolean flag
• payload.variables – all NUT variables for this UPS as key/value pairs
• payload.event – event name in monitor mode (if available), otherwise null
• payload.timestamp – ISO-8601 timestamp when the data was fetched

Example flow

A basic example flow is included in:

examples/nut-basic.json

It demonstrates:

• configuring a nut-server pointing to your NUT instance
• a nut-ups node in polling mode
• a manual Inject trigger
• basic post-processing using Switch and Debug nodes for
  • “On battery?”
  • “Low battery?” messages

Import steps:

1. In Node-RED, open the menu → Import
2. Choose Clipboard
3. Paste the contents of examples/nut-basic.json
4. Click Import

Internationalisation (i18n)

All editor labels, tooltips, help content and runtime status messages are localised via the Node-RED i18n mechanism.

Translator files:

• English:
  • nodes/locales/en-US/nut-server.json
  • nodes/locales/en-US/nut-server.html
  • nodes/locales/en-US/nut-ups.json
  • nodes/locales/en-US/nut-ups.html
• German:
  • nodes/locales/de/nut-server.json
  • nodes/locales/de/nut-server.html
  • nodes/locales/de/nut-ups.json
  • nodes/locales/de/nut-ups.html

The Node-RED editor language (or browser language, depending on configuration) controls which texts are displayed.

⚖️ License

MIT © 2025 Gerd Rütten

Changelog

See CHANGELOG.md for a detailed list of changes.