EATON HID: add missing usages and paths (addon)

NEWS.adoc

@@ -205,6 +205,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.
+
  - Introduced handling for the `ALARM` status, which already existed as a
    common denominator for devices seen with active `ups.alarm` variables.
    UPS devices in an `ALARM` status are generally considered volatile and
@@ -218,7 +231,7 @@ https://github.com/networkupstools/nut/milestone/11
    * Updated `upsmon` client with ability to report entering and exiting
      the ALARM status if reported by the driver;
    * Updated `upsmon` client with setting to toggle whether an `ALARM`
-     status can prompt the UPS to become critical in certain situations;
+     status can prompt the UPS to become critical in certain situations.
 
  - upsmon:
    * it was realized that the `POWERDOWNFLAG` must be explicitly set in the

clients/status.h

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

clients/upsmon.c

@@ -192,7 +192,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_ALARM | ST_CAL)) {
 		sleepval = pollfreq;
 		return 1;
@@ -716,6 +718,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_is_alarm(utype_t *ups)
 {
 	if (flag_isset(ups->status, ST_ALARM)) { 	/* no change */
@@ -1125,6 +1163,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 "
@@ -1350,6 +1389,7 @@ static void recalc(void)
 		 * whether this is really the best thing to do is undecided  */
 
 		/* crit = (FSD) || (OB & LB) > HOSTSYNC seconds || (CAL || BYPASS || ALARM || OFF) && nocomms */
+		/* Note: ECO mode not considered easily fatal here */
 		if (is_ups_critical(ups))
 			upsdebugx(1, "Critical UPS: %s", ups->sys);
 		else
@@ -1456,6 +1496,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 */
@@ -2412,6 +2456,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);
 	if (!strstr(status, "ALARM"))
 		ups_is_notalarm(ups);
 
@@ -2439,6 +2485,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);
 		if (!strcasecmp(statword, "ALARM"))
 			ups_is_alarm(ups);
 		/* do it last to override any possible OL */

clients/upsmon.h

@@ -36,7 +36,8 @@
 #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_ALARM       (1 << 10)      /* UPS has at least one active alarm        */
+#define ST_ECO         (1 << 10)      /* UPS is in ECO (High Efficiency) mode or similar tweak, e.g. Energy Saver System mode */
+#define ST_ALARM       (1 << 11)      /* UPS has at least one active alarm        */
 
 /* required contents of flag file */
 #define SDMAGIC "upsmon-shutdown-file"
@@ -70,6 +71,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	*/
 	int	alarmstate;		/* fire on a 0->1 transition;	*/
 					/* delays not implemented now	*/
 
@@ -96,7 +99,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     */
@@ -108,8 +111,10 @@ 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_ALARM	16	/* UPS has at least one active alarm    */
-#define NOTIFY_NOTALARM	17	/* UPS has no active alarms    */
+#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_ALARM	18	/* UPS has at least one active alarm    */
+#define NOTIFY_NOTALARM	19	/* UPS has no active alarms    */
 
 #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 */
@@ -158,6 +163,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_ALARM,    "ALARM",    NULL, "UPS %s is in an alarm state (has active alarms)", NOTIFY_DEFAULT },
 	{ NOTIFY_NOTALARM, "NOTALARM", NULL, "UPS %s is no longer in an alarm state (no active alarms)", 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=="ALARM")
 		return NOTIFY_ALARM;
 	else if(str=="NOTALARM")

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
 	"ALARM",	// NOTIFY_ALARM
 	"NOTALARM",	// NOTIFY_NOTALARM
 	"SUSPEND_STARTING",	// NOTIFY_SUSPEND_STARTING

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)"
 # NOTIFYMSG ALARM	"UPS %s is in an alarm state (has active alarms)"
 # NOTIFYMSG NOTALARM	"UPS %s is no longer in an alarm state (no active alarms)"
 #
@@ -381,6 +383,8 @@ POWERDOWNFLAG "@POWERDOWNFLAG@"
 # NOTIFYFLAG NOTOFF	SYSLOG+WALL
 # NOTIFYFLAG BYPASS	SYSLOG+WALL
 # NOTIFYFLAG NOTBYPASS	SYSLOG+WALL
+# NOTIFYFLAG ECO	SYSLOG+WALL
+# NOTIFYFLAG NOTECO	SYSLOG+WALL
 # NOTIFYFLAG ALARM	SYSLOG+WALL
 # NOTIFYFLAG NOTALARM	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)
+
 ALARM;; UPS is in an alarm state (has active alarms)
 
 NOTALARM;; UPS is no longer in an alarm state (no active alarms)

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).
+
 *ALARM*::
 UPS is in an alarm state (has active alarms).
 
@@ -508,15 +522,15 @@ implementations throughout the various UPS drivers and generally anytime
 that a "ups.alarm" variable is seen reported by the specific UPS driver.
 
 Alarms can be acted upon by the user using the "ALARM" and "NOTALARM" notifiers,
-which are reported by the "upsmon" when the "ALARM" status occurs or disappears.
+which are reported by the `upsmon` when the "ALARM" status occurs or disappears.
 
-As alarms raised by the UPS are usually severe in nature, the "upsmon" watches
+As alarms raised by the UPS are usually severe in nature, the `upsmon` watches
 a UPS in such a state more closely, bumping up the polling frequency as needed.
 
-When connection loss occurs in such an alarm state, the "upsmon" will by default
+When connection loss occurs in such an alarm state, the `upsmon` will by default
 consider the volatile UPS as critical/dead and this may lead to false shutdowns
 if the actual alarm was in fact mundane in nature (e.g. caused by a HE/ECO mode).
-This can be changed by utilizing the "ALARMCRITICAL" setting within "upsmon.conf".
+This can be changed by utilizing the `ALARMCRITICAL` setting within `upsmon.conf`.
 
 RELOADING NUANCES
 -----------------

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