Skip to content

Commit 0e6bd27

Browse files
libschmudie-solibschmudie-so
committed
drivers: add experimental APC Microlink serial driver
Implement a new apcmicrolink driver for APC Smart-UPS units that expose the Microlink serial protocol. The driver establishes a Microlink session over the serial link, reads the device descriptor blob, and uses that runtime descriptor map to publish standard NUT variables, writable settings, status bits, alarms, and supported instant commands. Add labeled Microlink command masks for battery tests, calibration, UPS control, and outlet-group power control; wire APC-style load and shutdown commands through the static command map; publish input.transfer.reason from UPS status change cause; and stop folding simple-signaling status bits into ups.status. Also hook upsdrv_shutdown() up to the Microlink shutdown request, document the driver, and clean up initial upstream review issues such as missing file headers, whitespace, and format-string warnings. Signed-off-by: Lukas Schmid <lukas.schmid@netcube.li>
1 parent d96f518 commit 0e6bd27

8 files changed

Lines changed: 2987 additions & 1 deletion

File tree

‎data/driver.list.in‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@
8080
"APC" "ups" "1" "Matrix-UPS" "" "apcsmart"
8181
"APC" "ups" "1" "Smart-UPS" "" "apcsmart"
8282
"APC" "ups" "1" "Smart-UPS SMT/SMX/SURTD" "Microlink models with RJ45 socket - they *require* AP9620 SmartSlot expansion card and smart cable" "apcsmart"
83+
"APC" "ups" "1" "Smart-UPS SMT/SMX Microlink" "Microlink serial driver" "apcmicrolink"
8384
"APC" "ups" "3" "Back-UPS Pro USB" "USB" "usbhid-ups"
8485
"APC" "ups" "3" "Back-UPS BK650M2-CH" "USB" "usbhid-ups" # https://github.com/networkupstools/nut/issues/1970
8586
"APC" "ups" "3" "Back-UPS (USB)" "USB" "usbhid-ups"

‎docs/man/Makefile.am‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -975,6 +975,7 @@ endif
975975
# (--with-serial)
976976
SRC_SERIAL_PAGES = \
977977
al175.txt \
978+
apcmicrolink.txt \
978979
apcsmart.txt \
979980
apcsmart-old.txt \
980981
bcmxcp.txt \
@@ -1029,6 +1030,7 @@ SRC_SERIAL_PAGES = \
10291030

10301031
INST_MAN_SERIAL_PAGES = \
10311032
al175.$(MAN_SECTION_CMD_SYS) \
1033+
apcmicrolink.$(MAN_SECTION_CMD_SYS) \
10321034
apcsmart.$(MAN_SECTION_CMD_SYS) \
10331035
apcsmart-old.$(MAN_SECTION_CMD_SYS) \
10341036
bcmxcp.$(MAN_SECTION_CMD_SYS) \

‎docs/man/apcmicrolink.txt‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
APCMICROLINK(8)
2+
===============
3+
4+
NAME
5+
----
6+
7+
apcmicrolink - Driver for APC Smart-UPS units using the Microlink serial protocol
8+
9+
SYNOPSIS
10+
--------
11+
12+
*apcmicrolink* -h
13+
14+
*apcmicrolink* -a 'UPS_NAME' ['OPTIONS']
15+
16+
NOTE: This man page documents the hardware-specific features of the
17+
*apcmicrolink* driver. For general information about NUT drivers, see
18+
linkman:nutupsdrv[8].
19+
20+
21+
DESCRIPTION
22+
-----------
23+
24+
The *apcmicrolink* driver talks the APC Microlink protocol used by newer
25+
serial-connected Smart-UPS families such as SMT and SMX units with the
26+
Microlink RJ45 serial port.
27+
28+
This driver is currently experimental. It discovers most values from the
29+
device descriptor blob at runtime and maps supported Microlink objects onto
30+
standard NUT variables where possible. Unknown descriptor fields can also be
31+
published for debugging and reverse-engineering.
32+
33+
34+
SUPPORTED HARDWARE
35+
------------------
36+
37+
This driver is intended for APC Smart-UPS models that expose the Microlink
38+
serial protocol, notably SMT and SMX units with the vendor Microlink serial
39+
cable.
40+
41+
Tested support currently targets:
42+
43+
* APC Smart-UPS SMT/SMX Microlink models
44+
45+
Other APC Microlink devices may work if they expose a compatible descriptor
46+
layout.
47+
48+
49+
CONFIGURATION
50+
-------------
51+
52+
The driver is configured via linkman:ups.conf[5].
53+
54+
A minimal configuration:
55+
56+
----
57+
[apc-microlink]
58+
driver = apcmicrolink
59+
port = /dev/ttyUSB0
60+
----
61+
62+
Optional settings
63+
~~~~~~~~~~~~~~~~~
64+
65+
*baudrate*='num'::
66+
Set the serial line speed. The default is `9600`.
67+
68+
*showinternals*='yes|no'::
69+
Publish additional internal Microlink runtime values. By default this follows
70+
the driver debug level and is enabled automatically when debug logging is on.
71+
72+
*showunmapped*='yes|no'::
73+
Publish descriptor values that do not currently map to a standard NUT variable.
74+
By default this follows the driver debug level and is enabled automatically
75+
when debug logging is on.
76+
77+
78+
IMPLEMENTED FEATURES
79+
--------------------
80+
81+
The driver publishes standard identity, status, runtime and outlet-group data
82+
when these objects are present in the Microlink descriptor.
83+
84+
Writable descriptor-backed variables are exposed as read-write NUT variables
85+
when the device reports them as modifiable. Depending on the connected model,
86+
this can include values such as:
87+
88+
* `ups.id`
89+
* `battery.testinterval`
90+
* `outlet.group.N.oncountdown`
91+
* `outlet.group.N.offcountdown`
92+
* `outlet.group.N.stayoffcountdown`
93+
* `outlet.group.N.minimumreturnruntime`
94+
* `outlet.group.N.lowruntimewarning`
95+
96+
Supported instant commands currently include:
97+
98+
* `test.battery.start`
99+
* `test.battery.stop`
100+
* `test.panel.start`
101+
* `test.panel.stop`
102+
103+
Driver-assisted shutdown is not yet implemented.
104+
105+
106+
CABLING
107+
-------
108+
109+
Use the APC Microlink serial cable appropriate for the UPS. USB-to-serial
110+
adapters can work if they present a standard TTY device to the operating
111+
system.
112+
113+
114+
AUTHORS
115+
-------
116+
117+
* Lukas Schmid <lukas.schmid@netcube.li>
118+
119+
120+
SEE ALSO
121+
--------
122+
123+
The core driver
124+
~~~~~~~~~~~~~~~
125+
126+
linkman:nutupsdrv[8], linkman:ups.conf[5]
127+
128+
Internet resources
129+
~~~~~~~~~~~~~~~~~~
130+
131+
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/

‎drivers/Makefile.am‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,7 @@ endif HAVE_LIBREGEX
147147
NUTSW_DRIVERLIST_DUMMY_UPS = dummy-ups$(EXEEXT)
148148
NUTSW_DRIVERLIST = $(NUTSW_DRIVERLIST_DUMMY_UPS) \
149149
clone clone-outlet failover apcupsd-ups skel
150-
SERIAL_DRIVERLIST = al175 bcmxcp belkin belkinunv bestfcom \
150+
SERIAL_DRIVERLIST = al175 apcmicrolink bcmxcp belkin belkinunv bestfcom \
151151
bestfortress bestuferrups bestups etapro everups \
152152
gamatronic genericups isbmex liebert liebert-esp2 liebert-gxe masterguard metasys \
153153
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)
234234

235235
# serial drivers: all of them use standard LDADD and CFLAGS
236236
al175_SOURCES = al175.c
237+
apcmicrolink_SOURCES = apcmicrolink.c apcmicrolink-maps.c
237238
apcsmart_SOURCES = apcsmart.c apcsmart_tabs.c
238239
apcsmart_LDADD = $(LDADD_DRIVERS_SERIAL) $(LIBREGEX_LIBS)
239240
apcsmart_old_SOURCES = apcsmart-old.c

0 commit comments

Comments
 (0)