networkupstools / nut

The Network UPS Tools repository. UPS management protocol Informational RFC 9271 published by IETF at https://www.rfc-editor.org/info/rfc9271 Please star NUT on GitHub, this helps with sponsorships!
https://networkupstools.org/
Other
1.73k stars 335 forks source link

Revise `ups.status` values set by shipped drivers to match NUT standards #2496

Open jimklimov opened 1 week ago

jimklimov commented 1 week ago

In docs/new-drivers.txt section on Status data aka https://networkupstools.org/docs/developer-guide.chunked/new-drivers.html#_status_data we define a number of possible values.

There is a fair amount of (sub-)drivers and maybe mappings which set something else, e.g. per https://github.com/networkupstools/nut/issues/2494#issuecomment-2193924034 nutdrv_qx_voltronic.c sets values like !OL instead of (presumably) OB.

A related separate issue #2495 is lack of a standard value for "ECO mode" altogether, while it is becoming popular with hardware and wants a consistent name.

While at it, there was also a discussion on ML recently about introducing a status name for "hover charging" (when batteries are kept not at 100% by always charging, but "hover" in a safe zone, e.g. only charging as they drop to some 90%, to conserve chemistry life/cycles - which would often be seen as "OL DISCHRG") which is what "HB" status might have meant or not, historically. We did not come up with a consistent name for the concept at the time, though: most of the search hits came up with charging of hoverboards :) => https://alioth-lists.debian.net/pipermail/nut-upsdev/2024-May/007989.html

clepple commented 1 week ago

There generally seems to be a mess in that subdriver with statuses like !OL instead of OB which many clients would not recognize if they parse it.

Not sure about the other drivers, but nutdrv_qx fixes up e.g. !OL in update_status(): https://github.com/networkupstools/nut/blob/v2.8.2/drivers/nutdrv_qx.c#L3693 (though there may be cases where that slips through)

gdt commented 1 week ago

If there are a larger number of possible states, which it seems like there is, we should have predicates that answer important questinos and reduce to less complicated. Like "is the UPS operating from input AC power, or is it using the battery because input power has failed". In asking that, I don't really want to know all the details about battery calibration and hovering. I want to know "are things ok are are we in an alarm condition".

In general, I think we should ask the questions, and use those to organize the values.

jimklimov commented 1 week ago

The way I see it, states are more or less boolean, presented like a bitmask via a string with a series of space-separated tokens that represent each boolean-ish state (I am on wall power, I feed from battery, Battery is discharging -- all of these can be at once, e.g. during calibration). They are primarily aimed at programmatic consumption.

Alarms are less structured, essentially an opaque string that can be meaningful-to and interpreted-by the end-users, delivered in mail or web page, etc.

And in some cases both can be raised, e.g. state "RB" and alarm "Replace your battery ASAP!"