lagertonne/nut
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Wiki Activity
nut/docs/nut-names.txt

472 lines
22 KiB
Text
Raw Normal View History

Imported Upstream version 2.6.0
2011-01-26 09:35:08 +00:00
ifndef::external_title[]
NUT command and variable naming scheme
======================================
endif::external_title[]
This is a dump of the standard variables and command names used in NUT.
Don't use a name with any of the dstate functions unless it exists here.
If you need a new variable or command name, contact the Development Team
first.
Put another way: if you make up a name that's not in this list and it
gets into the tree, and then we come up with a better name later, clients
that use the undocumented variable will break when it is changed.
NOTE: "opaque" means programs should not attempt to parse the value for
that variable as it may vary greatly from one UPS to the next. These
strings are best handled directly by the user.
Variables
---------
device: General unit information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
NOTE: these data will be redundant with some ups.* information
during a transition period. The ups.* data will then be removed.
[options="header"]
|========================================================================
| 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) | ups
|========================================================================
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
| 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.display.language | Language to use on front
panel (*** opaque) | E
| ups.contacts | UPS external contact sensors
(*** opaque) | F0
Imported Upstream version 2.6.1
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
Imported Upstream version 2.6.0
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
|===============================================================================
input: Incoming line/power information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[options="header"]
|===============================================================================
| Name | Description | Example value
| input.voltage | Input voltage | 121.5
| input.voltage.maximum | Maximum incoming voltage seen | 130
| input.voltage.minimum | Minimum incoming voltage seen | 100
| input.voltage.nominal | Nominal input voltage | 120
| input.voltage.extended | Extended input voltage range | no
| input.transfer.reason | Reason for last transfer
to battery (*** opaque) | T
| input.transfer.low | Low voltage transfer point | 91
| input.transfer.high | High voltage transfer point | 132
| input.transfer.low.min | smallest settable low
voltage transfer point | 85
| input.transfer.low.max | greatest settable low
voltage transfer point | 95
| input.transfer.high.min | smallest settable high
voltage transfer point | 131
| input.transfer.high.max | greatest settable high
voltage transfer point | 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.frequency | Input line frequency (Hz) | 60.00
| input.frequency.nominal | Nominal input line
frequency (Hz) | 60
| 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 | 190
| input.transfer.boost.high | High voltage boosting
transfer point | 210
| input.transfer.trim.low | Low voltage trimming
transfer point | 230
| input.transfer.trim.high | High voltage trimming
transfer point | 240
|===============================================================================
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
^^^^^^^^^^^^^^^^^^^^^^^^^
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 currrent and power measurements
L3 /
N - for current measurement
Valid SPECs
^^^^^^^^^^^
Valid with/without context (ie. per phase or aggregated/averaged)
[options="header"]
|===============================================================================
| Name | Description
| current | Current (A)
| current.maximum | Maximum seen current (A)
| current.minimum | Minimum seen current (A)
| peakcurrent | Peak current
| voltage | Voltage (V)
| voltage.nominal | Nominal voltage (V)
| voltage.maximum | Maximum seen voltage (V)
| voltage.minimum | Minimum seen voltage (V)
| power | Apparent power (VA)
| power.maximum | Maximum seen apparent power (VA)
| power.minimum | Maximum seen apparent power (VA)
| power.percent | Percentage of apparent power related to maximum load
| power.maximum.percent | Max seen percentage of apparent power
| power.minimum.percent | Min 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)
|===============================================================================
Valid without context (ie. aggregation of all phases):
[options="header"]
|===============================================================================
| Name | Description
| frequency | Frequency (Hz)
| frequency.nominal | Nominal frequency (Hz)
|===============================================================================
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[options="header"]
|===============================================================================
| Name | Description | Example value
| battery.charge | Battery charge (percent) | 100.0
| 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.voltage | Battery voltage (V) | 24.84
| battery.capacity | Battery capacity (Ah) | 7.2
| battery.current | Battery current (A) | 1.19
| battery.temperature | Battery temperature (degrees C) | 050.7
| battery.voltage.nominal | Nominal battery voltage (V) | 024
| battery.runtime | Battery runtime (seconds)
Remaining battery runtime | 1080
| battery.runtime.low | when UPS switches to LB
(seconds) | 180
| battery.alarm.threshold | Battery alarm threshold | 0 (immediate)
| battery.date | Battery change date (opaque
string) | 11/14/00
| battery.mfr.date | Battery manufacturing date
(opaque string) | 2005/04/02
| battery.packs | Number of battery packs | 001
| battery.packs.bad | Number of bad battery packs | 000
| battery.type | Battery chemistry (opaque
Imported Upstream version 2.6.2
2011-09-29 18:14:46 +00:00
string) | PbAc
Imported Upstream version 2.6.0
2011-01-26 09:35:08 +00:00
| battery.protection | Prevent deep discharge of
battery | yes
| battery.energysave | Switch off when running on
battery and no/low load | no
|===============================================================================
ambient: Conditions from external probe equipment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[options="header"]
|===============================================================================
| Name | Description | Example value
| ambient.temperature | Ambient temperature
(degrees C) | 25.40
| ambient.temperature.alarm | Temperature alarm
(enabled/disabled) | enabled
| ambient.temperature.high | Temperature threshold high
(degrees C) | 40
| ambient.temperature.low | Temperature threshold low
(degrees C) | 5
| ambient.temperature.maximum | Maximum temperature seen
(degrees C) | 37.6
| ambient.temperature.minimum | Minimum temperature seen
(degrees C) | 18.1
| ambient.humidity | Ambient relative humidity
(percent) | 038.8
| ambient.humidity.alarm | Relative humidity alarm
(enabled/disabled) | enabled
| ambient.humidity.high | Relative humidity
threshold high (percent) | 80
| ambient.humidity.low | Relative humidity
threshold high (percent) | 10
| ambient.humidity.maximum | Maximum relative humidity
seen (percent) | 60
| ambient.humidity.minimum | Minimum relative humidity
seen (percent) | 13
|===============================================================================
outlet: Smart outlet management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
NOTE: *n* stands for the outlet index. For more information, refer to the
NUT outlets management and PDU notes chapter of the user manual.
Imported Upstream version 2.6.1
2011-06-01 20:31:49 +00:00
A special case is "outlet.0" which is equivalent to "outlet", and
represent the whole set of outlets of the device.
Imported Upstream version 2.6.0
2011-01-26 09:35:08 +00:00
[options="header"]
|===============================================================================
| Name | Description | Example value
| outlet.n.id | Outlet system identifier
(opaque string) | 1
| outlet.n.desc | Outlet description
(opaque string) | Main outlet
| outlet.n.switch | Outlet switch control
(on/off) | on
| outlet.n.status | Outlet switch status
(on/off) | on
| outlet.n.switchable | Outlet switch ability
(yes/no) | yes
| outlet.n.autoswitch.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.current | Current (A) | 0.19
| outlet.n.current.maximum | Maximum seen current (A) | 0.56
| outlet.n.realpower | Current value of real
power (W) | 28
| outlet.n.voltage | Voltage (V) | 247.0
| 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
|===============================================================================
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
| driver.version.internal | Internal driver version
(if tracked separately) | 1.23.45
| 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
| shutdown.return | Turn off the load possibly after a delay
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
| 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
|========================================================================
Reference in a new issue Copy permalink