Merge f72ab53 into d96f518

Author: libschmudie-so

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

@@ -975,6 +975,7 @@ endif
 # (--with-serial)
 SRC_SERIAL_PAGES = \
 	al175.txt	\
+	apcmicrolink.txt	\
 	apcsmart.txt	\
 	apcsmart-old.txt	\
 	bcmxcp.txt 	\
@@ -1029,6 +1030,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) 	\

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/

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