Aggregation Sample Point
- 18 May 2021
- 6 Minutes to read
-
Contributors
-
Print
-
DarkLight
-
PDF
Aggregation Sample Point
- Updated on 18 May 2021
- 6 Minutes to read
-
Contributors
-
Print
-
DarkLight
-
PDF
The purpose of this article is to serve as a reference for the Aggregation part of the complete Data Collection Module documentation.
Prerequisite
A starter pack (SiteManager + accounts)
A device capable of supporting data collection via one of the DCM protocol's sample points from where the aggregation can retrieve data.
Aggregations
are special sample points that can take values from other sample points and use them in calculations and condition monitoring. An example of a calculation can be when a PLC reads a temperature sensor with the value 3400 as a representation of 34.0 degrees celsius. By dividing the value by 100 and delivering as a comma value you deliver a human readable value to the cloud, with no need for a post-calculation in the cloud. A condition monitoring aggregation (also described as event-based triggering) could be an aggregation that monitors a sample point value and the trigger changes to a sample interval on one or more sample points when a certain condition is met (true).
The Collectors' (array of objects, mandatory ) list elements contain the following fields:
Sample points items
The sample point objects contain the following elements:
| Function | Type | Importance | Description |
|---|---|---|---|
| SampleName | string | mandatory | Name of the sampled value (sometimes called a tag name). Follows the normal rules for names. |
| SampleDescription | string | optional | Text description of the sample value. |
| SampleUnit | string | optional | Description of the unit of measurement for this sample. |
| SampleGroup | string | optional | Designates (in some datasrvs) that all sample points in that group should be handled (displayed) together. The DCM system itself places no meaning on this group affiliation. |
| SamplesSaved | integer > 0 | mandatory | Number of values collected and saved as a minimum in the Store'n'Forward database. If set to 0 sample point is not stored in the S'n'F database and thus not delivered to the cloud but can be used for aggregations. |
| OnlySaveOnChanged | bool | optional | Control if new sample values should only be saved to the store-and-forward database if the values have changed since last sample. If not set, it is false. |
| SampleDataType | string-enum | mandatory | The type of data collected. The possible values are: "bool" (1 bit), "sbyte" (8 bit signed), "byte" (8 bit unsigned), "int16" (16 bit signed), "uint16" (16 bit unsigned), "int32" (32 signed), "uint32" (32 bit unsigned), "int64" (64 bit signed), "uint64" (64 bit unsigned), "float" (32 bit), "double" (64 bit) |
| SampleLowerLimit | integer/double | optional | The lower limit for the collected data. If the collected data value is less than SampleLowerLimit it is evaluated in accordance with SampleLimitDiscard and SampleLimitAlarm. |
| SampleUpperLimit | integer/double | optional | The upper limit for the collected data. If the collected data value is more than SampleUpperLimit it is evaluated in accordance with SampleLimitDiscard and SampleLimitAlarm. |
| SampleLimitDiscard | bool | maybe-optional | Controls if a sample limit violation results in the sample value being discarded. Mandatory if either SampleLowerLimit or SampleUpperLimit is present. |
| SampleLimitAlarm | bool | maybe-optional | Controls if a sample limit violation generates an alarm. Mandatory if either SampleLowerLimit or SampleUpperLimit is present. |
| Aggregation | Object | optional | Description of how to create a new sample value by performing an aggregation function of other sample values, either physical sample values or other aggregation created sample values. |
Aggregation
The Aggregation object contains the following fields:
| Function | Type | Importance | Description |
|---|---|---|---|
| Function | string-enum | mandatory | This is the aggregation function to be performed. The current possible values are: "max", "min", "avg", "mavg", "derived", "compute", "eventcompute". |
| Values | array of strings | maybe-optional | This is a list of sampleref references, whose values will be arguments for the aggregation function. Mandatory for all values of Function except "compute" and "eventcompute". |
| TriggerSample | string | mandatory | This is a sampleref to the sample that will trigger the evaluation of the aggregation function. Only when the sample is updated (either by sampling from a device or from another aggregation), will this aggregation function evaluate and create a new sample value itself. |
| Expression | string | maybe-optional | This is an arithmetic expression using Reverse Polish Notation (RPN) with sampleref, numeric constants and operators separated by commas. See the section on RPN expressions. This field is mandatory if Function is "compute" or "eventcompute". |
| TriggerNewInterval | integer > 0 | optional) | This is a new sample interval (in secs) for the TriggerSample that should be in effect when the event is triggered. When the event is not triggered, the TriggerSample's normal interval is used. Only used when the Function is "eventcompute". If more than one "eventcompute" event forces a new sample interval for the same sample, the lowest new interval is used. |
Aggregation sample point for condition monitoring (event-based logging)
{
"SampleName" : "EventValue",
"SampleDescription" : "When Test1_REG107 value >= 50, sample REG107 and Reg108 fast",
"SamplesSaved" : 0,
"SampleDataType" : "uint32",
"Aggregation" : {
"Function" : "eventcompute",
"Expression" : "Test1_REG107,50,>=",
"Values" : [ "Test1_REG108","Test1_REG107" ],
"TriggerSample" : "Test1_REG107",
"TriggerNewInterval" : 2
}
}Aggregation sample point for division
{
"SampleName": "Test1_REG100_DIV",
"SampleDescription": "Register 1 value divided by 100",
"SamplesSaved": 10,
"SampleDataType": "double",
"Aggregation" : {
"Function" : "compute",
"Expression" : "Test1_REG100, 100, /",
"TriggerSample" : "Test1_REG100"
}
}See complete aggregation examples in the related articles section below.
The RPN expression uses these operands:
The aggregation functions compute and eventcompute both have a string with an arithmetic expression that is evaluated whenever the TriggerSample value is updated. This expression is represented in RPN (Reverse Polish Notation), which operates on a stack (max 32 values). All calculations are done in either signed 64bit integer, unsigned 64bit integer or double floating point, depending on the datatype of the aggregation sample. Once the result is stored, any overflow is ignored. The RPN is a list of operators separated by commas. The operators are:
- sampleref which pushes the newest value of the designated value onto the stack.
- Constant, which pushes the constant onto the stack.
- "+" (addition), which pops the top 2 values off the stack, adds them and pushes the result onto the stack.
- "-" (subtraction), which pops the top 2 values off the stack, subtracts them and pushes the result onto the stack.
- "*" (multiplication), which pops the top 2 values off the stack, multiplies them and pushes the result onto the stack.
- "/" (division), which pops the top 2 values off the stack, divides them and pushes the result onto the stack.
- "%" (modulo), which pops the top 2 values off the stack, calculates the modulo of them and pushes the result onto the stack.
- "^" (exponential), which pops the top 2 values off the stack, calculates the exponential of them and pushes the result onto the stack.
- "sqrt" (square-root), which pops the top 1 value off the stack, calculates the square-root of it and pushes the result onto the stack.
- "abs" (absolute), which pops the top 1 value off the stack, calculates the absolute value of it and pushes the result onto the stack.
- "max" (maximum), which pops the top 2 values off the stack, calculates the maximum of them and pushes the result onto the stack.
- "min" (minimum), which pops the top 2 values off the stack, calculates the minimum of them and pushes the result onto the stack.
- "&&" (logical and), which pops the top 2 values off the stack, calculates the logical AND of them and pushes the result onto the stack.
- "||" (logical or), which pops the top 2 values off the stack, calculates the logical OR of them and pushes the result onto the stack.
- ">" (greater than), which pops the top 2 values off the stack, compares them and pushes 1 onto the stack if greater than and 0 otherwise.
- ">=" (greater than or equal to), which pops the top 2 values off the stack, compares them and pushes 1 onto the stack if greater than or equal to and 0 otherwise.
- "<" (less than), which pops the top 2 values off the stack, compares them and pushes 1 onto the stack if less than and 0 otherwise.
- "<=" (less than or equal to), which pops the top 2 values off the stack, compares them and pushes 1 onto the stack if less than or equal to and 0 otherwise.
- "==" (equal to), which pops the top 2 values off the stack, compares them and pushes 1 onto the stack if they are equal and 0 otherwise.
- "!=" (not equal to), which pops the top 2 values off the stack, compares them and pushes 1 onto the stack if they are not equal and 0 otherwise.
- "if" (3 values), which pops the top 3 values off the stack, pushes top-1 value if top value is non-zero, otherwise top-2 value is pushed.
- "dropif" (1 value), which pops the top value and if it is non-zero, execution of expression will stop and no new value will be stored. NOTE: Does not push any result.
When the RPN expression ends, the top value is the new value of the aggregation sample. If the aggregation is an "eventcompute" aggregation and the new value is non-zero, the Values list will be collected. This is known as event-driven collection.
If an expression results in a run-time error, (compilation error, divide by zero, stack overflow, insufficient operands for operator or empty stack on completion), the execution is suspended until DCM is restarted.
Was this article helpful?
