This page is part of archived documentation for openHAB 2.5. Go to the current stable version
# Network UPS Tools Binding
The primary goal of the Network UPS Tools (opens new window) (NUT) project is to provide support for power devices, such as uninterruptible power supplies (UPS), Power Distribution Units and Solar Controllers.
Network UPS Tools (NUT) provides many control and monitoring features, with a uniform control and management interface. More than 100 different manufacturers, and several thousands of models are compatible.
This binding lets you integrate NUT servers with openHAB.
# Supported Things
The binding can connect to multiple NUT instances.
The thing is an ups thing.
The thing supports a number of NUT features out-of-the-box and supports the option to configure additional channels to get other NUT variables.
The thing queries the NUT server for the status of the UPS approximate every 3 seconds and updates the status when a change happens.
When a change of the UPS status happens it will query the NUT server to update all linked channels.
Outside the status change updates, all linked channels are updated at the user configured refresh time.
Some NUT variables are static in nature and are not suited for a channel. Some of these could change, like of firmware version. Therefore these properties are updated with a 1 hour frequency. The following NUT variables are read and added to the thing as properties:
| Property | Description |
|---|---|
| ups.firmware | UPS firmware |
| ups.firmware.aux | Auxiliary device firmware |
| ups.id (opens new window) | UPS system identifier |
| ups.mfr | UPS manufacturer |
| ups.mfr.date | UPS manufacturing date |
| ups.model | UPS model |
| ups.serial | UPS serial number |
# Discovery
Discovery is not supported.
# Thing Configuration
The thing configuration requires the name of the UPS device as configured on the NUT server. If the NUT service isn't running locally the ip address or domain name (FDQN) of the server running NUT must be configured. Optional, port, username and password might need to be configured if required.
| Parameter | Default | Mandatory | Description |
|---|---|---|---|
| device | Yes | UPS device name, ups for example | |
| host | localhost | Yes | UPS server hostname |
| port | 3493 | No | UPS server port, 3493 for example |
| username | No | UPS server username | |
| password | No | UPS server password | |
| refresh | 60 | No | Refresh interval for channel updates in seconds |
# Channels
The following channels are available:
| Channel Name | Item Type | Unit | Description | Advanced |
|---|---|---|---|---|
| upsAlarm | String | UPS alarms | no | |
| upsLoad | Number:Dimensionless | % | Load on UPS (percent) | yes |
| upsPower | Number:Power | VA | Current value of apparent power (Volt-Amps) | yes |
| upsRealpower | Number:Power | W | Current value of real power (Watts) | no |
| upsStatus | String | Status of the UPS: OFF, OL,OB,LB,RB,OVER,TRIM,BOOST,CAL,BYPASS,NULL | no | |
| upsTemperature | Number:Temperature | °C | UPS temperature (degrees C) | yes |
| upsTestResult | String | Results of last self test (opaque string) | yes | |
| inputCurrent | Number:ElectricCurrent | A | Input current (A) | yes |
| inputCurrentStatus | String | Status relative to the thresholds | yes | |
| inputLoad | Number:Dimensionless | % | Load on (ePDU) input (percent of full) | no |
| inputRealpower | Number:Power | W | Current sum value of all (ePDU) phases real power (W) | yes |
| inputQuality | String | Input power quality (*** opaque) | yes | |
| inputTransferReason | String | Reason for last transfer to battery (*** opaque) | yes | |
| inputVoltage | Number:ElectricPotential | V | Input voltage (V) | yes |
| inputVoltageStatus | String | Status relative to the thresholds | yes | |
| outputCurrent | Number:ElectricCurrent | A | Output current (A) | yes |
| outputVoltage | Number:ElectricPotential | V | Output voltage (V) | yes |
| batteryCharge | Number:Dimensionless | % | Battery charge (percent) | no |
| batteryRuntime | Number:Time | s | Battery runtime (seconds) | no |
| batteryVoltage | Number:ElectricPotential | V | Battery voltage (V) | yes |
# Dynamic Channels
Because there is a lot of variation in UPS features, the binding supports dynamically adding channels for features, not supported out-of-the-box.
To get data from another NUT variable the channel needs to configured.
Channels can be created with as type: Number, Number:<Quantity>, String or Switch.
The following channel properties are needed:
| Property | Description | Example |
|---|---|---|
| networkupstools | Links to NUT variable | networkupstools="input.voltage.low.warning" |
| unit | The unit of Quantity Type data | unit="V" |
# Full Example
ups.things:
Thing networkupstools:ups:ups1 [ device="ups", host="localhost", refresh=60 ]
ups-with-channels.things:
Thing networkupstools:ups:ups2 [ device="ups", host="localhost", refresh=60 ] {
Channels:
String : testResult "Test Result" [networkupstools="ups.test.result"]
Number:Frequency : upsOutFreq "Output Frequency" [networkupstools="output.frequency", unit="Hz"]
Number:ElectricPotential : upsLowVoltage "Low Voltage" [networkupstools="input.voltage.low.warning", unit="V"]
Number:ElectricCurrent : upsLowCurrent "Low Current" [networkupstools="input.current.low.warning", unit="A"]
}
ups.items
Number:Dimensionless ups_battery_charge "Battery Charge [%d %%]" {channel="networkupstools:ups:ups1:batteryCharge"}
Number:ElectricCurrent ups_current "Input Current [%d mA]"{channel="networkupstools:ups:ups1:inputCurrent"}
String test_result "Test Result" {channel="networkupstools:ups:ups2:testResult"}
Number:Frequency ups_out_freq "Output Frequency" {channel="networkupstools:ups:ups2:upsOutFreq"}
Number:ElectricPotential ups_low_voltage "Low Voltage [%.1f V]" {channel="networkupstools:ups:ups2:upsLowVoltage"}
Number:ElectricCurrent ups_low_current "Input Current [%d A]" {channel="networkupstools:ups:ups2:upsLowCurrent"}