SysAdmin/Calculated-Fields.md

@@ -70,10 +70,29 @@ Unlike [[Transform Expressions]], there is unfortunately no general method for c
 
 |Function Name|Expression Performed|
 |-------------|--------------------|
-|`linear`|`slope * val + offset`<br>`slope` default is 1.0<br>`offset` default is 0.0|
+|linear|`slope * val + offset`<br>`slope` default is 1.0<br>`offset` default is 0.0|
 |AminusB|`A - B`|
 |AplusBplusCplusD|`A + B + C + D`<br>`C` default is 0.0<br>`D` default is 0.0|
-|fluidHeatFlow|`flow * (Thot - Tcold) * heat_capacity * (1.0-heat_recovery)`<br>`heat_recovery` default is 0.0|
+|fluidHeatFlow|`flow * (Thot - Tcold) * multiplier * (1.0-heat_recovery)`<br>`heat_recovery` default is 0.0|
+
+Each one of these functions can create a Calculated Field based by applying a mathematical expression to a number of variables.  The mathematical expression that is used is shown in the `Expression Performed` column of the table above.  Each expression has a number of variables.  Each variable can either be a number or Sensor ID (at least *one* of the variables *must* be a Sensor ID).  Variables may have default values, as indicated in the table above.  If a variable has a default value, it does not need to appear in the `Function Parameters` configuration box.  Here is an example for the `linear` function:
+
+[[images/calac_ex5.png]]
+
+In this example, there already is a sensor that reports the firing rate of a boiler as a percentage value varying from 0 to 100.  We now want to create a Calculated Field that displays the rate of natural gas use of the boiler, expressed in Btu/hour.  Because the gas use and the firing rate of the boiler are linearly related, we can use the `linear` Calculated Field function to create this gas usage field.  Multiplying the firing rate by 1500 will give the gas usage in Btu/hour since the maximum gas usage of the boiler is 150,000 Btu/hour; a 100 firing rate times 1500 gives a gas usage of 150,000.
+
+The `linear` function has three variables: `val`, `slope`, and `offset`.  For our example, our conversion multiplier of 1500 is the `slope` variable, and you can see its entry in the `Function Parameters` in the above screenshot.  The `offset` variable is not needed in this application; BMON has a default value of 0.0 for this variable, which is correct for our application, so therefore we need not provide the variable in the `Funcation Parameters` box.  Finally, the `val` variable will be used for the Firing Rate sensor values that we are using to calculate gas usage.  Since this variable needs to be filled in with sensor values, *we need to preface the variable with `id_`* to indicate that this variable is a set of sensor values.  Then, the value provided for the variable in the `Function Parameters` box is a Sensor ID:
+
+    id_val: Burt158_firing_rate
+
+The `id_` prefix on the variable `val` indicates that the variable will be taken from an existing sensor.  `Burt158_firing_rate` is the Sensor ID of the firing rate sensor.
+
+So, every 30 minutes BMON will gather up all of the `Burth158_firing_rate` sensor readings that have not already been used previously in this calculation, and BMON will multiply the by 1500 to create additional sensor readings for the `Burt158_boiler_gas` sensor.
+
+Here is a more complicated example, which also illustrates an additional feature:
+
+[[images/calc_ex6.png]]
+