SysAdmin/Calculated-Fields.md

@@ -45,7 +45,19 @@ The key differences from the National Weather Service configuration are:
 For how to form station codes, see the [[Weather Underground API documentation|http://www.wunderground.com/weather/api/d/docs?d=data/index]] for the `query` pararmeter. In this example, two personal weather stations are being used with station IDs of `KAKANCH0124` and `MD0691`.
 
 
+## Converting On/Off Events into Runtime Fraction
 
+Some sensors record the precise time of On and Off events.  An example of such a sensor is a Monnit Dry Contact sensor.  This sensor posts a reading every time its two contacts are closed or are opened, and the sensor is often used to record when a device turns on and turns off.  As well as seeing the exact times that a device turned on and turned off, it is often useful to record the *percentage of time* that the device was on during evenly spaced intervals.
+
+To provide this addtional information, a special Calculated Field function is provided in BMON.  The function will create a separate "sensor" in the BMON system that shows the fraction of time that a device was On for every half-hour interval (or other user-configurable interval).  This function is called `runtimeFromOnOff`, and here is an example of its use:
+
+[[images/calc_ex3.png]]
+
+The `Unit` entry generally should be `runtime: Runtime Fraction`.  `runtimeFromOnOff` must be entered as the `Transform or Calculated Field Function Name`.  Finally, you need to provide the Sensor ID of the sensor that records the precise On and Off times (that sensor needs to report a value of 1 when the device turns on and a value of 0 when the device turns off).  That Sensor ID is entered as the `onOffID` parameter in the `Function Parameters` box:
+
+    onOffID: 29631
+
+In this example, the Sensor ID is `29631`, an ID of a Monnit Dry Contact sensor.  This special runtime function is also useful with Motion or Occupancy Sensors and 1-wire Motor Sensors used with the [[Mini-Monitor]].
 
 ## Entering Sensor IDs for Calculated Fields