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).

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.

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

[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                   | <<_status_data,OL>>
| ups.alarm             | UPS alarms                   | OVERHEAT
| ups.time              | Internal UPS clock time
                          (opaque string)              | 12:34
| ups.date              | Internal UPS clock date
                          (opaque string)              | 01-02-03
| ups.model             | UPS model                    | SMART-UPS 700
| ups.mfr               | UPS manufacturer             | APC
| ups.mfr.date          | UPS manufacturing date
                          (opaque string)              | 10/17/96
| ups.serial            | UPS serial number (opaque
                          string)                      | WS9643050926
| ups.vendorid          | Vendor ID for USB devices    | 0463
| ups.productid         | Product ID for USB devices   | 0001
| ups.firmware          | UPS firmware (opaque string) | 50.9.D
| ups.firmware.aux      | Auxiliary device firmware    | 4Kx
| ups.temperature       | UPS temperature (degrees C)  | 042.7
| ups.load              | Load on UPS (percent)        | 023.4
| ups.load.high         | Load when UPS
                          switches to overload
                          condition ("OVER") (percent) | 100
| ups.id                | UPS system identifier
                          (opaque string)              | Sierra
| ups.delay.start       | Interval to wait before
                          restarting the load
                          (seconds)                    | 0
| ups.delay.reboot      | Interval to wait before
                          rebooting the UPS (seconds)  | 60
| ups.delay.shutdown    | Interval to wait after
                          shutdown with delay command
                          (seconds)                    | 20
| ups.timer.start       | Time before the load will be
                          started (seconds)            | 30
| ups.timer.reboot      | Time before the load will be
                          rebooted (seconds)           | 10
| ups.timer.shutdown    | Time before the load will be
                          shutdown (seconds)           | 20
| ups.test.interval     | Interval between self tests
                          (seconds)                    | 1209600 (two weeks)
| ups.test.result       | Results of last self test
                          (opaque string)              | Bad battery pack
| ups.test.date         | Date of last self test
                          (opaque string)              | 07/17/12
| ups.display.language  | Language to use on front
                          panel (*** opaque)           | E
| ups.contacts          | UPS external contact sensors
                          (*** opaque)                 | F0
| ups.efficiency        | Efficiency of the UPS (ratio
                          of the output current on the
                          input current) (percent)     | 95
| ups.power             | Current value of apparent
                          power (Volt-Amps)            | 500
| ups.power.nominal     | Nominal value of apparent
                          power (Volt-Amps)            | 500
| ups.realpower         | Current value of real
                          power (Watts)                | 300
| ups.realpower.nominal | Nominal value of real
                          power (Watts)                | 300
| ups.beeper.status     | UPS beeper status
                          (enabled, disabled or muted) | enabled
| ups.type              | UPS type (*** opaque)        | offline
| ups.watchdog.status   | UPS watchdog status
                          (enabled or disabled)        | disabled
| ups.start.auto        | UPS starts when mains is
                          (re)applied                  | yes
| ups.start.battery     | Allow to start UPS from
                          battery                      | yes
| ups.start.reboot      | UPS coldstarts from battery
                          (enabled or disabled)        | yes
| ups.shutdown          | Enable or disable UPS
                          shutdown ability (poweroff)  | enabled
|===============================================================================

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

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

input: Incoming line/power information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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

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.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: 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.

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


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.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.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"), 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
| 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
|=================================================================================

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