Desc: New command and variable naming scheme
File: new-names.txt
Date: 18 February 2004
Auth: Russell Kroll <rkroll@exploits.org>

This is a dump of the planning page for variables and command names.
Don't use a name with any of the dstate functions unless it exists here.

If you need a new variable or command name, contact me first.

   Note: "opaque" means programs should not attempt to parse the value for
   that variable as it may vary greatly from one UPS to the next. These
   strings are best handled directly by the user.

                                   Variables

ups: General unit information

   +------------------------------------------------------------------------+
   |         Name         |         Description          |  Typical value   |
   |----------------------+------------------------------+------------------|
   | ups.status           | UPS status                   | OL               |
   |----------------------+------------------------------+------------------|
   | ups.alarm            | UPS alarms                   | OVERHEAT         |
   |----------------------+------------------------------+------------------|
   | ups.time             | Internal UPS clock time      | 12:34            |
   |                      | (opaque string)              |                  |
   |----------------------+------------------------------+------------------|
   | ups.date             | Internal UPS clock date      | 01-02-03         |
   |                      | (opaque string)              |                  |
   |----------------------+------------------------------+------------------|
   | ups.model            | UPS model                    | SMART-UPS 700    |
   |----------------------+------------------------------+------------------|
   | ups.mfr              | UPS manufacturer             | APC              |
   |----------------------+------------------------------+------------------|
   | ups.mfr.date         | UPS manufacturing date       | 10/17/96         |
   |                      | (opaque string)              |                  |
   |----------------------+------------------------------+------------------|
   | ups.serial           | UPS serial number (opaque    | WS9643050926     |
   |                      | string)                      |                  |
   |----------------------+------------------------------+------------------|
   | 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.id               | UPS system identifier        | Sierra           |
   |                      | (opaque string)              |                  |
   |----------------------+------------------------------+------------------|
   |                      | Interval to wait before      |                  |
   | ups.delay.start      | restarting the load          | 0                |
   |                      | (seconds)                    |                  |
   |----------------------+------------------------------+------------------|
   | ups.delay.reboot     | Interval to wait before      | 60               |
   |                      | rebooting the UPS (seconds)  |                  |
   |----------------------+------------------------------+------------------|
   |                      | Interval to wait after       |                  |
   | ups.delay.shutdown   | shutdown with delay command  | 20               |
   |                      | (seconds)                    |                  |
   |----------------------+------------------------------+------------------|
   | ups.test.interval    | Interval between self tests  | 1209600 (two     |
   |                      | (seconds)                    | weeks)           |
   |----------------------+------------------------------+------------------|
   | ups.test.result      | Results of last self test    | Bad battery pack |
   |                      | (opaque string)              |                  |
   |----------------------+------------------------------+------------------|
   | ups.display.language | Language to use on front     | E                |
   |                      | panel (*** opaque)           |                  |
   |----------------------+------------------------------+------------------|
   | ups.contacts         | UPS external contact sensors | F0               |
   |                      | (*** opaque)                 |                  |
   +------------------------------------------------------------------------+

input: Incoming line/power information

   +------------------------------------------------------------------------+
   |           Name            |        Description         | Typical value |
   |---------------------------+----------------------------+---------------|
   | input.voltage             | Input voltage              | 121.5         |
   |---------------------------+----------------------------+---------------|
   | input.voltage.maximum     | Maximum incoming voltage   | 130           |
   |                           | seen                       |               |
   |---------------------------+----------------------------+---------------|
   | input.voltage.minimum     | Minimum incoming voltage   | 100           |
   |                           | seen                       |               |
   |---------------------------+----------------------------+---------------|
   | input.voltage.nominal     | Nominal input voltage      | 120           |
   |---------------------------+----------------------------+---------------|
   | input.transfer.reason     | Reason for last transfer   | T             |
   |                           | to battery (*** opaque)    |               |
   |---------------------------+----------------------------+---------------|
   | input.transfer.low        | Low voltage transfer point | 103           |
   |---------------------------+----------------------------+---------------|
   | input.transfer.high       | High voltage transfer      | 132           |
   |                           | point                      |               |
   |---------------------------+----------------------------+---------------|
   | input.sensitivity         | Input power sensitivity    | H (high)      |
   |---------------------------+----------------------------+---------------|
   | input.quality             | Input power quality (***   | FF            |
   |                           | opaque)                    |               |
   |---------------------------+----------------------------+---------------|
   | input.frequency           | Input line frequency (Hz)  | 60.00         |
   |---------------------------+----------------------------+---------------|
   | input.transfer.boost.low  | Low voltage boosting       | 190           |
   |                           | transfer point             |               |
   |---------------------------+----------------------------+---------------|
   | input.transfer.boost.high | High voltage boosting      | 210           |
   |                           | transfer point             |               |
   |---------------------------+----------------------------+---------------|
   | input.transfer.trim.low   | Low voltage trimming       | 230           |
   |                           | transfer point             |               |
   |---------------------------+----------------------------+---------------|
   | input.transfer.trim.high  | High voltage trimming      | 240           |
   |                           | transfer point             |               |
   +------------------------------------------------------------------------+

output: Outgoing power/inverter information

   +------------------------------------------------------------------------+
   | output.voltage                | Output voltage                 | 120.9 |
   |-------------------------------+--------------------------------+-------|
   | output.frequency              | Output frequency (Hz)          | 60    |
   |-------------------------------+--------------------------------+-------|
   | output.voltage.target.line    | Target output voltage when on  | 120   |
   |                               | line                           |       |
   |-------------------------------+--------------------------------+-------|
   | output.voltage.target.battery | Target output voltage when on  | 120   |
   |                               | battery                        |       |
   |-------------------------------+--------------------------------+-------|
   | output.current                | Output current (amps)          | 4.25  |
   +------------------------------------------------------------------------+

battery: Any battery details

   +------------------------------------------------------------------------+
   | battery.charge          | Battery charge (percent)     | 100.0         |
   |-------------------------+------------------------------+---------------|
   | battery.charge.low      | Remaining battery level when | 20            |
   |                         | UPS switches to LB (percent) |               |
   |-------------------------+------------------------------+---------------|
   | battery.charge.restart  | Minimum battery level for    | 20            |
   |                         | UPS restart after power-off  |               |
   |-------------------------+------------------------------+---------------|
   | battery.voltage         | Battery charge (volts)       | 24.84         |
   |-------------------------+------------------------------+---------------|
   | battery.current         | Battery current (amps)       | 1.19          |
   |-------------------------+------------------------------+---------------|
   | battery.temperature     | Battery temperature (degrees | 050.7         |
   |                         | C)                           |               |
   |-------------------------+------------------------------+---------------|
   | battery.voltage.nominal | Nominal battery voltage      | 024           |
   |-------------------------+------------------------------+---------------|
   | battery.runtime         | Battery runtime (seconds)    | 1080          |
   |-------------------------+------------------------------+---------------|
   |                         | Remaining battery runtime    |               |
   | battery.runtime.low     | when UPS switches to LB      | 180           |
   |                         | (seconds)                    |               |
   |-------------------------+------------------------------+---------------|
   | battery.alarm.threshold | Battery alarm threshold      | 0 (immediate) |
   |-------------------------+------------------------------+---------------|
   | battery.date            | Battery change date (opaque  | 11/14/00      |
   |                         | string)                      |               |
   |-------------------------+------------------------------+---------------|
   | battery.packs           | Number of battery packs      | 001           |
   |-------------------------+------------------------------+---------------|
   | battery.packs.bad       | Number of bad battery packs  | 000           |
   +------------------------------------------------------------------------+

ambient: Conditions from external probe equipment

   +------------------------------------------------------------------------+
   | ambient.temperature               | Ambient temperature        | 25.40 |
   |                                   | (degrees C)                |       |
   |-----------------------------------+----------------------------+-------|
   | ambient.temperature.alarm         | Set if ambient temperature | 0     |
   |                                   | alarm is active            |       |
   |-----------------------------------+----------------------------+-------|
   | ambient.temperature.alarm.maximum | Maximum allowed            | NO,NO |
   |                                   | temperature (*** opaque)   |       |
   |-----------------------------------+----------------------------+-------|
   | ambient.temperature.alarm.minimum | Minimum allowed            | NO,NO |
   |                                   | temperature (*** opaque)   |       |
   |-----------------------------------+----------------------------+-------|
   | ambient.temperature.alarm.enable  | Enable alarm for ambient   | 1     |
   |                                   | temperature                |       |
   |-----------------------------------+----------------------------+-------|
   | ambient.humidity                  | Ambient relative humidity  | 038.8 |
   |                                   | (percent)                  |       |
   |-----------------------------------+----------------------------+-------|
   | ambient.humidity.alarm            | Set if ambient humidity    | 0     |
   |                                   | alarm is active            |       |
   |-----------------------------------+----------------------------+-------|
   | ambient.humidity.alarm.maximum    | Maximum allowed humidity   | NO,NO |
   |                                   | (*** opaque)               |       |
   |-----------------------------------+----------------------------+-------|
   | ambient.humidity.alarm.minimum    | Minimum allowed humidity   | NO,NO |
   |                                   | (*** opaque)               |       |
   |-----------------------------------+----------------------------+-------|
   | ambient.humidity.alarm.enable     | Enable alarm for ambient   | 1     |
   |                                   | humidity                   |       |
   +------------------------------------------------------------------------+

output: Smart outlet management (smart on/off switch, ...)

   +------------------------------------------------------------------------+
   |                                | Outlet system           |             |
   | outlet.n.id                    | identifier (opaque      | 1           |
   |                                | string)                 |             |
   |--------------------------------+-------------------------+-------------|
   | outlet.n.desc                  | Outlet description      | Main outlet |
   |                                | (opaque string)         |             |
   |--------------------------------+-------------------------+-------------|
   | outlet.n.switch                | Outlet switch control   | on          |
   |                                | (on/off)                |             |
   |--------------------------------+-------------------------+-------------|
   | outlet.n.status                | Outlet switch status    | on          |
   |                                | (on/off)                |             |
   |--------------------------------+-------------------------+-------------|
   | outlet.n.switchable            | Outlet switch ability   | yes         |
   |                                | (yes/no)                |             |
   |--------------------------------+-------------------------+-------------|
   |                                | Remaining battery level |             |
   | outlet.n.autoswitch.charge.low | to power off this       | 90          |
   |                                | outlet (percent)        |             |
   |--------------------------------+-------------------------+-------------|
   |                                | Interval to wait before |             |
   | outlet.n.delay.shutdown        | shutting down this      | 180         |
   |                                | outlet (seconds)        |             |
   |--------------------------------+-------------------------+-------------|
   |                                | Interval to wait before |             |
   | outlet.n.delay.start           | restarting this outlet  | 120         |
   |                                | (seconds)               |             |
   +------------------------------------------------------------------------+

driver: Internal driver information

   +------------------------------------------------------------------------+
   | driver.name             | Driver name                | apcsmart        |
   |-------------------------+----------------------------+-----------------|
   | driver.version          | Driver version (NUT        | X.Y.Z           |
   |                         | release)                   |                 |
   |-------------------------+----------------------------+-----------------|
   | driver.version.internal | Internal driver version    | 1.23.45         |
   |                         | (if tracked separately)    |                 |
   |-------------------------+----------------------------+-----------------|
   | driver.parameter.xxx    | Parameter xxx (ups.conf or | (varies)        |
   |                         | cmdline -x) setting        |                 |
   |-------------------------+----------------------------+-----------------|
   | driver.flag.xxx         | Flag xxx (ups.conf or      | enabled (or not |
   |                         | cmdline -x) status         | present)        |
   +------------------------------------------------------------------------+

server: Internal server information

   +------------------------------------------------------------------------+
   | server.info    | Server         | Network UPS Tools upsd vX.Y.Z -      |
   |                | information    | http://www.networkupstools.org/      |
   |----------------+----------------+--------------------------------------|
   | server.version | Server version | X.Y.Z                                |
   +------------------------------------------------------------------------+

                                Instant commands

   +------------------------------------------------------------------------+
   |           Name           |                 Description                 |
   |--------------------------+---------------------------------------------|
   | load.off                 | Turn off the load immediately               |
   |--------------------------+---------------------------------------------|
   | load.on                  | Turn on the load immediately                |
   |--------------------------+---------------------------------------------|
   | shutdown.return          | Turn off the load possibly after a delay    |
   |                          | and return when power is back               |
   |--------------------------+---------------------------------------------|
   | shutdown.stayoff         | Turn off the load possibly after a delay    |
   |                          | and remain off even if power returns        |
   |--------------------------+---------------------------------------------|
   | shutdown.stop            | Stop a shutdown in progress                 |
   |--------------------------+---------------------------------------------|
   | shutdown.reboot          | Shut down the load briefly while rebooting  |
   |                          | the UPS                                     |
   |--------------------------+---------------------------------------------|
   | shutdown.reboot.graceful | After a delay, shut down the load briefly   |
   |                          | while rebooting the UPS                     |
   |--------------------------+---------------------------------------------|
   | test.panel.start         | Start testing the UPS panel                 |
   |--------------------------+---------------------------------------------|
   | test.panel.stop          | Stop a UPS panel test                       |
   |--------------------------+---------------------------------------------|
   | test.failure.start       | Start a simulated power failure             |
   |--------------------------+---------------------------------------------|
   | test.failure.stop        | Stop simulating a power failure             |
   |--------------------------+---------------------------------------------|
   | test.battery.start       | Start a battery test                        |
   |--------------------------+---------------------------------------------|
   | test.battery.stop        | Stop the battery test                       |
   |--------------------------+---------------------------------------------|
   | calibrate.start          | Start runtime calibration                   |
   |--------------------------+---------------------------------------------|
   | calibrate.stop           | Stop runtime calibration                    |
   |--------------------------+---------------------------------------------|
   | bypass.start             | Put the UPS in bypass mode                  |
   |--------------------------+---------------------------------------------|
   | bypass.stop              | Take the UPS out of bypass mode             |
   |--------------------------+---------------------------------------------|
   | reset.input.minmax       | Reset minimum and maximum input voltage     |
   |                          | status                                      |
   |--------------------------+---------------------------------------------|
   | reset.watchdog           | Reset watchdog timer (forced reboot of      |
   |                          | load)                                       |
   |--------------------------+---------------------------------------------|
   | beeper.on                | Enable UPS beeper/buzzer                    |
   |--------------------------+---------------------------------------------|
   | beeper.off               | Disable UPS beeper/buzzer                   |
   +------------------------------------------------------------------------+
