forked from networkupstools/nut
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathnut-names.txt
877 lines (783 loc) · 44.9 KB
/
nut-names.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
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.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.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
|===============================================================================
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: *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.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"), 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.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
|========================================================================