[juslex]

Adds read-only support for the Ragtech Easy Way units to ragtech, as a second protocol family ("family 14", "NEW/QUADRI" in the OEM device table, 21 models). Closes #3755 once confirmed on hardware.

Background

The Easy Way uses the same USB ids as the Easy Pro (04d8:000a, CDC-ACM), but a different protocol. It does not answer the family 10 polls; instead it pushes, on its own, a 32-byte frame about every 1.3 s at 2400 baud 8N1:

55 55 AE | 27 register bytes (0x00..0x1A) | tail | CS

CS is the 8-bit sum of the 31 preceding bytes. The tail byte is not constant (0x09 on mains, 0x08 on battery), so the driver relies on the sync bytes plus the sum only. Unlike family 10, the PIC does apply the line coding here, so the port has to be at 2400.

All of this comes from data that @pedroaugustosmribeiro collected in #3755: the Supervise 8.9.7 devices.xml, two USBPcap captures of the vendor software (one on mains, one with a mains cut and restore) and the matching Supervise CSV logs. The vendor software never sends anything to these units: there is no bulk OUT at all in either capture.

What the change does

• New ups.conf option family = auto (default) | 10 | 14.
  • auto first listens passively at 2400 baud for up to 3 s, writing nothing. If a valid family 14 frame arrives, the unit is treated as family 14. Otherwise the termios state saved before the speed change is restored, DTR/RTS are forced low again, and the family 10 path runs as before.
  • family=10 skips the listen and leaves the port exactly as 0.10 did (recommended for existing Easy Pro setups, to avoid the ~3 s start-up delay).
  • family=14 requires the Easy Way protocol (recommended for Easy Way owners).
• Family 14 code is kept in its own static f14_* functions with its own model table. The family 10 code only gained the dispatch points.
• Read-only: nothing is ever written to a family 14 unit, no instant commands are registered, upsdrv_shutdown fails, and allow_shutdown is ignored with a warning. No write command is known for this family: the OEM table lists no actions for it, and none was seen in the captures.
• Published data: ups.mfr, ups.model, ups.firmware, ups.power.nominal, ups.temperature, ups.load, ups.status, ups.alarm, input.voltage(.nominal), output.voltage(.nominal), output.frequency(.nominal), battery.voltage(.nominal) and battery.charge. The conversions follow the OEM table.
• No valid frame for more than 5 s marks the data stale.
• Man page, driver.list.in (21 models), NEWS.adoc and nut.dict updated. Driver version 0.10 → 0.11.

What was verified, and what was not

• Verified on captures: a test harness fed the bulk-IN byte stream of both captures, split into chunks of 1 to 32 bytes, through the real framing, decoding and publishing code. All 124 frames decode with 0 differences from an independent reference decoder, and match the Supervise CSV at the same timestamps: input/output voltage, frequency, load, battery voltage and temperature. OL → OB → OL follow the mains cut, using the firmware's on-battery flag (0x10 bit 3), which the "no input" flag confirms. Resync cases were also exercised: starting mid-frame, a corrupted byte, back-to-back frames, buffer overflow and a false sync.
• Inferred from the OEM bit names only, never observed: CHRG (on mains with the battery-full flag clear; it stays clear for the whole recharge after the cut), LB, OVER and every ups.alarm entry. BOOST/TRIM and the beeper are not reported.
• The M1/M2 variants come from the OEM table only. Its M2 (220 V) output-voltage formula looks doubtful, and the man page says so.
• Not yet run on real hardware under Linux. The only Linux attempt at 2400 in Ragtech Driver: can't communicate with Easy Way 1500 GT #3755 used stty and cat as separate processes and came back empty, which is probably a tooling artefact; the driver sets the speed on the same open descriptor it reads from. @pedroaugustosmribeiro, a run with family = 14 and -DDDDD (the RX14 hex lines) would confirm it.
• The build was only syntax-checked locally (clang -fsyntax-only -Wall -Wextra, C89-style declarations). CI will be the first full build.
• On Windows the driver does not change the line speed, so family 14 is unlikely to work there yet.

Note on other open PRs

#3716 (runtime model) and #3795 (iout_calib override) also touch drivers/ragtech.c and the driver version, so whichever lands later will need a rebase. I'm happy to do it on my side.

🤖 Generated with Claude Code

[pedroaugustosmribeiro]

Thank you for the quick support, I will test on Monday, as the UPS and computer are on my workplace.

[github-actions]

A ZIP file with standard source tarball and another tarball with pre-built docs for commit 5521bd7 is temporarily available: NUT-tarballs-PR-3798.zip.

[AppVeyorBot]

✅ Build nut 2.8.5.5903-master completed (commit 2de87853f2 by @juslex)

• artifacts
• A 7-zip archive with built NUT for Windows debug binaries is temporarily available: NUT-for-Windows-x86_64-SNAPSHOT-2.8.5.5903-master.7z
• ccache: 403 of 410 compilations were cache hits (98.3%); cache size 748 of 750 MiB after cleanup