avatar  

Log out

Recently viewed tickets

Aggregation

The purpose of this article is to be a reference for Aggregation part
of the full Data Collection Module documentation

Prerequisite:

A Starter package (SiteManager + accounts)
A device capable of supporting data collection via 1 of the DCM protocols
Samplepoints where the aggregation can get data from
Other sections in DCM:


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 is that a PLC reads a temperature sensor with the value 3400 as a representation of 34.0 degrees celcius. So by dividing the value by 100 and delivering as a comma value you deliver a human readable value to the cloud, with no need to do after calculation in the cloud. A condition monitoring aggregation (also mentioned as eventbased triggering) could be an aggregation that monitors a sample point value and the trigger changes to sampleinterval on 1 or more samplepoints when a certain condition is met (true).


The Collectors (array of objects, mandatory ) list elements contains the following fields:

Samplepoint items

The SamplePoints objects contains the following elements:
FunctionTypeImportanceDescription
SampleNamestringmandatoryName of this sampled value (sometimes called a tagname). Follows the normal rules for names.
SampleDescriptionstringoptionalis a text description of this sample value.
SampleUnitstringoptionalis a description of the unit of messurement for this sample.
SampleGroupstringoptionaldesignates (in some datasrvs) that all samplepoints in that group should be handled (displayed) together. The DCM system itself places no meaning on this group affiliation.
SamplesSavedinteger > 0mandatoryis the number of values collected that is saved as minimum in the Store'n'Forward database. If set to 0 the Samplepoint isn't stored in the S'n'F database and thus not delivered to cloud, but can be used for aggregations.
OnlySaveOnChangedbooloptionalcontrol 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.
SampleDataTypestring-enummandatoryThe 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)
SampleLowerLimitinteger/doubleoptionalThe lower limit for the collected data. If the collected data value is less than SampleLowerLimit it is evaluated inaccordance to SampleLimitDiscard and SampleLimitAlarm.
SampleUpperLimitinteger/doubleoptionalThe upper limit for the collected data. If the collected data value is more than SampleUpperLimit it is evaluated inaccordance to SampleLimitDiscard and SampleLimitAlarm.
SampleLimitDiscardboolmaybe-optionalControls if a sample limit violation results in the sample value being discarded. Mandatory if either SampleLowerLimit or SampleUpperLimit is present.
SampleLimitAlarmboolmaybe-optionalControls if a sample limit violation generates an alarm. Mandatory if either SampleLowerLimit or SampleUpperLimit is present.
AggregationObjectoptionalDescription of how to create a new sample value by performing an aggregation function of other sample values, either physically sample values or other aggregation created sample values.



Aggregation

The Aggregation object contains the following fields:
FunctionTypeImportanceDescription
Functionstring-enummandatoryThis is the aggregation function to be performed. The currently possible values are:
"max",
"min",
"avg",
"mavg",
"derived",
"compute",
"eventcompute".
Valuesarray of stringsmaybe-optionalThis is a list of sampleref references, whose values will be arguments to the aggregation function. Mandatory for all values of Function except "compute" and "eventcompute".
TriggerSamplestringmandatoryThis 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.
Expressionstringmaybe-optionalThis 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".
TriggerNewIntervalinteger > 0optional)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 samplepoint 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 samplepoint 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 here:


The RPN expression uses these operands:

The aggregation functions compute and eventcompute both have a string with an arithmetic expression, that is being 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 calculation 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 values is non-zero, the Values list will be collected. This is known as event driven data 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.

Creation date: 11/12/2019 14:10 (skr@secomea.com)      Updated: 29/10/2020 12:08 (tvo@secomea.com)