Skip to content

Commit

Permalink
Merge pull request #2813 from sshambar/master
Browse files Browse the repository at this point in the history
scripts/external_apis: add example external protocol script
  • Loading branch information
jimklimov authored Feb 25, 2025
2 parents 53a539b + 0885680 commit 5e4b733
Show file tree
Hide file tree
Showing 12 changed files with 1,403 additions and 3 deletions.
1 change: 1 addition & 0 deletions Makefile.am
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,7 @@ spellcheck spellcheck-interactive:
(cd $(builddir)/scripts/Solaris && $(MAKE) $(AM_MAKEFLAGS) -s $@) || RES=$$? ; \
(cd $(builddir)/scripts/Windows && $(MAKE) $(AM_MAKEFLAGS) -s $@) || RES=$$? ; \
(cd $(builddir)/scripts/devd && $(MAKE) $(AM_MAKEFLAGS) -s $@) || RES=$$? ; \
(cd $(builddir)/scripts/external_apis && $(MAKE) $(AM_MAKEFLAGS) -s $@) || RES=$$? ; \
(cd $(builddir)/scripts/hotplug && $(MAKE) $(AM_MAKEFLAGS) -s $@) || RES=$$? ; \
(cd $(builddir)/scripts/installer && $(MAKE) $(AM_MAKEFLAGS) -s $@) || RES=$$? ; \
(cd $(builddir)/scripts/python && $(MAKE) $(AM_MAKEFLAGS) -s $@) || RES=$$? ; \
Expand Down
3 changes: 3 additions & 0 deletions NEWS.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ https://github.com/networkupstools/nut/milestone/9

- (expected) Bug fixes for fallout possible due to "fightwarn" effort in 2.8.0+

- added `scripts/external_apis` with an example script integrating a
non-native protocol with NUT; that example can be installed using
`configure --enable-extapi-enphase`. [issue #2807, PR #2813]

PLANNED: Release notes for NUT 2.8.3 - what's new since 2.8.2
-------------------------------------------------------------
Expand Down
38 changes: 37 additions & 1 deletion configure.ac
Original file line number Diff line number Diff line change
Expand Up @@ -5465,6 +5465,39 @@ dnl Use these at best for tests (e.g. nutconf), not production code:
AC_DEFINE_UNQUOTED([ABS_TOP_SRCDIR], ["${ABS_TOP_SRCDIR}"], [NUT source directory when the build was configured])
AC_DEFINE_UNQUOTED([ABS_TOP_BUILDDIR], ["${ABS_TOP_BUILDDIR}"], [NUT build directory when the build was configured])

AC_MSG_CHECKING([whether to install External API integration script: Enphase Monitor])
nut_with_extapi_enphase="no"
AC_ARG_ENABLE([extapi-enphase],
AS_HELP_STRING([--enable-extapi-enphase=(yes|auto|no)], [Enable installation of integration script for External API: Enphase Monitor (default: no)]),
[
case "${enableval}" in
yes|"")
nut_enable_extapi_enphase="auto"
;;
auto|no)
nut_enable_extapi_enphase="${enableval}"
;;
*)
AC_MSG_ERROR([Unexpected argument for --enable-extapi-enphase=${enableval}])
;;
esac
], [])

if test x"$nut_enable_extapi_enphase" != xno ; then
dnl Depends on usability of further programs and bash version
dnl Luckily the script checks that itself, before handling CLI args
/usr/bin/env bash "${ABS_TOP_SRCDIR}/scripts/external_apis/enphase/enphase-monitor.in" --help >/dev/null \
&& nut_can_extapi_enphase="yes" \
|| nut_can_extapi_enphase="no"

if test x"$nut_enable_extapi_enphase" = xyes && x"$nut_can_extapi_enphase" = xno ; then
AC_MSG_ERROR([Caller required installation --enable-extapi-enphase but the system can not run it])
fi
nut_enable_extapi_enphase="${nut_can_extapi_enphase}"
fi
AC_MSG_RESULT([${nut_enable_extapi_enphase}])
AM_CONDITIONAL(ENABLE_EXTAPI_ENPHASE, test x"$nut_enable_extapi_enphase" = x"yes")

AC_MSG_CHECKING([whether to customize ${TOP_BUILDDIR}/scripts/systemd/nut-common-tmpfiles.conf.in for this system])
dnl TOTHINK: Some distributions make the directories below owned
dnl by "root:${RUN_AS_GROUP}" with 77x permissions. Is it safer?..
Expand Down Expand Up @@ -5685,6 +5718,8 @@ AC_CONFIG_FILES([
scripts/augeas/nutupssetconf.aug
scripts/avahi/nut.service
scripts/devd/Makefile
scripts/external_apis/Makefile
scripts/external_apis/enphase/[email protected]
scripts/hotplug/Makefile
scripts/hotplug/libhidups
scripts/HP-UX/nut.psf
Expand Down Expand Up @@ -5738,9 +5773,10 @@ m4_foreach_w([SCRIPTFILE], [
scripts/HP-UX/postinstall
scripts/RedHat/upsd
scripts/RedHat/upsmon
scripts/augeas/gen-nutupsconf-aug.py
scripts/external_apis/enphase/enphase-monitor
scripts/python/app/NUT-Monitor-py2gtk2
scripts/python/app/NUT-Monitor-py3qt5
scripts/augeas/gen-nutupsconf-aug.py
scripts/python/module/test_nutclient.py
scripts/upsdrvsvcctl/nut-driver-enumerator.sh
scripts/upsdrvsvcctl/upsdrvsvcctl
Expand Down
25 changes: 25 additions & 0 deletions docs/configure.txt
Original file line number Diff line number Diff line change
Expand Up @@ -619,6 +619,31 @@ Change the facility used when writing to the log file. Read the man
page for `openlog` to get some idea of what's available on your system.
Default is `LOG_DAEMON`.

External API integration scripts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sometimes as a developer or user you need to interact with a device for
which a "proper" NUT driver does not yet exist (or is not in your version),
but some proof-of-concept script can be good enough to collect some data.

In some cases, an UPS does not support local monitoring at all, but has
a network port for cloud-based monitoring through its vendor's portal.

Such data can be converted and fed into the NUT `dummy-ups` driver, and so
represented in the NUT ecosystem, by rewriting the "sequence" file whose
contents it processes in a loop (see linkman:dummy-ups[8] for more details).

NUT provides sample scripts for such integration, which can be used if you
have a suitable use-case, or provide inspiration for you to begin experiments
with a new device and (as often happens) a shell or Python script polling
it for information. For more details, see `scripts/external_apis` in NUT
sources (and pull requests with more integrations would be welcome there).

--enable-extapi-enphase=(yes|auto|no)

Enable installation of integration script for External API: Enphase Monitor
(default: no)


Installation directories
------------------------
Expand Down
30 changes: 29 additions & 1 deletion docs/nut.dict
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
personal_ws-1.1 en 3289 utf-8
personal_ws-1.1 en 3317 utf-8
AAC
AAS
ABI
Expand Down Expand Up @@ -347,11 +347,13 @@ Eltek
Emilien
Energia
EnergySaving
Enphase's
Erikson
Eriksson
Evgeny
Exar
ExecCGI
ExecStart
ExecStartPre
FD
FEMEA
Expand Down Expand Up @@ -409,6 +411,7 @@ GNUmakefile
GObject
GPIO
GPL
GPLv
GPSER
GRs
GTK
Expand Down Expand Up @@ -539,6 +542,7 @@ JRE
JSON
JVM
JW
JWT
Jageson
Jarosch
Jasuny
Expand Down Expand Up @@ -605,7 +609,9 @@ LISTRW
LISTVARS
LLDB
LLNC
LOADKWH
LOADPCT
LOCALSTATE
LOCKFN
LOCKNAME
LOTRANS
Expand Down Expand Up @@ -898,6 +904,7 @@ PaaS
Pac
PackageRequired
Parisi
PartOf
Patrik
Pavel
Pawe
Expand Down Expand Up @@ -1038,6 +1045,7 @@ René
Repotec's
Repoteck
RequireAny
RestartSec
Richthof
Rickard
Ridgway
Expand All @@ -1063,12 +1071,14 @@ SDE
SDFLAG
SDR
SDT
SECCTRL
SELFTEST
SELinux
SENTR
SER
SERIALNO
SERVER's
SESS
SETFL
SETINFOs
SETLK
Expand Down Expand Up @@ -1116,6 +1126,7 @@ SPECs
SPLY
SPS
SRC
SSD
SSSS
STARTTLS
STB
Expand Down Expand Up @@ -1157,6 +1168,7 @@ SerialNumber
Serv
Serveur
SetRWVar
Shambarger
Shara
ShareAlike
Shaul
Expand Down Expand Up @@ -1492,6 +1504,7 @@ apcupsd
aphel
api
apinames
apis
appveyor
ar
architecting
Expand Down Expand Up @@ -1630,6 +1643,7 @@ bypassOff
bypassOn
cStandard
cablepower
calc
calloc
cb
cbe
Expand Down Expand Up @@ -1698,6 +1712,7 @@ collectd
command's
commandlen
committer
comms
compat
compilerPath
conf
Expand Down Expand Up @@ -1888,6 +1903,7 @@ endl
energizerups
energysave
english
enphase
enum
env
envvar
Expand All @@ -1913,6 +1929,7 @@ execfuse
executables
executeCommand
execve
extapi
extern
externalConsole
extradata
Expand All @@ -1924,6 +1941,7 @@ fatalx
fc
fcb
fcntl
fcontext
fd
fdX
fds
Expand Down Expand Up @@ -2163,6 +2181,7 @@ ish
iso
isolator
iter
ivp
ivtscd
jNUT
jNut
Expand All @@ -2175,6 +2194,7 @@ jimklimov
journalctl
jpeg
jpg
jq
jre
json
kVA
Expand Down Expand Up @@ -2281,6 +2301,7 @@ linuxdoc
lipo
listDeviceClients
littleguy
livedata
lk
lldb
llvm
Expand Down Expand Up @@ -2471,6 +2492,7 @@ noAuthNoPriv
nobody's
nobreak
nobt
nocomms
nodev
nodownload
noexec
Expand Down Expand Up @@ -2552,6 +2574,7 @@ openlog
openmp
openssh
openssl
oper
optimizations
optiups
oq
Expand Down Expand Up @@ -2619,6 +2642,8 @@ pollfreq
pollinterval
pollonly
popa
portfile
portfiles
portname
porttype
posix
Expand Down Expand Up @@ -2729,6 +2754,7 @@ repotec
req
resetter
resolv
restoreconf
resync
ret
retrydelay
Expand Down Expand Up @@ -2793,11 +2819,13 @@ se
searchable
secLevel
secName
secctrl
secretpass
securityLevel
securityName
sed
selftest
semanage
semver
sendback
sendline
Expand Down
2 changes: 1 addition & 1 deletion scripts/Makefile.am
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ EXTRA_DIST = \
Windows/halt.c \
Windows/Makefile

SUBDIRS = augeas devd hotplug installer python systemd udev ufw Solaris Windows upsdrvsvcctl
SUBDIRS = augeas devd hotplug installer python systemd udev ufw Solaris Windows upsdrvsvcctl external_apis

SPELLCHECK_SRC = README.adoc RedHat/README.adoc usb_resetter/README.adoc valgrind/README.adoc

Expand Down
53 changes: 53 additions & 0 deletions scripts/external_apis/Makefile.am
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Network UPS Tools: scripts/external_apis

EXTRA_DIST = \
README.adoc \
enphase/README.adoc \
enphase/enphase-monitor.in \
enphase/[email protected]

SPELLCHECK_SRC = README.adoc enphase/README.adoc

# Handle optional installation:
if ENABLE_EXTAPI_ENPHASE

extapi_enphase_datadir = @datadir@/external_apis/enphase
extapi_enphase_data_DATA = enphase/README.adoc

extapi_enphase_execdir = @libexec@
extapi_enphase_exec_SCRIPTS = enphase/enphase-monitor

if HAVE_SYSTEMD

systemdsystemunit_DATA = \
enphase/[email protected]

endif HAVE_SYSTEMD

endif ENABLE_EXTAPI_ENPHASE

# NOTE: Due to portability, we do not use a GNU percent-wildcard extension.
# We also have to export some variables that may be tainted by relative
# paths when parsing the other makefile (e.g. MKDIR_P that may be defined
# via expanded $(top_builddir)/install-sh):
#%-spellchecked: % Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT)
# +$(MAKE) -s -f $(top_builddir)/docs/Makefile $(AM_MAKEFLAGS) MKDIR_P="$(MKDIR_P)" builddir="$(builddir)" srcdir="$(srcdir)" top_builddir="$(top_builddir)" top_srcdir="$(top_srcdir)" SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@

# NOTE: Portable suffix rules do not allow prerequisites, so we shim them here
# by a wildcard target in case the make implementation can put the two together.
*-spellchecked: Makefile.am $(top_srcdir)/docs/Makefile.am $(abs_srcdir)/$(NUT_SPELL_DICT)

.sample.sample-spellchecked:
+$(MAKE) -s -f $(top_builddir)/docs/Makefile $(AM_MAKEFLAGS) MKDIR_P="$(MKDIR_P)" builddir="$(builddir)" srcdir="$(srcdir)" top_builddir="$(top_builddir)" top_srcdir="$(top_srcdir)" SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@

.in.in-spellchecked:
+$(MAKE) -s -f $(top_builddir)/docs/Makefile $(AM_MAKEFLAGS) MKDIR_P="$(MKDIR_P)" builddir="$(builddir)" srcdir="$(srcdir)" top_builddir="$(top_builddir)" top_srcdir="$(top_srcdir)" SPELLCHECK_SRC_ONE="$<" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@

spellcheck spellcheck-interactive spellcheck-sortdict:
+$(MAKE) -f $(top_builddir)/docs/Makefile $(AM_MAKEFLAGS) MKDIR_P="$(MKDIR_P)" builddir="$(builddir)" srcdir="$(srcdir)" top_builddir="$(top_builddir)" top_srcdir="$(top_srcdir)" SPELLCHECK_SRC="$(SPELLCHECK_SRC)" SPELLCHECK_SRCDIR="$(srcdir)" SPELLCHECK_BUILDDIR="$(builddir)" $@

CLEANFILES = *-spellchecked enphase/*-spellchecked \
enphase/enphase-monitor \
enphase/[email protected]

MAINTAINERCLEANFILES = Makefile.in .dirstamp
Loading

0 comments on commit 5e4b733

Please sign in to comment.