SysAdmin/Calculated-Fields.md

@@ -45,6 +45,54 @@ 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`.
 
 
+## Acquiring Building Energy Usage Information from ARIS
+
+BMON can import building energy usage information from AHFC's Alaska Retrofit Information System (ARIS). Configuring a sensor for the imported data is very similar to the process for acquiring weather data from the internet described above.
+
+Using the administration interface, create a new Sensor ID.  `Title` and `Unit` entries are filled out as they are for standard sensors.  The `Calculated Field` box must be checked.  The `Transform or Calculated Field Function Name` must contain the value `getUsageFromARIS` (correct capitalization is critical and must be as shown).  Finally, the `Function Parameters in YAML form` box must have an entry of `building_id: ` (there must be a space after the colon) with a valid building id number from the ARIS database, and an entry of `energy_type_id: ` with a valid energy type value as described below.
+
+Required Function Parameters in YAML form:
+
+    building_id: 1
+    energy_type_id: 1
+
+Additional Optional Function Parameters in YAML form:
+
+    energy_parameter: 'EnergyQuantity'
+    energy_multiplier: 1
+    expected_period_months: 1
+
+####`building_id` Parameter
+The easiest way to find a building_id value is to look on the 'Commercial REAL Form' in the ARIS user interface. When you select a building the building_id should show up in the upper left corner of the form.
+
+####`energy_type_id` Parameter
+Possible values for the energy_type_id parameter:
+- 1: 'Electric'
+- 2: 'Natural Gas'
+- 3: 'Propane'
+- 6: 'Coal'
+- 7: 'Demand - Electric'
+- 8: 'Demand - Nat Gas'
+- 10: 'Steam District Ht'
+- 11: 'Hot Wtr District Ht'
+- 12: 'Spruce Wood'
+- 13: 'Birch Wood'
+- 14: '#1 Fuel Oil'
+- 15: '#2 Fuel Oil'
+
+####`energy_parameter` Optional Parameter
+The energy_parameter specifies which value will be read from the ARIS database:
+- EnergyQuantity: The amount of energy used
+- DollarCost: The cost of energy for the given month
+- DemandUse: The amount of energy demand
+- DemandCost: The cost of energy demand for the given month, in dollars
+
+A value of 'EnergyQuantity' will be used by default if you don't include this parameter. 
+####`energy_multiplier` Optional Parameter
+The energy_multiplier is a multiplier that is used to scale the value that is read from the ARIS database if hte energy_parameter is 'EnergyQuantity'. If you don't include the parameter, a value of 1.0 will be used by default. The value that is stored is calculated as:
+    [stored value] = [value from ARIS] / [hours in the read period] * energy_multiplier
+####`expected_period_months` Optional Parameter
+In rare cases where the normal read period for the energy usage is other than one month, you can enter a different number of months using this parameter. This value is used for estimating the previous read date when the date wasn't set for the previous entry in ARIS, and for detecting missing data when the previous read date is more than 1.75 * [expected period months] earlier than the current read date.
 ## 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.
@@ -95,5 +143,4 @@ Here is a more complicated example that creates a Calculated Field that estimate
 
 The Calculated Function being used here is the `fluidHeatFlow` function, as described in the table above.  You can see in the `Function Parameters` box that the `heat_recovery` variable is *not* provided in the configuration of this Calculated Field.  Therefore, the `heat_recovery` variable will assume its default value of 0.0.  Three of the variables in the math expression for the `fluidHeatFlow` function come from existing sensor values: `flow`, `Thot`, and `Tcold`.  In the `Function Parameter` box, these variable names are prefaced by the `id_` prefix, indicating the values provided are Sensor IDs.  The `multiplier` variable is not a sensor value but instead the constant 14960.0.
 
-Finally, you can see that the `flow` variable appears in the `Function Parameter` box as `id_flow_sync`.  As explained before, the `id_` prefix indicates that the variable comes from a Sensor.  The `_sync` suffix indicates that the final calculated values for the new sensor (`manor_snw1_gas`) should be synchronized on the timestamps of this sensor. The other input sensor values (`Thot` and `Tcold`) will be interpolated to these timestamp values when the calculation occurs.  If you have multiple sensor values entering into a Calculated Field, you can add the suffix `_sync` to the variable whose timestamp values should be used for the resulting calculated values.  If you do not append `_sync` to one of the variable names, one of the inputs sensors will be used for synchronization, but it will not be easy to determine which one.
-
+Finally, you can see that the `flow` variable appears in the `Function Parameter` box as `id_flow_sync`.  As explained before, the `id_` prefix indicates that the variable comes from a Sensor.  The `_sync` suffix indicates that the final calculated values for the new sensor (`manor_snw1_gas`) should be synchronized on the timestamps of this sensor. The other input sensor values (`Thot` and `Tcold`) will be interpolated to these timestamp values when the calculation occurs.  If you have multiple sensor values entering into a Calculated Field, you can add the suffix `_sync` to the variable whose timestamp values should be used for the resulting calculated values.  If you do not append `_sync` to one of the variable names, one of the inputs sensors will be used for synchronization, but it will not be easy to determine which one.
\ No newline at end of file