belkinunv(8)

1BELKINUNV(8)                      NUT Manual                      BELKINUNV(8)
2
3
4

NAME

6       belkinunv - Driver for Belkin "Universal UPS" and compatible
7

NOTE

9       This man page only documents the hardware-specific features of the
10       belkin driver. For information about the core driver, see nutupsdrv(8).
11
12       This driver only supports serial connections. If your UPS has a USB
13       port, please consult the Hardware Compatibility List (HCL) to see which
14       of the USB drivers you should use.
15

SUPPORTED HARDWARE

17       The belkinunv driver is known to work with the Belkin Universal UPS
18       models F6C800-UNV and F6C120-UNV, and is expected to work with other
19       Belkin Universal UPS models. The driver only supports serial
20       communication, not USB.
21
22       The Trust UPS and older Belkin units are not supported by this driver,
23       and neither are the Belkin Home Office models (F6H500-SER and so
24       forth). However, some Belkin models, such as the Regulator Pro, are
25       supported by the belkin(8) driver, and the Home Office models are
26       supported using the genericups(8) driver with upstype=7.
27

SOFT SHUTDOWN WORKAROUND

29       One problem with the Belkin Universal UPS is that it cannot enter a
30       soft shutdown (shut down the load until AC power returns) unless the
31       batteries are completely depleted. Thus, one cannot just shut off the
32       UPS after operating system shutdown; it will not come back on when the
33       power comes back on. Therefore, the belkinunv driver should never be
34       used with the -k option. Instead, the -x wait option is provided as a
35       workaround.
36
37       When called with the -x wait option, belkinunv behaves as a standalone
38       program (i.e., it does not fork into the background). It performs one
39       simple task: it connects to the UPS, waits for AC power to return, and
40       then exits with status 0.
41
42       This is meant to be used in a shutdown script as follows: during a
43       shutdown, after all filesystems have been remounted read-only, and just
44       before the system would normally be halted: check /etc/killpower (or
45       similar) to see if this shutdown was caused by upsmon(8), and if yes,
46       call belkinunv -x wait. If AC power comes back on, belkinunv exits, and
47       things should be arranged so that the system reboots in this case. If
48       AC power does not come back on, the UPS will eventually run out of
49       batteries, kill the computer’s power supply, and go into soft shutdown
50       mode, which means everything will reboot properly when the power
51       returns. In either case, a deadlock is avoided.
52
53       In addition, if an optional integer argument is given to the -x wait
54       option, this causes belkinunv to wait not only for AC power to be
55       present, but also for the battery charge to reach the given level. I
56       use this as part of my startup scripts, to ensure that the batteries
57       are sufficiently charged before the computer continues booting. This
58       should be put very early in the startup script, before any filesystems
59       are mounted read/write, and before any filesystem checks are performed.
60
61       Several other -x options are provided to fine-tune this behavior. See
62       the options below for detailed descriptions. See the examples below for
63       examples of how to use belkinunv in shutdown and startup scripts.
64

OPTIONS

66       See also nutupsdrv(8) for generic options. Never use the -k option with
67       this driver; it does not work properly.
68
69       -x wait[=level]
70           When this option is used, belkinunv does not fork into the
71           background, but behaves as a standalone program. It connects to the
72           UPS and waits until AC power is present. If level is specified, it
73           also waits until the battery charge reaches at least the given
74           level in percent. Then, and only then, belkinunv exits. In
75           addition, while belkinunv runs in this mode, it displays a status
76           line with information on the UPS status and battery level. This is
77           intended for use in the computer’s shutdown and startup scripts, as
78           described under Soft Shutdown Workaround above.
79
80       -x nohang
81           This option only has an effect when used in conjunction with the -x
82           wait option. It causes belkinunv to exit if a connection with the
83           UPS cannot be established or is lost, instead of retrying forever,
84           which is the default behavior. The -x nohang option should be used
85           in a startup script, to ensure the computer remains bootable even
86           if the UPS has been disconnected during the power failure (for
87           instance, you attached your computer to a generator, carried it to
88           a neighbor’s house, or whatever).
89
90       -x flash
91           This option only has an effect when used in conjunction with the -x
92           wait option. It causes the UPS load to be shut off for a short time
93           ("flashed") just after the AC power has returned and the requested
94           battery level (if any) has been attained. This is useful if slaves
95           are attached to this UPS; the flash will cause all of them to
96           reboot. Note that, due to the design of the Belkin UPS hardware,
97           the load shutdown lasts ca. 1—2 minutes; a shorter flash cannot be
98           performed reliably. Also, the computers will reboot at the
99           scheduled time, on battery power if necessary, even if AC power
100           fails again in the meantime. This should not be a problem, as your
101           startup scripts can catch this situation.
102
103       -x silent
104           This option only has an effect when used in conjunction with the -x
105           wait option. It suppresses the status line which belkinunv would
106           normally print.
107
108       -x dumbterm
109           This option only has an effect when used in conjunction with the -x
110           wait option. It changes the way in which belkinunv prints its
111           status line. Normally, terminal control sequences are used to
112           overwrite the same line with new status information, each time the
113           status is updated. This may not work on all terminals. If the -x
114           dumbterm option is given, each status update is written on a new
115           line.
116

VARIABLES

118       battery.charge, battery.runtime
119           not supported by all hardware.
120
121       battery.voltage, battery.voltage.nominal, input.frequency,
122       input.frequency.nominal
123           e.g. 60 for 60Hz
124
125       input.sensitivity
126           writable: normal/medium/low
127
128       input.transfer.high
129           writable: high transfer voltage point in V
130
131       input.transfer.low
132           writable: low transfer voltage point in V
133
134       input.voltage, input.voltage.maximum, input.voltage.minimum,
135       input.voltage.nominal, output.frequency, output.voltage,
136       ups.beeper.status
137           writable. Values: enabled/disabled/muted. This variable controls
138           the state of the panel beeper. Enabled means sound when the alarm
139           is present, disabled means never sound, and muted means the sound
140           is temporarily disabled until the alarm would normally stop
141           sounding. In the muted state, the beeper is automatically turned
142           back on at the next event (AC failure, battery test, etc). Also,
143           the beeper can’t be turned off during a critical event (low
144           battery). Note that not all UPS models support the "disabled"
145           state.
146
147       ups.firmware, ups.load, ups.model, ups.power.nominal
148           e.g. 800 for an 800VA system
149
150       ups.status
151           a list of flags; see the status flags below.
152
153       ups.temperature
154           not supported by all hardware.
155
156       ups.test.result, ups.delay.restart
157           time to restart (read only)
158
159       ups.delay.shutdown
160           time to shutdown (read only). This is always a multiple of 60
161           seconds.
162
163       ups.type
164           ONLINE/OFFLINE/LINEINT. This describes the basic layout of this UPS
165           (for GUI clients which want to draw an animated picture of power
166           flow). An offline UPS has a direct connection from AC input to AC
167           output, and also a connection from AC input to the battery, and
168           from the battery to AC output. An online UPS lacks the direct
169           connection from AC input to AC output, whereas a line interactive
170           UPS lacks the connection from AC input to the battery.
171

COMMANDS

173       beeper.enable, beeper.disable, beeper.mute
174           Enable, disable or mute the panel beeper. Note that if the beeper
175           is muted, it is automatically turned back on at the next event (AC
176           failure, battery test, etc). Also, the beeper can’t be turned muted
177           during a critical event (low battery).
178
179       reset.input.minmax
180           Reset the variables input.voltage.minimum and
181           input.voltage.maximum.
182
183       shutdown.reboot
184           Shut down load immediately for about 1—2 minutes.
185
186       shutdown.reboot.graceful
187           After 40 second delay, shut down load for about 1—2 minutes.
188
189       shutdown.stayoff
190           Shut down load immediately and stay off. The only way it can be
191           turned back on is by manually pressing the front panel button.
192
193       test.battery.start, test.battery.stop
194           Start/stop 10 second battery test.
195
196       test.failure.start, test.failure.stop
197           Start/stop "deep" battery test.
198

STATUS FLAGS

200       OB
201           load is on battery, including during tests
202
203       OFF
204           load is off
205
206       OL
207           load is online
208
209       ACFAIL
210           AC failure. Note that this refers to the AC input, and thus it is
211           not the same as "OB". An AC failure can occur at any time, for
212           instance, during a battery test, or when the UPS load is off.
213
214       OVER
215           overload
216
217       OVERHEAT
218           overheat
219
220       COMMFAULT
221           UPS fault
222
223       LB
224           low battery
225
226       CHRG
227           charging
228
229       DEPLETED
230           the battery is depleted. When the UPS raises this flag, it
231           simultaneously switches off the load.
232
233       RB
234           replace battery
235

EXAMPLES

237       Here is an example for how belkinunv should be used in a computer’s
238       shutdown script. These commands should go in the very last part of the
239       shutdown script, after all file systems have been mounted read-only,
240       and just before the computer halts. Note that belkinunv must be
241       installed in a directory which is still readable at that point.
242
243           # NEAR END OF SHUTDOWN SCRIPT:
244           # if shutdown was caused by UPS, perform Belkin UPS workaround.
245           if [ -f /etc/killpower ] ; then
246              echo "Waiting for AC power, or for UPS batteries to run out..."
247              /usr/bin/belkinunv -x wait /dev/ttyS1
248
249              # we get here if the power came back on. Reboot.
250              echo "Power is back. Rebooting..."
251              reboot
252           fi
253
254       And here is an example of how to use belkinunv in the startup script.
255       These commands should go near the beginning of the startup script,
256       before any file systems are mounted read/write, and before any file
257       system integrity checks are done.
258
259           # NEAR BEGINNING OF STARTUP SCRIPT:
260           # if we are recovering from a power failure, wait for the UPS to
261           # charge to a comfortable level before writing anything to disk
262           if [ -f /etc/killpower ] ; then
263              echo "Waiting for UPS battery charge to reach 60%..."
264              /usr/bin/belkinunv -x wait=60 -x nohang /dev/ttyS1
265           fi
266

EXIT STATUS

268       When used normally, belkinunv forks into the background and its
269       diagnostics are the same as for all NUT drivers, see nutupsdrv(8).
270
271       When used with the -x wait option, the exit status is normally 0. If
272       the -x nohang option has also been specified, an exit status of 1
273       indicates that communication with the UPS was lost. If the -x flash
274       option has been specified, an exit status of 2 indicates that the timed
275       shutdown has failed.
276

EXTRA ARGUMENTS

278       This driver does not support any extra settings in ups.conf(5).
279

AUTHOR

281       Peter Selinger <selinger@users.sourceforge.net>
282