Merge 38a242f into eb08bd4

Author: libschmudie-so

NEWS.adoc

@@ -42,6 +42,10 @@ https://github.com/networkupstools/nut/milestone/13
  - (expected) CI automation for use of data points in drivers that conform
    to patterns defined in link:docs/nut-names.txt[]
 
+ - 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]
+ 
  - Second-level bullet points listed in this file will now use 4 spaces
    (not 3 like before) for easier initial indentation of new entries.
 

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

@@ -976,6 +976,7 @@ endif
 # (--with-serial)
 SRC_SERIAL_PAGES = \
 	al175.txt	\
+	apcmicrolink.txt	\
 	apcsmart.txt	\
 	apcsmart-old.txt	\
 	bcmxcp.txt 	\
@@ -1030,6 +1031,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) 	\
@@ -1148,6 +1150,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,131 @@
+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.
+
+
+IMPLEMENTED FEATURES
+--------------------
+
+The driver publishes standard identity, status, runtime and outlet-group data
+when these objects are present in the Microlink descriptor.
+
+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`
+* `battery.testinterval`
+* `outlet.group.N.oncountdown`
+* `outlet.group.N.offcountdown`
+* `outlet.group.N.stayoffcountdown`
+* `outlet.group.N.minimumreturnruntime`
+* `outlet.group.N.lowruntimewarning`
+
+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 3734 utf-8
+personal_ws-1.1 en 3741 utf-8
 AAC
 AAS
 ABI
@@ -705,6 +705,7 @@ LogMin
 LowBatt
 Loyer
 Luca
+Lukas
 Luxeon
 Lygre
 Lynge
@@ -1113,6 +1114,7 @@ RISC
 RK
 RMCARD
 RMCPplus
+RMI
 RMXL
 RNF
 RNG
@@ -1265,6 +1267,7 @@ Salvia
 Santinoli
 Savia
 Sawatzky
+Schmid
 Schmier
 Schoch
 Schonefeld
@@ -1640,6 +1643,7 @@ apc
 apcc
 apcd
 apcevilhack
+apcmicrolink
 apcsmart
 apctest
 apcupsd
@@ -3209,6 +3213,8 @@ sha
 shellcheck
 shellenv
 shm
+showinternals
+showunmapped
 shutdownArguments
 shutdowncmd
 shutdowndelay
@@ -3397,6 +3403,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
 apcsmart_SOURCES = apcsmart.c apcsmart_tabs.c
 apcsmart_LDADD = $(LDADD_DRIVERS_SERIAL) $(LIBREGEX_LIBS)
 apcsmart_old_SOURCES = apcsmart-old.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 \
+ 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	\