1HUAWEI_UPS2000(8) NUT Manual HUAWEI_UPS2000(8)
2
6 huawei-ups2000 - Driver for Huawei UPS2000 (1kVA-3kVA) UPS with USB or
7 RS-232 serial Modbus connection.
8
10 huawei-ups2000 -h
11 huawei-ups2000 -a DEVICE_NAME [OPTIONS]
13 Note
15 This man page only documents the hardware-specific features of the
16 huawei-ups2000 driver. For information about the core driver, see
17 nutupsdrv(8).
18
20 This driver supports Huawei UPS2000 series, online (double conversion)
21 UPS with the following characteristics.
22 1. Output power: 1 kVA to 3 kVA (higher power models are unsupported).
24 2. Connection: USB or RS-232 (USB is only supported on Linux 5.12 and
26 newer kernels, read the section Cabling carefully).
27 The UPS2000 series has two variants: UPS2000-A with a tower chassis,
29 and UPS2000-G with a rack-mount chassis. Both should be equally
30 supported, but more testers are needed.
31 Currently, it has been tested on the following models.
33 • UPS2000-A-1KTTS (firmware: V2R1C1SPC40, P1.0-D1.0)
35 • UPS2000-A-2KTTS (firmware: V2R1C1SPC50, P1.0-D1.0)
37 • UPS2000-G-3KRTS (firmware: V2R1C1SPC40, P1.0-D1.0)
39 If your model is not in the list, we encourage you to report successful
41 or unsuccessful results to the bug tracker or the mailing list. Make
42 sure to include the full model number of your UPS manually in your
43 report, because the firmware only reports "UPS2000-A" for all models,
44 including the G series.
45 huawei-ups2000 uses the libmodbus project, for Modbus implementation.
47
49 The UPS has a USB port and a RS-232 port. Both are supported, but USB
50 is only usable on Linux 5.12 and later, via the xr_serial kernel module
51 (see subsection USB for details). RS-232 is supported on all operating
52 systems.
53 Only one port can be used at a time. When USB is used, RS-232 should be
55 unplugged from the UPS, and vice versa. Further, optional adapter
56 cards, such as RS-485 or SNMP, are not supported. They should be
57 removed from the UPS.
58 Because the UPS port can be unresponsive under certain circumstances,
60 it’s recommended to power cycle your UPS after making a cabling change,
61 especially after changing the port type. That is, turn off the UPS
62 power output via the front panel, then unplug the UPS from line power
63 input. Wait for the LCD screen to go black. Finally reconnect line
64 power and restart your UPS.
65 USB
67 The USB port on the UPS2000 is powered by a MaxLinear/Exar RX21V1410
68 USB-to-serial converter chip, it’s only supported by Linux 5.12 or
69 newer, via the xr_serial kernel module.
70 When the UPS2000 is connected via USB to a supported Linux system, you
72 should see the following logs in dmesg.
73 xr_serial 1-1.2:1.1: xr_serial converter detected
75 usb 1-1.2: xr_serial converter now attached to ttyUSB0
76 The driver must be xr_serial. If your system doesn’t have the necessary
78 device driver, you will get this message instead:
79 cdc_acm 1-1.2:1.0: ttyACM0: USB ACM device
81 The generic driver cdc_acm is incompatible and cannot be used. You
83 should upgrade your Linux kernel to Linux 5.12 or newer.
84 Warning
86 On an unsupported system, the USB device can still be recognized as
87 a USB ACM device, but communication is impossible, please don’t
88 waste your time on cdc_acm.
89 If you’re already running on Linux 5.12 or newer kernels, but still
91 cannot see the xr_serial driver, it means the driver is not enabled in
92 your kernel build. If you’re a regular user, you should file a bug
93 report to your Linux distro maintainers and ask them to enable
94 xr_serial (kernel option CONFIG_USB_SERIAL_XR).
95 When upgrading the Linux kernel isn’t an option, or when you are using
97 another operating system (e.g. FreeBSD), RS-232 must be used.
98 RS-232
100 RS-232 is supported on all operating systems, either via a built-in
101 serial port on your computer, or by using an external USB-to-RS-232
102 converter. If you plan to use an USB-to-RS-232 converter, make sure
103 it’s supported by your operating system.
104
106 This driver is not built by default. You can build it by installing
107 libmodbus (with development packages) and running
108 configure --with-serial=yes --with-modbus=yes
110 You also need to give proper (R/W) permissions on the local serial
112 device file to allow the NUT driver run-time user to access it. This
113 may need additional setup for start-up scripting, udev or upower rules,
114 to apply the rights on every boot — especially if your device nodes are
115 tracked by a virtual filesystem.
116 For example, a USB-to-serial converter can be identified as
118 /dev/ttyACM0 or /dev/ttyUSB0 on Linux, or /dev/ttyU0 on FreeBSD (note
119 the capital "U"). A built-in serial port can be identified as
120 /dev/ttyS0 on Linux or one of /dev/cua* names on FreeBSD.
121
123 This driver supports the following optional settings in the ups.conf(5)
124 file:
125 offdelay=value
127 Time to wait before shutting down the UPS (seconds), acceptable
128 range is 6 seconds (0.1 minutes) to 5940 seconds (99 minutes).
129 Defaults to 60 seconds. Must be a multiple of 6 seconds. To ensure
130 your system has adequate time to shut down after a power failure,
131 it’s highly recommended to adjust offdelay.
132 rebootdelay=value
134 Time to wait before rebooting the UPS (seconds), acceptable range
135 is 6 seconds (0.1 minutes) to 5940 seconds (99 minutes). Defaults
136 to 60 seconds. Must be a multiple of 6 seconds. This is used by the
137 shutdown.reboot.graceful instant command. If you’ve adjusted
138 offdelay, you should also adjust rebootdelay.
139 ondelay=value
141 Time to wait before switching on the UPS (seconds), acceptable
142 range is 60 seconds (1 minutes) to 5940 seconds (99 minutes).
143 Defaults to 60 seconds. Must be a multiple of 60 seconds (not 6
144 seconds). You don’t need to adjust this delay unless you have
145 special requirements.
146 Note
148 Due to hardware limitation, in this driver, ondelay is respected
149 only when line power is available. If a power failure has occurred,
150 the UPS and the load is always immediately switched on, as soon (or
151 as late) as line power is restored.
152
154 This driver supports some instant commands (see upscmd(8)):
155 shutdown.stayoff
157 After an offdelay, turn off the load. When line power is back,
158 remain off.
159 shutdown.return
161 After an offdelay, turn off the load. When line power is back, turn
162 on the load, possibly after an ondelay.
163 Note
165 Normally, the load is turned on as soon as line power is back. But
166 if line power is never lost, or has came back unexpectedly in the
167 middle of an ongoing shutdown (an undesirable "power race"
168 condition that many entry-level products on the market fail to
169 recover from), the load is turned on after an ondelay. Thus,
170 UPS2000 is unaffected by a power race, the load is guaranteed to
171 always restart.
172 shutdown.reboot
174 Like shutdown.return, except that the load is turned off
175 immediately (6 seconds in this implementation).
176 shutdown.reboot.graceful
178 Like shutdown.return, except that the load is turned off after a
179 rebootdelay, not an offdelay.
180 beeper.enable
182 Enable the UPS beeper.
183 beeper.disable
185 Disable the UPS beeper.
186 beeper.toggle
188 Toggle the UPS beeper.
189 bypass.start
191 Put the UPS in bypass mode. Use with caution. It exposes your
192 equipment to unregulated line power and provides no protection from
193 power failures. Also, the UPS may shut down whenever the bypass
194 input voltage is out of the nominal range. As a warning, the UPS
195 beeps once every 10 seconds in bypass mode.
196 Note
198 The driver has a basic foolproof mechanism. If the bypass input is
199 already abnormal due to a power failure, the driver refuses to
200 enter bypass mode by aborting the command and logging an error.
201 However, it offers no protection after the UPS has entered (or in
202 the middle of entering) bypass mode. Thus, again, use with caution.
203 bypass.stop
205 Put the UPS out of bypass mode.
206 load.on
208 Turn on the load immediately.
209 load.off
211 Turn off the load immediately. Use with caution, everything on the
212 UPS will lost power.
213 test.battery.start.quick
215 Perform a short battery test.
216 test.battery.start.deep
218 Perform a long battery test.
219 test.battery.stop
221 Stop a running battery test.
222
224 This driver supports some writable runtime variables (see upsrw(8)):
225 ups.beeper.status
227 Enable or disable the UPS beeper, disabled or enabled.
228 Note
230 The beeper can only be disabled completely, it cannot be temporally
231 muted until the next alarm, but the option muted is also accepted
232 for convenience, muted is treated as an alias of disabled.
233 ups.delay.shutdown
235 Seconds to wait after shutdown with delay command. It’s the runtime
236 equivalent of offdelay. See description of offdelay.
237 ups.delay.reboot
239 Seconds to wait before rebooting the UPS, it’s the runtime
240 equivalent of rebootdelay. See description of rebootdelay.
241 ups.delay.start
243 Seconds to wait before restarting the load, it’s the runtime
244 equivalent of ondelay. See description of ondelay.
245
247 Battery status has a non-fatal read failure
248 It’s usually harmless and can be safely ignored. It’s only logged for
249 informative purposes (LOG_INFO), not as a warning or error.
250 Data stale
252 Under certain circumstances, some registers can return invalid values
253 and trigger a "data stale" error. Once a data stale error has occurred,
254 you should see error messages similar to the example below in the
255 system log.
256 huawei-ups2000: register 2002 has invalid value a000,
258 upsd: Data for UPS [huawei] is stale - check driver
259 upsd: UPS [huawei] data is no longer stale
260 So far all known problems have been fixed by the author, but an unknown
262 one cannot be ruled out. If you have encountered "data stale" problems
263 during normal uses, please file a bug report with full logs attached.
264 Before troubleshooting or reporting a problem, it’s important to check
266 your dmesg log for USB connect and disconnect events to avoid wasting
267 time on the NUT driver when the actual problem is USB. For example, if
268 someone yanks the cable out of the USB port, or if a new USB device is
269 plugged into a USB host/hub that is struggling to power its ports
270 (common on single-board computers like Raspberry Pi), or if you have
271 flaky cabling or EMI noise, the serial converter can get disconnected
272 from USB, at least briefly. This creates a permanent data stale, the
273 driver must be restarted (plugging the USB back won’t fix it, since the
274 driver is still using the nonexistent serial device). These USB
275 problems usually have nothing to do with NUT. If it’s the case, you
276 should solve the underlying USB problem - check the cable, check the
277 converter, try a powered USB hub, try a full-speed USB isolator, etc.
278 Serial port becomes unresponsive
280 Some malformed commands are known to lock up the serial port (including
281 USB, which is a USB-to-serial device). Upon receiving them, UPS2000
282 stops all serial communications. The result is a completely
283 unresponsive UPS, regardless of what you do - restarting NUT, rebooting
284 the computer - cannot restore connectivity, as if someone has unplugged
285 the RS-232 cable. To recover, simply power cycle the UPS: Turn off the
286 UPS output via the front panel, then unplug the UPS from line power.
287 Wait for the LCD front screen to go black. Finally reconnect line power
288 and restart your UPS.
289 That being said, a serial port lockup is unlikely to happen. To our
291 best knowledge, this driver never sends malformed commands to the UPS
292 (it was only a problem during early development). Furthermore, due to a
293 CRC checksum, they’re unlikely to be accidentally generated.
294 Still, we recommend to power cycle your UPS after making a cabling
296 change, especially after changing from RS-485/USB to RS-232, just to
297 ensure the UPS selects the correct communication interface. Also, if
298 you have discovered a reproducible serial port lockup problem, it can
299 be an previously unknown bug, make sure to file a bug report.
300 USB is unsupported
302 As previously stated, only RS-232 is supported on all systems. USB
303 requires a device-specific driver, which is only available on Linux
304 5.12 and newer kernels.
305 On an unsupported system, the USB device can still be recognized as a
307 USB ACM device, but in reality, communication is impossible. It can
308 only be fixed by implementing a driver for your system, nothing can be
309 done within NUT.
310 Finally, in the unlike scenario that you are using NUT on Microsoft
312 Windows, you should be able to install the USB device driver following
313 the steps in the Huawei UPS2000 (1 kVA-3 kVA) Modbus Protocol
314 Development Guide.
315
317 Yifeng Li <tomli@tomli.me>
318
320 The core driver:
321 nutupsdrv(8)
322 Internet resources:
324 • The NUT (Network UPS Tools) home page:
325 http://www.networkupstools.org/
326 • Huawei UPS2000-A (1 kVA-3 kVA) User Manual:
328 https://support.huawei.com/enterprise/en/doc/EDOC1000084260
329 • Huawei UPS2000 (1 kVA-3 kVA) Modbus Protocol Development Guide:
331 https://support.huawei.com/enterprise/en/doc/EDOC1000110696
332 • libmodbus home page: http://libmodbus.org
334Network UPS Tools 2.8.0 04/26/2022 HUAWEI_UPS2000(8)