nut/docs/man/huawei-ups2000.8

'\" t
.\"     Title: huawei_ups2000
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/26/2022
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools 2.8.0
.\"  Language: English
.\"
.TH "HUAWEI_UPS2000" "8" "04/26/2022" "Network UPS Tools 2\&.8\&.0" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
huawei-ups2000 \- Driver for Huawei UPS2000 (1kVA\-3kVA) UPS with USB or RS\-232 serial Modbus connection\&.
.SH "SYNOPSIS"
.sp
\fBhuawei\-ups2000\fR \-h
.sp
\fBhuawei\-ups2000\fR \-a \fIDEVICE_NAME\fR [\fIOPTIONS\fR]
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
This man page only documents the hardware\-specific features of the huawei\-ups2000 driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.sp .5v
.RE
.SH "SUPPORTED HARDWARE"
.sp
This driver supports Huawei UPS2000 series, online (double conversion) UPS with the following characteristics\&.
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
Output power: 1 kVA to 3 kVA (higher power models are unsupported)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
Connection: USB or RS\-232 (USB is only supported on Linux 5\&.12 and newer kernels, read the section
\fBCabling\fR
carefully)\&.
.RE
.sp
The UPS2000 series has two variants: UPS2000\-A with a tower chassis, and UPS2000\-G with a rack\-mount chassis\&. Both should be equally supported, but more testers are needed\&.
.sp
Currently, it has been tested on the following models\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
UPS2000\-A\-1KTTS (firmware: V2R1C1SPC40, P1\&.0\-D1\&.0)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
UPS2000\-A\-2KTTS (firmware: V2R1C1SPC50, P1\&.0\-D1\&.0)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
UPS2000\-G\-3KRTS (firmware: V2R1C1SPC40, P1\&.0\-D1\&.0)
.RE
.sp
If your model is not in the list, we encourage you to report successful or unsuccessful results to the bug tracker or the mailing list\&. Make sure to include the full model number of your UPS manually in your report, because the firmware only reports "UPS2000\-A" for all models, including the G series\&.
.sp
huawei\-ups2000 uses the libmodbus project, for Modbus implementation\&.
.SH "CABLING"
.sp
The UPS has a USB port and a RS\-232 port\&. Both are supported, but USB is only usable on Linux 5\&.12 and later, via the \fBxr_serial\fR kernel module (see subsection \fBUSB\fR for details)\&. RS\-232 is supported on all operating systems\&.
.sp
Only one port can be used at a time\&. When USB is used, RS\-232 should be unplugged from the UPS, and vice versa\&. Further, optional adapter cards, such as RS\-485 or SNMP, are not supported\&. They should be removed from the UPS\&.
.sp
Because the UPS port can be unresponsive under certain circumstances, it\(cqs recommended to power cycle your UPS after making a cabling change, especially after changing the port type\&. That is, turn off the UPS power output via the front panel, then unplug the UPS from line power input\&. Wait for the LCD screen to go black\&. Finally reconnect line power and restart your UPS\&.
.SS "USB"
.sp
The USB port on the UPS2000 is powered by a MaxLinear/Exar RX21V1410 USB\-to\-serial converter chip, it\(cqs only supported by Linux 5\&.12 or newer, via the \fBxr_serial\fR kernel module\&.
.sp
When the UPS2000 is connected via USB to a supported Linux system, you should see the following logs in \fBdmesg\fR\&.
.sp
.if n \{\
.RS 4
.\}
.nf
xr_serial 1\-1\&.2:1\&.1: xr_serial converter detected
usb 1\-1\&.2: xr_serial converter now attached to ttyUSB0
.fi
.if n \{\
.RE
.\}
.sp
The driver must be \fBxr_serial\fR\&. If your system doesn\(cqt have the necessary device driver, you will get this message instead:
.sp
.if n \{\
.RS 4
.\}
.nf
cdc_acm 1\-1\&.2:1\&.0: ttyACM0: USB ACM device
.fi
.if n \{\
.RE
.\}
.sp
The generic driver \fBcdc_acm\fR is incompatible and cannot be used\&. You should upgrade your Linux kernel to Linux 5\&.12 or newer\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBWarning\fR
.ps -1
.br
.sp
On an unsupported system, the USB device can still be recognized as a USB ACM device, but communication is impossible, please don\(cqt waste your time on \fBcdc_acm\fR\&.
.sp .5v
.RE
.sp
If you\(cqre already running on Linux 5\&.12 or newer kernels, but still cannot see the \fBxr_serial\fR driver, it means the driver is not enabled in your kernel build\&. If you\(cqre a regular user, you should file a bug report to your Linux distro maintainers and ask them to enable \fBxr_serial\fR (kernel option CONFIG_USB_SERIAL_XR)\&.
.sp
When upgrading the Linux kernel isn\(cqt an option, or when you are using another operating system (e\&.g\&. FreeBSD), RS\-232 must be used\&.
.SS "RS\-232"
.sp
RS\-232 is supported on all operating systems, either via a built\-in serial port on your computer, or by using an external USB\-to\-RS\-232 converter\&. If you plan to use an USB\-to\-RS\-232 converter, make sure it\(cqs supported by your operating system\&.
.SH "INSTALLATION"
.sp
This driver is not built by default\&. You can build it by installing libmodbus (with development packages) and running
.sp
.if n \{\
.RS 4
.\}
.nf
configure \-\-with\-serial=yes \-\-with\-modbus=yes
.fi
.if n \{\
.RE
.\}
.sp
You also need to give proper (R/W) permissions on the local serial device file to allow the NUT driver run\-time user to access it\&. This may need additional setup for start\-up scripting, udev or upower rules, to apply the rights on every boot \(em especially if your device nodes are tracked by a virtual filesystem\&.
.sp
For example, a USB\-to\-serial converter can be identified as /dev/ttyACM0 or /dev/ttyUSB0 on Linux, or /dev/ttyU0 on FreeBSD (note the capital "U")\&. A built\-in serial port can be identified as /dev/ttyS0 on Linux or one of /dev/cua* names on FreeBSD\&.
.SH "EXTRA ARGUMENTS"
.sp
This driver supports the following optional settings in the \fBups.conf\fR(5) file:
.PP
\fBoffdelay=\fR\fIvalue\fR
.RS 4
Time to wait before shutting down the UPS (seconds), acceptable range is 6 seconds (0\&.1 minutes) to 5940 seconds (99 minutes)\&. Defaults to 60 seconds\&. Must be a multiple of 6 seconds\&. To ensure your system has adequate time to shut down after a power failure, it\(cqs highly recommended to adjust
\fBoffdelay\fR\&.
.RE
.PP
\fBrebootdelay=\fR\fIvalue\fR
.RS 4
Time to wait before rebooting the UPS (seconds), acceptable range is 6 seconds (0\&.1 minutes) to 5940 seconds (99 minutes)\&. Defaults to 60 seconds\&. Must be a multiple of 6 seconds\&. This is used by the
\fBshutdown\&.reboot\&.graceful\fR
instant command\&. If you\(cqve adjusted
\fBoffdelay\fR, you should also adjust
\fBrebootdelay\fR\&.
.RE
.PP
\fBondelay=\fR\fIvalue\fR
.RS 4
Time to wait before switching on the UPS (seconds), acceptable range is 60 seconds (1 minutes) to 5940 seconds (99 minutes)\&. Defaults to 60 seconds\&. Must be a multiple of 60 seconds (not 6 seconds)\&. You don\(cqt need to adjust this delay unless you have special requirements\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
Due to hardware limitation, in this driver, \fBondelay\fR is respected only when line power is available\&. If a power failure has occurred, the UPS and the load is always immediately switched on, as soon (or as late) as line power is restored\&.
.sp .5v
.RE
.SH "INSTANT COMMANDS"
.sp
This driver supports some instant commands (see \fBupscmd\fR(8)):
.PP
\fBshutdown\&.stayoff\fR
.RS 4
After an
\fBoffdelay\fR, turn off the load\&. When line power is back, remain off\&.
.RE
.PP
\fBshutdown\&.return\fR
.RS 4
After an
\fBoffdelay\fR, turn off the load\&. When line power is back, turn on the load, possibly after an
\fBondelay\fR\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
Normally, the load is turned on as soon as line power is back\&. But if line power is never lost, or has came back unexpectedly in the middle of an ongoing shutdown (an undesirable "power race" condition that many entry\-level products on the market fail to recover from), the load is turned on after an \fBondelay\fR\&. Thus, UPS2000 is unaffected by a power race, the load is guaranteed to always restart\&.
.sp .5v
.RE
.PP
\fBshutdown\&.reboot\fR
.RS 4
Like
\fBshutdown\&.return\fR, except that the load is turned off immediately (6 seconds in this implementation)\&.
.RE
.PP
\fBshutdown\&.reboot\&.graceful\fR
.RS 4
Like
\fBshutdown\&.return\fR, except that the load is turned off after a
\fBrebootdelay\fR, not an
\fBoffdelay\fR\&.
.RE
.PP
\fBbeeper\&.enable\fR
.RS 4
Enable the UPS beeper\&.
.RE
.PP
\fBbeeper\&.disable\fR
.RS 4
Disable the UPS beeper\&.
.RE
.PP
\fBbeeper\&.toggle\fR
.RS 4
Toggle the UPS beeper\&.
.RE
.PP
\fBbypass\&.start\fR
.RS 4
Put the UPS in bypass mode\&. Use with caution\&. It exposes your equipment to unregulated line power and provides no protection from power failures\&. Also, the UPS may shut down whenever the bypass input voltage is out of the nominal range\&. As a warning, the UPS beeps once every 10 seconds in bypass mode\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
The driver has a basic foolproof mechanism\&. If the bypass input is already abnormal due to a power failure, the driver refuses to enter bypass mode by aborting the command and logging an error\&. However, it offers no protection after the UPS has entered (or in the middle of entering) bypass mode\&. Thus, again, use with caution\&.
.sp .5v
.RE
.PP
\fBbypass\&.stop\fR
.RS 4
Put the UPS out of bypass mode\&.
.RE
.PP
\fBload\&.on\fR
.RS 4
Turn on the load immediately\&.
.RE
.PP
\fBload\&.off\fR
.RS 4
Turn off the load immediately\&. Use with caution, everything on the UPS will lost power\&.
.RE
.PP
\fBtest\&.battery\&.start\&.quick\fR
.RS 4
Perform a short battery test\&.
.RE
.PP
\fBtest\&.battery\&.start\&.deep\fR
.RS 4
Perform a long battery test\&.
.RE
.PP
\fBtest\&.battery\&.stop\fR
.RS 4
Stop a running battery test\&.
.RE
.SH "VARIABLES"
.sp
This driver supports some writable runtime variables (see \fBupsrw\fR(8)):
.PP
\fBups\&.beeper\&.status\fR
.RS 4
Enable or disable the UPS beeper,
\fBdisabled\fR
or
\fBenabled\fR\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
The beeper can only be disabled completely, it cannot be temporally muted until the next alarm, but the option \fBmuted\fR is also accepted for convenience, \fBmuted\fR is treated as an alias of \fBdisabled\fR\&.
.sp .5v
.RE
.PP
\fBups\&.delay\&.shutdown\fR
.RS 4
Seconds to wait after shutdown with delay command\&. It\(cqs the runtime equivalent of
\fBoffdelay\fR\&. See description of
\fBoffdelay\fR\&.
.RE
.PP
\fBups\&.delay\&.reboot\fR
.RS 4
Seconds to wait before rebooting the UPS, it\(cqs the runtime equivalent of
\fBrebootdelay\fR\&. See description of
\fBrebootdelay\fR\&.
.RE
.PP
\fBups\&.delay\&.start\fR
.RS 4
Seconds to wait before restarting the load, it\(cqs the runtime equivalent of
\fBondelay\fR\&. See description of
\fBondelay\fR\&.
.RE
.SH "KNOWN ISSUES AND BUGS"
.SS "Battery status has a non\-fatal read failure"
.sp
It\(cqs usually harmless and can be safely ignored\&. It\(cqs only logged for informative purposes (\fBLOG_INFO\fR), not as a warning or error\&.
.SS "Data stale"
.sp
Under certain circumstances, some registers can return invalid values and trigger a "data stale" error\&. Once a data stale error has occurred, you should see error messages similar to the example below in the system log\&.
.sp
.if n \{\
.RS 4
.\}
.nf
huawei\-ups2000: register 2002 has invalid value a000,
upsd: Data for UPS [huawei] is stale \- check driver
upsd: UPS [huawei] data is no longer stale
.fi
.if n \{\
.RE
.\}
.sp
So far all known problems have been fixed by the author, but an unknown one cannot be ruled out\&. If you have encountered "data stale" problems during normal uses, please file a bug report with full logs attached\&.
.sp
Before troubleshooting or reporting a problem, it\(cqs important to check your \fBdmesg\fR log for USB connect and disconnect events to avoid wasting time on the NUT driver when the actual problem is USB\&. For example, if someone yanks the cable out of the USB port, or if a new USB device is plugged into a USB host/hub that is struggling to power its ports (common on single\-board computers like Raspberry Pi), or if you have flaky cabling or EMI noise, the serial converter can get disconnected from USB, at least briefly\&. This creates a permanent data stale, the driver must be restarted (plugging the USB back won\(cqt fix it, since the driver is still using the nonexistent serial device)\&. These USB problems usually have nothing to do with NUT\&. If it\(cqs the case, you should solve the underlying USB problem \- check the cable, check the converter, try a powered USB hub, try a full\-speed USB isolator, etc\&.
.SS "Serial port becomes unresponsive"
.sp
Some malformed commands are known to lock up the serial port (including USB, which is a USB\-to\-serial device)\&. Upon receiving them, UPS2000 stops all serial communications\&. The result is a completely unresponsive UPS, regardless of what you do \- restarting NUT, rebooting the computer \- cannot restore connectivity, as if someone has unplugged the RS\-232 cable\&. To recover, simply power cycle the UPS: Turn off the UPS output via the front panel, then unplug the UPS from line power\&. Wait for the LCD front screen to go black\&. Finally reconnect line power and restart your UPS\&.
.sp
That being said, a serial port lockup is unlikely to happen\&. To our best knowledge, this driver never sends malformed commands to the UPS (it was only a problem during early development)\&. Furthermore, due to a CRC checksum, they\(cqre unlikely to be accidentally generated\&.
.sp
Still, we recommend to power cycle your UPS after making a cabling change, especially after changing from RS\-485/USB to RS\-232, just to ensure the UPS selects the correct communication interface\&. Also, if you have discovered a reproducible serial port lockup problem, it can be an previously unknown bug, make sure to file a bug report\&.
.SS "USB is unsupported"
.sp
As previously stated, only RS\-232 is supported on all systems\&. USB requires a device\-specific driver, which is only available on Linux 5\&.12 and newer kernels\&.
.sp
On an unsupported system, the USB device can still be recognized as a USB ACM device, but in reality, communication is impossible\&. It can only be fixed by implementing a driver for your system, nothing can be done within NUT\&.
.sp
Finally, in the unlike scenario that you are using NUT on Microsoft Windows, you should be able to install the USB device driver following the steps in the Huawei UPS2000 (1 kVA\-3 kVA) Modbus Protocol Development Guide\&.
.SH "AUTHOR"
.sp
Yifeng Li <tomli@tomli\&.me>
.SH "SEE ALSO"
.SS "The core driver:"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources:"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The NUT (Network UPS Tools) home page:
http://www\&.networkupstools\&.org/
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Huawei UPS2000\-A (1 kVA\-3 kVA) User Manual:
https://support\&.huawei\&.com/enterprise/en/doc/EDOC1000084260
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Huawei UPS2000 (1 kVA\-3 kVA) Modbus Protocol Development Guide:
https://support\&.huawei\&.com/enterprise/en/doc/EDOC1000110696
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
libmodbus home page:
http://libmodbus\&.org
.RE