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

SUPPORTED HARDWARE

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

SOFT SHUTDOWN WORKAROUND

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

OPTIONS

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

VARIABLES

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

COMMANDS

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

STATUS FLAGS

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

EXAMPLES

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

EXIT STATUS

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

EXTRA ARGUMENTS

274       This driver does not support any extra settings in ups.conf(5).
275

SEE ALSO

277   The core driver:
278       nutupsdrv(8)
279
280   Internet resources:
281       ·   The NUT (Network UPS Tools) home page:
282           http://www.networkupstools.org/
283
284       ·   The documentation for the protocol used by this UPS:
285           belkin-universal-ups.html
286

AUTHOR

288       Peter Selinger <selinger@users.sourceforge.net>
289
290
291
292Network UPS Tools                 09/15/2011                      BELKINUNV(8)
Impressum