ragtech: new driver for Ragtech UPS (USB CDC-ACM, family 10)

NEWS.adoc

@@ -365,6 +365,16 @@ but the `nutshutdown` script would bail out quickly and quietly. [PR #3008]
      subdriver definition then). For consistency, these pointers are now
      assigned. [#1962]
 
+ - Introduced a new NUT driver named `ragtech` which provides support for the
+   Ragtech "Easy Pro" family of line-interactive UPS units (also sold under
+   the NEP, TORO, INNERGIE and OneUP brands in Brazil). Devices present a USB
+   CDC-ACM serial interface (VID `0x04D8`, PID `0x000A`) and speak a proprietary
+   6-byte register-access protocol with read/write/AND/OR opcodes; the driver
+   covers the 20 models in the family-10 device table and was validated
+   end-to-end against an Easy 2000 TI. Shutdown-related instant commands are
+   opt-in via the `allow_shutdown` flag because the firmware does not
+   auto-restart on mains return. [PR #3447]
+
  - `riello_ser` and `riello_usb` driver updates:
    * Since the beginning, these drivers fenced availability of *either*
      `load.*` *or* `shutdown.return` instant commands based on current

data/driver.list.in

@@ -1271,6 +1271,27 @@
 
 "Phantom"	"pdu"	"1"	"Rackable Systems"	"1 outlets"	"powerman-pdu (experimental)"
 
+"Ragtech"	"ups"	"1"	"Easy 600 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 600 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 700 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 700 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 900 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 900 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 1200 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 1200 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 1300 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 1300 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 1400 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 1400 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 1600 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 1600 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 1800 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 1800 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 2000 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 2000 M2"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 2200 TI"	""	"ragtech (experimental)"
+"Ragtech"	"ups"	"1"	"Easy 2200 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)"
 "Raritan"	"pdu"	"3"	"Switched PDU - Raritan RPC"	"no report, but should be supported"	"snmp-ups (experimental)"

docs/man/Makefile.am

@@ -1024,6 +1024,7 @@ SRC_SERIAL_PAGES = \
 	powercom.txt 	\
 	powerpanel.txt	\
 	powervar_cx_ser.txt	\
+	ragtech.txt	\
 	rhino.txt		\
 	riello_ser.txt	\
 	sms_ser.txt \
@@ -1077,6 +1078,7 @@ INST_MAN_SERIAL_PAGES = \
 	powercom.$(MAN_SECTION_CMD_SYS) 	\
 	powerpanel.$(MAN_SECTION_CMD_SYS)	\
 	powervar_cx_ser.$(MAN_SECTION_CMD_SYS)	\
+	ragtech.$(MAN_SECTION_CMD_SYS)	\
 	rhino.$(MAN_SECTION_CMD_SYS)		\
 	riello_ser.$(MAN_SECTION_CMD_SYS)	\
 	sms_ser.$(MAN_SECTION_CMD_SYS) \
@@ -1147,6 +1149,7 @@ INST_HTML_SERIAL_MANS = \
 	powercom.html 	\
 	powerpanel.html	\
 	powervar_cx_ser.html	\
+	ragtech.html	\
 	rhino.html		\
 	riello_ser.html	\
 	sms_ser.html \

docs/man/ragtech.txt

@@ -0,0 +1,98 @@
+RAGTECH(8)
+==========
+
+NAME
+----
+
+ragtech - Driver for Ragtech UPS units (USB CDC-ACM)
+
+SYNOPSIS
+--------
+
+*ragtech* -h
+
+*ragtech* -a 'UPS_NAME' ['OPTIONS']
+
+NOTE: This man page only documents the hardware-specific features of
+the ragtech driver. For information about the core driver, see
+linkman:nutupsdrv[8].
+
+
+SUPPORTED HARDWARE
+------------------
+
+Targets Ragtech UPSes that expose a USB CDC-ACM serial interface
+(USB VID 0x04D8, PID 0x000A -- Microchip PIC with CDC firmware).
+The device shows up under Linux as `/dev/ttyACM*`.
+
+Validated end-to-end against the Ragtech Easy 2000 TI (model id 16 in
+the family-10 device table). The other 19 models in the same table --
+Easy 600/700/900/1200/1300/1400/1600/1800/2000/2200 in both TI (115 V)
+and M2 (220 V) variants, also sold under the NEP, TORO, INNERGIE and
+OneUP brands in Brazil -- share the same wire protocol and register
+layout and are expected to work; please report results.
+
+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`
+are implemented but not yet verified end-to-end (see the
+*allow_shutdown* note below). The beeper-control wire encoding has
+not been reverse-engineered yet.
+
+
+EXTRA ARGUMENTS
+---------------
+
+This driver supports the following options in the *ups.conf*:
+
+*iout_calib*='number';;
+Per-unit output current calibration constant. If omitted (default),
+the driver reads the value from register `0xF3` at startup. Set this
+only to override a wrong factory-stored calibration.
+
+*allow_shutdown*;;
+Enable the `shutdown.return`, `shutdown.stayoff`, `shutdown.stop` and
+`test.battery.start.deep` instant commands. Disabled by default for
+safety: the Easy 2000 TI firmware does **not** auto-restart after a
+coordinated shutdown, so an `upsmon`-driven shutdown on low battery
+will leave the UPS (and everything plugged into it) powered off until
+someone presses the physical power button. Only set this flag if you
+have an out-of-band way to power the UPS back up, or if you are
+deliberately running a UPS that should stay off after a critical-
+battery event. With this flag unset, `upsdrv_shutdown` logs the
+refusal and exits with failure instead of cutting the output.
+
+
+CAVEATS
+-------
+
+The serial control lines DTR and RTS are forced low by the driver
+immediately after opening the port. Non-zero levels on either line
+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.
+
+
+AUTHOR
+------
+
+juslex
+
+
+SEE ALSO
+--------
+
+linkman:nutupsdrv[8],
+linkman:ups.conf[5]
+
+Internet resources:
+~~~~~~~~~~~~~~~~~~~
+
+* The NUT (Network UPS Tools) home page: https://www.networkupstools.org/
+
+* Reverse-engineering reference:
+  https://github.com/antunesls/UPS_ESP32_tinySrv

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3764 utf-8
+personal_ws-1.1 en 3775 utf-8
 AAC
 AAS
 ABI
@@ -3763,3 +3763,14 @@ zwfa
 zzz
 Åstrand
 Ørpetveit
+INNERGIE
+NEP
+OneUP
+Ragtech
+TORO
+calib
+iout
+juslex
+ragtech
+xAA
+xF

drivers/Makefile.am

@@ -152,7 +152,8 @@ SERIAL_DRIVERLIST = al175 apcmicrolink bcmxcp belkin belkinunv bestfcom	\
  gamatronic genericups isbmex liebert liebert-esp2 liebert-gxe masterguard metasys	\
  mge-utalk microdowell microsol-apc mge-shut nutdrv_hashx oneac optiups powercom powervar_cx_ser rhino	\
  safenet nutdrv_siemens-sitop solis tripplite tripplitesu upscode2 victronups powerpanel \
- blazer_ser ivtscd apcsmart apcsmart-old riello_ser sms_ser bicker_ser ve-direct meanwell_ntu
+ blazer_ser ivtscd apcsmart apcsmart-old riello_ser sms_ser bicker_ser ve-direct meanwell_ntu \
+ ragtech
 if HAVE_LINUX_SERIAL_H
 # Temporary, until ported to more OSes
 SERIAL_DRIVERLIST += nhs_ser
@@ -246,6 +247,8 @@ bestfcom_SOURCES = bestfcom.c
 bestfortress_SOURCES = bestfortress.c
 bestuferrups_SOURCES = bestuferrups.c
 bestups_SOURCES = bestups.c
+ragtech_SOURCES = ragtech.c
+ragtech_LDADD = $(LDADD_DRIVERS_SERIAL)
 blazer_ser_SOURCES = blazer.c blazer_ser.c
 blazer_ser_LDADD = $(LDADD_DRIVERS_SERIAL) -lm
 etapro_SOURCES = etapro.c