SysAdmin/Transform-Expressions.md

@@ -10,6 +10,24 @@ Transform Expressions are entered on the Sensor editing screen.  The screenshot
 
 [[images/transform_ex1.png]]
 
-In the `Transform or Calculated Field Function Name` box you can see the transform expression:  `val*35.0 - 140.0`.  The variable `val` is always available in a Transform Expression and it contains the raw sensor value that was posted.  This transform multiplies that raw value by 35.0 and then subtracts 140.0.  When creating these expressions, you have all the [[built-in functions|https://docs.python.org/2/library/functions.html]]  (e.g. `abs()` for absolute value, ) from the Python programming language plus the functions available in the [[Python `math` module|https://docs.python.org/2/library/math.html]]  (e.g. `sqrt()`, `sin()`, `log10()`).  So, an expression such as `sqrt(val)/(val - 8.6)` is a valid transform expression.
+In the `Transform or Calculated Field Function Name` box you can see the transform expression:  `val*35.0 - 140.0`.  The variable `val` is always available in a Transform Expression and it contains the raw sensor value that was posted.  This transform multiplies that raw value by 35.0 and then subtracts 140.0.  When creating these expressions, you have all the [[built-in functions|https://docs.python.org/2/library/functions.html]]  (e.g. `abs()` for absolute value, ) from the Python programming language plus the functions available in the [[Python math module|https://docs.python.org/2/library/math.html]]  (e.g. `sqrt()`, `sin()`, `log10()`).  So, an expression such as `sqrt(val)/(val - 8.6)` is a valid transform expression.
 
 In the above screenshot, note that the `Calculated Field` box is **not** checked.  This is not a new calculated field, created from other sensor values or the gathered from the Internet.  Instead, this is just a conversion of an incoming sensor value.
+
+## Pulse Counter Transforms
+
+Electric meters, gas meters, water meters, and fuel meters often produce pulses as a means of electronically communicating flow through the meter.  Each pulse represents a fixed amount of energy or volume of material flowing through the meter.  The pulse output of the meter can be connected to a pulse counter that reports total pulse counts to the BMON system.  It is generally desirable to convert these pulse count totals into a rate of flow of energy, fluid, or gas.  By converting to a rate (units / second), variations in the length of the interval measured by the pulse counter are factored out of the measured value.
+
+Special pulse counter Transform features were developed to address this situation.  The recommended setting for a pulse counter is to have it continually accumulate pulse counts, only resetting to zero when a maximum rollover pulse count is reached.  If your pulse counter is set up in this way, below is an example of how you can transform the total pulse count values into a usable rate value.  In this example, a natural gas meter is being read, and a pulse occurs for each CCF of gas passing through the meter.  Our objective is to convert the pulse count readings into a gas flow measured in Btu/hour.
+
+[[images/transform_ex2.png]]
+
+The BMON Transform feature has a special variable named `rate`.  If a Transform expression uses this variable, BMON knows that a pulse count is being measured, and BMON automatically calculates the pulse rate per second indicated by the last pulse count reading received relative to the prior pulse count reading.  This pulse rate is stored in the variable `rate`.  As an example, assume that the last pulse count received was a total count of 10,435.  The prior pulse count reading from the sensor was 9,623 and it was receive 605 seconds prior to current reading.  The pulse rate that occurred between the two readings was `(10435 - 9623) / 605 = 1.342 pulses/second`.  This value of 1.342 is stored in the `rate` variable.
+
+So continuing with the example, we know that BMON has already calculated pulse rate per second for the gas meter.  We also know that one CCF of gas contains 1,010 Btus.  To convert the pulse rate into Btus/hour we would do the following:
+
+    rate (pulses/sec)  *  1,010 Btus/pulse  *  3,600 sec/hour
+        which is
+    rate * 3636000
+
+`rate * 3636000` is the expression shown in the `Transform or Calculated Field Function Name` box.
\ No newline at end of file