nut-names.txt

ifndef::external_title[]
NUT variable names and instant commands
=======================================
endif::external_title[]

[NOTE]
.RFC 9271 Recording Document
====
This document is defined by RFC 9271 published by IETF at
https://www.rfc-editor.org/info/rfc9271 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
(not to be confused with <<_status_data,device status data>> described in
ifdef::website[]
another chapter).
endif::website[]
ifndef::website[]
the `docs/new-drivers.txt` in NUT source codebase).
endif::website[]

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.

Similarly, some source files (`drivers/*-mib.c` and `drivers/*-hid.c`)
may mention data point names following the pattern of `unmapped.x.y`.
These are generated by helper scripts which walk the reports from SNMP
and USB HID devices, respectively `scripts/subdriver/gen-snmp-subdriver.sh`
and `scripts/subdriver/gen-usbhid-subdriver.sh`, and assign names based on
strings in those reports. The `unmapped` entries should not be exposed in
"production" builds of the NUT drivers. They are an aid for developers to
know that such entries are served by their device, so an existing standard
NUT name can be assigned for the concept (or new name negotiated with the
community), but are normally hidden with `#if WITH_UNMAPPED_DATA_POINTS`
clauses which can be enabled in custom NUT builds by use of
`./configure --with-unmapped-data-points` option.

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.

Structured naming
-----------------

All standard NUT names of variables and commands are structured, with
a certain domain-specific prefix and purpose-specific suffix parts.
NUT tools provide and interpret them as dot-separated strings (although
third-party tools might restructure them by cutting and pasting at the
dot separation location, e.g. to represent as a JSON data tree or as
data model classes for specific programming languages).

If you would be making a parser of this information, please do also note
that in some *but not all* cases there is a defined data point for some
reading or command at the "root level" of what evolved to be a collection
of further structured related information (and there are no guarantees
for future evolution in this regard), for example:

* an `input.voltage` reports the momentary voltage level value and
  there is a `input.voltage.maximum` for a certain related detail;
* conversely, there are several items like `input.transfer.reason`
  but there is no actual `input.transfer` report.

There may be more layers than two (e.g. `input.voltage.low.warning`),
and in certain cases detailed below there may be a variable component
in the practical values (e.g. the `n` in `ambient.n.temperature.alarm`
variable or `outlet.n.load.off` command names).

Numeric format
--------------

Depending on the use-case, decimal numbers may be represented as integers
or as floating-point numbers with a dot character as the separator for the
fractional part (typically one or two digits long).  Leading zeroes may be
present. Leading (negative) sign characters are possible, although use-cases
for them are rare (if any).

Spaces or commas must not be used inside the numeric values.

Scientific notation (with mantissa/exponent) must not be used to represent
numeric values set into variables, to serve the values as exact as we have
them and keep the client-side parsing simple and predictable.

For example: "01200.2" and "1200.20" are valid, while "1,200.20" and "1200,20"
and "1 200.20" and "1.2e4" are invalid.

Programming note: floating-point numbers should be emitted using the `%f`
format specifier in the C `printf` family of methods and derived methods
(including NUT `dstate_setinfo()` in the driver code). Specifiers like `%e`
and `%g` which can emit the scientific notation should be avoided when setting
variable values (directly in code or when providing format string patterns in
mapping tables). They may however be used in debug traces, where reasonable.

Note that in some cases (e.g. USB vendor and product identifiers) technically
numeric values may be reported as hexadecimal and should be treated generally
as opaque strings (with the consumer ascribing a known meaning to certain
variable names).

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.

[NOTE]
======
Values of certain variables may be propagated from device reports formally
as opaque strings, which happen to convey a date/time value (commonly the
device or battery manufacture date, replacement date, last self-test or
calibration time stamp, device clock, etc.) in some format, not necessarily
a standard one.

While the drivers may convert them from original vendor-provided markup
to the standard Time and Date format described above (if the formula is
known for certain -- e.g. which locale is used by the device, which part
of that string is the year/month/day, or how to add offset or prefix for
the year, etc.), they are not generally required to do so.
======

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.

[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, 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 (firmware-reported) USB version     | 01.29
|====================================================================================

[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.
======

ups: General unit information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[options="header"]
|===============================================================================
| Name                  | Description                  | Example value
| ups.status            | UPS status (opaque string comprised
                          of space-separated tokens; many of
                          those are ascribed certain meanings)
                                                       | <<_status_data,OL>>
| ups.alarm             | UPS alarms (opaque string, may be
                          a collection of whole sentences;
                          separate entries may be enclosed
                          in brackets for convenience, but
                          this standard does not require it)
                                                       | OVERHEAT [EEPROM Error]
| 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.mode              | Current UPS mode (see the
                          note below)                  | line-interactive
| experimental.ups.mode.buzzwords
                        | UPS mode details, not
                          classified (opaque string,
                          presumably comprised of
                          space-separated tokens;
                          see the note below)          | vendor:eaton:ECO
| 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 present, the value of `ups.mode` specifies the currently enabled
mode of operation of the inverter and other components in the UPS.
Some devices are wired to only have one mode, others may support several
modes and usually have a way to select which one you want to be currently
active, either via protocol commands or by a physical switch.

There are many marketing keywords of different vendors and device generations
that sometimes correspond to same or very similar concepts, other times overlap
with wildly different meanings.

For example, some devices may be "online" (doing double-conversion and
feeding the load from battery even when wall power is available) when
charging or compensating for poor quality of input power, but become
"line-interactive" or even power off some of their electronics when the
input is deemed reliable.

The `ups.mode` can have one of the following standard values, possibly
changing over time or never changing (for devices with one known mode):

- `online`: battery is always charging on one side, and always feeds the
  inverter and so the load on the other (pros: instant protection from
  outages; cons: higher overheads of the UPS itself, possibly faster wear
  of the battery);
- `line-interactive`: battery is charged and then kept at rest, load is
  fed from input, but in case of outage or other troubles the inverter
  or other compensation mechanism (trim/buck) would be fired up (after
  a small but non-trivial delay);
- `bypass`: inverter and battery are bypassed (e.g. for maintenance),
  so input directly feeds the output, until it suddenly does not.

The `experimental.ups.mode.buzzwords` can have one or more values, separated
by spaces, to provide information we know from the device but have not yet
agreed how to reflect it in a well-structured fashion (hence `experimental`
namespace is used):

- `vendor:VENDORNAME:MODENAME`: we know that the "vendor's marketing
  buzzword" mode is activated.  Users may read vendor documentation for
  their device model, and know better than the driver what this actually
  means for them.  It is recommended to keep vendor names lower-cased
  and mode names upper-cased, for more deterministic matching and sorting
  in NUT clients.
  * A number of `MODENAME` values/patterns may be interpreted by
    linkman:upsmon[8] to produce notifications about entering or
    exiting the "ECO" mode state.

Other values may be introduced later.

See also `output.inverter.latency`.
======

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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[options="header"]
|=================================================================================
| 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 (opaque string)       | 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
|=================================================================================

[NOTE]
.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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[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
| output.inverter.latency   | Delay of inverter activation
                              when switching to battery
                              (seconds, floating-point)      | 0.01
|===============================================================================

[NOTE]
======
One practical aspect that the users may be actually interested in is the
`output.inverter.latency`, representing the time gap when an outage begins,
after the mains power has disappeared and before the inverter begins to feed
the load from battery.  Typical values are 0 for double-conversion devices,
which always feed the load from battery, and 10msec (0.01 seconds in standard
units) for "line-interactive" devices which monitor input status and take time
to react to an outage or breach of thresholds.  While common computer power
sources include elements that allow them to slide over such a short outage,
other protected devices (laser printers, Hi-Fi audio) might not, and would
restart.

See also `ups.mode` and `experimental.ups.mode.buzzwords`.
======

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)

[options="header"]
|===============================================================================
| 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):

[options="header"]
|===============================================================================
| 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[options="header"]
|===============================================================================
| 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.

[options="header"]
|==================================================================================
| 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.

[options="header"]
|===============================================================================
| 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
                                   (opaque string)             | 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:

[options="header"]
|=================================================================================
| 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[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      | 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[options="header"]
|===============================================================================
| 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
|===============================================================================

Instant commands
----------------

[options="header"]
|========================================================================
| Name                     | Description
| load.off                 | Turn off the load immediately
| load.on                  | Turn on the load immediately
| load.off.delay           | Turn off the load possibly after a delay
| load.on.delay            | Turn on the load possibly after a delay
| shutdown.default         | Run default driver-defined (device-specific)
                             routine, primarily intended for emergency
                             poweroff performed as part of FSD handling;
                             often an alias to other `shutdown.*` and/or
                             `load.off` operations or a chain to try
                             several of those. See also `sdcommands` in
                             common driver options.
| 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
| test.system.start        | Start a system 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
| outlet.n.shutdown.return | Turn off the outlet possibly after a delay
                             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
| outlet.n.shutdown.return | Turn off the outlet and return when power is back
|========================================================================

Experimental instant commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following commands were added to test feature support, but are not expected
to last as part of NUT standard protocol in the long run.

.Vendor-dependent "ECO" modes
[options="header"]
|========================================================================
| Name                              | Driver/Devices        | Description
| experimental.ecomode.enable       | usbhid-ups => mge-hid (Eaton/MGE)
    | Put UPS in High Efficiency (aka ECO) mode
| experimental.ecomode.disable      | usbhid-ups => mge-hid (Eaton/MGE)
    | Take the UPS out of High Efficiency (aka ECO) mode
| experimental.essmode.enable       | usbhid-ups => mge-hid (Eaton/MGE)
    | Put UPS in Energy Saver System (aka ESS) mode
| experimental.essmode.disable      | usbhid-ups => mge-hid (Eaton/MGE)
    | Take the UPS out of Energy Saver System (aka ESS) mode
|========================================================================

.Vendor-dependent instant commands
[options="header"]
|========================================================================
| Name                              | Driver/Devices        | Description
| experimental.test.beeper.start    | nutdrv_hashx => Atlantis Land
    | Start testing the UPS beeper
| experimental.test.beeper.stop     | nutdrv_hashx => Atlantis Land
    | Stop a UPS beeper test
|========================================================================

Currently the commands above are present in one subdriver and are specific
to the vendor's proposed power state machine. The plan is to generalize the
concept with vendor specifics, similarly to `experimental.ups.mode.buzzwords`.