 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.
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 storeandforward database if the values have changed since last sample. If not set, it is false. 
SampleDataType  stringenum  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  maybeoptional  Controls if a sample limit violation results in the sample value being discarded. Mandatory if either SampleLowerLimit or SampleUpperLimit is present. 
SampleLimitAlarm  bool  maybeoptional  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  stringenum  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  maybeoptional  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  maybeoptional  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 (eventbased 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 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" (squareroot), which pops the top 1 value off the stack, calculates the squareroot 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 top1 value if top value is nonzero, otherwise top2 value is pushed.
 "dropif" (1 value), which pops the top value and if it is nonzero, 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 nonzero, the Values list will be collected. This is known as eventdriven collection.
If an expression results in a runtime 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.