nut/docs/nut-names.txt

749 lines
38 KiB
Text
Raw Normal View History

2011-01-26 09:35:08 +00:00
ifndef::external_title[]
2022-06-29 10:37:36 +00:00
NUT variable names and instant commands
=======================================
2011-01-26 09:35:08 +00:00
endif::external_title[]
2022-06-29 10:37:36 +00:00
[NOTE]
.RFC xxxx Recording Document
====
This document is defined by (pending) RFC xxxx and is referenced as the
document of record for the variable names and the instant commands used
in the protocol described by the RFC.
On behalf of the RFC, this document records the names of variables
describing the abstracted state of an UPS or similar power distribution
device, and the instant commands sent to the UPS using command `INSTCMD`,
as used in commands and messages between the Attachment Daemon (the `upsd`
in case of NUT implementation of the standard) and the clients.
====
This document defines the standard names of NUT commands and variables.
Developers should use the names recorded here, with dstate functions and
data mappings provided in NUT drivers for interactions with power devices.
If you need to express a state which cannot be described by any existing
name, please make a request to the NUT developers' mailing list for
definition and assignment of a new name. Clients using unrecorded names
risk breaking at a future update. If you wish to experiment with new
concepts before obtaining your requested variable name, you should use
a name of the form `experimental.x.y` for those states.
Put another way: if you make up a name that is not in this list and it
gets into the source code tree, and then the NUT community comes up with
a better name later, clients that already use the undocumented variable
will break when it is eventually changed. An explicitly "experimental"
data point is less surprising in this regard.
NOTE: In the descriptions, "opaque" means programs should not attempt to
parse the value for that variable as it may vary greatly from one UPS
(or similar device) to the next. These strings are best handled directly
by the user.
Time and Date format
--------------------
When possible, dates should be expressed in ISO 8601 and RFC 3339 compatible
Calendar format, that is to say "YYYY-MM-DD", or otherwise a Combined Date
and Time representation (`<date>T<time>`, so "YYYY-MM-DDThh:mm").
Separators for the date (hyphen) and time (colon) components are required
to conform to both ISO 8601 "extended" format and RFC 3339 required format.
In the case of Date and Time representation, a timezone can be added as per
RFC 3339 and the newer revisions of the ISO 8601 standard (which allow for
negative offsets):
* by appending the letter `Z` for UTC (e.g. "YYYY-MM-DDThh:mmZ"), or
* by appending the complete "hours:minutes" positive or negative time
offsets from UTC (e.g. "YYYY-MM-DDThh:mm+03:00").
For more details see examples at
link:https://en.wikipedia.org/wiki/ISO_8601[Wikipedia page on ISO 8601]
and the publicly available RFC at
link:http://tools.ietf.org/html/rfc3339[RFC 3339].
Other representations from those specifications are not necessarily supported.
2011-01-26 09:35:08 +00:00
Variables
---------
device: General unit information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2012-06-01 13:55:19 +00:00
NOTE: some of these data will be redundant with ups.* information
2011-01-26 09:35:08 +00:00
during a transition period. The ups.* data will then be removed.
[options="header"]
2012-06-01 13:55:19 +00:00
|====================================================================================
| Name | Description | Example value
| device.model | Device model | BladeUPS
| device.mfr | Device manufacturer | Eaton
| device.serial | Device serial number (opaque string) | WS9643050926
2016-07-18 00:11:41 +00:00
| device.type | Device type (ups, pdu, scd, psu, ats) | ups
2012-06-01 13:55:19 +00:00
| device.description | Device description (opaque string) | Some ups
| device.contact | Device administrator name (opaque string) | John Doe
2013-11-24 15:00:12 +00:00
| device.location | Device physical location (opaque string) | 1st floor
2012-06-01 13:55:19 +00:00
| device.part | Device part number (opaque string) | 123456789
2022-06-29 10:37:36 +00:00
| device.macaddr | Physical network address of the device | 68:b5:99:f5:89:27
2013-11-24 15:00:12 +00:00
| device.uptime | Device uptime in seconds | 1782
2022-06-29 10:37:36 +00:00
| device.count | Total number of daisychained devices | 1
|====================================================================================
[NOTE]
======
When present, `device.count` implies daisychain support. For more
information, refer to the <<daisychain,NUT daisychain support notes>> chapter
of the user manual and developer guide.
======
2011-01-26 09:35:08 +00:00
ups: General unit information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[options="header"]
|===============================================================================
| Name | Description | Example value
| ups.status | UPS status | linkdoc:developer-guide[OL,_status_data]
| 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
2022-06-29 10:37:36 +00:00
| ups.serial | UPS serial number (opaque
2011-01-26 09:35:08 +00:00
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
2012-08-12 21:39:31 +00:00
| ups.test.date | Date of last self test
(opaque string) | 07/17/12
2011-01-26 09:35:08 +00:00
| ups.display.language | Language to use on front
panel (*** opaque) | E
| ups.contacts | UPS external contact sensors
(*** opaque) | F0
2011-06-01 20:31:49 +00:00
| ups.efficiency | Efficiency of the UPS (ratio
of the output current on the
input current) (percent) | 95
2011-01-26 09:35:08 +00:00
| 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
2013-11-24 15:00:12 +00:00
| ups.shutdown | Enable or disable UPS
shutdown ability (poweroff) | enabled
2011-01-26 09:35:08 +00:00
|===============================================================================
2022-06-29 10:37:36 +00:00
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.
2011-01-26 09:35:08 +00:00
input: Incoming line/power information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[options="header"]
2016-07-18 00:11:41 +00:00
|=================================================================================
| 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.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.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.load | Load on (ePDU) input (percent
of full) | 25
| input.realpower | Current sum value of all (ePDU)
phases real power (W) | 300
2022-06-29 10:37:36 +00:00
| input.realpower.nominal | Nominal sum value of all (ePDU)
phases real power (W) | 850
2016-07-18 00:11:41 +00:00
| input.power | Current sum value of all (ePDU)
phases apparent power (VA) | 500
| input.source | The current input power source | 1
2022-06-29 10:37:36 +00:00
| input.source.preferred | The preferred power source | 1
| input.phase.shift | Voltage dephasing between input
sources (degrees) | 181
2016-07-18 00:11:41 +00:00
|=================================================================================
2011-01-26 09:35:08 +00:00
output: Outgoing power/inverter information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[options="header"]
|===============================================================================
| 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
^^^^^^^^^^^^^^^^^^^^^^^^^
2022-06-29 10:37:36 +00:00
`input.phases` (3 for three-phase, absent or 1 for 1phase)
`output.phases` (as for `input.phases`)
2011-01-26 09:35:08 +00:00
DOMAINs
^^^^^^^
2022-06-29 10:37:36 +00:00
2011-01-26 09:35:08 +00:00
Any input or output is considered a valid DOMAIN.
2022-06-29 10:37:36 +00:00
* input (should really be called input.mains, but keep this for compat)
** input.bypass
** input.servicebypass
2011-01-26 09:35:08 +00:00
2022-06-29 10:37:36 +00:00
* output (should really be called output.load, but keep this for compat)
** output.bypass
** output.inverter
** output.servicebypass
2011-01-26 09:35:08 +00:00
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
2022-06-29 10:37:36 +00:00
2011-01-26 09:35:08 +00:00
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.
2022-06-29 10:37:36 +00:00
2011-01-26 09:35:08 +00:00
Example: `input.L1.current`
Valid CONTEXTs
^^^^^^^^^^^^^^
2022-06-29 10:37:36 +00:00
L1-L2 \
L2-L3 \
L3-L1 for voltage measurements
L1-N /
L2-N /
L3-N /
2011-01-26 09:35:08 +00:00
2022-06-29 10:37:36 +00:00
L1 \
L2 for current and power measurements
L3 /
N - for current measurement
2011-01-26 09:35:08 +00:00
Valid SPECs
^^^^^^^^^^^
2015-04-30 13:53:36 +00:00
Valid with/without context (i.e. per phase or aggregated/averaged)
2011-01-26 09:35:08 +00:00
[options="header"]
|===============================================================================
| Name | Description
2016-07-18 00:11:41 +00:00
| alarm | Alarms for phases, published in ups.alarm
2011-01-26 09:35:08 +00:00
| current | Current (A)
| current.maximum | Maximum seen current (A)
| current.minimum | Minimum seen current (A)
2016-07-18 00:11:41 +00:00
| 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)
2012-06-01 13:55:19 +00:00
| current.peak | Peak current
2011-01-26 09:35:08 +00:00
| voltage | Voltage (V)
| voltage.nominal | Nominal voltage (V)
| voltage.maximum | Maximum seen voltage (V)
| voltage.minimum | Minimum seen voltage (V)
2022-06-29 10:37:36 +00:00
| voltage.status | Status relative to the thresholds
2016-07-18 00:11:41 +00:00
| 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)
2011-01-26 09:35:08 +00:00
| power | Apparent power (VA)
| power.maximum | Maximum seen apparent power (VA)
2012-08-12 21:39:31 +00:00
| power.minimum | Minimum seen apparent power (VA)
2011-01-26 09:35:08 +00:00
| power.percent | Percentage of apparent power related to maximum load
2012-08-12 21:39:31 +00:00
| power.maximum.percent | Maximum seen percentage of apparent power
| power.minimum.percent | Minimum seen percentage of apparent power
2011-01-26 09:35:08 +00:00
| 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)
2015-04-30 13:53:36 +00:00
| load | Load on (ePDU) input
2011-01-26 09:35:08 +00:00
|===============================================================================
2015-04-30 13:53:36 +00:00
Valid without context (i.e. aggregation of all phases):
2011-01-26 09:35:08 +00:00
[options="header"]
|===============================================================================
| Name | Description
| frequency | Frequency (Hz)
| frequency.nominal | Nominal frequency (Hz)
2015-04-30 13:53:36 +00:00
| realpower | Current value of real power (Watts)
| power | Current value of apparent power (Volt-Amps)
2011-01-26 09:35:08 +00:00
|===============================================================================
EXAMPLES
~~~~~~~~
2022-06-29 10:37:36 +00:00
Partial Three phase -- Three phase example:
2011-01-26 09:35:08 +00:00
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
2022-06-29 10:37:36 +00:00
Partial Three phase -- One phase example:
2011-01-26 09:35:08 +00:00
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[options="header"]
|===============================================================================
2015-04-30 13:53:36 +00:00
| Name | Description | Example value
| battery.charge | Battery charge (percent) | 100.0
2022-06-29 10:37:36 +00:00
| battery.charge.approx | Rough approximation of battery
charge (opaque, percent) | <85
2015-04-30 13:53:36 +00:00
| 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
2016-07-18 00:11:41 +00:00
| battery.charger.status | Status of the battery charger
(see the note below) | charging
2015-04-30 13:53:36 +00:00
| battery.voltage | Battery voltage (V) | 24.84
2022-06-29 10:37:36 +00:00
| 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
2015-04-30 13:53:36 +00:00
| 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
2022-06-29 10:37:36 +00:00
| battery.capacity.nominal | Nominal battery capacity (Ah) | 8.0
2015-04-30 13:53:36 +00:00
| battery.current | Battery current (A) | 1.19
| battery.current.total | Total battery current (A) | 1.19
2022-06-29 10:37:36 +00:00
| battery.status | Health status of the battery
(opaque string) | ok
2015-04-30 13:53:36 +00:00
| battery.temperature | Battery temperature (degrees C) | 050.7
2022-06-29 10:37:36 +00:00
| 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
2015-04-30 13:53:36 +00:00
| 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)
2022-06-29 10:37:36 +00:00
| 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
2015-04-30 13:53:36 +00:00
(opaque string) | 2005/04/02
2022-06-29 10:37:36 +00:00
| 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
2015-04-30 13:53:36 +00:00
| 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
2011-01-26 09:35:08 +00:00
|===============================================================================
2016-07-18 00:11:41 +00:00
NOTE:
2022-06-29 10:37:36 +00:00
`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:
2016-07-18 00:11:41 +00:00
2022-06-29 10:37:36 +00:00
- `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.
2016-07-18 00:11:41 +00:00
2022-06-29 10:37:36 +00:00
NOTE: When possible, time-stamps and dates should be expressed as detailed
above in the Time and Date format chapter.
2011-01-26 09:35:08 +00:00
ambient: Conditions from external probe equipment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2012-08-12 21:39:31 +00:00
NOTE: multiple sensors can be exposed using the indexed notation.
'ambient.*', without index or using '0', relates to the embedded sensor.
For example: 'ambient.temperature' represent the embedded sensor temperature.
Other sensors (external, communication card, ...) can use indexes
from '1' to 'n'. For example: 'ambient.1.temperature' for the first external
sensor temperature.
2011-01-26 09:35:08 +00:00
[options="header"]
2016-07-18 00:11:41 +00:00
|==================================================================================
| Name | Description | Example value
| 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
|==================================================================================
2011-01-26 09:35:08 +00:00
outlet: Smart outlet management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2022-06-29 10:37:36 +00:00
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.
2011-01-26 09:35:08 +00:00
[options="header"]
|===============================================================================
2016-07-18 00:11:41 +00:00
| Name | Description | Example value
| outlet.count | Total number of outlets | 12
2022-06-29 10:37:36 +00:00
| outlet.switchable | General outlet switch ability
of the unit (yes/no) | yes
2011-01-26 09:35:08 +00:00
| outlet.n.id | Outlet system identifier
2016-07-18 00:11:41 +00:00
(opaque string) | 1
2022-06-29 10:37:36 +00:00
| outlet.n.name | Outlet name (opaque string) | A1
| outlet.n.desc | Outlet description
2016-07-18 00:11:41 +00:00
(opaque string) | Main outlet
| outlet.n.groupid | Identifier of the group to
which the outlet belongs to | 1
2011-01-26 09:35:08 +00:00
| outlet.n.switch | Outlet switch control
2016-07-18 00:11:41 +00:00
(on/off) | on
2011-01-26 09:35:08 +00:00
| outlet.n.status | Outlet switch status
2016-07-18 00:11:41 +00:00
(on/off) | on
| outlet.n.alarm | Alarms for outlets and PDU,
published in ups.alarm | outlet 1 low
voltage warning
2011-01-26 09:35:08 +00:00
| outlet.n.switchable | Outlet switch ability
2016-07-18 00:11:41 +00:00
(yes/no) | yes
2011-01-26 09:35:08 +00:00
| outlet.n.autoswitch.charge.low | Remaining battery level to
power off this outlet
2016-07-18 00:11:41 +00:00
(percent) | 80
2012-06-01 13:55:19 +00:00
| outlet.n.battery.charge.low | Remaining battery level to
power off this outlet
2016-07-18 00:11:41 +00:00
(percent) | 80
2011-01-26 09:35:08 +00:00
| outlet.n.delay.shutdown | Interval to wait before
shutting down this outlet
2016-07-18 00:11:41 +00:00
(seconds) | 180
2011-01-26 09:35:08 +00:00
| outlet.n.delay.start | Interval to wait before
restarting this outlet
2012-06-01 13:55:19 +00:00
(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
2016-07-18 00:11:41 +00:00
| 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
2011-01-26 09:35:08 +00:00
| outlet.n.realpower | Current value of real
2016-07-18 00:11:41 +00:00
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
2022-06-29 10:37:36 +00:00
| outlet.n.type | Physical outlet type | french
2011-01-26 09:35:08 +00:00
|===============================================================================
2016-07-18 00:11:41 +00:00
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'
2022-06-29 10:37:36 +00:00
and "outlet.group.count".
2016-07-18 00:11:41 +00:00
Most of the data published for outlets also apply to outlet.group,
including: id, name (similar as outlet "desc"), status, current and
voltage (including status, alarm and thresholds).
Some specific data to outlet groups exists:
[options="header"]
|=================================================================================
| Name | Description | Example value
| outlet.group.n.type | Type of outlet group (OPAQUE) | outlet-section
2022-06-29 10:37:36 +00:00
| outlet.group.n.color | Color-coding of the outlets
in this group (OPAQUE) | yellow
2016-07-18 00:11:41 +00:00
| outlet.group.n.count | Number of outlets in the group | 12
2022-06-29 10:37:36 +00:00
| outlet.group.n.phase | Electrical phase to which the
physical outlet group (Gang) is
connected to | L1
2016-07-18 00:11:41 +00:00
|=================================================================================
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
2022-06-29 10:37:36 +00:00
outlet.group.1.phase: L1
2016-07-18 00:11:41 +00:00
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
2011-01-26 09:35:08 +00:00
driver: Internal driver information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[options="header"]
|===============================================================================
| Name | Description | Example value
| driver.name | Driver name | usbhid-ups
| driver.version | Driver version (NUT release) | X.Y.Z
2012-08-12 21:39:31 +00:00
| 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
2022-06-29 10:37:36 +00:00
| driver.version.usb | USB library version | libusb-1.0.21
2011-01-26 09:35:08 +00:00
| 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)
|===============================================================================
server: Internal server information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[options="header"]
|===============================================================================
| Name | Description | Example value
| server.info | Server information | Network UPS Tools upsd vX.Y.Z -
http://www.networkupstools.org/
| server.version | Server version | X.Y.Z
|===============================================================================
Instant commands
----------------
[options="header"]
|========================================================================
| Name | Description
| load.off | Turn off the load immediately
| load.on | Turn on the load immediately
2022-06-29 10:37:36 +00:00
| load.off.delay | Turn off the load possibly after a delay
| load.on.delay | Turn on the load possibly after a delay
| shutdown.return | Turn off the load possibly after a delay
2011-01-26 09:35:08 +00:00
and return when power is back
| shutdown.stayoff | Turn off the load possibly after a delay
and remain off even if power returns
| shutdown.stop | Stop a shutdown in progress
| shutdown.reboot | Shut down the load briefly while rebooting the UPS
| shutdown.reboot.graceful | After a delay, shut down the load briefly
while rebooting the UPS
| test.panel.start | Start testing the UPS panel
| test.panel.stop | Stop a UPS panel test
| test.failure.start | Start a simulated power failure
| test.failure.stop | Stop simulating a power failure
| test.battery.start | Start a battery test
| test.battery.start.quick | Start a "quick" battery test
| test.battery.start.deep | Start a "deep" battery test
| test.battery.stop | Stop the battery test
2013-11-24 15:00:12 +00:00
| test.system.start | Start a system test
2011-01-26 09:35:08 +00:00
| calibrate.start | Start runtime calibration
| calibrate.stop | Stop runtime calibration
| bypass.start | Put the UPS in bypass mode
| bypass.stop | Take the UPS out of bypass mode
| reset.input.minmax | Reset minimum and maximum input voltage status
| reset.watchdog | Reset watchdog timer (forced reboot of load)
| beeper.enable | Enable UPS beeper/buzzer
| beeper.disable | Disable UPS beeper/buzzer
| beeper.mute | Temporarily mute UPS beeper/buzzer
| beeper.toggle | Toggle UPS beeper/buzzer
2022-06-29 10:37:36 +00:00
| outlet.n.shutdown.return | Turn off the outlet possibly after a delay
2012-06-01 13:55:19 +00:00
and return when power is back
| outlet.n.load.off | Turn off the outlet immediately
| outlet.n.load.on | Turn on the outlet immediately
| outlet.n.load.cycle | Power cycle the outlet immediately
2015-04-30 13:53:36 +00:00
| outlet.n.shutdown.return | Turn off the outlet and return when power is back
2011-01-26 09:35:08 +00:00
|========================================================================