Matterbridge UPS

Matterbridge plugin for UPS devices exposed by Network UPS Tools (NUT).

Each NUT UPS is exposed as a Matter device with:

• mains presence through the Contact Sensor device type;
• load power, current, and voltage through Matter electrical measurement clusters;
• battery level, voltage, charging state, runtime, low-battery state, and replacement state through a rechargeable Power Source cluster;
• reachability that reflects the NUT connection, with active UPS alarms logged;
• a quick battery test when the Matter Identify action is invoked.

Matter has no standard clusters for changing the NUT low-battery threshold or enabling/disabling the beeper, so the Homebridge-specific controls for those settings are not exposed.

Prerequisites

• Matterbridge 3.10.0 or newer;
• a supported Node.js release (20.19+, 22.13+, 24, or 26);
• an accessible upsd server, normally on TCP port 3493.

Installation

Install Matterbridge, then add this plugin from the Matterbridge frontend or from a terminal:

matterbridge --add matterbridge-ups

For local development from this checkout:

matterbridge --add .

Configuration

{
  "name": "matterbridge-ups",
  "type": "DynamicPlatform",
  "hosts": [
    {
      "host": "localhost:3493",
      "name": "server",
      "username": "optional-user",
      "password": "optional-password"
    }
  ],
  "timeout": 15,
  "debug": false,
  "unregisterOnShutdown": false
}

username and password can instead be supplied through UPS_USERNAME and UPS_PASSWORD. Credentials are normally only required for the Identify quick-test command.

Command-Line Utility

The package retains the dependency-free ups troubleshooting utility:

ups --host localhost:3493 info
ups --host localhost:3493 info --verbose
ups --host localhost:3493 test --quick myups

Run ups --help for all options.

Troubleshooting

Check the NUT connection independently before troubleshooting Matter:

ups --host localhost:3493 info --verbose

Enable debug in the plugin configuration for NUT request and response logging. Remove credentials and private network details before sharing configuration or logs.

Development

Install dependencies and run all repository checks:

npm install
npm run check

See CONTRIBUTING.md for Matterbridge development setup and pull request guidance.

Origin and Attribution

Matterbridge UPS is created and maintained by Joel Kirchmeyer. It is based in part on Homebridge UPS, created by Erik Baauw. Both projects are licensed under the Apache License 2.0.

The NUT protocol client and ups command-line utility derive from the original Homebridge project and were adapted to remove the Homebridge runtime dependency. The original Git history is retained. Erik Baauw and original contributor Dan McGee remain credited through that history and the upstream contributors page. See NOTICE for additional provenance.

Issues for this Matterbridge port belong in the Matterbridge UPS issue tracker. Please do not use the original Homebridge repository for support with this port.