update docs on elec metering (#24)

* per feedback from community & Labs WG

Author: rick-jennings

src/docHaystack/doc/Meters.fandoc

@@ -71,26 +71,27 @@ Primary Quantities for AC and DC measurements [#primaryQuantities]
 ==================================================================
 Both `ac-elec-meter` and `dc-elec-meter` support measurements of the
 following electrical primary quantities:
-  - `power`: Instantaneously measured in "kW" units for 'dc' measurements.
-  Instantaneously measured in "kW", "kVAR", or "kVA" units for 'ac'
-  measurements depending on the characteristic `active`, `reactive`, or `apparent`.
-  - `demand`: Measurements indicate an average of instantaneous power values over
-  a defined time interval (e.g., 5, 15, or 30 minutes) and have the same units
-  that are used for `power` measurements.
-  - `energy`: Similar to `demand`, measurements indicate an average of
-  instantaneous power values over a defined time interval (e.g., 60 minutes).
-  Measured in "kWh" units for 'dc' measurements.  Measured in "kWh", "kVARh",
-  or "kVAh" units for 'ac' measurements depending on the characteristic `active`,
-  `reactive`, or `apparent`.
-  - `volt`: Instantaneously measured in "V" units for both 'ac' and 'dc'
+  - `power`: Average electric power over one or several alternating current (AC) cycles
+  or instantaneous DC electric power. Measured in "kW", "kVAR", or "kVA" units for 'ac'
+  measurements depending on the characteristic `active`, `reactive`, or `apparent`,
+  respectively. Measured in "kW" units for 'dc' measurements.
+  - `demand`: Average electric power over a defined time interval (e.g., 5, 15, or 30
+  minutes).  Measured in the same units that are used for `power` measurements.
+  - `energy`: Integral of electric power over time. Measured in "kWh", "kVARh", or
+  "kVAh" units for 'ac' measurements depending on the characteristic `active`,
+  `reactive`, or `apparent`, respectively. Measured in "kWh" units for 'dc'
   measurements.
-  - `current`: Instantaneously measured in "A" units for both 'ac' and
-  'dc' measurements.
+  - `volt`: Effective voltage. Root mean square (RMS) voltage is assumed for `ac`
+  measurements. Measured in "V" units.
+  - `current`: Effective current. Root mean square (RMS) current is assumed for `ac`
+  measurements. Measured in "A" units.
 
 The following primary quantities apply only to AC electrical measurements:
-  - `freq`: Instantaneously measured in "Hz" units.
-  - `pf`: Instantaneously measured as a percentage of AC active power to
-  AC apparent power.
+  - `freq`: The number of cycles per second in an alternating current (AC) sinusoidal
+  waveform. Measured in "Hz" units.
+  - `pf`: The ratio of active power to apparent power. Measured with numbers in the
+  range of -1.0 to 1.0 or 0.0 to 1.0 with a special unit called 'pf', which is
+  effectively unitless and used for data visualization.
 
 Some electric meters log interval-based data, demand or energy, using a
 monotonically increasing value in time.  The difference of these values
@@ -151,7 +152,7 @@ AC voltage and current measurements are further qualified by the following
 characteristics:
   - `magnitude`: magnitude (assumed as default)
   - `angle`: phase angle, typically measured in "deg"
-  - `imbalance`: imbalance between phases, measured in "%"
+  - `imbalance`: imbalance, measured in "%"
   - `thd`: total harmonic distortion, measured in "%"
 
 Similarly AC power factor measurements are further qualified using a
@@ -188,10 +189,6 @@ Non-aggregated 'ac' electrical measurement locations are qualified by:
   - `neutral`: for electrical current measurement of the electrical neutral
   conductor
 
-Note: In the future 'phaseDemand' and 'lineDemand' tags may be defined.  For now
-'phasePower' or 'linePower' tags may be used to describe point entities with the
-'demand' tag.
-
 Aggregated three-phase 'ac' electrical measurement locations are qualified by:
   - `lineAvg`: When applied to a point entity with the 'current' tag, indicates the
   average of the values for the 'current' primary quantity characteristic at all
@@ -222,9 +219,13 @@ Aggregated split-phase 'ac' electrical measurement locations are qualified by:
   'elecLine'.
   - `total`: Applies only to point entities with 'power', 'demand', or 'energy' tags.
   Indicates the sum of the values for the primary quantity's characteristic at the "L1"
-  and "L2" locations defined in 'elecLine'. This tag is also used in conjunction with
-  the 'elecLineToLine' tag that has a value "L1-L2" to help describe the complete flow
-  of electricity in a common way for three-phase and split-phase electrical systems.
+  and "L2" locations defined in 'elecLine'.
+
+Only one tag indicating the location of a measurement should be applied to a point
+entity. The 'total' tag takes precedence when applicable to allow for common queries
+between three-phase and split-phase AC electrical systems. For example, in a
+split-phase 'ac' electrical system the 'total' tag should be applied to a point entity
+instead of 'linePower' to indicate the L1-L2 power measurement.
 
 Note:  The primary quantity 'freq' does not have location related tags.
 

src/phIoT/lib/elec.trio

@@ -242,8 +242,10 @@ is: ^quantity
 quantityOf: ^ac-elec
 prefUnit: ["pf"]
 doc:
-  Electrical power factor; unitless number between 0.0 and 1.0 which is ratio
-  of active to apparent power in an AC power system.
+  Electric power factor; which is the ratio of active power to apparent
+  power in an AC electric power system.  Measured with numbers in the range
+  of -1.0 to 1.0 or 0.0 to 1.0 with a special unit called 'pf', which is
+  effectively unitless and used for data visualization.
 --------------------------------------------------------------------------
 def: ^pfScope
 is: ^choice
@@ -340,13 +342,13 @@ def: ^current-imbalance
 is: ^quantity
 quantityOf: ^ac-elec
 prefUnit: ["%"]
-doc: "Current phase imbalance in a multiphase AC system"
+doc: "AC current imbalance"
 --------------------------------------------------------------------------
 def: ^current-thd
 is: ^quantity
 quantityOf: ^ac-elec
 prefUnit: ["%"]
-doc: "Total harmonic current distortion"
+doc: "Total harmonic distortion (THD) of current"
 --------------------------------------------------------------------------
 
 //////////////////////////////////////////////////////////////////////////
@@ -370,7 +372,13 @@ def: ^volt-imbalance
 is: ^quantity
 quantityOf: ^ac-elec
 prefUnit: ["%"]
-doc: "AC voltage phase imbalance"
+doc: "AC voltage imbalance"
+--------------------------------------------------------------------------
+def: ^volt-thd
+is: ^quantity
+quantityOf: ^ac-elec
+prefUnit: ["%"]
+doc: "Total harmonic distortion (THD) of voltage"
 --------------------------------------------------------------------------
 
 //////////////////////////////////////////////////////////////////////////