C.3. Variables

device: General unit information

Note

some of these data will be redundant with ups.* information during a transition period. The ups.* data will then be removed.

Name Description Example value

device.model

Device model

BladeUPS

device.mfr

Device manufacturer

Eaton

device.serial

Device serial number (opaque string)

WS9643050926

device.type

Device type (ups, pdu, scd, psu, ats)

ups

device.description

Device description (opaque string)

Some ups

device.contact

Device administrator name (opaque string)

John Doe

device.location

Device physical location (opaque string)

1st floor

device.part

Device part number (opaque string)

123456789

device.macaddr

Physical network address of the device

68:b5:99:f5:89:27

device.uptime

Device uptime in seconds

1782

device.count

Total number of daisychained devices

1

device.usb.version

Device USB version

01.29

Note

When present, device.count implies daisychain support. For more information, refer to the NUT daisychain support notes chapter of the user manual and developer guide.

ups: General unit information

Name Description Example value

ups.status

UPS status

OL

ups.alarm

UPS alarms

OVERHEAT

ups.time

Internal UPS clock time (opaque string)

12:34

ups.date

Internal UPS clock date (opaque string)

01-02-03

ups.model

UPS model

SMART-UPS 700

ups.mfr

UPS manufacturer

APC

ups.mfr.date

UPS manufacturing date (opaque string)

10/17/96

ups.serial

UPS serial number (opaque string)

WS9643050926

ups.vendorid

Vendor ID for USB devices

0463

ups.productid

Product ID for USB devices

0001

ups.firmware

UPS firmware (opaque string)

50.9.D

ups.firmware.aux

Auxiliary device firmware

4Kx

ups.temperature

UPS temperature (degrees C)

042.7

ups.load

Load on UPS (percent)

023.4

ups.load.high

Load when UPS switches to overload condition ("OVER") (percent)

100

ups.id

UPS system identifier (opaque string)

Sierra

ups.delay.start

Interval to wait before restarting the load (seconds)

0

ups.delay.reboot

Interval to wait before rebooting the UPS (seconds)

60

ups.delay.shutdown

Interval to wait after shutdown with delay command (seconds)

20

ups.timer.start

Time before the load will be started (seconds)

30

ups.timer.reboot

Time before the load will be rebooted (seconds)

10

ups.timer.shutdown

Time before the load will be shutdown (seconds)

20

ups.test.interval

Interval between self tests (seconds)

1209600 (two weeks)

ups.test.result

Results of last self test (opaque string)

Bad battery pack

ups.test.date

Date of last self test (opaque string)

07/17/12

ups.display.language

Language to use on front panel (* opaque)

E

ups.contacts

UPS external contact sensors (* opaque)

F0

ups.efficiency

Efficiency of the UPS (ratio of the output current on the input current) (percent)

95

ups.power

Current value of apparent power (Volt-Amps)

500

ups.power.nominal

Nominal value of apparent power (Volt-Amps)

500

ups.realpower

Current value of real power (Watts)

300

ups.realpower.nominal

Nominal value of real power (Watts)

300

ups.beeper.status

UPS beeper status (enabled, disabled or muted)

enabled

ups.type

UPS type (* opaque)

offline

ups.watchdog.status

UPS watchdog status (enabled or disabled)

disabled

ups.start.auto

UPS starts when mains is (re)applied

yes

ups.start.battery

Allow to start UPS from battery

yes

ups.start.reboot

UPS coldstarts from battery (enabled or disabled)

yes

ups.shutdown

Enable or disable UPS shutdown ability (poweroff)

enabled

Note

When present, the value of ups.start.auto has an impact on shutdown.* commands. For the sake of coherence, shutdown commands will set ups.start.auto to the right value before issuing the command. That is, shutdown.stayoff will first set ups.start.auto to no, while shutdown.return will set it to yes.

Note

When possible, time-stamps and dates should be expressed as detailed above in the Time and Date format chapter.

input: Incoming line/power information

Name Description Example value

input.voltage

Input voltage (V)

121.5

input.voltage.maximum

Maximum incoming voltage seen (V)

130

input.voltage.minimum

Minimum incoming voltage seen (V)

100

input.voltage.status

Status relative to the thresholds

critical-low

input.voltage.low.warning

Low warning threshold (V)

205

input.voltage.low.critical

Low critical threshold (V)

200

input.voltage.high.warning

High warning threshold (V)

230

input.voltage.high.critical

High critical threshold (V)

240

input.voltage.nominal

Nominal input voltage (V)

120

input.voltage.extended

Extended input voltage range

no

input.transfer.delay

Delay before transfer to mains (seconds)

60

input.transfer.reason

Reason for last transfer to battery (* opaque)

T

input.transfer.low

Low voltage transfer point (V)

91

input.transfer.high

High voltage transfer point (V)

132

input.transfer.low.min

smallest settable low voltage transfer point (V)

85

input.transfer.low.max

greatest settable low voltage transfer point (V)

95

input.transfer.high.min

smallest settable high voltage transfer point (V)

131

input.transfer.high.max

greatest settable high voltage transfer point (V)

136

input.eco.switchable

Input High Efficiency (aka ECO) mode switch (0-2)

normal

input.sensitivity

Input power sensitivity

H (high)

input.quality

Input power quality (* opaque)

FF

input.current

Input current (A)

4.25

input.current.nominal

Nominal input current (A)

5.0

input.current.status

Status relative to the thresholds

critical-high

input.current.low.warning

Low warning threshold (A)

4

input.current.low.critical

Low critical threshold (A)

2

input.current.high.warning

High warning threshold (A)

10

input.current.high.critical

High critical threshold (A)

12

input.feed.color

Color of the input feed (opaque string)

3831236

input.feed.desc

Description of the input feed

Feed A

input.frequency

Input line frequency (Hz)

60.00

input.frequency.nominal

Nominal input line frequency (Hz)

60

input.frequency.status

Frequency status

out-of-range

input.frequency.low

Input line frequency low (Hz)

47

input.frequency.high

Input line frequency high (Hz)

63

input.frequency.extended

Extended input frequency range

no

input.transfer.boost.low

Low voltage boosting transfer point (V)

190

input.transfer.boost.high

High voltage boosting transfer point (V)

210

input.transfer.trim.low

Low voltage trimming transfer point (V)

230

input.transfer.trim.high

High voltage trimming transfer point (V)

240

input.transfer.eco.low

Low voltage ECO transfer point (V)

218

input.transfer.bypass.low

Low voltage Bypass transfer point (V)

184

input.transfer.eco.high

High voltage ECO transfer point (V)

241

input.transfer.bypass.high

High voltage Bypass transfer point (V)

264

input.transfer.frequency.bypass.range

Frequency range Bypass transfer point (percent of nominal Hz)

10

input.transfer.frequency.eco.range

Frequency range ECO transfer point (percent of nominal Hz)

5

input.transfer.hysteresis

Threshold of switching protection modes, voltage transfer point (V)

10

input.transfer.bypass.forced

Rule for allow auto Bypass switch (on/off) transfer modes (enabled or disabled)

enabled

input.transfer.bypass.overload

Rule for auto transfer on Bypass when overload (enabled or disabled)

enabled

input.transfer.bypass.outlimits

Rule for auto transfer on Bypass when out of tolerance (enabled or disabled)

enabled

input.bypass.switchable

Input auto transfer on Bypass when overload or out of tolerance (enabled or disabled)

enabled

input.bypass.switch.on

Automatically put the UPS in Bypass mode

on

input.bypass.switch.off

Automatically take the UPS out of Bypass mode

disabled

input.bypass.voltage

Input bypass voltage (V)

233

input.bypass.frequency

Input bypass frequency (Hz)

50

input.load

Load on (ePDU) input (percent of full)

25

input.realpower

Current sum value of all (ePDU) phases real power (W)

300

input.realpower.nominal

Nominal sum value of all (ePDU) phases real power (W)

850

input.power

Current sum value of all (ePDU) phases apparent power (VA)

500

input.source

The current input power source

1

input.source.preferred

The preferred power source

1

input.phase.shift

Voltage dephasing between input sources (degrees)

181

Input Voltage Hysteresis

The input voltage hysteresis concept refers to a specific behavior related to how some UPS models can handle changes in input voltage.

When the UPS is running normally (powered by utility or generator), it maintains a steady output voltage for your critical equipment. But what if the input voltage "wiggles" a bit due to fluctuations or other minor disturbances?

Rapid switching between UPS protection modes (utility power to battery and vice versa) can stress both the UPS and its connected devices.

So, some UPS models set up thresholds: If the input voltage drops below a certain "Low" level, the UPS won’t immediately switch to battery mode. Instead, it waits until it is sure the voltage stays consistently low for a bit. Similarly, if the input voltage rises above another threshold (the "High" level), the UPS won’t rush back to normal mode. It waits for stability.

By introducing hysteresis, such an UPS avoids unnecessary toggling, ensuring smoother transitions and better protection for your sensitive and expensive gear.

output: Outgoing power/inverter information

Name Description Example value

output.voltage

Output voltage (V)

120.9

output.voltage.nominal

Nominal output voltage (V)

120

output.frequency

Output frequency (Hz)

59.9

output.frequency.nominal

Nominal output frequency (Hz)

60

output.current

Output current (A)

4.25

output.current.nominal

Nominal output current (A)

5.0

Three-phase additions

The additions for three-phase measurements would produce a very long table due to all the combinations that are possible, so these additions are broken down to their base components.

Phase Count Determination

input.phases (3 for three-phase, absent or 1 for 1phase)

output.phases (as for input.phases)

DOMAINs

Any input or output is considered a valid DOMAIN.

  • input (should really be called input.mains, but keep this for compat)

    • input.bypass
    • input.servicebypass
  • output (should really be called output.load, but keep this for compat)

    • output.bypass
    • output.inverter
    • output.servicebypass
Specification (SPEC)

Voltage, current, frequency, etc are considered to be a specification of the measurement.

With this notation, the old 1phase naming scheme becomes DOMAIN.SPEC

Example: input.current

CONTEXT

When in three-phase mode, we need some way to specify the target for most measurements in more detail. We call this the CONTEXT.

With this notation, the naming scheme becomes DOMAIN.CONTEXT.SPEC when in three-phase mode.

Example: input.L1.current

Valid CONTEXTs
L1-L2  \
L2-L3   \
L3-L1    for voltage measurements
L1-N    /
L2-N   /
L3-N  /
L1  \
L2  for current and power measurements
L3  /
N  - for current measurement
Valid SPECs

Note

For cursory readers — the following couple of tables lists just the short SPEC component of the larger DOMAIN.CONTEXT.SPEC naming scheme for phase-aware values, as discussed in other sections of this chapter just above. These are NOT to be used verbatim as complete data-point names!

Valid with/without context (i.e. per phase or aggregated/averaged)

Name Description

alarm

Alarms for phases, published in ups.alarm

current

Current (A)

current.maximum

Maximum seen current (A)

current.minimum

Minimum seen current (A)

current.status

Status relative to the thresholds

current.low.warning

Low warning threshold (A)

current.low.critical

Low critical threshold (A)

current.high.warning

High warning threshold (A)

current.high.critical

High critical threshold (A)

current.peak

Peak current

voltage

Voltage (V)

voltage.nominal

Nominal voltage (V)

voltage.maximum

Maximum seen voltage (V)

voltage.minimum

Minimum seen voltage (V)

voltage.status

Status relative to the thresholds

voltage.low.warning

Low warning threshold (V)

voltage.low.critical

Low critical threshold (V)

voltage.high.warning

High warning threshold (V)

voltage.high.critical

High critical threshold (V)

power

Apparent power (VA)

power.maximum

Maximum seen apparent power (VA)

power.minimum

Minimum seen apparent power (VA)

power.percent

Percentage of apparent power related to maximum load

power.maximum.percent

Maximum seen percentage of apparent power

power.minimum.percent

Minimum seen percentage of apparent power

realpower

Real power (W)

powerfactor

Power Factor (dimensionless value between 0.00 and 1.00)

crestfactor

Crest Factor (dimensionless value greater or equal to 1)

load

Load on (ePDU) input

Valid without context (i.e. aggregation of all phases):

Name Description

frequency

Frequency (Hz)

frequency.nominal

Nominal frequency (Hz)

realpower

Current value of real power (Watts)

power

Current value of apparent power (Volt-Amps)

EXAMPLES

Partial Three phase — Three phase example:

input.phases: 3
input.frequency: 50.0
input.L1.current: 133.0
input.bypass.L1-L2.voltage: 398.3
output.phases: 3
output.L1.power: 35700
output.powerfactor: 0.82

Partial Three phase — One phase example:

input.phases: 3
input.L2.current: 48.2
input.N.current: 3.4
input.L3-L1.voltage: 405.4
input.frequency: 50.1
output.phases: 1
output.current: 244.2
output.voltage: 120
output.frequency.nominal: 60.0

battery: Any battery details

Name Description Example value

battery.charge

Battery charge (percent)

100.0

battery.charge.approx

Rough approximation of battery charge (opaque, percent)

<85

battery.charge.low

Remaining battery level when UPS switches to LB (percent)

20

battery.charge.restart

Minimum battery level for UPS restart after power-off

20

battery.charge.warning

Battery level when UPS switches to "Warning" state (percent)

50

battery.charger.status

Status of the battery charger (see the note below)

charging

battery.charger.type

Type of battery charger

ABM

battery.voltage

Battery voltage (V)

24.84

battery.voltage.cell.max

Maximum battery voltage seen of the Li-ion cell (V)

3.44

battery.voltage.cell.min

Minimum battery voltage seen of the Li-ion cell (V)

3.41

battery.voltage.nominal

Nominal battery voltage (V)

024

battery.voltage.low

Minimum battery voltage, that triggers FSD status

21,52

battery.voltage.high

Maximum battery voltage (i.e. battery.charge = 100)

26,9

battery.capacity

Battery capacity (Ah)

7.2

battery.capacity.nominal

Nominal battery capacity (Ah)

8.0

battery.current

Battery current (A)

1.19

battery.current.total

Total battery current (A)

1.19

battery.status

Health status of the battery (opaque string)

ok

battery.temperature

Battery temperature (degrees C)

050.7

battery.temperature.cell.max

Maximum battery temperature seen of the Li-ion cell (degrees C)

25.85

battery.temperature.cell.min

Minimum battery temperature seen of the Li-ion cell (degrees C)

24.85

battery.runtime

Battery runtime (seconds)

1080

battery.runtime.low

Remaining battery runtime when UPS switches to LB (seconds)

180

battery.runtime.restart

Minimum battery runtime for UPS restart after power-off (seconds)

120

battery.alarm.threshold

Battery alarm threshold

0 (immediate)

battery.date

Battery installation or last change date (opaque string)

11/14/20

battery.date.maintenance

Battery next change or maintenance date (opaque string)

11/13/24

battery.mfr.date

Battery manufacturing date (opaque string)

2005/04/02

battery.packs

Number of internal battery packs

1

battery.packs.bad

Number of bad battery packs

0

battery.packs.external

Number of external battery packs

1

battery.type

Battery chemistry (opaque string)

PbAc

battery.protection

Prevent deep discharge of battery

yes

battery.energysave

Switch off when running on battery and no/low load

no

battery.energysave.load

Switch off UPS if on battery and load level lower (percent)

5

battery.energysave.delay

Delay before switch off UPS if on battery and load level low (min)

3

battery.energysave.realpower

Switch off UPS if on battery and load level lower (Watts)

10

NOTE: battery.charger.status replaces the historic flags CHRG and DISCHRG that were exposed through ups.status. The battery.charger.status can have one of the following values:

  • charging: battery is charging,
  • discharging: battery is discharging,
  • floating: battery has completed its charge cycle, and waiting to go to resting mode,
  • resting: the battery is fully charged, and not charging nor discharging.

Note

When possible, time-stamps and dates should be expressed as detailed above in the Time and Date format chapter.

ambient: Conditions from external probe equipment

Note

n stands for the sensors index. A special case is "ambient.0" which is equivalent to "ambient" (without index), and represents the default sensor of the device. This is not to be confused with the device embedded sensor, which is published as ups.temperature. The most important data is "ambient.count", used to iterate over the whole set of outlets. For more information, refer to the NUT sensors management notes chapter of the user manual.

Name Description Example value

ambient.count

Total number of sensors

2

ambient.n.name

Ambient sensor name

sensor 1

ambient.n.id

Ambient sensor identifier (opaque string)

80f09325-2838-5637-b62a-cef9cbe2747

ambient.n.address

Ambient sensor address (opaque string)

1

ambient.n.parent.serial

Ambient sensor parent serial number (opaque string)

U603E34000

ambient.n.mfr

Ambient sensor manufacturer

EATON

ambient.n.model

Ambient sensor model

EMPDT1H1C2

ambient.n.firmware

Ambient sensor firmware

01.03.0011

ambient.n.present

Ambient sensor presence

yes

ambient.n.temperature

Ambient temperature (degrees C)

25.40

ambient.n.temperature.alarm

Temperature alarm (enabled/disabled)

enabled

ambient.n.temperature.status

Ambient temperature status relative to the thresholds

warning-low

ambient.n.temperature.high

Temperature threshold high (degrees C)

60

ambient.n.temperature.high.warning

Temperature threshold high warning (degrees C)

40

ambient.n.temperature.high.critical

Temperature threshold high critical (degrees C)

60

ambient.n.temperature.low

Temperature threshold low (degrees C)

5

ambient.n.temperature.low.warning

Temperature threshold low warning (degrees C)

10

ambient.n.temperature.low.critical

Temperature threshold low critical (degrees C)

5

ambient.n.temperature.maximum

Maximum temperature seen (degrees C)

37.6

ambient.n.temperature.minimum

Minimum temperature seen (degrees C)

18.1

ambient.n.humidity

Ambient relative humidity (percent)

038.8

ambient.n.humidity.alarm

Relative humidity alarm (enabled/disabled)

enabled

ambient.n.humidity.status

Ambient humidity status relative to the thresholds

warning-low

ambient.n.humidity.high

Relative humidity threshold high (percent)

80

ambient.n.humidity.high.warning

Relative humidity threshold high warning (percent)

70

ambient.n.humidity.high.critical

Relative humidity threshold high critical (percent)

80

ambient.n.humidity.low

Relative humidity threshold low (percent)

10

ambient.n.humidity.low.warning

Relative humidity threshold low warning (percent)

20

ambient.n.humidity.low.critical

Relative humidity threshold low critical (percent)

10

ambient.n.humidity.maximum

Maximum relative humidity seen (percent)

60

ambient.n.humidity.minimum

Minimum relative humidity seen (percent)

13

ambient.n.contacts.x.status

State of the dry contact sensor x

open

ambient.n.contacts.x.config

Configuration of the dry contact sensor x

normal-open

ambient.n.contacts.x.name

Name of the dry contact sensor x

smoke-detector1

NOTE: - ambient.n.contacts.x.status may either be the raw status (open or closed), or may relate to ambient.n.contacts.x.config. In this case, the value can be active or inactive.

outlet: Smart outlet management

Note

n stands for the outlet index. A special case is "outlet.0" which is equivalent to "outlet" (without index), and represent the whole set of outlets of the device. The most important data is "outlet.count", used to iterate over the whole set of outlets. For more information, refer to the NUT outlets management and PDU notes chapter of the user manual.

Name Description Example value

outlet.count

Total number of outlets

12

outlet.switchable

General outlet switch ability of the unit (yes/no)

yes

outlet.n.id

Outlet system identifier (opaque string)

1

outlet.n.name

Outlet name (opaque string)

A1

outlet.n.desc

Outlet description (opaque string)

Main outlet

outlet.n.groupid

Identifier of the group to which the outlet belongs to

1

outlet.n.switch

Outlet switch control (on/off)

on

outlet.n.status

Outlet switch status (on/off)

on

outlet.n.protect.status

Outlet protection status (0-2)

protected

outlet.n.alarm

Alarms for outlets and PDU, published in ups.alarm

outlet 1 low voltage warning

outlet.n.switchable

Outlet switch ability (yes/no)

yes

outlet.n.ecocontrol

Master Outlet used to automatically power off the slave outlets

The outlet is not ECO controlled

outlet.n.designator

Outlet designator

AC OUTPUT

outlet.n.autoswitch.charge.low

Remaining battery level to power off this outlet (percent)

80

outlet.n.battery.charge.low

Remaining battery level to power off this outlet (percent)

80

outlet.n.delay.shutdown

Interval to wait before shutting down this outlet (seconds)

180

outlet.n.delay.start

Interval to wait before restarting this outlet (seconds)

120

outlet.n.timer.shutdown

Time before the outlet load will be shutdown (seconds)

20

outlet.n.timer.start

Time before the outlet load will be started (seconds)

30

outlet.n.current

Current (A)

0.19

outlet.n.current.maximum

Maximum seen current (A)

0.56

outlet.n.current.status

Current status relative to the thresholds

good

outlet.n.current.low.warning

Low warning threshold (A)

0.10

outlet.n.current.low.critical

Low critical threshold (A)

0.05

outlet.n.current.high.warning

High warning threshold (A)

0.30

outlet.n.current.high.critical

High critical threshold (A)

0.40

outlet.n.realpower

Current value of real power (W)

28

outlet.n.voltage

Voltage (V)

247.0

outlet.n.voltage.status

Voltage status relative to the thresholds

good

outlet.n.voltage.low.warning

Low warning threshold (V)

205

outlet.n.voltage.low.critical

Low critical threshold (V)

200

outlet.n.voltage.high.warning

High warning threshold (V)

230

outlet.n.voltage.high.critical

High critical threshold (V)

240

outlet.n.powerfactor

Power Factor (dimensionless, value between 0 and 1)

0.85

outlet.n.crestfactor

Crest Factor (dimensionless, equal to or greater than 1)

1.41

outlet.n.power

Apparent power (VA)

46

outlet.n.type

Physical outlet type

french

outlet.group: groups of smart outlets

This is a refinement of the outlet collection, providing grouped management for a set of outlets. The same principles and data than the outlet collection apply to outlet.group, especially for the indexing n and "outlet.group.count".

Most of the data published for outlets also apply to outlet.group, including: id, name (similar as outlet "desc"), color, status, current and voltage (including status, alarm and thresholds). Other actions and settings also apply ({delay,timer}.{shutdown,start})

Some specific data to outlet groups exists:

Name Description Example value

outlet.group.n.type

Type of outlet group (OPAQUE)

outlet-section

outlet.group.n.color

Color-coding of the outlets in this group (OPAQUE)

yellow

outlet.group.n.count

Number of outlets in the group

12

outlet.group.n.phase

Electrical phase to which the physical outlet group (Gang) is connected to

L1

outlet.group.n.input

Input to which an outlet group is connected

1

Example:

outlet.group.1.current: 0.00
outlet.group.1.current.high.critical: 16.00
outlet.group.1.current.high.warning: 12.80
outlet.group.1.current.low.warning: 0.00
outlet.group.1.current.nominal: 16.00
outlet.group.1.current.status: good
outlet.group.1.id: 1
outlet.group.1.name: Branch Circuit A
outlet.group.1.phase: L1
outlet.group.1.status: on
outlet.group.1.voltage: 244.23
outlet.group.1.voltage.high.critical: 265.00
outlet.group.1.voltage.high.warning: 255.00
outlet.group.1.voltage.low.critical: 180.00
outlet.group.1.voltage.low.warning: 190.00
outlet.group.1.voltage.status: good
...
outlet.group.count: 3.00

driver: Internal driver information

Name Description Example value

driver.name

Driver name

usbhid-ups

driver.version

Driver version (NUT release)

X.Y.Z

driver.version.internal

Internal driver version

1.23.45

driver.version.data

Version of the internal data mapping, for generic drivers

Eaton HID 1.31

driver.version.usb

USB library version

libusb-1.0.21

driver.parameter.xxx

Parameter xxx (ups.conf or cmdline -x) setting

(varies)

driver.flag.xxx

Flag xxx (ups.conf or cmdline -x) status

enabled (or absent)

driver.state

Current state in driver’s lifecycle, primarily to help readers discern long-running init (with full device walk) or cleanup stages from the stable working loop

init.starting, init.quiet, init.device, init.info, init.updateinfo (first walk), reconnect.trying, reconnect.updateinfo, updateinfo, quiet, dumping, cleanup.upsdrv, cleanup.exit

server: Internal server information

Name Description Example value

server.info

Server information

Network UPS Tools upsd vX.Y.Z - https://www.networkupstools.org/

server.version

Server version

X.Y.Z