SysAdmin/Transform-Expressions.md

@@ -22,7 +22,7 @@ Special pulse counter Transform features were developed to address this situatio
 
 [[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.
+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 the 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 automatically 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:
 
@@ -31,3 +31,16 @@ So continuing with the example, we know that BMON has already calculated pulse r
     rate * 3636000
 
 `rate * 3636000` is the expression shown in the `Transform or Calculated Field Function Name` box.
+
+There are couple other optional but often important parameters that can be entered in the `Function Parameters in YAML form` box:
+
+**`max_rate`** (default value = 5.0, expressed as pulses/second):  Pulse count reporting errors (one common one described below) can sometimes lead to an erroneous high pulse rate calculation.  BMON will not save any sensor values if the pulse rate is above this `max_rate` value.  For the example above, a maximum pulse rate 1.5 pulses per second is set.  This corresponds to a 5,454,000 Btu/hour rate.  Reported sensor values will be rejected if they exceed this rate.  Note that there is a default `max_rate` value of 5.0 pulses/second if you value is provided in the `Function Parameters` box.
+
+**`rollover`** (default value = 65536, largest 16 bit value):  Pulse counters usually have a maximum pulse count that they record before rolling over to zero.  BMON will account for this rollover when calculating the pulse rate.  Year 2014 and prior [[Monnit wireless pulse counters|http://www.monnit.com/ProductSearch?SortBy=Rank&Asc=False+&PageSize=12&ProductCategory=1&SensorType=32&SensorProfile=30]] roll over at a count of 65,536, the default value for this parameter.  Newer Monnit pulse counters are 32 bit and roll over at 4,294,967,296.  If you expect your pulse counter to eventually roll over, you need to ensure that BMON is using the correct `rollover` value.
+
+**`ignore_zero`** (default value = `True`, the other valid value is `False`): Monnit Wireless pulse counters occasionally reset to a pulse count of zero if there are transmission problems or an accidental reset of the sensor.  So, the pulse count value of zero is usually an erroneous value.  By leaving this `ignore_zero` parameter at its default value of `True`, these zero pulse count readings will be ignored and no value will be stored until the next valid reading.
+
+**`min_interval`** (default value = 60, measured in seconds): Monnit wireless pulse counters sometimes send the same pulse count value twice but with slight separation in time, resulting in a zero calculated pulse rate.  To filter out these erroneous readings you can set a `min_interval` between valid readings, measured in seconds.  If two successive readings are separated by less than this number of seconds, the second reading will be rejected.  The default value is 60 seconds.
+
+Also note that all readings that use this pulse count transform are time-stamped at the midpoint between the current reading time and the previous reading time, since the rate reported is derived from the interval spanning those two time points.
+