ragtech: add read-only support for the Easy Way (family 14) units

NEWS.adoc

@@ -505,6 +505,20 @@ https://github.com/networkupstools/nut/milestone/13
      firmware model id is shared between product lines, correcting
      `ups.power.nominal`, `ups.realpower.nominal` and the computed
      `ups.load`. [issue #3500]
+   * Added read-only support for the Ragtech Easy Way units ("family 14",
+     "NEW/QUADRI" in the OEM device table; 21 models), which share the USB
+     ids of the Easy Pro but push, on their own, a 32-byte frame with a
+     checksum at 2560 baud instead of answering polls. The new `family` option
+     (`auto`, `10` or `14`) selects the protocol; by default the driver first
+     listens passively and only then falls back to the Easy Pro polling,
+     which is unchanged. No write command is known for these units, so
+     nothing is sent to them and no instant commands are offered. Only
+     the on-line and on-battery states, voltages, frequency, load, battery
+     and temperature were checked against captures of the OEM software.
+     The line speed is 2560 baud, set directly (no standard constant); frames
+     are accepted only if the constant registers match a reference confirmed
+     by two frames and the values are plausible, and the rarely seen status
+     bits need two consecutive frames. [issue #3755]
 
  - `richcomm_usb` driver updates:
     * Completed support for NUT standard USB configuration options, and fixed

data/driver.list.in

@@ -1322,6 +1322,27 @@
 "Ragtech"	"ups"	"1"	"Easy 2000 M2"	""	"ragtech (experimental)"
 "Ragtech"	"ups"	"1"	"Easy 2200 TI"	""	"ragtech (experimental)"
 "Ragtech"	"ups"	"1"	"Easy 2200 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 500 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 500 M1"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 500 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 600 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 600 M1"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 600 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 700 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 700 M1"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 700 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 1200 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 1200 M1"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 1200 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 1300 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 1300 M1"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 1300 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 1400 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 1400 M1"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 1400 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 1600 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 1600 M1"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy Way 1600 M2"	""	"ragtech (experimental)"
 
 "Raritan"	"pdu"	"3"	"Intelligent PDU - Dominion PX"	"no report, but should be supported"	"snmp-ups (experimental)"
 "Raritan"	"pdu"	"3"	"Metered PDU - Raritan PM"	"no report, but should be supported"	"snmp-ups (experimental)"

docs/man/ragtech.txt

@@ -37,6 +37,14 @@ the Easy Pro "GT" series) speak the same protocol but may report a model
 id that collides with a table entry, so the driver can pick the wrong VA
 rating. Use the *va* option below to set the correct rating in that case.
 
+A second protocol, "family 14", covers the Ragtech Easy Way units (21
+models, Easy Way 500/600/700/1200/1300/1400/1600 in TI, M1 and M2
+variants). They use the same USB ids but a different, push-only
+protocol; see the *FAMILY 14 (EASY WAY)* section below. Support for
+family 14 is *read-only* and was developed from captures of the OEM
+software on one unit (an Easy Way TI 1400, sold as "Easy Way 1500 VA
+GT"); the other 20 models come from the OEM device table only.
+
 This driver is *experimental*. Polling, status decoding and the
 `shutdown.stayoff` / `shutdown.stop` instant commands have been
 verified on hardware; `shutdown.return` and `test.battery.start.deep`
@@ -50,6 +58,20 @@ EXTRA ARGUMENTS
 
 This driver supports the following options in the *ups.conf*:
 
+*family*='auto|10|14';;
+Select the protocol family. The default, *auto*, first listens for a
+few seconds without writing anything to the UPS: if it receives a
+checksum-valid family 14 frame at 2560 baud, the unit is treated as
+family 14;
+otherwise the driver continues with the family 10 protocol, with the
+serial settings it had before the listen. Set *family=10* on an Easy Pro
+unit to skip the listen (and its start-up delay of about three seconds,
+which also applies to `-k`) and to leave the port settings exactly as
+earlier versions did. Set *family=14* to require the Easy Way protocol;
+owners of an Easy Way unit are advised to do so, because if the automatic
+listen ever misses the stream, the driver falls back to polling it with
+family 10 commands, which that protocol does not use.
+
 *iout_calib*='number';;
 Per-unit output current calibration constant. If omitted (default),
 the driver reads the value from register `0xF3` at startup. Set this
@@ -77,6 +99,75 @@ battery event. With this flag unset, `upsdrv_shutdown` logs the
 refusal and exits with failure instead of cutting the output.
 
 
+FAMILY 14 (EASY WAY)
+--------------------
+
+The Easy Way units transmit a 32-byte frame about every 1.3 seconds on
+their own, at 2560 baud 8N1, without being asked. The driver only
+reads: it never writes anything to a family 14 unit, it registers no
+instant commands, and `upsdrv_shutdown` fails (so the `FSD` handling of
+`upsmon` cannot power such a UPS off through this driver). If
+*allow_shutdown* is set it is ignored with a warning. No write command
+is known for this family: the OEM device table lists no actions for it
+and none was seen in captures of the OEM software.
+
+Unlike family 10, these units do use the line speed, so the port must be
+at 2560 baud (not the usual 2400: that is the first speed listed for this
+family in the OEM device table, and the OEM software uses it); the driver
+sets that itself. Read at 2400 the stream is corrupted in a systematic
+way: bit 7 of the bytes arrives set and bit 6 is unreliable, so most
+frames fail the checksum, and a few corrupted ones still pass it. A
+speed like 2560 has no standard constant, so the driver asks the system
+for it directly (the `termios2` interface on Linux, the numeric speed on
+BSD and macOS). If that fails, for instance on a platform without such
+support, the driver logs a warning ("could not set 2560 baud; falling
+back to 2400, expect corrupted frames") and uses 2400; the checks below
+then drop most frames and the data will often be marked stale.
+
+The 8-bit sum of the frame is a weak check (two bytes that both gain bit
+7 add up to zero), so a frame is only accepted if it also passes these:
+
+* Registers 0x00 to 0x09 (version, model and calibration constants) are
+fixed in the unit. They must equal a reference, which is taken from two
+consecutive checksum-valid frames having identical values there; nothing
+is published before that, so the start-up takes a few seconds longer. If
+frames keep being dropped for this reason for more than 30 seconds and
+two consecutive ones agree on other values, those become the new
+reference.
+* The tap index is at most 3, the load at most 150 %, the temperature at
+most 100 degrees C and the battery voltage between 6 and 18 V.
+* `ups.alarm` entries, `OVER` and `LB` appear, and disappear, only after
+two consecutive accepted frames agree. `OL`, `OB` and `CHRG` follow
+each accepted frame, so a mains cut is reported without that delay.
+
+Published data: `ups.mfr`, `ups.model`, `ups.firmware`,
+`ups.power.nominal`, `ups.temperature`, `ups.load`, `ups.status`,
+`ups.alarm`, `input.voltage`, `input.voltage.nominal`,
+`output.voltage`, `output.voltage.nominal`, `output.frequency`,
+`output.frequency.nominal`, `battery.voltage`, `battery.voltage.nominal`
+and `battery.charge`. There is no output current. `ups.load` is the
+load ratio reported by the firmware. `ups.power.nominal` is the number
+in the model name, with the same convention as for family 10;
+`ups.realpower.nominal` is not published because the OEM table does not
+say whether that number is VA or watts. `battery.charge` is an estimate
+computed from the battery voltage, as in the OEM software.
+
+What was observed on hardware (mains cut and restored on one TI unit):
+`OL` and `OB` follow the firmware's on-battery flag, and the voltages,
+frequency, load, battery voltage and temperature match the values shown
+by the OEM software. What is inferred from bit names in the OEM table
+and was *not* observed: `CHRG` (shown while on mains and the
+battery-full flag is clear), `LB`, `OVER`, and every `ups.alarm` entry.
+`BOOST`, `TRIM` and the beeper are not reported. The M1 and M2
+variants follow the OEM table, but the output voltage formula of the M2
+(220 V) models in that table is the 115 V one with different tap factors,
+which looks doubtful, so treat `output.voltage` on those with suspicion
+until someone confirms it.
+
+If no accepted frame arrives for more than five seconds the data is marked
+stale.
+
+
 CAVEATS
 -------
 
@@ -86,9 +177,12 @@ are interpreted by the UPS as a remote shutdown signal -- never run
 this driver alongside other software that toggles those lines on the
 same device node.
 
-Replies are framed by a 0xAA start byte and have no checksum; the
-driver re-synchronizes by scanning for the start byte after any
-short read.
+On family 10, replies are framed by a 0xAA start byte and have no
+checksum; the driver re-synchronizes by scanning for the start byte
+after any short read. On family 14 the frames start with `55 55 AE` and
+end with an 8-bit sum; the driver checks every frame whose sum is right
+against the constants and ranges described above, and keeps the newest
+one that passes.
 
 
 AUTHOR

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3917 utf-8
+personal_ws-1.1 en 3918 utf-8
 AAC
 AAS
 ABI
@@ -1146,6 +1146,7 @@ QQ
 QQQ
 QRI
 QTS
+QUADRI
 QVFW
 QWS
 QinHeng

drivers/Makefile.am

@@ -252,7 +252,7 @@ bestfcom_SOURCES = bestfcom.c
 bestfortress_SOURCES = bestfortress.c
 bestuferrups_SOURCES = bestuferrups.c
 bestups_SOURCES = bestups.c
-ragtech_SOURCES = ragtech.c
+ragtech_SOURCES = ragtech.c ragtech_speed.c
 ragtech_LDADD = $(LDADD_DRIVERS_SERIAL)
 blazer_ser_SOURCES = blazer.c blazer_ser.c
 blazer_ser_LDADD = $(LDADD_DRIVERS_SERIAL) -lm
@@ -557,7 +557,7 @@ dist_noinst_HEADERS = \
  hidparser.h hidtypes.h ietf-mib.h libhid.h libshut.h nut_libusb.h libwinhid.h liebert-hid.h	\
  main.h mge-hid.h mge-mib.h mge-utalk.h		\
  mge-xml.h microdowell.h microsol-apc.h microsol-common.h netvision-mib.h netxml-ups.h nut-ipmi.h oneac.h		\
- powercom.h powerpanel.h powerp-bin.h powerp-txt.h powervar_cx.h raritan-pdu-mib.h	\
+ powercom.h powerpanel.h powerp-bin.h powerp-txt.h powervar_cx.h ragtech_speed.h raritan-pdu-mib.h	\
  safenet.h serial.h sms_ser.h snmp-ups.h solis.h tripplite.h tripplite-hid.h 			\
  upshandler.h usb-common.h usbhid-ups.h powercom-hid.h compaq-mib.h idowell-hid.h microdowell-hid.h \
  apc_common.h apcmicrolink-maps.h apcmicrolink.h apcmicrolink-usb.h apcsmart.h apcsmart_tabs.h apcsmart-old.h apcupsd-ups.h cyberpower-mib.h riello.h openups-hid.h \