WIP: Ecoflow River3+ and Delta3+ support

[ykuksenko]

Attempting to add EcoFlow support in response to #2735. Specifically Delta 3 Plus and River 3 Plus models.

Working:

• Basic status works (charging, discharging, online, onbattery, ...).
• Charge level works.
• Discharge limit from app shows correctly. Load turns off at battery.low with current mapping.

Not working:

• Any sort of control does not seem to work for load or beeper/light. Or I do not understand how to do it.

Model differences:

• Delta 3 Plus (firmware V6.31.48.29):
  • Has a beeper; it does not trigger on power loss.
  • Seems to lose USB connection randomly, needing to replug and/or restart software. (Both upsc and usbhid-scripts saw this)
• River 3 Plus (firmware V1.32.75.41):
  • Has a light instead of beeper; it does trigger on power loss.
  • Did not see USB connection issues on River 3 Plus but did less testing with it.

Attribute Details/Questions:

1. Where should the HU_FLAG_QUICK_POLL flag be used? The boolean values all seem to be alarm and status related. Does this look okay?
2. Code comments show attempted commands to control beeper and load. Please correct if I missed something there.
3. DesignCapacity and FullChargeCapacity metrics seem to be percent. Are the mappings okay to use despite NUT docs wanting these in Ah?
4. flow.[4].configactivepower attribute is close to unit Wh ratings. It matches on Delta 3+ but is not correct for River 3+. What should Wh metrics be mapped to if anything? Maybe use to calculate/estimate DesignCapacity/FullChargeCapacity.
5. RemainingCapacityLimit attribute shows the percentage at which the load will be turned off. Is this okay to map to battery.low? It is definitely a useful thing to have, just not sure if with that mapping.
6. RunTimeToEmpty does not take RemainingCapacityLimit in to account. How should the user be informed of this? The unit is in minutes, does this need to be converted to seconds or can it be left as is?

---

General points

• Described the changes in the PR submission or a separate issue, e.g.
  known published or discovered protocols, applicable hardware (expected
  compatible and actually tested/developed against), limitations, etc.

• There may be multiple commits in the PR, aligned and commented with
  a functional change. Notably, coding style changes better belong in a
  separate PR, but certainly in a dedicated commit to simplify reviews
  of "real" changes in the other commits. Similarly for typo fixes in
  comments or text documents.

• Please star NUT on GitHub, this helps with sponsorships! ;)

Frequent "underwater rocks" for driver addition/update PRs

• Revised existing driver families and added a sub-driver if applicable
  (nutdrv_qx, usbhid-ups...) or added a brand new driver in the other
  case.

• Did not extend obsoleted drivers with new hardware support features
  (notably blazer and other single-device family drivers for Qx protocols,
  except the new nutdrv_qx which should cover them all).

• For updated existing device drivers, bumped the DRIVER_VERSION macro
  or its equivalent.

• For USB devices (HID or not), revised that the driver uses unique
  VID/PID combinations, or raised discussions when this is not the case
  (several vendors do use same interface chips for unrelated protocols).

• For new USB devices, built and committed the changes for the
  scripts/upower/95-upower-hid.hwdb file

• Proposed NUT data mapping is aligned with existing docs/nut-names.txt
  file. If the device exposes useful data points not listed in the file, the
  experimental.* namespace can be used as documented there, and discussion
  should be raised on the NUT Developers mailing list to standardize the new
  concept.

• Updated data/driver.list.in if applicable (new tested device info)

Frequent "underwater rocks" for general C code PRs

• Did not "blindly assume" default integer type sizes and value ranges,
  structure layout and alignment in memory, endianness (layout of bytes and
  bits in memory for multi-byte numeric types), or use of generic int where
  language or libraries dictate the use of size_t (or ssize_t sometimes).

• Progress and errors are handled with upsdebugx(), upslogx(),
  fatalx() and related methods, not with direct printf() or exit().
  Similarly, NUT helpers are used for error-checked memory allocation and
  string operations (except where customized error handling is needed,
  such as unlocking device ports, etc.)

• Coding style (including whitespace for indentations) follows precedent
  in the code of the file, and examples/guide in docs/developers.txt file.

• For newly added files, the Makefile.am recipes were updated and the
  make distcheck target passes.

General documentation updates

• Updated docs/acknowledgements.txt (for vendor-backed device support)

• Added or updated manual page information in docs/man/*.txt files
  and corresponding recipe lists in docs/man/Makefile.am for new pages

• Passed make spellcheck, updated spell-checking dictionary in the
  docs/nut.dict file if needed (did not remove any words -- the make
  rule printout in case of changes suggests how to maintain it).

Additional work may be needed after posting this PR

• Propose a PR for NUT DDL with detailed device data dumps from tests
  against real hardware (the more models, the better).

• Address NUT CI farm build failures for the PR: testing on numerous
  platforms and toolkits can expose issues not seen on just one system.

• Revise suggestions from LGTM.COM analysis about "new issues" with
  the changed codebase.
  LGTM.COM looks to be shutdown as of Dec 16 (2022?).*

[kirashi3]

Thanks for getting the ball rolling on this! I only recently found out that Ecoflow is planning to support its Power Manager software for both the River 3 and Delta 3 series of portable batteries, though the Delta 3 seems delayed until "end of February" according to the page I linked to above.

I've got a Synology DS918+ currently powered by a Delta 3 Plus that I'd be happy to test with, if necessary. I'd just need to dig out a USB-C to USB-A cable (unless perhaps they're supporting SNMP-based UPS HID?), and receive some instruction on modifying Synology's DSM via SSH, if that's what it takes.

Either way, I'ma subscribe to see where this leads, as it'd be super cool to program our NAS hardware to gracefully shutdown once an Ecoflow battery reaches whatever low-capacity threshold we specify.

[jimklimov]

This PR source was assimilated into #2837, thanks for the extensive comments about investigation results!