Skip to content

Calculated Fields · Changes

Page history
Merge branch 'master' of https://github.com/alanmitchell/bmon.wiki authored by Root's avatar Root
Hide whitespace changes
Inline Side-by-side
SysAdmin/Calculated-Fields.md
View page @ 412030d4
......@@ -3,7 +3,7 @@ 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:
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.
......@@ -16,9 +16,9 @@ We will start by explaining the second use of Calculated Fields, i.e. gathering
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]]
![image](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):
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
......@@ -26,11 +26,11 @@ The only changes necessary to acquire a wind speed value in miles per hour is to
---
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).
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]]
![image](images/calc_ex2.png)
The key differences from the National Weather Service configuration are:
......@@ -42,7 +42,7 @@ The key differences from the National Weather Service configuration are:
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`.
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
......@@ -108,7 +108,7 @@ Some sensors record the precise time of On and Off events. An example of such a
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]]
![image](images/calc_ex3.png)
The `Unit` entry generally should be `runtime: Runtime Fraction` or `fraction: Occupied 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:
......@@ -119,22 +119,22 @@ In this example, the Sensor ID is `29631`, an ID of a Monnit Dry Contact sensor.
onOffID: 29631
runtimeInterval: 15
This special runtime function is also useful with Motion or Occupancy Sensors and 1-wire Motor Sensors used with the [[Mini-Monitor]].
This special runtime function is also useful with Motion or Occupancy Sensors and 1-wire Motor Sensors used with the [Mini-Monitor).
## Mathematical Calculated Fields
Unlike [[Transform Expressions]], there is unfortunately no general method for creating calculated fields through use of math expressions. Instead, there are a number of predetermined functions available for creating calculated fields from existing sensor values. The table below shows the functions available and use of the functions is explained in the section following the table.
Unlike [Transform Expressions), there is unfortunately no general method for creating calculated fields through use of math expressions. Instead, there are a number of predetermined functions available for creating calculated fields from existing sensor values. The table below shows the functions available and use of the functions is explained in the section following the table.
|Function Name|Expression Performed|
|-------------|--------------------|
|linear|`slope * val + offset`<br>`slope` default is 1.0<br>`offset` default is 0.0|
|AminusB|`A - B`|
|AplusBplusCplusD|`A + B + C + D`<br>`C` default is 0.0<br>`D` default is 0.0|
|fluidHeatFlow|`flow * (Thot - Tcold) * multiplier * (1.0-heat_recovery)`<br>`heat_recovery` default is 0.0|
](Function Name](Expression Performed](
](-------------](--------------------](
](linear](`slope * val + offset`<br>`slope` default is 1.0<br>`offset` default is 0.0](
](AminusB](`A - B`](
](AplusBplusCplusD](`A + B + C + D`<br>`C` default is 0.0<br>`D` default is 0.0](
](fluidHeatFlow](`flow * (Thot - Tcold) * multiplier * (1.0-heat_recovery)`<br>`heat_recovery` default is 0.0](
Each one of these functions can create a Calculated Field based by applying a mathematical expression to a number of variables. The mathematical expression that is used is shown in the `Expression Performed` column of the table above. Each expression has a number of variables. Each variable can either be a number or Sensor ID (at least *one* of the variables *must* be a Sensor ID). Variables may have default values, as indicated in the table above. If a variable has a default value, it does not need to appear in the `Function Parameters` configuration box. Here is an example for the `linear` function:
[[images/calc_ex5.png]]
![image](images/calc_ex5.png)
In this example, there already is a sensor that reports the firing rate of a boiler as a percentage value varying from 0 to 100. We now want to create a Calculated Field that displays the rate of natural gas use of the boiler, expressed in Btu/hour. Because the gas use and the firing rate of the boiler are linearly related, we can use the `linear` Calculated Field function to create this gas usage field. Multiplying the firing rate by 1500 will give the gas usage in Btu/hour since the maximum gas usage of the boiler is 150,000 Btu/hour; a 100 firing rate times 1500 gives a gas usage of 150,000.
......@@ -148,7 +148,7 @@ So, every 30 minutes BMON will gather up all of the `Burth158_firing_rate` senso
Here is a more complicated example that creates a Calculated Field that estimates the natural gas usage of a sidewalk snowmelt system based on measuring supply and return temperatures and the runtime of a circulating pump:
[[images/calc_ex6.png]]
![image](images/calc_ex6.png)
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.
......