Modbus driver for Huawei UPS2000/2000A (1kVA-3kVA)

[biergaizi]

I recently purchased a Huawei UPS2000 for my server, but the vendor only provided a Windows management program. The program is heavy, it's written in Java that comes with a whole web server and a MySQL database, and it goes without saying that it could not be used in other operating systems - and they want to sell people an SNMP adapter card for that, which would make the UPS to be as expensive as other competing vendors. No thanks...

Fortunately, documentation is publicly available. I reasoned that it would be a waste of effort if it remains unpublished for my private use - implementing it as a NUT driver and upstreaming the driver could benefit others, thus I'm now submitting a Pull Request.

This is only an initial draft of Huawei UPS2000 (1kVA-3kVA) driver on the RS-232 interface. This driver is still a work-in-progress, so far only voltage, frequency, current, power, and temperature monitoring is implemented (I think submitting it right now is helpful to get some useful feedback), I plan to also implement UPS status flag and battery monitoring in the following day, and also to do some coding style fixes.

Notably, I had to work around a significant technical problem. The UPS uses a Modbus-based serial protocol, and right now in NUT, Modbus is already supported via libmodbus. However, libmodbus has a serious technical limitation - it only supports register reads and writes. In this driver, it needs to read device identification information to ensures that it has been hooked up to the correct UPS - which is unsupported by libmodbus. Worse, although libmodmus supports sending custom commands via modbus_send_raw_request(), but modbus_receive_confirmation() assumes the response message is formatted in a certain way with a length in the header - which is not true for our purpose - it simply stops reading in the middle. To add insult to injury, libmodbus does not provide any low-level public API for us to receive the raw message from the serial device. Thus, implementing device identification is literally impossible in libmodbus.

To solve the problem, I devised the following workaround:

1. Open the serial port via ser_open()
2. Open the same serial port via libmodbus.
3. Construct a Modbus device identification message manually via ser_send_buf() and ser_get_buf(), and manually parse the response. Also, the CRC-16 verification code has to be copied and pasted into the driver.
4. After the device identification sequence has been completed, sending and receiving normal Modbus registers reads via libmodbus as usual. Because ser_*() functions are never used anymore at this point, it's safe to do so.

Other than that, the rest of the implementation is trivial. See the code comments in the patch for more technical details.

Your code review is appreciated, thanks for your time.

Signed-off-by: Yifeng Li <tomli@tomli.me>

MAINTAINER NOTE: Issues #1066 and #1017 provide many details about this device series

[aquette]

Lgtm, apart maybe from the go-to. But no big deal

[biergaizi]

@aquette I just eliminated goto in the latest commit - it was purely coincidental, the goto was simply no longer needed after some logic reorganization for status_set() implementation.

[biergaizi]

I just implemented status and alarm reporting. The driver is almost complete.

[biergaizi]

I must have triggered a bug in the LGTM.com static analyzer. It says

uint16_t val;
...
if (val != 0 || val != 1)
/* Alert: Comparison is always true because val <= 0. */

It's in fact a real bug, the || should be &&, but this alert is obviously nonsense. I wonder if someone at LGTM.com mistyped assert uint16_t >= 0 as assert uint16_t <= 0 in its ruleset.

[biergaizi]

It's ready for a final review. The driver may still have some sharp edges, but this should be good enough for a DRV_EXPERIMENTAL. -;)

[biergaizi]

Please do not merge the PR yet. I just realized the device driver for the MaxLinear RX21V1410 USB chip has been upstreamed since Linux 5.13, just shortly after I finished the initial driver. It means the driver should also support USB by now. I need to do some retests, and if it really works, update the code comments and documentations. On the other hand, no code change is necessary, it's strictly a kernel update, code reviews are still free to proceed.

[biergaizi]

USB support has been confirmed on Linux 5.12 and newer kernels. Code comments and documentation has been updated. It's the final version of this pull request, ready for review.

[biergaizi]

Bump. This PR is merge-ready since last week.

[jimklimov]

Sorry it took a while to rectify the NUT CI side as well to get to the PRs in queue, great thanks for your contribution and patience!