From 7beccb53d109dd8561cf5ef4480bc3dab84ce350 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 21 Sep 2023 11:30:14 +0200 Subject: [PATCH 1/2] docs/nut-names.txt: add a section to define and discuss Structured naming Signed-off-by: Jim Klimov --- docs/nut-names.txt | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/nut-names.txt b/docs/nut-names.txt index af804d2ec4..0f735a836e 100644 --- a/docs/nut-names.txt +++ b/docs/nut-names.txt @@ -61,6 +61,31 @@ parse the value for that variable as it may vary greatly from one UPS (or similar device) to the next. These strings are best handled directly by the user. +Structured naming +----------------- + +All standard NUT names of variables and commands are structured, with +a certain domain-specific prefix and purpose-specific suffix parts. +NUT tools provide and interpret them as dot-separated strings (although +third-party tools might restructure them by cutting and pasting at the +dot separation location, e.g. to represent as a JSON data tree or as +data model classes for specific programming languages). + +If you would be making a parser of this information, please do also note +that in some *but not all* cases there is a defined data point for some +reading or command at the "root level" of what evolved to be a collection +of further structured related information (and there are no guarantees +for future evolution in this regard), for example: + +* an `input.voltage` reports the momentary voltage level value and + there is a `input.voltage.maximum` for a certain related detail; +* conversely, there are several items like `input.transfer.reason` + but there is no actual `input.transfer` report. + +There may be more layers than two (e.g. `input.voltage.low.warning`), +and in certain cases detailed below there may be a variable component +in the practical values (e.g. the `n` in `ambient.n.temperature.alarm` +variable or `outlet.n.load.off` command names). Time and Date format -------------------- From 3094174ffa7ff93ea20651cf19aa446419be0b28 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Thu, 21 Sep 2023 11:31:12 +0200 Subject: [PATCH 2/2] docs/nut-names.txt: clarify that the tables of short SPEC names is just a component in longer phase-aware naming scheme Signed-off-by: Jim Klimov --- docs/nut-names.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/nut-names.txt b/docs/nut-names.txt index 0f735a836e..2c48c1959b 100644 --- a/docs/nut-names.txt +++ b/docs/nut-names.txt @@ -383,6 +383,10 @@ Valid CONTEXTs Valid SPECs ^^^^^^^^^^^ +NOTE: For cursory readers -- the following couple of tables lists just the +short `SPEC` component of the larger `DOMAIN.CONTEXT.SPEC` naming scheme +for phase-aware values, as discussed in other sections of this chapter. + Valid with/without context (i.e. per phase or aggregated/averaged) [options="header"]