Adding a dummy-ups script to examples?

[sshambar]

I wrote a bash script to integrate my local Enphase's Envoy API (a simple JSON based local web API) with a dummy-ups driver's port file. I've just published it (GPLv3) at https://github.com/sshambar/enphase-monitor

The script is simple to use, and provides information on "grid" online/offline status, battery SOC, and several other details (like "load" and "runtime") from the Enphase system. I use it to integrate with current UPS + ATS (automatic transfer switch) to treat my house battery system as 2nd UPS. I didn't feel it merited writing a full driver as I'm not using it for FSD, outlet control or anything "interactive", I just didn't want my servers shutting down when my UPS failed (don't ask) and the house still had backup power. Plus it's nice to have another way to monitor the Enphase system using the NUT cgi programs...

The script is probably something others could use as an basis for integrating with similar web APIs using the dummy-ups as a hook to the NUT system, so I thought perhaps it made sense to add as an "example" script someplace in the source?

The script has nice features such as:

• retains existing/extra values in the port file
• gracefully handles split-phase or 3-phase input/output values
• handles no-comms with temporary rename of the port file (indicates "stale data")
• support portfile value customization (things like battery voltage range, or battery.charge.low for LB trigger)
• contains logic for login and token based API authentication, with automatic token renewal
• has it's own config for authentication and API query timing etc
• checks permissions on files that use secrets
• is fully self-documented (leading comment in the script)
• GPLv3 licensed
• minimal requirements: bash, jq, base64 and curl
• has details on setting up a systemd service to use with dummy-ups, and SELinux config
• includes a "TEST" mode that loops through various states and randomly expires the token
• ... and it's pretty well tested :)

I would have rather created a pull request against NUT, but I honestly don't know where I would add the file here... perhaps someone can suggest a directory if you think it might be useful.

In any case, anyone wanting to add Enphase local API support to NUT can use it as is.

PS. yes I know there's a "external" Enphase API, but it's request limits are severely restricted without paying a high fee...

[jimklimov]

Sounds interesting, thanks!

Some new entry under the scripts/ directory sounds right for this. You would need also a README.adoc to describe this script (e.g. with text above as a starting point), and a Makefile.am to EXTRA_DIST the new files and spellcheck the document. If it is about a couple of new files, maybe add the names to scripts/Makefile.am here and there.

Also a NEWS.adoc entry would be nice :)

Tech-wise, it may be hard to specify Data stale'ness with a state file like this, e.g. if the API client script dies off, but otherwise the idea seems viable for a small-scale PoC at least. NUT drivers started out with files to talk to upsd way back when :)

[sshambar]

Some new entry under the scripts/ directory sounds right for this. You would need also a README.adoc to describe this script (e.g. with text above as a starting point), and a Makefile.am to EXTRA_DIST the new files and spellcheck the document. If it is about a couple of new files, maybe add the names to scripts/Makefile.am here and there.

I can probably blend the description above with the existing README from the file comments... I'll have to research the .adoc format :) (btw, where there spelling mistakes I missed?)

Tech-wise, it may be hard to specify Data stale'ness with a state file like this, e.g. if the API client script dies off, but otherwise the idea seems viable for a small-scale PoC at least. NUT drivers started out with files to talk to upsd way back when :)

Yeah, the staleness was really designed to reflect the network connectivity to the API server, not the liveliness of the monitor, but that did give me a couple ideas:

A. I should probably have the monitor start "before" the dummy-ups driver with a ExecStartPre mode to disable the port-file, so any pre-shutdown (and now quite stale) state isn't exposed at startup, and connectivity is "proved" before a real ups.status is made available.

B. I could potentially offer a pull request for dummy-ups with a new "keyword" (TBD named, "ACTIVE_TIMEOUT"?) which would cause the driver to claim data "stale" if the modify-time wasn't changed by the stated timeout, proving an active file manager. Useful?

Unrelated, I noticed that to be "net-protocol" consistent, the float numbers need to be in "POSIX" format, and running the monitor in some locales (eg da_DK) would result in incorrect radix characters; so I'm fixing that...and I should map non-POSIX radix characters retrieved from the API as well...