Merge pull request #2712 from dvdesolve/innova_rt_31

First attempt to add support for Ippon Innova RT 3/1

NEWS.adoc

@@ -144,9 +144,11 @@ https://github.com/networkupstools/nut/milestone/11
      In fact, the driver should try fully reconnecting upon getting into
      a prolonged data stale condition. [issue #704, PR #2564]
 
- - added Visench C1K (using serial port converter with USB ID `1a86:7523`)
-   as known supported by `nutdrv_qx` (Megatec protocol) since at least
-   NUT v2.7.4 release [#2395]
+ - nutdrv_qx updates:
+   * added Visench C1K (using serial port converter with USB ID `1a86:7523`)
+     as known supported by `nutdrv_qx` (Megatec protocol) since at least
+     NUT v2.7.4 release. [#2395]
+   * introduced `innovart31` protocol support for Innova RT 3/1 UPSes. [#2712]
 
  - bicker_ser: added new driver for Bicker 12/24Vdc UPS via RS-232 serial
    communication protocol, which supports any UPS shipped with the PSZ-1053

data/driver.list.in

@@ -590,6 +590,7 @@
 "Ippon"	"ups"	"2"	"Smart Power Pro II Euro 1200/1600/2200"	"USB"	"usbhid-ups"	# https://github.com/networkupstools/nut/issues/2702 https://github.com/networkupstools/nut/issues/701
 "Ippon"	"ups"	"2"	"Pacific 1000/2000/3000"	"USB"	"usbhid-ups"	# https://github.com/networkupstools/nut/issues/2702
 "Ippon"	"ups"	"2"	"Ampere 1000/1500/2000/3000 bl"	"USB"	"usbhid-ups"	# https://github.com/networkupstools/nut/issues/2702
+"Ippon"	"ups"	"2"	"Innova RT 3/1 10K/10K compact/20K"	"USB"	"nutdrv_qx"	# https://github.com/networkupstools/nut/issues/2712
 "Ippon"	"ups"	"2"	"Innova RTB 1000/1500/2000/3000"	"USB"	"usbhid-ups"	# https://github.com/networkupstools/nut/issues/2702
 "Ippon"	"ups"	"2"	"Innova TBE 1000/2000/3000"	"USB"	"usbhid-ups"	# https://github.com/networkupstools/nut/issues/2702
 "Ippon"	"ups"	"2"	"Innova TB 1000/2000/3000"	"USB"	"usbhid-ups"	# https://github.com/networkupstools/nut/issues/2702

docs/man/nutdrv_qx.txt

@@ -67,7 +67,7 @@ If you set stayoff in linkman:ups.conf[5] when FSD arises the UPS will call a *s
 
 *protocol =* 'string'::
 Skip autodetection of the protocol to use and only use the one specified.
-Supported values: 'bestups', 'hunnox', 'masterguard', 'mecer', 'megatec', 'megatec/old', 'mustek', 'q1', 'voltronic', 'voltronic-qs', 'voltronic-qs-hex' and 'zinto'.
+Supported values: 'bestups', 'hunnox', 'innovart31', 'masterguard', 'mecer', 'megatec', 'megatec/old', 'mustek', 'q1', 'voltronic', 'voltronic-qs', 'voltronic-qs-hex' and 'zinto'.
 +
 Run the driver program with the `--help` option to see the exact list of
 `protocol` values it would currently recognize.
@@ -147,8 +147,8 @@ If not specified, the driver defaults to 10%.
 Only used if *runtimecal* is also specified.
 
 
-BESTUPS, MECER, MEGATAEC, MEGATEC/OLD, MUSTEK, Q1, VOLTRONIC-QS, VOLTRONIC-QS-HEX, ZINTO PROTOCOLS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+BESTUPS, INNOVART31, MECER, MEGATEC, MEGATEC/OLD, MUSTEK, Q1, VOLTRONIC-QS, VOLTRONIC-QS-HEX, ZINTO PROTOCOLS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 *ignoresab*::
 Some UPSes incorrectly report the `Shutdown Active' bit as always on, consequently making the driver believe the UPS is nearing a shutdown (and, as a result, ups.status always contains +FSD+... and you know what this means).
@@ -196,8 +196,8 @@ Safeguard against talking to the wrong one of several identical UPSes on the sam
 Note that when changing *ups.id* (through linkman:upsrw[8]) the driver will continue to talk to the UPS with the new 'slave address', but won't claim it again on restart until the *slave_addr* parameter is adjusted.
 
 
-Q1 PROTOCOL
-~~~~~~~~~~~
+INNOVART31, Q1 PROTOCOLS
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 *ondelay*::
 The acceptable range is +0..599940+ seconds.
@@ -439,8 +439,8 @@ Stop a running battery test.
 (Not available on some hardware)
 
 
-BESTUPS, MECER, MEGATEC, MEGATEC/OLD, MUSTEK, Q1, ZINTO PROTOCOLS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+BESTUPS, INNOVART31, MECER, MEGATEC, MEGATEC/OLD, MUSTEK, Q1, ZINTO PROTOCOLS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 *test.battery.start* 'value'::
 Perform a battery test for the duration of 'value' seconds (truncated to 60 seconds) [+60..5940+].

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3264 utf-8
+personal_ws-1.1 en 3269 utf-8
 AAC
 AAS
 ABI
@@ -2065,6 +2065,7 @@ iDialog
 iDowell
 iManufacturer
 iPlug
+iProduct
 iSerial
 iUSB
 ib
@@ -2108,6 +2109,7 @@ initups
 inline
 inlined
 innotech
+innovart
 inode
 inplace
 installable
@@ -2920,6 +2922,7 @@ subdirectories
 subdirectory
 subdriver
 subdriver's
+subdrivername
 subdrivers
 subdrv
 sublicense
@@ -3129,6 +3132,8 @@ usbhid
 usbif
 usbinfo
 usbmisc
+usbsubdriver
+usbsubdrvname
 usbups
 usbus
 usd

docs/nutdrv_qx-subdrivers.txt

@@ -11,6 +11,33 @@ It consists of a core driver that handles most of the work of talking to the har
 
 Adding support for a new UPS device is easy, because it requires only the creation of a new sub-driver.
 
+[NOTE]
+======
+Due to historic reasons, there is a bit of a mess with terminology here:
+among the set of driver parameters passed on command-line or via `ups.conf`,
+the `subdriver` value is for Serial-over-USB dialect ("usbsubdriver" in code),
+and the `protocol` value is for Qx dialect (but referred to as "subdriver"
+in most of the documentation, and variable names in the code itself)..
+
+An additional set of source code files named `nutdrv_qx_subdrivername.{c,h}`
+defines a `subdriver_t` entry that is listed as in `subdrivers_list` array in
+the main `nutdrv_qx.c` file.  However, in `ups.conf` this entity is referred
+to via the communication `protocol` keyword, if the end-user wants to pick
+one explicitly (bypassing auto-detection).
+
+Confusingly, there *is* also an optional USB `subdriver` setting (available
+when the driver is built with USB support), for "Serial-over-USB subdriver
+selection", corresponding to entries in the `usbsubdriver` array and several
+`usbsubdrvname_command()` methods defined directly in `nutdrv_qx.c`.
+
+There are also methods called `usbsubdrvname_subdriver()` which are called
+via `qx_usb_id[]` array for USB VendorID/ProductID/iManufacturer/iProduct
+based matching, and typically set the `subdriver_command` variable to point
+to the corresponding `usbsubdrvname_command()` method when auto-detection
+happens.  Otherwise, this variable is set according to a text name requested
+in the `subdriver` driver parameter.
+======
+
 
 Creating a subdriver
 ~~~~~~~~~~~~~~~~~~~~
@@ -1144,6 +1171,7 @@ You can then recompile +nutdrv_qx+, and start experimenting with the new subdriv
 For more details, have a look at the currently available subdrivers:
 
 - +nutdrv_qx_bestups.+{+c+,+h+}
+- +nutdrv_qx_innovart31.+{+c+,+h+}
 - +nutdrv_qx_masterguard.+{+c+,+h+}
 - +nutdrv_qx_mecer.+{+c+,+h+}
 - +nutdrv_qx_megatec.+{+c+,+h+}

drivers/Makefile.am

@@ -379,6 +379,7 @@ nutdrv_qx_SOURCES += $(LIBUSB_IMPL) usb-common.c
 nutdrv_qx_LDADD += $(LIBUSB_LIBS)
 endif
 NUTDRV_QX_SUBDRIVERS = nutdrv_qx_bestups.c nutdrv_qx_blazer-common.c	\
+ nutdrv_qx_innovart31.c	\
  nutdrv_qx_masterguard.c	\
  nutdrv_qx_mecer.c nutdrv_qx_megatec.c nutdrv_qx_megatec-old.c	\
  nutdrv_qx_mustek.c nutdrv_qx_q1.c nutdrv_qx_voltronic.c	\
@@ -404,6 +405,7 @@ dist_noinst_HEADERS = \
  upshandler.h usb-common.h usbhid-ups.h powercom-hid.h compaq-mib.h idowell-hid.h \
  apcsmart.h apcsmart_tabs.h apcsmart-old.h apcupsd-ups.h cyberpower-mib.h riello.h openups-hid.h \
  delta_ups-mib.h nutdrv_qx.h nutdrv_qx_bestups.h nutdrv_qx_blazer-common.h	\
+ nutdrv_qx_innovart31.h	\
  nutdrv_qx_masterguard.h	\
  nutdrv_qx_mecer.h nutdrv_qx_ablerex.h  \
  nutdrv_qx_megatec.h nutdrv_qx_megatec-old.h nutdrv_qx_mustek.h nutdrv_qx_q1.h nutdrv_qx_hunnox.h	\

drivers/nutdrv_qx.c

@@ -58,7 +58,7 @@
 #	define DRIVER_NAME	"Generic Q* Serial driver"
 #endif	/* QX_USB */
 
-#define DRIVER_VERSION	"0.38"
+#define DRIVER_VERSION	"0.39"
 
 #ifdef QX_SERIAL
 #	include "serial.h"
@@ -71,6 +71,7 @@
 /* Include all known subdrivers */
 #include "nutdrv_qx_bestups.h"
 #include "nutdrv_qx_hunnox.h"
+#include "nutdrv_qx_innovart31.h"
 #include "nutdrv_qx_mecer.h"
 #include "nutdrv_qx_megatec.h"
 #include "nutdrv_qx_megatec-old.h"
@@ -97,6 +98,7 @@ static subdriver_t	*subdriver_list[] = {
 	&masterguard_subdriver,
 	&hunnox_subdriver,
 	&ablerex_subdriver,
+	&innovart31_subdriver,
 	/* Fallback Q1 subdriver */
 	&q1_subdriver,
 	NULL
@@ -2913,7 +2915,7 @@ void	upsdrv_help(void)
 	 * are listed in usbsubdriver[] array (just above in this
 	 * source file).
 	 */
-	printf("\nAcceptable values for 'subdriver' via -x or ups.conf in this driver: ");
+	printf("\nAcceptable values for USB 'subdriver' via -x or ups.conf in this driver: ");
 	for (i = 0; usbsubdriver[i].name != NULL; i++) {
 		if (i>0)
 			printf(", ");
@@ -3325,7 +3327,7 @@ void	upsdrv_initups(void)
 
 			if (!regex_array[0] || !regex_array[1]) {
 				fatalx(EXIT_FAILURE,
-					"When specifying a subdriver, "
+					"When specifying a USB 'subdriver', "
 					"'vendorid' and 'productid' are mandatory.");
 			}
 

drivers/nutdrv_qx_blazer-common.c

@@ -1,4 +1,4 @@
-/* nutdrv_qx_blazer-common.c - Common functions/settings for nutdrv_qx_{mecer,megatec,megatec-old,mustek,q1,voltronic-qs,zinto}.{c,h}
+/* nutdrv_qx_blazer-common.c - Common functions/settings for nutdrv_qx_{innovart31,mecer,megatec,megatec-old,mustek,q1,voltronic-qs,zinto}.{c,h}
  *
  * Copyright (C)
  *   2013 Daniele Pezzini <[email protected]>

drivers/nutdrv_qx_blazer-common.h

@@ -1,4 +1,4 @@
-/* nutdrv_qx_blazer-common.h - Common functions/settings for nutdrv_qx_{mecer,megatec,megatec-old,mustek,q1,voltronic-qs,zinto}.{c,h}
+/* nutdrv_qx_blazer-common.h - Common functions/settings for nutdrv_qx_{innovart31,mecer,megatec,megatec-old,mustek,q1,voltronic-qs,zinto}.{c,h}
  *
  * Copyright (C)
  *   2013 Daniele Pezzini <[email protected]>