sms_ser: fix status for newer line-interactive models, validate replies, reopen the port, send delays as the vendor software does [#1987]

NEWS.adoc

@@ -513,6 +513,41 @@ https://github.com/networkupstools/nut/milestone/13
  - `riello_usb`, `riello_ser` driver updates:
     * riello_usb, riello_ser: report NAK on RE as failure [issue #3546]
 
+ - `sms_ser` driver updates [issue #1987]:
+    * The `ups.status` is now built from all flags of the UPS, as `OL` or
+      `OB` with `LB`, `RB` and `BOOST` added as needed, instead of a single
+      value picked by precedence. Newer line-interactive models (SMS Premium,
+      SMS Gamer) raise the bypass flag whenever their inverter runs, so a
+      power outage was reported as `BYPASS` and never as `OB` or `LB`. The
+      topology byte of the status reply (now published as `ups.type`) is
+      used to only report `BYPASS` for on-line models, as the vendor software
+      does.
+    * A running battery test is reported as `CAL` with `ups.test.result`;
+      `LB` is also raised while on battery if the charge is at or below
+      `battery.charge.low`, when that is defined.
+    * Shutdown and test delays are now sent as 16-bit values as the vendor
+      software does (a delay of 64 used to be sent as `0x40FF`); added the
+      `offdelay` and `ondelay` settings with `ups.delay.shutdown`,
+      `ups.delay.start` and `ups.delay.reboot` variables, and the
+      `test.battery.start.deep` command. Times given in seconds, for battery
+      tests and shutdown delays, are converted to the time unit of the UPS,
+      which is 0.6 seconds for line-interactive models (a 10 second test
+      used to run for 6); the restore delay is sent in whole minutes, as the
+      UPS counts it. See also `UPGRADING.adoc`.
+    * Replies are now checked for their checksum and terminator, and the
+      serial port is reopened after repeated failures (e.g. a re-plugged
+      USB adapter).
+    * Two flags give a way back if a device which worked before does not
+      cope with these changes: `legacydelays` and `novalidate`. Reports
+      about devices which need them are welcome.
+    * Measurements keep their decimal digit; `ups.mfr`, `ups.model`,
+      `device.mfr` and `output.voltage.nominal` are published;
+      `battery.charger.status` no longer says `floating` at the start of an
+      outage; sent and received frames can be seen at debug level 4.
+    * Tested with an SMS Premium 1500 VA (a line-interactive model),
+      including the battery test commands and their timing; the shutdown
+      commands were only checked against a protocol simulator so far.
+
  - `usbhid-ups` driver updates:
     * When reconnecting, report success more visibly (not only in debug), and
       do not reset driver state to "quiet" when it will loop trying. [PR #3423]

UPGRADING.adoc

@@ -140,6 +140,31 @@ NOTE: In a future NUT release, the default `configure` script handling for the
   usual reconciliation, including driver restarts; subsequent checks of
   unchanged configuration remain stable. [PR #3635]
 
+- The `sms_ser` driver changed the meaning of some commands and values
+  [issue #1987]:
+  * `test.battery.start.quick` used to start a test that runs until the
+    battery is low; it now runs a 10 second test. Use the new
+    `test.battery.start.deep` for the former behavior.
+  * `shutdown.return` (also used to power off the load at the end of a
+    system shutdown) and `shutdown.reboot` now send their delays in the
+    format used by the vendor software. Previously `shutdown.return` sent
+    no usable delays, and the `shutdown.reboot` delay was mangled (64 was
+    sent as `0x40FF`), and converts seconds to the time unit of the UPS,
+    so the timing seen with your device may change. See
+    the `offdelay`, `ondelay` and `rebootdelay` settings in
+    linkman:sms_ser[8]. A malformed `rebootdelay` in `ups.conf` is now fatal
+    instead of being silently ignored. If a shutdown or test which worked
+    before does not work now, the `legacydelays` flag restores the old
+    format; please report such a device.
+  * Replies from the UPS are now checked for their checksum. If a device
+    which worked before is rejected, the `novalidate` flag turns the check
+    off; please report such a device.
+  * `ups.status` may now hold several values (e.g. `OB LB`) where only one
+    was reported before, and line-interactive models no longer report
+    `BYPASS`; drop any workarounds which translated that value. With a low
+    battery properly reported, `upsmon` will now shut the system down where
+    it previously did not.
+
 - The `powervar_cx_usb`, `tripplite_usb` drivers used a built-in limit on
   reconnection attempts after which they exited ('60' and '10' respectively).
   This was revised to follow the new common setting `reconnect_max_tries`,

data/driver.list.in

@@ -1418,6 +1418,7 @@
 "SmartLabs"	"pdu"	"1"	"2412S Power Line Modem"	"for X10/Insteon"	"powerman-pdu (experimental)"
 
 "SMS (Brazil)"	"ups"	"2"	"Manager III"	""	"blazer_ser"
+"SMS (Brazil)"	"ups"	"2"	"Premium 1500 VA (PRM1500BiBiW)"	"USB (built-in Prolific PL2303 serial adapter)"	"sms_ser"	# https://github.com/networkupstools/nut/issues/1987
 
 "SNR"	"ups"	"2"	"SNR-UPS-LID-600"	""	"nutdrv_qx"
 "SNR"	"ups"	"2"	"SNR-UPS-LID-600-XPS"	""	"nutdrv_qx"

docs/man/sms_ser.txt

@@ -31,6 +31,114 @@ the `monofasico.xml` file delivered with the device.
 Other SMS protocols (for their other products) are not supported by
 this driver.
 
+Models with a USB port that were seen so far have a serial-to-USB adapter
+inside (Cypress or Prolific), so the driver talks to the serial device node
+which the operating system creates for it, e.g. `/dev/ttyUSB0`.
+
+
+EXTRA ARGUMENTS
+---------------
+
+This driver supports the following optional settings in the
+linkman:ups.conf[5] file:
+
+*offdelay*='value'::
+Time to wait before the output is cut by the `shutdown.return` command
+and when the driver is asked to power off the load at the end of a system
+shutdown, in seconds (default=30). Also available as the writable
+`ups.delay.shutdown` variable.
+
+*ondelay*='value'::
+Time to wait before the output returns, once mains power is back, after
+the shutdown above, in seconds (default=60). The UPS counts this delay in
+whole minutes, so the value is rounded up to the next minute, and never
+below one minute, as the vendor software never sends 0 here. When mains
+power is absent the UPS switches itself off about a minute after the output
+is cut and returns a few seconds after mains power is back, regardless of
+this setting. Also available as the writable `ups.delay.start` variable.
+
+*rebootdelay*='value'::
+Time to wait before the output is cut by the `shutdown.reboot` command,
+in seconds (default=64). Also available as the writable `ups.delay.reboot`
+variable.
+
+The protocol has 16 bits for each of these values. Line-interactive models
+count time in hundredths of a minute (0.6 seconds), so the driver converts
+seconds accordingly, which limits them to about 39000 seconds; models of
+the on-line type are sent the seconds unchanged. The unit was measured on a
+line-interactive model (SMS Premium 1500 VA) for battery tests and for both
+shutdown delays, with the restore delay in minutes as described above.
+
+*legacydelays*::
+Send the parameters of the battery test and shutdown commands the way
+driver versions before 1.06 did (the low byte of the seconds for a timed
+test or `shutdown.reboot`, and no delays at all for `shutdown.return`),
+instead of the format used by the vendor software. Only meant as a way back
+for a device whose shutdown or test worked before and does not now; please
+report such a device to the NUT project.
+
+*novalidate*::
+Do not check the checksum and the terminator of the replies from the UPS.
+Only meant as a way back for a device which worked before and whose replies
+are now rejected ("Bad checksum or terminator" in the log); please report
+such a device to the NUT project.
+
+As with any driver, a `default.battery.charge.low` or
+`override.battery.charge.low` setting may be added, see NOTES below.
+
+
+INSTANT COMMANDS
+----------------
+
+*beeper.toggle*::
+Toggle the UPS beeper.
+
+*test.battery.start* ['seconds']::
+Test the battery for the given time (default=10).
+
+*test.battery.start.quick*::
+Test the battery for 10 seconds.
+
+*test.battery.start.deep*::
+Test the battery until the UPS considers it low.
+
+*test.battery.stop*::
+Stop a battery test in progress.
+
+*shutdown.return*::
+Turn off the load after `ups.delay.shutdown` and return when power is back.
+
+*shutdown.reboot* ['seconds']::
+Turn off the load after the given time (default is `ups.delay.reboot`).
+
+*shutdown.stop*::
+Stop a shutdown in progress.
+
+
+NOTES
+-----
+
+The flags of the UPS are reported as independent `ups.status` values:
+`OL` or `OB`, with `LB`, `RB` and `BOOST` added as needed. While the UPS
+runs a battery test, `CAL` is added and `ups.test.result` says so, which
+lets linkman:upsmon[8] tell a test from a power outage.
+
+The first byte of the status reply tells whether the UPS is a
+line-interactive or an on-line design; it is published as `ups.type`.
+Line-interactive models have no bypass, but at least some of them raise the
+bypass flag whenever their inverter runs. Hence `BYPASS` is only reported
+for the on-line designs, and never while on battery.
+
+The battery level the UPS reports follows the battery voltage while on
+battery. On mains power, at least some models restart it at a low value
+after any battery use (even a few seconds) and let it climb back to 100
+within minutes, so it should not be read as a state of charge then.
+If `battery.charge.low` is defined, the driver raises `LB` when the UPS is
+on battery and the level is at or below it, in addition to honoring the
+low battery flag of the UPS itself.
+
+The protocol has no battery runtime value.
+
 
 AUTHOR
 ------

docs/nut.dict

@@ -2605,6 +2605,7 @@ ld
 ldd
 ldflags
 le
+legacydelays
 legrand
 len
 leveloffset
@@ -2943,6 +2944,7 @@ notifyme
 notifymsg
 notifytype
 notransferoids
+novalidate
 novendor
 nowait
 nowarn