SysAdmin/Calculated-Fields.md

-Calculated Fields
+Calculated Fields are used for two purposes:
+
+- to calculate new sensor readings from other readings that are in the sensor database.
+- to add sensor readings gathered from the Internet.  The current implementation allows for acquistion of temperature and wind speed data from Internet weather services.
+
+A Calculated Field uses the same editing form in BMON as a standard Sensor does.  So, to add a Calculated Field, you follow the normal procedure for adding a Sensor, as described in [[this document|Adding Buildings and Sensors]].  The important configuration differences relative to a standard sensor are:
+
+- For a Calculated Field, you need to create your own Sensor ID for the calculated field.  The Sensor ID must be unique across the entire BMON set of Sensors.  The Sensor ID needs to be 30 characters or less, using numbers and letters but no spaces.
+- In the Sensor editing form, you need to make sure that the `Calculated Field` box is checked.
+
+The BMON system processes Calculated Fields every one-half hour.  If the calculated fields involve sensors that report more frequently than every half hour, multiple calculated sensor readings will be generated at each half-hour processing interval to match up with the frequency of the source sensors.
+
+We will start by explaining the second use of Calculated Fields, i.e. gathering data from Internet Weather Services.
+
+## Acquiring Weather Data from the Internet
+
+BMON can currently access outdoor dry-bulb temperature and wind speed data from the National Weather Service and from the Weather Underground service.  Here is an example of the needed configuration for the National Weather Service:
+
+[[images/calc_ex1.png]]
+
+In the top box, a Sensor ID has been created, in this example: `elmendorf_temp`.  `Title` and `Unit` entries are filled out as they are for standard sensors.  The `Calculated Field` box must be checked.  For gathering outdoor dry-bulb temperature, the `Transform or Calculated Field Function Name` must contain the value `getInternetTemp` (correct capitalization is critical and must be as shown).  Finally, the `Function Parameters in YAML form` box must have an entry of `stnCode: ` plus a 4 character [[National Weather Service station code|http://www.weather.gov/]], in this example (there must be a space after the colon):
+
+    stnCode: PAED
+
+The only changes necessary to acquire a wind speed value in miles per hour is to enter `getInternetWindSpeed` into the `Transform or Calculated Field Function Name` box, to change the `Unit` to `velocity: mph`, and enter an appropriate Sensor ID and Title.
+
+---
+
+The Weather Underground service has a broader variety of weather stations, including personal weather stations.  To gather temperature or wind data from this service, you must first acquire a [[Weather Undergroup API Key|http://www.wunderground.com/weather/api/]] and enter that key into the [[BMON Settings File|How to Install BMON on a Web Server]] as the `BMSAPP_WU_API_KEY` setting (restarting the Django web application after changing a setting is necessary).
+
+Here is a sample configuration for acquiring temperature data from the service:
+
+[[images/calc_ex2.png]]
+
+The key differences from the National Weather Service configuration are:
+
+- `getWUtemperature` must be entered into the `Transform or Calculated Field Function Name` box.  If you are acquiring wind speed data, then the correct entry is `getWUwindSpeed`.  Capitalization must be as shown.
+- The `Function Parameters` box must contain a `stn` entry for the main weather station you want data from and possibly a `stn2` code for a weather station to use as a backup in case the primary station is not available.  An example entry is:
+
+    stn: pws:KAKANCHO124
+    stn2: pws:MD0691
+
+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`.
 
-## YAML Format for Function Parameters and Building Info
 
-There must be a space after the colon.  Correct: `stnCode: PANC`;  Incorrect `stnCode:PANC`.  A space *before* the colon is OK, like `stnCode : PANC`.
 
-For Boolean parameters, 'Yes/No', 'True/False' and 'On/Off' will work and are *not* sensitive to case.  'Y/N' will **not** work.
 
 ## Entering Sensor IDs for Calculated Fields