Merge 8418030 into 66af085

Author: libschmudie-so

NEWS.adoc

@@ -44,6 +44,10 @@ https://github.com/networkupstools/nut/milestone/13
  - Second-level bullet points listed in this file will now use 4 spaces
    (not 3 like before) for easier initial indentation of new entries.
 
+ - Introduced an experimental `apcmicrolink` driver for devices with
+   the APC Microlink protocol on serial port connections. Tested against
+   APC Smart-UPS 750 (SMT750RMI2UC). [PR #3406]
+
  - `apc_modbus` driver updates:
     * Fixed string join not doing zero termination. [PR #3413]
     * Decode `RunTimeCalibrationStatus_BF` into

data/driver.list.in

@@ -80,6 +80,7 @@
 "APC"	"ups"	"1"	"Matrix-UPS"	""	"apcsmart"
 "APC"	"ups"	"1"	"Smart-UPS"	""	"apcsmart"
 "APC"	"ups"	"1"	"Smart-UPS SMT/SMX/SURTD"	"Microlink models with RJ45 socket - they *require* AP9620 SmartSlot expansion card and smart cable"	"apcsmart"
+"APC"	"ups"	"1"	"Smart-UPS SMT/SMX Microlink"	"Microlink serial driver"	"apcmicrolink"
 "APC"	"ups"	"3"	"Back-UPS Pro USB"	"USB"	"usbhid-ups"
 "APC"	"ups"	"3"	"Back-UPS BK650M2-CH"	"USB"	"usbhid-ups"	# https://github.com/networkupstools/nut/issues/1970
 "APC"	"ups"	"3"	"Back-UPS (USB)"	"USB"	"usbhid-ups"

docs/man/Makefile.am

@@ -983,6 +983,7 @@ endif
 # (--with-serial)
 SRC_SERIAL_PAGES = \
 	al175.txt	\
+	apcmicrolink.txt	\
 	apcsmart.txt	\
 	apcsmart-old.txt	\
 	bcmxcp.txt 	\
@@ -1037,6 +1038,7 @@ SRC_SERIAL_PAGES = \
 
 INST_MAN_SERIAL_PAGES = \
 	al175.$(MAN_SECTION_CMD_SYS)	\
+	apcmicrolink.$(MAN_SECTION_CMD_SYS)	\
 	apcsmart.$(MAN_SECTION_CMD_SYS)	\
 	apcsmart-old.$(MAN_SECTION_CMD_SYS)	\
 	bcmxcp.$(MAN_SECTION_CMD_SYS) 	\
@@ -1155,6 +1157,7 @@ INST_HTML_SERIAL_MANS = \
 	upscode2.html	\
 	ve-direct.html	\
 	victronups.html	\
+	apcmicrolink.html \
 	apcupsd-ups.html
 
 if HAVE_LINUX_SERIAL_H

docs/man/apcmicrolink.txt

@@ -0,0 +1,147 @@
+APCMICROLINK(8)
+===============
+
+NAME
+----
+
+apcmicrolink - Driver for APC Smart-UPS units using the Microlink serial protocol
+
+SYNOPSIS
+--------
+
+*apcmicrolink* -h
+
+*apcmicrolink* -a 'UPS_NAME' ['OPTIONS']
+
+NOTE: This man page documents the hardware-specific features of the
+*apcmicrolink* driver. For general information about NUT drivers, see
+linkman:nutupsdrv[8].
+
+
+DESCRIPTION
+-----------
+
+The *apcmicrolink* driver talks the APC Microlink protocol used by newer
+serial-connected Smart-UPS families such as SMT and SMX units with the
+Microlink RJ45 serial port.
+
+This driver is currently experimental. It discovers most values from the
+device descriptor blob at runtime and maps supported Microlink objects onto
+standard NUT variables where possible. Unknown descriptor fields can also be
+published for debugging and reverse-engineering.
+
+
+SUPPORTED HARDWARE
+------------------
+
+This driver is intended for APC Smart-UPS models that expose the Microlink
+serial protocol, notably SMT and SMX units with the vendor Microlink serial
+cable.
+
+Tested support currently targets:
+
+* APC Smart-UPS SMT/SMX Microlink models
+
+Other APC Microlink devices may work if they expose a compatible descriptor
+layout.
+
+
+CONFIGURATION
+-------------
+
+The driver is configured via linkman:ups.conf[5].
+
+A minimal configuration:
+
+----
+[apc-microlink]
+    driver = apcmicrolink
+    port = /dev/ttyUSB0
+----
+
+Optional settings
+~~~~~~~~~~~~~~~~~
+
+*baudrate*='num'::
+Set the serial line speed. The default is `9600`.
+
+*showinternals*='yes|no'::
+Publish additional internal Microlink runtime values. By default this follows
+the driver debug level and is enabled automatically when debug logging is on.
+
+*showunmapped*='yes|no'::
+Publish descriptor values that do not currently map to a standard NUT variable.
+By default this follows the driver debug level and is enabled automatically
+when debug logging is on.
+
+*cmdsrc*='rj45|usb|localuser|smartslot1|internalnetwork1'::
+Select the Microlink command source used for outgoing command writes. The
+default is `rj45`.
+
+
+IMPLEMENTED FEATURES
+--------------------
+
+The driver publishes standard identity, status, runtime and outlet-group data
+when these objects are present in the Microlink descriptor. Descriptor-backed
+values are interpreted as strings, hex identifiers, dates, times, fixed-point
+numbers, and enum or bitfield maps depending on the Microlink type reported by
+the device.
+
+Writable descriptor-backed variables are exposed as read-write NUT variables
+when the device reports them as modifiable. Depending on the connected model,
+this can include values such as:
+
+* `ups.id`
+* `ups.display.language`
+* `ups.test.interval`
+* `battery.date`
+* `input.transfer.delay`
+* `input.transfer.high`
+* `input.transfer.low`
+* `outlet.group.N.timer.shutdown`
+* `outlet.group.N.timer.reboot`
+* `outlet.group.N.timer.start`
+* `outlet.group.N.delay.shutdown`
+* `outlet.group.N.delay.reboot`
+* `outlet.group.N.delay.start`
+* `outlet.group.N.minimumreturnruntime`
+* `outlet.group.N.lowruntimewarning`
+* `outlet.group.N.name`
+
+Supported instant commands currently include:
+
+* `test.battery.start`
+* `test.battery.stop`
+* `test.panel.start`
+* `test.panel.stop`
+
+Driver-assisted shutdown is not yet implemented.
+
+
+CABLING
+-------
+
+Use the APC Microlink serial cable appropriate for the UPS. USB-to-serial
+adapters can work if they present a standard TTY device to the operating
+system.
+
+
+AUTHORS
+-------
+
+* Lukas Schmid <lukas.schmid@netcube.li>
+
+
+SEE ALSO
+--------
+
+The core driver
+~~~~~~~~~~~~~~~
+
+linkman:nutupsdrv[8], linkman:ups.conf[5]
+
+Internet resources
+~~~~~~~~~~~~~~~~~~
+
+The NUT (Network UPS Tools) home page: https://www.networkupstools.org/

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3749 utf-8
+personal_ws-1.1 en 3761 utf-8
 AAC
 AAS
 ABI
@@ -708,6 +708,7 @@ LogMin
 LowBatt
 Loyer
 Luca
+Lukas
 Luxeon
 Lygre
 Lynge
@@ -1117,6 +1118,7 @@ RISC
 RK
 RMCARD
 RMCPplus
+RMI
 RMXL
 RNF
 RNG
@@ -1270,6 +1272,7 @@ Salvia
 Santinoli
 Savia
 Sawatzky
+Schmid
 Schmier
 Schoch
 Schonefeld
@@ -1646,6 +1649,7 @@ apc
 apcc
 apcd
 apcevilhack
+apcmicrolink
 apcsmart
 apctest
 apcupsd
@@ -1763,6 +1767,7 @@ bigups
 bindir
 binfmt
 binutils
+bitfield
 bitmapped
 bitmask
 bitness
@@ -1882,6 +1887,7 @@ cmdline
 cmdname
 cmdparam
 cmds
+cmdsrc
 cmdvartab
 cnf
 codebase
@@ -2400,6 +2406,7 @@ integrations
 intel
 intelliSenseMode
 intercharacter
+internalnetwork
 internet
 interoperability
 interoperate
@@ -2589,6 +2596,7 @@ localhost
 localip
 localport
 localtime
+localuser
 lockf
 logfacility
 logfile
@@ -3223,6 +3231,8 @@ sha
 shellcheck
 shellenv
 shm
+showinternals
+showunmapped
 shutdownArguments
 shutdowncmd
 shutdowndelay
@@ -3247,6 +3257,7 @@ slaveid
 slavesync
 slibtool
 sm
+smartslot
 smartups
 smbus
 sms
@@ -3411,6 +3422,7 @@ tempmax
 tempmin
 termios
 testime
+testinterval
 testtime
 testuser
 testvar

drivers/Makefile.am

@@ -147,7 +147,7 @@ endif HAVE_LIBREGEX
 NUTSW_DRIVERLIST_DUMMY_UPS = dummy-ups$(EXEEXT)
 NUTSW_DRIVERLIST = $(NUTSW_DRIVERLIST_DUMMY_UPS) \
  clone clone-outlet failover apcupsd-ups skel
-SERIAL_DRIVERLIST = al175 bcmxcp belkin belkinunv bestfcom	\
+SERIAL_DRIVERLIST = al175 apcmicrolink bcmxcp belkin belkinunv bestfcom	\
  bestfortress bestuferrups bestups etapro everups 	\
  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	\
@@ -234,6 +234,7 @@ upsdrvctl_LDADD = libdummy_upsdrvquery.la $(LDADD_COMMON)
 
 # serial drivers: all of them use standard LDADD and CFLAGS
 al175_SOURCES = al175.c
+apcmicrolink_SOURCES = apcmicrolink.c apcmicrolink-maps.c apc_common.c
 apcsmart_SOURCES = apcsmart.c apcsmart_tabs.c
 apcsmart_LDADD = $(LDADD_DRIVERS_SERIAL) $(LIBREGEX_LIBS)
 apcsmart_old_SOURCES = apcsmart-old.c
@@ -459,7 +460,7 @@ adelsystem_cbi_LDADD = $(LDADD_DRIVERS) $(LIBMODBUS_LIBS)
 # APC Modbus driver (with support of modbus over different media)
 # Note that a version of libmodbus built with USB support is also needed
 # for USB connections. Legacy versions work for Serial and TCP links.
-apc_modbus_SOURCES = apc_modbus.c
+apc_modbus_SOURCES = apc_modbus.c apc_common.c
 apc_modbus_LDADD = $(LDADD_DRIVERS) $(LIBMODBUS_LIBS)
 if WITH_MODBUS_USB
   apc_modbus_SOURCES += hidparser.c
@@ -539,7 +540,7 @@ dist_noinst_HEADERS = \
  powercom.h powerpanel.h powerp-bin.h powerp-txt.h powervar_cx.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 \
- apcsmart.h apcsmart_tabs.h apcsmart-old.h apcupsd-ups.h cyberpower-mib.h riello.h openups-hid.h \
+ apc_common.h apcmicrolink-maps.h apcmicrolink.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_gtec.h nutdrv_qx_innovart31.h nutdrv_qx_innovart33.h nutdrv_qx_innovatae.h	\
  nutdrv_qx_masterguard.h nutdrv_qx_mecer.h nutdrv_qx_ablerex.h	\