1BELKINUNV(8) Network UPS Tools (NUT) BELKINUNV(8)
2
6 belkinunv - Driver for Belkin "Universal UPS" and compatible
7
9 This man page only documents the hardware‐specific features of the
10 belkin driver. For information about the core driver, see nutups‐
11 drv(8).
12
15 The belkinunv driver is known to work with the Belkin Universal UPS
16 models F6C800‐UNV and F6C120‐UNV, and is expected to work with other
17 Belkin Universal UPS models. The driver only supports serial communica‐
18 tion, not USB.
19 The Trust UPS and older Belkin units are not supported by this driver,
21 and neither are the Belkin Home Office models (F6H500‐SER and so
22 forth). However, some Belkin models, such as the Regulator Pro, are
23 supported by the belkin(8) driver, and the Home Office models are sup‐
24 ported using the genericups(8) driver with upstype=7.
25
28 One problem with the Belkin Universal UPS is that it cannot enter a
29 soft shutdown (shut down the load until AC power returns) unless the
30 batteries are completely depleted. Thus, one cannot just shut off the
31 UPS after operating system shutdown; it will not come back on when the
32 power comes back on. Therefore, the belkinunv driver should never be
33 used with the -k option. Instead, the -x wait option is provided as a
34 workaround.
35 When called with the -x wait option, belkinunv behaves as a standalone
37 program (i.e., it does not fork into the background). It performs one
38 simple task: it connects to the UPS, waits for AC power to return, and
39 then exits with status 0.
40 This is meant to be used in a shutdown script as follows: during a
42 shutdown, after all filesystems have been remounted read‐only, and just
43 before the system would normally be halted: check /etc/killpower (or
44 similar) to see if this shutdown was caused by upsmon(8), and if yes,
45 call belkinunv -x wait. If AC power comes back on, belkinunv exits, and
46 things should be arranged so that the system reboots in this case. If
47 AC power does not come back on, the UPS will eventually run out of bat‐
48 teries, kill the computer's power supply, and go into soft shutdown
49 mode, which means everything will reboot properly when the power
50 returns. In either case, a deadlock is avoided.
51 In addition, if an optional integer argument is given to the -x wait
53 option, this causes belkinunv to wait not only for AC power to be
54 present, but also for the battery charge to reach the given level. I
55 use this as part of my startup scripts, to ensure that the batteries
56 are sufficiently charged before the computer continues booting. This
57 should be put very early in the startup script, before any filesystems
58 are mounted read/write, and before any filesystem checks are performed.
59 Several other -x options are provided to fine‐tune this behavior. See
61 OPTIONS below for detailed descriptions. See EXAMPLES below for exam‐
62 ples of how to use belkinunv in shutdown and startup scripts.
63
66 See also nutupsdrv(8) for generic options. Never use the -k option with
67 this driver; it does not work properly.
68 -x wait[=level]
70 When this option is used, belkinunv does not fork into the
71 background, but behaves as a standalone program. It con‐
72 nects to the UPS and waits until AC power is present. If
73 level is specified, it also waits until the battery charge
74 reaches at least the given level in percent. Then, and only
75 then, belkinunv exits. In addition, while belkinunv runs in
76 this mode, it displays a status line with information on
77 the UPS status and battery level. This is intended for use
78 in the computer's shutdown and startup scripts, as
79 described under SOFT SHUTDOWN WORKAROUND above.
80 -x nohang This option only has an effect when used in conjunction
82 with the -x wait option. It causes belkinunv to exit if a
83 connection with the UPS cannot be established or is lost,
84 instead of retrying forever, which is the default behavior.
85 The -x nohang option should be used in a startup script, to
86 ensure the computer remains bootable even if the UPS has
87 been disconnected during the power failure (for instance,
88 you attached your computer to a generator, carried it to a
89 neighbor's house, or whatever).
90 -x flash This option only has an effect when used in conjunction
92 with the -x wait option. It causes the UPS load to be shut
93 off for a short time ("flashed") just after the AC power
94 has returned and the requested battery level (if any) has
95 been attained. This is useful if slaves are attached to
96 this UPS; the flash will cause all of them to reboot. Note
97 that, due to the design of the Belkin UPS hardware, the
98 load shutdown lasts ca. 1‐2 minutes; a shorter flash cannot
99 be performed reliably. Also, the computers will reboot at
100 the scheduled time, on battery power if necessary, even if
101 AC power fails again in the meantime. This should not be a
102 problem, as your startup scripts can catch this situation.
103 -x silent This option only has an effect when used in conjunction
105 with the -x wait option. It suppresses the status line
106 which belkinunv would normally print.
107 -x dumbterm This option only has an effect when used in conjunction
109 with the -x wait option. It changes the way in which belki‐
110 nunv prints its status line. Normally, terminal control
111 sequences are used to overwrite the same line with new sta‐
112 tus information, each time the status is updated. This may
113 not work on all terminals. If the -x dumbterm option is
114 given, each status update is written on a new line.
115
118 battery.charge
119 battery.runtime
121 not supported by all hardware.
122 battery.voltage
124 battery.voltage.nominal
126 driver.version.internal
128 input.frequency
130 input.frequency.nominal
132 e.g. 60 for 60Hz
133 input.sensitivity
135 writable: normal/medium/low
136 input.transfer.high
138 writable: high transfer voltage point in V
139 input.transfer.low
141 writable: low transfer voltage point in V
142 input.voltage
144 input.voltage.maximum
146 input.voltage.minimum
148 input.voltage.nominal
150 output.frequency
152 output.voltage
154 ups.beeper.status
156 writable. Values: enabled/disabled/muted. This variable
157 controls the state of the panel beeper. Enabled means sound
158 when the alarm is present, disabled means never sound, and
159 muted means the sound is temporarily disabled until the
160 alarm would normally stop sounding. In the muted state, the
161 beeper is automatically turned back on at the next event
162 (AC failure, battery test, etc). Also, the beeper can't be
163 turned off during a critical event (low battery). Note that
164 not all UPS models support the "disabled" state.
165 ups.firmware
167 ups.load
169 ups.model
171 ups.power.nominal
173 e.g. 800 for an 800VA system
174 ups.status a list of flags; see STATUS FLAGS below.
176 ups.temperature
178 not supported by all hardware.
179 ups.test.result
181 ups.delay.restart
183 time to restart (read only)
184 ups.delay.shutdown
186 time to shutdown (read only). This is always a multiple of
187 60 seconds.
188 ups.type ONLINE/OFFLINE/LINEINT. This describes the basic layout of
190 this UPS (for GUI clients which want to draw an animated
191 picture of power flow). An offline UPS has a direct connec‐
192 tion from AC input to AC output, and also a connection from
193 AC input to the battery, and from the battery to AC output.
194 An online UPS lacks the direct connection from AC input to
195 AC output, whereas a line interactive UPS lacks the connec‐
196 tion from AC input to the battery.
197
200 beeper.on, beeper.off
201 turn the panel beeper on (enabled state) or off (muted
202 state). Note that if the beeper is muted, it is automati‐
203 cally turned back on at the next event (AC failure, battery
204 test, etc). Also, the beeper can't be turned off during a
205 critical event (low battery).
206 reset.input.minmax
208 reset the variables input.voltage.minimum and input.volt‐
209 age.maximum.
210 shutdown.reboot
212 shut down load immediately for ca. 1‐2 minutes
213 shutdown.reboot.graceful
215 after 40 second delay, shut down load for ca. 1‐2 minutes
216 shutdown.stayoff
218 shut down load immediately and stay off. The only way it
219 can be turned back on is by manually pressing the front
220 panel button.
221 test.battery.start, test.battery.stop
223 start/stop 10 second battery test
224 test.failure.start, test.failure.stop
226 start/stop "deep" battery test
227
230 OB load is on battery, including during tests
231 OFF load is off
233 OL load is online
235 ACFAIL AC failure. Note that this refers to the AC input, and thus
237 it is not the same as "OB". An AC failure can occur at any
238 time, for instance, during a battery test, or when the UPS
239 load is off.
240 OVER overload
242 OVERHEAT overheat
244 COMMFAULT UPS fault
246 LB low battery
248 CHRG charging
250 DEPLETED the battery is depleted. When the UPS raises this flag, it
252 simultaneously switches off the load.
253 RB replace battery
255
257 Here is an example for how belkinunv should be used in a computer's
258 shutdown script. These commands should go in the very last part of the
259 shutdown script, after all file systems have been mounted read‐only,
260 and just before the computer halts. Note that belkinunv must be
261 installed in a directory which is still readable at that point.
262 # NEAR END OF SHUTDOWN SCRIPT:
264 # if shutdown was caused by UPS, perform Belkin UPS workaround.
265 if [ -f /etc/killpower ] ; then
266 echo "Waiting for AC power, or for UPS batteries to run out..."
267 /usr/bin/belkinunv -x wait /dev/ttyS1
268 # we get here if the power came back on. Reboot.
270 echo "Power is back. Rebooting..."
271 reboot
272 fi
273 And here is an example of how to use belkinunv in the startup script.
275 These commands should go near the beginning of the startup script,
276 before any file systems are mounted read/write, and before any file
277 system integrity checks are done.
278 # NEAR BEGINNING OF STARTUP SCRIPT:
280 # if we are recovering from a power failure, wait for the UPS to
281 # charge to a comfortable level before writing anything to disk
282 if [ -f /etc/killpower ] ; then
283 echo "Waiting for UPS battery charge to reach 60%..."
284 /usr/bin/belkinunv -x wait=60 -x nohang /dev/ttyS1
285 fi
286
288 When used normally, belkinunv forks into the background and its diag‐
289 nostics are the same as for all NUT drivers, see nutupsdrv(8).
290 When used with the -x wait option, the exit status is normally 0. If
292 the -x nohang option has also been specified, an exit status of 1 indi‐
293 cates that communication with the UPS was lost. If the -x flash option
294 has been specified, an exit status of 2 indicates that the timed shut‐
295 down has failed.
296
298 This driver does not support any extra settings in ups.conf(5).
299
301 The documentation for the protocol used by this UPS:
302 belkin‐universal‐ups.html
303 The core driver:
306 nutupsdrv(8)
307 Internet resources:
310 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
311
314 Peter Selinger <selinger@users.sourceforge.net>
315 Sun Dec 7 2003 BELKINUNV(8)