EATON HID: add missing usages and paths

NEWS.adoc

@@ -203,6 +203,19 @@ https://github.com/networkupstools/nut/milestone/11
    approach seems to have good potential to expand into covering more devices
    and perhaps platforms. [#2430]
 
+ - Introduced `ECO` status concept for "ECO mode" (or "High Efficiency" mode,
+   or "Energy Saver System"...) as named and defined by hardware vendors.
+   One common aspect is that this is a balance of electrical efficiency vs.
+   robust outage protection (which may be overkill for IT equipment whose
+   PSU can survive several milliseconds on capacitors alone) which can be
+   selected at run-time.  Previously such choice was made at the time of
+   purchase, with the UPSes only supporting some one protection strategy.
+   [issue #2495, PR #2637]
+   * Updated documentation, end-user clients (CGI, NUT-Monitor UI);
+   * Updated `upsmon` client with ability to report entering and exiting
+     the ECO mode if reported by the driver;
+   * Initial implementation for Eaton devices with `usbhid-ups` driver.
+
  - upsmon:
    * it was realized that the `POWERDOWNFLAG` must be explicitly set in the
      configuration file, there is no built-in default in the binary program

clients/status.h

@@ -45,6 +45,7 @@ static struct {
 	{ "BOOST",	"VOLTAGE BOOST",	1	},
 	{ "CAL",	"CALIBRATION",		1	},
 	{ "BYPASS",	"BYPASS",		2	},
+	{ "ECO",	"ECO",			2	},
 	{ NULL,		NULL,			0	}
 };
 

clients/upsmon.c

@@ -189,7 +189,9 @@ static int flag_isset(int num, int flag)
 
 static int try_restore_pollfreq(utype_t *ups) {
 	/* Use relaxed pollfreq if we are not in a hardware
-	 * power state that is prone to UPS disappearance */
+	 * power state that is prone to UPS disappearance.
+	 * Note: ECO mode not considered easily fatal here!
+	 */
 	if (!flag_isset(ups->status, ST_ONBATT | ST_OFF | ST_BYPASS | ST_CAL)) {
 		sleepval = pollfreq;
 		return 1;
@@ -713,6 +715,42 @@ static void ups_is_notbypass(utype_t *ups)
 	}
 }
 
+static void ups_is_eco(utype_t *ups)
+{
+	if (flag_isset(ups->status, ST_ECO)) {	/* no change */
+		upsdebugx(4, "%s: %s (no change)", __func__, ups->sys);
+		return;
+	}
+
+	/* For example, Eaton defines ECO (High Efficiency) mode
+	 * as a sort of hardware-monitored bypass with switch-over
+	 * under 10ms into Online mode in case of troubles, instead
+	 * of always running in dual-conversion mode (wasteful, safe).
+	 * No reason to monitor it closely on NUT side.
+	 */
+	/*sleepval = pollfreqalert;*/	/* bump up polling frequency */
+
+	ups->ecostate = 1;	/* if we lose comms, consider it AWOL */
+
+	upsdebugx(3, "%s: %s (first time)", __func__, ups->sys);
+
+	/* must have changed from !ECO to ECO, so notify */
+
+	do_notify(ups, NOTIFY_ECO);
+	setflag(&ups->status, ST_ECO);
+}
+
+static void ups_is_noteco(utype_t *ups)
+{
+	/* Called when ECO is NOT among known states */
+	ups->ecostate = 0;
+	if (flag_isset(ups->status, ST_ECO)) {	/* actual change */
+		do_notify(ups, NOTIFY_NOTECO);
+		clearflag(&ups->status, ST_ECO);
+		try_restore_pollfreq(ups);
+	}
+}
+
 static void ups_on_batt(utype_t *ups)
 {
 	if (flag_isset(ups->status, ST_ONBATT)) { 	/* no change */
@@ -1092,6 +1130,7 @@ static int is_ups_critical(utype_t *ups)
 	time(&now);
 
 	if (ups->commstate == 0) {
+		/* Note: ECO mode not considered easily fatal here */
 		if (flag_isset(ups->status, ST_CAL)) {
 			upslogx(LOG_WARNING,
 				"UPS [%s] was last known to be calibrating "
@@ -1298,6 +1337,7 @@ static void recalc(void)
 		 * whether this is really the best thing to do is undecided  */
 
 		/* crit = (FSD) || (OB & LB) > HOSTSYNC seconds || (OFF || BYPASS) && nocomms */
+		/* Note: ECO mode not considered easily fatal here */
 		if (is_ups_critical(ups))
 			upsdebugx(1, "Critical UPS: %s", ups->sys);
 		else
@@ -1397,6 +1437,10 @@ static void drop_connection(utype_t *ups)
 	if(flag_isset(ups->status, ST_CAL))
 		upsdebugx(2, "Disconnected UPS [%s] was last seen in status CAL, this UPS might be considered critical later.", ups->sys);
 
+	/* Note: ECO mode not considered easily fatal here */
+	if(ups->ecostate == 1 || flag_isset(ups->status, ST_ECO))
+		upsdebugx(2, "Disconnected UPS [%s] was last seen in status ECO.", ups->sys);
+
 	ups->commstate = 0;
 
 	/* forget poll-failure logging throttling */
@@ -2347,6 +2391,8 @@ static void parse_status(utype_t *ups, char *status)
 		ups_is_notoff(ups);
 	if (!strstr(status, "BYPASS"))
 		ups_is_notbypass(ups);
+	if (!strstr(status, "ECO"))
+		ups_is_noteco(ups);
 
 	statword = status;
 
@@ -2372,6 +2418,8 @@ static void parse_status(utype_t *ups, char *status)
 			ups_is_off(ups);
 		if (!strcasecmp(statword, "BYPASS"))
 			ups_is_bypass(ups);
+		if (!strcasecmp(statword, "ECO"))
+			ups_is_eco(ups);
 		/* do it last to override any possible OL */
 		if (!strcasecmp(statword, "FSD"))
 			ups_fsd(ups);

clients/upsmon.h

@@ -36,6 +36,7 @@
 #define ST_CAL         (1 << 7)       /* UPS calibration in progress (CAL)        */
 #define ST_OFF         (1 << 8)       /* UPS is administratively off or asleep (OFF) */
 #define ST_BYPASS      (1 << 9)       /* UPS is on bypass so not protecting       */
+#define ST_ECO         (1 << 10)      /* UPS is in ECO (High Efficiency) mode or similar tweak, e.g. Energy Saver System mode */
 
 /* required contents of flag file */
 #define SDMAGIC "upsmon-shutdown-file"
@@ -69,6 +70,8 @@ typedef struct {
 					/* be delayed vs. seeing OFF state	*/
 	int	bypassstate;		/* fire on a 0->1 transition;	*/
 					/* delays not implemented now	*/
+	int	ecostate;		/* fire on a 0->1 transition;	*/
+					/* delays not implemented now	*/
 
 	/* see detailed comment for pollfail_log_throttle_max in upsmon.c
 	 * about handling of poll failure log throttling (syslog storage I/O)
@@ -93,7 +96,7 @@ typedef struct {
 #define NOTIFY_ONBATT	1	/* UPS went on battery                  */
 #define NOTIFY_LOWBATT	2	/* UPS went to low battery              */
 #define NOTIFY_FSD	3	/* Primary upsmon set FSD flag          */
-#define NOTIFY_COMMOK	4	/* Communication established	            */
+#define NOTIFY_COMMOK	4	/* Communication established            */
 #define NOTIFY_COMMBAD	5	/* Communication lost                   */
 #define NOTIFY_SHUTDOWN	6	/* System shutdown in progress          */
 #define NOTIFY_REPLBATT	7	/* UPS battery needs to be replaced     */
@@ -105,6 +108,8 @@ typedef struct {
 #define NOTIFY_NOTOFF	13	/* UPS is not anymore administratively OFF or asleep*/
 #define NOTIFY_BYPASS	14	/* UPS is administratively on bypass    */
 #define NOTIFY_NOTBYPASS	15	/* UPS is not anymore administratively on bypass    */
+#define NOTIFY_ECO	16	/* UPS is in ECO mode or similar        */
+#define NOTIFY_NOTECO	17	/* UPS is not anymore in ECO mode or similar */
 
 #define NOTIFY_SUSPEND_STARTING	30	/* OS is entering sleep/suspend/hibernate slumber mode, and we know it   */
 #define NOTIFY_SUSPEND_FINISHED	31	/* OS just finished sleep/suspend/hibernate slumber mode, and we know it */
@@ -153,6 +158,8 @@ static struct {
 	{ NOTIFY_NOTOFF,   "NOTOFF",   NULL, "UPS %s: no longer administratively OFF or asleep", NOTIFY_DEFAULT },
 	{ NOTIFY_BYPASS,   "BYPASS",   NULL, "UPS %s: on bypass (powered, not protecting)", NOTIFY_DEFAULT },
 	{ NOTIFY_NOTBYPASS,"NOTBYPASS",NULL, "UPS %s: no longer on bypass", NOTIFY_DEFAULT },
+	{ NOTIFY_ECO,      "ECO",      NULL, "UPS %s: in ECO mode (as defined by vendor)", NOTIFY_DEFAULT },
+	{ NOTIFY_NOTECO,   "NOTECO",   NULL, "UPS %s: no longer in ECO mode", NOTIFY_DEFAULT },
 
 	{ NOTIFY_SUSPEND_STARTING, "SUSPEND_STARTING", NULL, "OS is entering sleep/suspend/hibernate mode", NOTIFY_DEFAULT },
 	{ NOTIFY_SUSPEND_FINISHED, "SUSPEND_FINISHED", NULL, "OS just finished sleep/suspend/hibernate mode, de-activating obsolete UPS readings to avoid an unfortunate shutdown", NOTIFY_DEFAULT },

common/nutconf.cpp

@@ -1316,6 +1316,10 @@ UpsmonConfiguration::NotifyType UpsmonConfiguration::NotifyTypeFromString(const
 		return NOTIFY_BYPASS;
 	else if(str=="NOTBYPASS")
 		return NOTIFY_NOTBYPASS;
+	else if(str=="ECO")
+		return NOTIFY_ECO;
+	else if(str=="NOTECO")
+		return NOTIFY_NOTECO;
 	else if(str=="SUSPEND_STARTING")
 		return NOTIFY_SUSPEND_STARTING;
 	else if(str=="SUSPEND_FINISHED")

common/nutwriter.cpp

@@ -404,6 +404,8 @@ const NotifyFlagsStrings::TypeStrings NotifyFlagsStrings::type_str = {
 	"NOTOFF",	// NOTIFY_NOTOFF
 	"BYPASS",	// NOTIFY_BYPASS
 	"NOTBYPASS",	// NOTIFY_NOTBYPASS
+	"ECO\t",	// NOTIFY_ECO (including padding)
+	"NOTECO",	// NOTIFY_NOTECO
 	"SUSPEND_STARTING",	// NOTIFY_SUSPEND_STARTING
 	"SUSPEND_FINISHED",	// NOTIFY_SUSPEND_FINISHED
 };

conf/upsmon.conf.sample.in

@@ -332,6 +332,8 @@ POWERDOWNFLAG "@POWERDOWNFLAG@"
 # NOTIFYMSG NOTOFF	"UPS %s: no longer administratively OFF or asleep"
 # NOTIFYMSG BYPASS	"UPS %s: on bypass (powered, not protecting)"
 # NOTIFYMSG NOTBYPASS	"UPS %s: no longer on bypass"
+# NOTIFYMSG ECO		"UPS %s: in ECO mode (as defined by vendor)"
+# NOTIFYMSG NOTECO	"UPS %s: no longer in ECO mode (as defined by vendor)"
 #
 # A few messages not directly related to UPS events are also available:
 #
@@ -379,6 +381,8 @@ POWERDOWNFLAG "@POWERDOWNFLAG@"
 # NOTIFYFLAG NOTOFF	SYSLOG+WALL
 # NOTIFYFLAG BYPASS	SYSLOG+WALL
 # NOTIFYFLAG NOTBYPASS	SYSLOG+WALL
+# NOTIFYFLAG ECO	SYSLOG+WALL
+# NOTIFYFLAG NOTECO	SYSLOG+WALL
 #
 # NOTIFYFLAG SUSPEND_STARTING	SYSLOG+WALL
 # NOTIFYFLAG SUSPEND_FINISHED	SYSLOG+WALL

data/cmdvartab

@@ -67,6 +67,10 @@ VARDESC input.transfer.low.min "smallest settable low voltage transfer point (V)
 VARDESC input.transfer.low.max "greatest settable low voltage transfer point (V)"
 VARDESC input.transfer.high.min "smallest settable high voltage transfer point (V)"
 VARDESC input.transfer.high.max "greatest settable high voltage transfer point (V)"
+VARDESC input.eco.switchable "Input High Efficiency (aka ECO) mode switch"
+VARDESC input.transfer.forced "Input forced transfer modes enable/disable"
+VARDESC input.bypass.switch.on "Put the UPS in bypass mode"
+VARDESC input.bypass.switch.off "Take the UPS out of bypass mode"
 VARDESC input.sensitivity "Input power sensitivity"
 VARDESC input.quality "Input power quality"
 VARDESC input.current "Input current (A)"
@@ -161,6 +165,7 @@ VARDESC outlet.id "Outlet system identifier"
 VARDESC outlet.desc "Outlet description"
 VARDESC outlet.switch "Outlet switch control"
 VARDESC outlet.status "Outlet switch status"
+VARDESC outlet.protect.status "Outlet protection status"
 VARDESC outlet.switchable "Outlet switch ability"
 VARDESC outlet.autoswitch.charge.low "Remaining battery level to power off this outlet (percent)"
 VARDESC outlet.delay.shutdown "Interval to wait before shutting down this outlet (seconds)"
@@ -169,15 +174,19 @@ VARDESC outlet.1.id "Outlet system identifier"
 VARDESC outlet.1.desc "Outlet description"
 VARDESC outlet.1.switch "Outlet switch control"
 VARDESC outlet.1.status "Outlet switch status"
+VARDESC outlet.1.protect.status "Outlet protection status"
 VARDESC outlet.1.switchable "Outlet switch ability"
+VARDESC outlet.1.ecocontrol "Master Outlet used to automatically power off the slave outlets"
 VARDESC outlet.1.autoswitch.charge.low "Remaining battery level to power off this outlet (percent)"
 VARDESC outlet.1.delay.shutdown "Interval to wait before shutting down this outlet (seconds)"
 VARDESC outlet.1.delay.start "Interval to wait before restarting this outlet (seconds)"
 VARDESC outlet.2.id "Outlet system identifier"
 VARDESC outlet.2.desc "Outlet description"
 VARDESC outlet.2.switch "Outlet switch control"
 VARDESC outlet.2.status "Outlet switch status"
+VARDESC outlet.2.protect.status "Outlet protection status"
 VARDESC outlet.2.switchable "Outlet switch ability"
+VARDESC outlet.2.ecocontrol "Master Outlet used to automatically power off the slave outlets"
 VARDESC outlet.2.autoswitch.charge.low "Remaining battery level to power off this outlet (percent)"
 VARDESC outlet.2.delay.shutdown "Interval to wait before shutting down this outlet (seconds)"
 VARDESC outlet.2.delay.start "Interval to wait before restarting this outlet (seconds)"
@@ -227,6 +236,10 @@ CMDDESC calibrate.start "Start run time calibration"
 CMDDESC calibrate.stop "Stop run time calibration"
 CMDDESC bypass.start "Put the UPS in bypass mode"
 CMDDESC bypass.stop "Take the UPS out of bypass mode"
+CMDDESC ecomode.enable "Put UPS in High Efficiency (aka ECO) mode"
+CMDDESC ecomode.disable "Take the UPS out of High Efficiency (aka ECO) mode"
+CMDDESC essmode.enable "Put UPS in Energy Saver System (aka ESS) mode"
+CMDDESC essmode.disable "Take the UPS out of Energy Saver System (aka ESS) mode"
 CMDDESC reset.input.minmax "Reset minimum and maximum input voltage status"
 CMDDESC reset.watchdog "Reset watchdog timer"
 CMDDESC beeper.on "Obsolete (use beeper.enable)"

docs/man/upsmon.conf.txt

@@ -275,6 +275,11 @@ BYPASS;; UPS on bypass (powered, not protecting)
 
 NOTBYPASS;; UPS no longer on bypass
 
+ECO;; UPS in ECO or similar mode (as defined and named by vendor);
+for more details see linkman:upsmon[8].
+
+NOTECO;; UPS no longer in ECO mode (see above)
+
 SUSPEND_STARTING;; OS is entering sleep/suspend/hibernate mode
 
 SUSPEND_FINISHED;; OS just finished sleep/suspend/hibernate mode,

docs/man/upsmon.txt

@@ -178,6 +178,20 @@ UPS on bypass (powered, not protecting).
 *NOTBYPASS*::
 UPS no longer on bypass.
 
+*ECO*::
+UPS in ECO or similar mode (as defined and named by vendor); other
+names include High Efficiency mode and Energy Saver System.
++
+For example, Eaton docs define High Efficiency mode as a sort of
+hardware-monitored bypass with switch-over under 10ms into Online
+mode in case of troubles (so what was known as Line-Interactive
+in the older days), which can be *chosen* instead of always running
+in a dual-conversion mode (safer, but more wasteful and with a toll
+on battery life). Older devices only implemented one or the other.
+
+*NOTECO*::
+UPS no longer in ECO mode (see above).
+
 *SUSPEND_STARTING*::
 OS is entering sleep/suspend/hibernate mode.
 

docs/nut-names.txt

@@ -262,6 +262,8 @@ input: Incoming line/power information
                                 voltage transfer point (V)        | 131
 | input.transfer.high.max     | greatest settable high
                                 voltage transfer point (V)        | 136
+| input.eco.switchable        | Input High Efficiency (aka ECO)
+                                mode switch (0-2)                 | normal
 | input.sensitivity           | Input power sensitivity           | H (high)
 | input.quality               | Input power quality (***
                                 opaque)                           | FF
@@ -305,6 +307,10 @@ input: Incoming line/power information
                                 point (percent of nominal Hz)     | 5
 | input.transfer.hysteresis   | Threshold of switching protection modes,
                                 voltage transfer point (V)        | 10
+| input.transfer.forced       | Input forced transfer modes
+                                (enabled or disabled)             | enabled
+| input.bypass.switch.on      | Put the UPS in bypass mode        | on
+| input.bypass.switch.off     | Take the UPS out of bypass mode   | disabled
 | input.load                  | Load on (ePDU) input (percent
                                 of full)                          | 25
 | input.realpower             | Current sum value of all (ePDU)
@@ -693,11 +699,16 @@ of the user manual.
                                    (on/off)                    | on
 | outlet.n.status                | Outlet switch status
                                    (on/off)                    | on
+| outlet.n.protect.status        | Outlet protection status
+                                   (0-2)                       | protected
 | outlet.n.alarm                 | Alarms for outlets and PDU,
                                    published in ups.alarm      | outlet 1 low
                                                                  voltage warning
 | outlet.n.switchable            | Outlet switch ability
                                    (yes/no)                    | yes
+| outlet.n.ecocontrol            | Master Outlet used to
+                                   automatically power off the
+                                   slave outlets               | The outlet is not ECO controlled
 | outlet.n.autoswitch.charge.low | Remaining battery level to
                                    power off this outlet
                                    (percent)                   | 80
@@ -862,6 +873,10 @@ Instant commands
 | calibrate.stop           | Stop runtime calibration
 | bypass.start             | Put the UPS in bypass mode
 | bypass.stop              | Take the UPS out of bypass mode
+| ecomode.enable           | Put UPS in High Efficiency (aka ECO) mode
+| ecomode.disable          | Take the UPS out of High Efficiency (aka ECO) mode
+| essmode.enable           | Put UPS in Energy Saver System (aka ESS) mode
+| essmode.disable          | Take the UPS out of Energy Saver System (aka ESS) mode
 | reset.input.minmax       | Reset minimum and maximum input voltage status
 | reset.watchdog           | Reset watchdog timer (forced reboot of load)
 | beeper.enable            | Enable UPS beeper/buzzer

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3220 utf-8
+personal_ws-1.1 en 3226 utf-8
 AAC
 AAS
 ABI
@@ -320,6 +320,7 @@ EPFCLCD
 EPO
 EPS
 ESC
+ESS
 ESV
 ESXi
 ETIME
@@ -739,6 +740,7 @@ NOP
 NOPARENT
 NOTBYPASS
 NOTCAL
+NOTECO
 NOTIFYCMD
 NOTIFYFLAG
 NOTIFYFLAGS
@@ -1600,6 +1602,8 @@ bullseye
 busport
 busybox
 bv
+bypassOff
+bypassOn
 cStandard
 cablepower
 calloc
@@ -1836,6 +1840,7 @@ ePDUs
 eaton
 ec
 eco
+ecomode
 edb
 editorconfig
 edl
@@ -1864,6 +1869,7 @@ epdu
 eq
 errno
 esac
+essmode
 esupssmart
 et
 etapro