Clean-up or legalise: revise status_set() values vs. the NUT standard dictionary

[jimklimov]

The "Status data" section in docs/new-drivers.txt defines certain keywords that are "Possible values for status_set", stressing that "Anything else will not be recognized by the usual clients. Coordinate with the nut-upsdev list before creating something new, since there will be duplication and ugliness otherwise."

In fact we do have a number of other values in code, currently:

:; git grep -w status_set | sed 's,^.*\(status_set[^;]*\);.*$,\1,' | sort | uniq -c
      1 docs/new-drivers.txt:   status_set(val) -- add a status word (OB, OL, etc)
      1 docs/new-drivers.txt:Possible values for status_set:
      1 drivers/dstate.c:void status_set(const char *buf)
      1 drivers/huawei-ups2000.c: * be set via status_set(), those are listed in "status_name".
      1 drivers/huawei-ups2000.c: * for status_set(), for example, "OL" or "OB", the field
      1 drivers/usbhid-ups.c:/** Helper to both status_set("CAL") and track last_calibration_start timestamp */
      6 status_set( status_buf )
      1 status_set("ACFAIL")
      1 status_set("ALARM")
     32 status_set("BOOST")
      1 status_set("BY")
     21 status_set("BYPASS")
     12 status_set("CAL")
     17 status_set("CHRG")
      2 status_set("COMMFAULT")
      1 status_set("DEPLETED")
     13 status_set("DISCHRG")
      1 status_set("ECO")
      5 status_set("FSD")
      4 status_set("HB")
      1 status_set("HE")
      1 status_set("LB ")
     60 status_set("LB")
     63 status_set("OB")
     31 status_set("OFF")
      1 status_set("OL BYPASS")
     67 status_set("OL")
     31 status_set("OVER")
      2 status_set("OVERHEAT")
     35 status_set("RB")
      1 status_set("SD")
      5 status_set("TEST")
      1 status_set("TIP")
     27 status_set("TRIM")
      1 status_set((u8 & 0x04) > 0 ? "OL" : "OB")
      1 status_set(alarms->status_value)
      1 status_set(const char *buf)
      1 status_set(ctx->arglist[counter])
      1 status_set(current <= 0 ? "OL" : "OB")
      1 status_set(flag[j].status_name)
      1 status_set(gpioupsfdlocal->rules[ruleNo]->stateName)
      1 status_set(info_value)
      1 status_set(is_online ? (is_off ? "OFF " : "OL ") : "OB ")
      1 status_set(online ? "OL" : "OB")
      1 status_set(ups2000_alarm[i].status_name)
      1 status_set(val)

• Values like ALARM => upsmon: add ALARM support #415 and introduce further handling and notifiers for ALARM status #2658, and ECO => ecomode_addon-2 #2684 are recent additions, not standardized here yet but elaborated a lot in other parts of the code base, including C++ bindings, clients like upsmon and should be CGI...
  • Note that ALARM is set in dstate.c since before 2007, see 5f42691 - recent PRs just added its handling in upsmon and other parts of code
• Values like ACFAIL, BY, COMMFAULT, DEPLETED, HE, OVERHEAT, SD, TIP, TEST are not defined
  • HE may be renamed to ECO now that it has led in evolution across the code base; should other advanced power management technology (ESS, ABM) activation states also be aliased to ECO? (WDYT - @desertwitch @masterwishx ?)
  • is TEST same as CAL?
  • what about others?
• Some values are set from variables or arrays, to be revised separately.
• One case sets a two-token string right away, and some have tokens followed by space, which is pedantically incorrect.
  • Fix by setting a token at a time, and committing, as NUT status API dictates.
  • I suppose a similar situation can happen in numerous SNMP subdrivers with e.g. info_lkp_default(4, "OL BYPASS"), seen in a cpqpower_pwr_info[] array. Somebody gotta use those strings, right?..
  • While the implementation of status_set() does check that its argument is absent in a collected status_buf string (although since after NUT v2.8.2 release), it relies on strstr matching of the whole argument - this is one way how some drivers can end up with duplicate status values like OL OL BYPASS I suppose.
  • UPDATE: status_set() for arguments with multiple tokens separated or surrounded by spaces should now do the right thing: recurse to add (or not) each non-trivial token independently.

Gotta decide what to do with the unknown names - can rename some cases, but what about others? Legalize them into the docs chapter (also concerns "ALARM" and "ECO"), and add handling in C++ bindings, augeas, clients, etc.?

Perhaps more importantly: would such legalization of keywords acceptable in ups.status constitute a bump of NUT protocol/API for formal versioning, as in "clients conforming to protocol N are expected to handle at least tokens X,Y,Z with ascribed meanings" (free about considering, logging or ignoring other tokens, as long as the client does not crash on them)?

CC @clepple @aquette - WDYT?

[desertwitch]

I will give this some more thought, but condensing HE and ESS into ECO would make sense to me. In general - I think - UPS statuses should foremost denote important conditions of the UPS (that the user should more or less immediately notice), so - I think - it makes sense to tidy this up some. ABM is more related to internal handling of battery management (resulting in respective charging/discharging statuses), so this one I'd say is not worthy a status of its own (and currently isn't one, rather ABM enabled/disabled can be checked via their exposed other variables instead).

[gdt]

Assorted thoughts:

• the protocol spec ought to direct clients to ignore status values they don't understand. If not, we should say that

• in general, the point is to abstract a UPS into generic behavior/status that can be understood without knowing the details. So I think we need to ask not "what word do we use for proprietary feature foo" but "what does this feature mean in general, and then how do we name that".

• There are probably lots of oddball things that should be cleaned up, and we should just do that, separately from any hard questions about common/abstractable tags.

• There are clearly going to be device-specific or manufacturer-specific semantics that are too complicated and not amenabel to a multi-vendor abstraction. Probably those should just not go into status. Maybe, we should have a way to have a device-specific status object carried in nut, which is perhaps json, with no expectation that software can process it, unless it is specifically coded for a private interface. And then try not to use this mechanism.

• For ECO, I don't think we should have a word that means "it is eco as the vendor names it". I think we should define what it means and then for each vendor map that status to ECO if it meets our definition. I don't even know what it means, and why someone would operate less efficiently. I am guessing that it's a switch between "operate on inverter all the time" and "passthrough, but switch to inverter if input fails or goes out of bounds". Historically that's been a fixed design parameter. So maybe instead we should have something that reports "device is on inverter being operated by input" that turns on and off.

• This means that ECO will appear on devices that always do standby, and will not appear on devices that are always running the inverter. So ECO is the wrong word; it should be something that indicates "input ok and inverter in use". Or maybe it's just "inverter in use" and that comes on when any device goes on battery. I'm not really sure what the right answer is. My point is don't accept any one vendor's labels, and don't accept content-free marketing labels.

• It is very important as things get more complicated that simpler clients get the correct understanding. So the basics of is the UPS providing output power, is the input AC ok, is the UPS operating from the battery, need to be reliably indicated by the older statuses even if we add new ones. It's not ok to split a status into two parts and have something expecting the old name to cover it all find the new one instead and ignore it. This is like in openstreetmap where we have amenity=foo and then if that gets complicated we keep that and have foo=bar or foo=baz, so that things that only as "is this a foo" get the right answer relative to their ability to comprehend.

• I think 99% of the value in clients is grasping

  • is the UPS providing output power normally while in put is ok?
  • Is the UPS providing output power from battery?
  • are there any alarms?
  • what are the input/output V, freq, load VA, battery V, battery runtime?
    and after that it's details that are not such a big deal.

[masterwishx]

• HE may be renamed to ECO now that it has led in evolution across the code base; should other advanced power management technology (ESS, ABM) activation states also be aliased to ECO?

Sorry for delay.
Like you said HE =ECO 100% can be renamed.

ESS = I think something like advanced ECO = when converter is on (for switch to online in 2ms instead 10ms in ECO) but in bypass like in ECO mode.
So it's a little different from ECO mode also only two enterprise model in Eaton support it (9390,9395) like I wrote in comments in code.
So not sure if can be renamed becouse of reasons above.

ABM ≠ ECO.
Like @desertwitch said it's Advanced battery monitoring for charger, also we have variables like battery.charger.abm.status to see if enabled and battery.charger.type that show if charger in ABM or Constant charge.

I hope I understood the question right...

[masterwishx]

https://eaton-powerware.ru/ess.html
https://www.a-energy.ru/article/eaton-ess-tech/

Some info from copilot:

ESS is an innovative technology designed to significantly enhance the energy efficiency of uninterruptible power supplies (UPSs) without compromising load protection. Here are the key points about ESS:

What Is ESS?
Energy Saver System (ESS) is a mode of operation available in certain Eaton UPS models.
Its primary goal is to maximize efficiency while ensuring reliable power delivery to connected loads.
How Does ESS Work?
In normal power conditions (when the mains supply quality is good), the UPS operates in ESS mode.
During ESS mode, the UPS feeds the loads directly from the mains supply (similar to bypass mode).
The losses in ESS mode are minimal—typically around 1%—because there are no additional devices in the power path between the mains supply and the loads.
Seamless Transition:
If the mains supply fails or its quality deteriorates, the UPS switches to double-conversion mode within milliseconds.
This rapid transition ensures that connected equipment remains protected even during power disturbances.
Benefits of ESS:
Energy Efficiency: ESS allows UPSs to achieve up to 99% efficiency across their entire operating range.
Reliability: ESS maintains UPS reliability by using existing functional elements without introducing complexity.
Minimal Wastage: ESS minimizes energy wastage, making it ideal for data centers and critical applications.
Applications for ESS:
ESS is suitable for various scenarios, including data centers, industrial facilities, and critical infrastructure.
Anywhere energy efficiency and reliability are essential, ESS shines.
Remember, ESS is like the UPS doing a little energy-saving dance—keeping your power efficient while ensuring your devices stay protected! If you have more questions or need further details, feel free to ask! 😊🔌

[masterwishx]

Oh seems I didn't got the question so right.

So I think HE should be renamed to ECO status.
ESS can be ESS status, not much ups have it.

ABM no need for status as per above comments. :)

[jimklimov]

It's not ok to split a status into two parts and have something expecting the old name to cover it all find the new one instead and ignore it.

This point is a bit harder historically. Gotta check what different drivers do, but according to notes in the document, for some time now (since before my time IIRC) the CHRG and DISCHRG tokens in ups.status are being phased away in favor of possibly more detailed battery.charger.status, for example. A client expecting either one of these clues may not see the full picture with each and every driver. (The "gotta check" part is whether all drivers do set the status tokens along with the dstate data point.)

For ECO, I don't think we should have a word that means "it is eco as the vendor names it". I think we should define what it means and then for each vendor map that status to ECO if it meets our definition. I don't even know what it means, and why someone would operate less efficiently...

To me, the "ECO" definition is fundamentally vague and "as vendor says", with one common feature being that it is some togglable trade-off between power overheads wasted by the UPS to do its job with different strategies, and reliability. Generally it boils down to either being hardwired for two power circuits with inverter and battery in the middle always active (marketed in the past decades as an "on-line UPS"), or hardwired for the inverter being inactive most of the time - with less waste and maybe less wear (marketed as "line-interactive"), or software-defined to have a run-time choice between whichever options the vendor gives. The "ECO" token in ups.status IMHO should convey "currently running less wasteful than I know I can be" and if there are deeper details (e.g. which of many strategies is now in place) - that can be sought in key-value data points.

As such, I think the "ECO" ups.status also applies to "ESS mode" being active, as one of such vaguely-similar implementations of minimizing UPS overhead in the power budget.

[masterwishx]

As such, I think the "ECO" ups.status also applies to "ESS mode" being active, as one of such vaguely-similar implementations of minimizing UPS overhead in the power budget

Sure you right, also as i wrote befor seems only 2 enterprise models using this mode, but after merging essmode status maybe they users will use NUT :)

[masterwishx]

To me, the "ECO" definition is fundamentally vague and "as vendor says", with one common feature being that it is some togglable trade-off between power overheads wasted by the UPS to do its job with different strategies, and reliability. Generally it boils down to either being hardwired for two power circuits with inverter and battery in the middle always active (marketed in the past decades as an "on-line UPS"), or hardwired for the inverter being inactive most of the time - with less waste and maybe less wear (marketed as "line-interactive"), or software-defined to have a run-time choice between whichever options the vendor gives

The only Confusing thing with ECO I found was
Ellipse ECO ups with ECO control that other technology for outlets to disable.

[gdt]

https://eaton-powerware.ru/ess.html https://www.a-energy.ru/article/eaton-ess-tech/

Some info from copilot:

The track record of this sort of "AI" is that it is unreliable. I would like to see a group-wide norm not to use such tools at all.

[gdt]

• HE may be renamed to ECO now that it has led in evolution across the code base; should other advanced power management technology (ESS, ABM) activation states also be aliased to ECO?

Sorry for delay. Like you said HE =ECO 100% can be renamed.

ESS = I think something like advanced ECO = when converter is on (for switch to online in 2ms instead 10ms in ECO) but in bypass like in ECO mode. So it's a little different from ECO mode also only two enterprise model in Eaton support it (9390,9395) like I wrote in comments in code. So not sure if can be renamed becouse of reasons above.

Stepping back: why do we have tokens in ups.status at all? Just because some UPS has some feature doesn't mean it should be put in ups.status. That only makes sense for things that are broadly definned/implemented in a way which seems common across manufacturers.

I'm basically saying that for now, a driver that supports something like this should just put in a variable, and people can log/process it and then eventually, if we think there is a common definition, and it is useful, it can be promoted to a flag. But interfaces once defined stick around, so I think we should very much lean to not adding things until we can write a spec modification that holds up to scrutiny.

[gdt]

It's not ok to split a status into two parts and have something expecting the old name to cover it all find the new one instead and ignore it.

This point is a bit harder historically. Gotta check what different drivers do, but according to notes in the document, for some time now (since before my time IIRC) the CHRG and DISCHRG tokens in ups.status are being phased away in favor of possibly more detailed battery.charger.status, for example. A client expecting either one of these clues may not see the full picture with each and every driver. (The "gotta check" part is whether all drivers do set the status tokens along with the dstate data point.)

Sure, realiity is messier. I just meant that changing tokens around should start off with a presumption that it's bad, and then think about how things are affected.

For ECO, I don't think we should have a word that means "it is eco as the vendor names it". I think we should define what it means and then for each vendor map that status to ECO if it meets our definition. I don't even know what it means, and why someone would operate less efficiently...

To me, the "ECO" definition is fundamentally vague and "as vendor says", with one common feature being that it is some togglable trade-off between power overheads wasted by the UPS to do its job with different strategies, and reliability. Generally it boils down to either being hardwired for two power circuits with inverter and battery in the middle always active (marketed in the past decades as an "on-line UPS"), or hardwired for the inverter being inactive most of the time - with less waste and maybe less wear (marketed as "line-interactive"), or software-defined to have a run-time choice between whichever options the vendor gives. The "ECO" token in ups.status IMHO should convey "currently running less wasteful than I know I can be" and if there are deeper details (e.g. which of many strategies is now in place) - that can be sought in key-value data points.

I think from a Free Software ethics viewpoint, we need to define and then map. Parroting marketing goofiness (or sometthing that might make sense) is not responible to users. Carrying a vendor-specific mode bit without judging it so that users can get at it is fine. But we should not pretend there is a global meaning. We should not aggregate N fuzzy meanings into one flag; that is an assertion that they mean the same thing. I think it is better to decline to play the game then to give people bad information.

Some UPS systems are always in standby (when power is ok). Thus the ECO flag applies to them; they simply lack the less efficient mode. So if a flag is defined to mean "in operation such that input is piped to output and no inverter is running, basicaly only usage is battery trikcle and control electronics", those UPS units should have it set.

The real question is: what are we trying to define and why? Who wants to know this? How do they benefit? We should insist on coherent answers to this in a multi-vendor way before we define multi-vendor flags.

Thus, I think we should remove the ECO token in ups.status, and we can add mode variables to manufacturer/model-specific drivers.

[masterwishx]

Some UPS systems are always in standby (when power is ok). Thus the ECO flag applies to them; they simply lack the less efficient mode

I have now OL CHRG ECO so not sure why you want to remove it from status.
OL = online
CHRG = charging cc
ECO = eco mode (input from bypass, inverter off)
Without it we will have wrong status!

[gdt]

My UPS doesn't say ECO but it is doing the same thing. It's a Best Fortress 660 and that's the only mode it has.

My point is that we should either define ECO without involving "the device manufacturer says eco", and have a flag, or we should remove it from ups.status and put in each driver a variable that only claims to mean some word that one manufacturer uses.

ECO in particular is problematic as there is lots of greenwashing, and structurally it is a word everybody tries to claim. Thus, I see it as starting off with a rebuttable presumption that it is at best vague and at worst fake. This can be overcome with a good definition that does not reference 'the manufacturer uses the word eco".

As for "wrong", no, without it you would not be having a report in ups.status that this mode is active or not. That is not in any way "wrong".

So far, I remain skeptical that we have an adequate definition to base a flag on, and I think we should have a RFC-modifcation process (at least having text in the nut repo) before we use them.

[masterwishx]

Also by Eaton UPS HID Path we have variable that Represent UPS ECO status for NUT software , like other statuses Onlne, Bypass you cant avoid this one only and make it invisible:

nut/drivers/mge-hid.c

Line 1869 in 077c08c

{ "BOOL", 0, 0, "UPS.PowerConverter.Input.[5].PresentStatus.Used", NULL, NULL, 0, eco_mode_info }, /* ECO(HE), ESS Mode */

[gdt]

What do you mean "can't avoid"? nut reads from the ups and translates to nut protocol. Of course we can avoid.

[masterwishx]

What do you mean "can't avoid"? nut reads from the ups and translates to nut protocol. Of course we can avoid.

i meaned we should not avoid this but not others . why to avoid this one HID but not bypass or other?

[masterwishx]

PresentStatus.Used = status we have now

[masterwishx]

My UPS doesn't say ECO but it is doing the same thing. It's a Best Fortress 660 and that's the only mode it has.

if this one backup ups its not the really same as online with eco

[jimklimov]

I guess it's good the discussion happened sooner or later, many good points raised by both sides, and thanks for some reality check even if harsh - life hurts :)

A few random thoughts from recent reading:

• with an UPS whose inverter is always on standby (so there's a ~10ms gap), the user/sysadmin knows about this deterministic behavior, and that e.g. non-IT equipment without inertia of capacitors, coils etc. can get restarted during the switch-over. For UPSes where this is a run-time choice, it may be good to know and avoid inadvertent mishaps.

• if the matter is about "knowing" that status, it depends on who/what/hoq should know it. Maybe a token in ups.status is not required, if the goal is to have specifically upsmon notifications - I visited its get_val() method today, and we are not limited to parsing ups.status, can add other queries.

• this eviction of ECO token from ups.status (especially before it grew long roots) would have precedent in e.g. CHRG/DISCHRG depreciation in favor of a dstate value. A benefit is that it's more flexible/extensible (e.g. can have several nut-standard readings to represent the marketing-word techs available on the device, and the one(s) active now if any), a relative downside is that a yes-no answer for "am I safe or wasteful given a choice?" may be not as easy and can require similar non-trivial coding/updates in each client.

• BYPASS is different as it tells us the UPS is currently a power strip and will stay that way. If wall power is lost, we can immediately consider its load dead.

My commute time is over, but I think it's all I had to say right now :)

Not sure I'll be online tomorrow, got a conference at dayjob...

[desertwitch]

After reading up and giving this some more in-depth thought, I'm also overall leaning more towards @gdt 's views. I think ups.status should ideally be reserved for statuses which are first and foremost important, operational conditions that the user should notice on a first glance and which are also somewhat universally understood with a common meaning (cross-vendor).

HE, ESS, ECO feel a bit out of place in this otherwise meaningful list, as they are vendor-specific statuses with no apparent special, urgent significance for the UPSes operation (good to know, nevertheless, but just as informative as a dstate key/value).

But then I'd argue CHRG and DISCHRG are special cases that I'd keep within ups.status, I think many people would still want to see on a first glance that the UPS is charging at the moment (which has a more volatile feeling to it; is not something I want to look up in a variable table personally). Perhaps a toggle to control this (chrg_dischrg_as_status) could be a compromise here?

I also really like the addition of get_val() for better non-status handling of notifications within upsmon, so thanks a lot for that Jim. I think some statuses were probably initially implemented as statuses just to be able to trigger notifications for them.

In any case - HE, ESS, ECO seem mostly vendor-specific buzz-words to me that don't really seem to have a significant place in ups.status. There being more than one entirely different definition of ECO (automatic bypass vs. selective outlet disabling) alone should disqualify that as a status in my opinion.

[masterwishx]

CC @arnaudquette-eaton
it would be great to hear your opinion

[jimklimov]

Finally got a moment to dive into this, as the situation with ECO status remains as one significant blocker before a release (so that standard documentation snapshots remain authoritative and stable).

First however I've addressed the case of status_set() with white-space in arguments: now each token should get added (or not, if duplicate) independently, extra spaces stripped. Unit test added to make sure it does happen. Apparently botched a related check in #2565 too (added after 2.8.2 release, so nice to have fixed before 2.8.3).

[aquette]

Iirc, snmp-ups is suffering some similar issues