data/cmdvartab, drivers/mge-hid.c, drivers/usbhid-ups.c, docs/nut-names.txt: move "ecomode" and "essmode" INSTCMDs into "experimental." namespace [#2708]

Signed-off-by: Jim Klimov <[email protected]>

Author: jimklimov

data/cmdvartab

@@ -258,11 +258,11 @@ 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 ecomode.start.auto "Put UPS in Bypass mode then 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 experimental.ecomode.enable "Put UPS in High Efficiency (aka ECO) mode"
+CMDDESC experimental.ecomode.disable "Take the UPS out of High Efficiency (aka ECO) mode"
+CMDDESC experimental.ecomode.start.auto "Put UPS in Bypass mode then High Efficiency (aka ECO) mode"
+CMDDESC experimental.essmode.enable "Put UPS in Energy Saver System (aka ESS) mode"
+CMDDESC experimental.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/nut-names.txt

@@ -1020,11 +1020,6 @@ 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
-| ecomode.start.auto       | Put UPS in Bypass mode then 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
@@ -1038,3 +1033,29 @@ Instant commands
 | outlet.n.load.cycle      | Power cycle the outlet immediately
 | outlet.n.shutdown.return | Turn off the outlet and return when power is back
 |========================================================================
+
+Experimental instant commands
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following commands were added to test feature support, but are not expected
+to last as part of NUT standard protocol in the long run.
+
+.Vendor-dependent "ECO" modes
+[options="header"]
+|========================================================================
+| Name                              | Driver/Devices        | Description
+| experimental.ecomode.enable       | usbhid-ups => mge-hid (Eaton/MGE)
+    | Put UPS in High Efficiency (aka ECO) mode
+| experimental.ecomode.disable      | usbhid-ups => mge-hid (Eaton/MGE)
+    | Take the UPS out of High Efficiency (aka ECO) mode
+| experimental.ecomode.start.auto   | usbhid-ups => mge-hid (Eaton/MGE)
+    | Put UPS in Bypass mode then High Efficiency (aka ECO) mode
+| experimental.essmode.enable       | usbhid-ups => mge-hid (Eaton/MGE)
+    | Put UPS in Energy Saver System (aka ESS) mode
+| experimental.essmode.disable      | usbhid-ups => mge-hid (Eaton/MGE)
+    | Take the UPS out of Energy Saver System (aka ESS) mode
+|========================================================================
+
+Currently the commands above are present in one subdriver and are specific
+to the vendor's proposed power state machine. The plan is to generalize the
+concept with vendor specifics, similarly to `experimental.ups.mode.buzzwords`.

drivers/mge-hid.c

@@ -2133,12 +2133,12 @@ static hid_info_t mge_hid2nut[] =
 	{ "outlet.2.load.on", 0, 0, "UPS.OutletSystem.Outlet.[3].DelayBeforeStartup", NULL, "0", HU_TYPE_CMD, NULL },
 
 	/* Command to switch ECO(HE), ESS Mode */
-	{ "ecomode.disable", 0, 0, "UPS.PowerConverter.Input.[5].Switchable", NULL, "0", HU_TYPE_CMD, NULL },
-	{ "ecomode.enable", 0, 0, "UPS.PowerConverter.Input.[5].Switchable", NULL, "1", HU_TYPE_CMD, eaton_input_eco_mode_on_off_info },
-	{ "essmode.enable", 0, 0, "UPS.PowerConverter.Input.[5].Switchable", NULL, "2", HU_TYPE_CMD, NULL },
-	{ "essmode.disable", 0, 0, "UPS.PowerConverter.Input.[5].Switchable", NULL, "0", HU_TYPE_CMD, NULL },
+	{ "experimental.ecomode.disable", 0, 0, "UPS.PowerConverter.Input.[5].Switchable", NULL, "0", HU_TYPE_CMD, NULL },
+	{ "experimental.ecomode.enable", 0, 0, "UPS.PowerConverter.Input.[5].Switchable", NULL, "1", HU_TYPE_CMD, eaton_input_eco_mode_on_off_info },
+	{ "experimental.essmode.enable", 0, 0, "UPS.PowerConverter.Input.[5].Switchable", NULL, "2", HU_TYPE_CMD, NULL },
+	{ "experimental.essmode.disable", 0, 0, "UPS.PowerConverter.Input.[5].Switchable", NULL, "0", HU_TYPE_CMD, NULL },
 	/* Command to switch ECO(HE) Mode with switch to Automatic Bypass Mode on before */
-	{ "ecomode.start.auto", 0, 0, "UPS.PowerConverter.Input.[5].Switchable", NULL, "1", HU_TYPE_CMD, eaton_input_eco_mode_auto_on_info },
+	{ "experimental.ecomode.start.auto", 0, 0, "UPS.PowerConverter.Input.[5].Switchable", NULL, "1", HU_TYPE_CMD, eaton_input_eco_mode_auto_on_info },
 
 	/* Command to switch Automatic Bypass Mode on/off */
 	{ "bypass.start", 0, 0, "UPS.PowerConverter.Input.[2].SwitchOnControl", NULL, "1", HU_TYPE_CMD, eaton_input_bypass_mode_on_info },

drivers/usbhid-ups.c

@@ -294,8 +294,8 @@ static status_lkp_t status_info[] = {
 	{ "boost", STATUS(BOOST) },
 	{ "bypassauto", STATUS(BYPASSAUTO) },
 	{ "bypassman", STATUS(BYPASSMAN) },
-	{ "ecomode", STATUS(ECOMODE) },
-	{ "essmode", STATUS(ESSMODE) },
+	{ "ecomode", STATUS(ECOMODE) },	/* Should not get used (at least not via */
+	{ "essmode", STATUS(ESSMODE) },	/* ups.status), but tracked just in case */
 	{ "off", STATUS(OFF) },
 	{ "cal", STATUS(CALIB) },
 	{ "overheat", STATUS(OVERHEAT) },
@@ -387,6 +387,9 @@ info_lkp_t bypass_manual_info[] = {
 	{ 0, "!bypassman", NULL, NULL },
 	{ 0, NULL, NULL, NULL }
 };
+
+/* Should not get used (at least not via ups.status), but tracked just in case.
+ * Currently referenced in mge-hid.c */
 info_lkp_t eco_mode_info[] = {
 	{ 0, "normal", NULL, NULL },
 	{ 1, "ecomode", NULL, NULL },