Tag configuration

To configure a tag as a Derived Tag, you must set the source to DerivedTags. First, create the tag and enable the source. Then, select the module type and choose the module instance as the source, as illustrated in the screenshot below:

After setting the source to DerivedTags, the following options will appear:

• Mode: 

• Options: This section contains options for the currently selected DerivedTag mode.

Aggregated Tags

Aggregated Tags are used to generate aggregated values based on the values of another tag acting as a data source. The following screenshot displays the available options for an Aggregated Tag:

• Aggregation method: Selects which aggregation to use in order to calculate the value for this tag. The valid values are:

  • Average: Returns the calculated time-weighted average of all good quality values received during the specified period. Periods with bad quality data are excluded from the calculation. If no good quality values are present throughout the entire period, the result will be a bad quality data point.

  • Minimum: Returns the lowest good quality value received during the period. If no good quality values exist during the entire period, a bad quality data point is returned.

  • Maximum: Returns the highest good quality value received during the period. If no good quality values exist during the entire period, a bad quality data point is returned.

  • First: Returns the value and its quality at the end of the aggregation period. The timestamp also reflects the end of the period.

  • Last: Returns the value and its quality at the end of the aggregation period. The timestamp also reflects the end of the period.

  • Count: Returns the total number of tag values received during the period.

  • Good: Returns the percentage of time the value maintained good quality throughout the period. (1.0 = good quality entire time, 0.0 = bad quality entire time).

  • Delta: Returns the difference between the values at the end and beginning of the period, but only if both have good quality. A bad quality data point is returned if either value has bad quality.

    Note:

    Delta aggregation method is available from N3uron version 1.21.4.

  • Standard Deviation: Returns the time-weighted standard deviation of all good quality values received during the period. Periods with bad quality data are excluded from the calculation. If no good quality values exist during the entire period, a bad quality data point is returned.

  • Custom: Allows you to define a script to calculate the aggregation in a way that best suits your needs.

    Note:

    Standard Deviation and Custom aggregation methods are available from N3uron version 1.21.10.

The timestamps returned by the aggregation methods correspond to the end of the chosen aggregation period.

• Period type:

  • Periodic: The tag executes periodically in fixed intervals.

  • Cron expression: The tag executes according to a cron expression.

    Note:

    Cron expression is available from N3uron version 1.21.4. Readers can find further information at Crontab Guru.

    Note:

    Cron expressions are evaluated according to the System Timezone.

• Aggregation period: Specifies the aggregation period. The minimum value is 10,000ms. 

• Source Tag: Specifies the tag used as the source for the aggregation. This can be a local tag or a tag from a remote node. It's possible to browse and discover the source tag by clicking on the button to the right.

  

  

Expression Tags

Expression Tags are used to generate a value based on a JavaScript expression. This can either be standalone or can involve a different source tag whose values are available in this expression. After setting the Type to Expression Tag, the following options will be shown:

• Trigger: Specifies the type of execution trigger. The available options are: 

  • On change: The Expression Tag will execute every time one of the inputs changes.

  • Periodic: The Expression Tag will execute after the specified period elapses.

  • Cron expression: The Expression Tag will execute according to a cron expression.

• Period: The time period between executions, displayed in milliseconds. This only applies when the Trigger is set to “Periodic”.

• Cron expression: Cron expression that determines when the script will be executed. This only applies when the Trigger is set to "Cron expression".

• Pause on connection loss: Enables or disables tag execution to be paused while the link for any remote input tag is down and the tag is in an uncertain quality. This setting only applies if there are remote tags involved in the expression. A remote tag is a tag received from another node through a N3uron link.

• Expression: Specifies the expression that will be executed whenever the Expression Tag triggers in order to obtain the value, quality, and timestamp of the derived tag. By clicking on this icon, a text box popup will appear, allowing for expressions that span multiple lines. See more information in Expressions. 

• Alias: This is used to define aliases for other tags within the model so that they can be referenced in the expression for this tag.

  • Input tag: Specifies the tag associated with the corresponding alias. It can point to any local or remote tag. If this tag is not present on startup, the subscription to the source tag fails and the expression cannot be executed. This tag path can either be absolute (beginning with /) or relative to the current group (optionally beginning with ./). The tag path can be left blank, in which case this alias will be ignored (and as such, it will not exist in  $.input).

    Note:

    Each alias must be unique. If two aliases point to the same tag, a warning is logged and the expression is not executed.

    
    
    

    Note:

    Users are free to add any number of aliases, but it’s important to be careful and ensure that only those with associated tags are used in the expression, as shown in the example below.

    //$.output=$.input.alias1.value+$.input.alias2.value+$.input.alias3.value+$.input.alias4.value
    
    // Initialize the output to 0
    $.output = 0;
    
    // Define an array of aliases
    const aliases = ['alias1', 'alias2', 'alias3', 'alias4'];
    
    // Use a for loop to iterate through the aliases
    for (let i = 0; i < aliases.length; i++) {
      const alias = aliases[i];
      
      // Check if the alias exists in $.input
      if ($.input[alias]) {
        // If the alias exists, add its value to the output
        $.output += $.input[alias].value;
      } else {
        // If the alias is missing, you can handle it here, e.g., set a default value
        $.output += 0; // Set to 0 for missing aliases, or handle the error as needed
      }
    }
    
    // $.output now contains the sum of values of existing aliases

Alias Tags

Note:

Alias Tags are available from N3uron version 1.2.4.

Note:

Starting from N3uron version 1.21.10, you can grant Read/Write permissions to the Alias Tag, allowing values written to it to be reflected in the input tag.

An Alias Tag is a copy of its input tag. That is, its value, timestamp, and quality will be a replica of those in the original tag. After setting the Type to Alias Tag, the following options will be shown:

• Input Tag: Selects the input tag that will be copied to this tag. This tag must be present in the tag model. Otherwise, a configuration error will be raised during runtime. It's possible to browse and discover the tag by clicking on the button to the right.

  
  

Redundant Tags

Note:

Redundant Tags are available from N3uron version 1.21.4.

Note:

Starting from N3uron version 1.21.10, you can grant Read/Write permissions to the Redundant Tag, allowing values written to it to be reflected in the input tags.

Redundant Tags are used to create tags with several inputs acting as redundant sources. The value, quality, and timestamp of the output tag correspond to the input tag with the highest quality. After setting the Type to Redundant Tag, the following options will be shown:

• Sources:

  • Input tag: Selects the input tag that will be copied to this tag. This tag must be present in the tag model. Otherwise, a configuration error will be raised during runtime. It's possible to browse and discover the tag by clicking on the button to the right.

    

     

    
    

Node tags

Note:

Node Tags are available from N3uron version 1.21.4.

Node Tags are used to retrieve information about the node, including diagnostics, performance, links, and module status. After setting the Type to Node Tag, the following options will be shown:

Expressions

When using Expressions, JavaScript code can be created to perform calculations, custom logic, and even advanced data analysis. The result of the expression can be the value, quality, timestamp and initial (indicate when the event is received in response to a new subscription) of the destination tag, expressed as a JSON object with value, quality, ts, and initial properties and assigned to $.output. 

Quality and timestamp properties are optional. If quality is omitted, then 192 - Good Quality is automatically assigned and if ts is omitted, then the current timestamp is assigned.

In order to use other tags as inputs in the expression, an alias per input tag must be created pointing to its tag path. These input tags are then referred to using their alias instead of the tag path. The properties of the aliases are accessed using value, quality, ts and initial. For example, accessing the value, quality, and timestamps of a tag with alias "tag1" is done in the following way: tag1.value, tag1.quality, tag1.ts and tag1.initial. More information about tag aliases and their properties can be found in Alias.  

Expressions also have access to the global variables defined in the module configuration (see more information in Global Variables). A global variable can be accessed directly by using its name (for example, if there is a global variable called counter, it can be incremented by simply using counter++).  

Expressions have access to the following Node.js libraries: os, process, Moment.js, and sprintf. These libraries can be accessed by using process, os, moment, or sprintf, in lowercase. For instance, obtaining the RAM memory can be done using: $.output = os.totalmem()/1024/1024;

Nevertheless, the $ object provides access to the following properties:

Note:

The initial argument is available from N3uron version 1.21.7.

$.input

This object contains the values of all the input tag aliases defined for this tag. Each input contains the value, quality, ts and initial. For example, for a tag with alias name tag1:  $.input.tag1.value provides the value, $.input.tag1.quality provides the quality, $.input.tag1.ts provides the timestamp in UNIX Epoch with milliseconds format and $input.tag1.initial (boolean) indicates whether the value is an event value or comes as a result of the tag being subscribed to other tags.

$.output

This property is used to set the value returned by the expression. It can support a plain value (string, Boolean, or number) that is assigned directly to the value of the derived tag, or an object with value, quality, ts (timestamp displayed in UNIX Epoch with milliseconds), and initial. Quality, timestamp and initial properties are optional. If quality is omitted, then 192 - Good Quality is automatically assigned and if ts is omitted, then the current timestamp is assigned.  

Example: $.output = 23.5; assigns this value to the derived tag with good quality and the current timestamp. $.output = {value:23.5, quality:192, ts:1531410114945, initial:True}; assigns the value, quality, timestamp and initial provided.

$.logger 

Allows for user-defined messages to be sent to the log file. It allows for messages to be organized in the following log levels: $.logger.error, $.logger.warn, $.logger.info, $.logger.debug, and $.logger.trace. It takes two arguments; a format string using % as a placeholder and a set of arguments that replace the placeholders.

For example, $.logger.trace("Value of tag1 is: %.2f", $.input.tag1.value) logs the message Value of tag1 is: 12.34 when the log of the module is in trace level.

$.links

This object contains the status of the links for the remote tags involved in the expression. The status is a Boolean with a true value when the link is online, and false when it is offline. 

For example, if $.links.link01 is `true`, then the link link01 is online.

$.currentValue

This object contains the current value, quality, and timestamp of the derived tag in a JSON object like this: {value:23.5, quality:192, ts:1531410114945}.

Note:

This value can be overwritten by writing the expression tag from N3uron version 1.21.4.

For example, $.currentValue.value returns the current value, $.currentValue.quality returns the current quality, and $.currentValue.ts returns the current timestamp in UNIX Epoch format with milliseconds.

$.variables

Note:

$.variables is available from N3uron version 1.21.4.

This object contains user-defined variables. These variables are maintained between tag executions, but cannot be shared with other tags. It is only dropped when the tag configuration is modified or the module is restarted.

For example, to make a counter:

if ($.variables.counter === undefined){
  $.variables.counter = 0;
}
const count = $.variables.counter++;
$.output = count

buffer

Note:

Buffer is available from N3uron version 1.21.10.

buffer is an array that stores tag events occurring during a specified aggregation period. These events are used for performing custom calculations when Custom Aggregation is selected. Examples of custom calculations include summing values, averaging values, identifying minimum and maximum values, and calculating statistical measures, all within the given period. The buffer can be accessed within Custom Aggregation JavaScript code to perform these calculations. Each tag event in the buffer contains the following properties:

• value: The measurement or reading value of the tag event.

• quality: The quality rating of the tag event, indicating a level of confidence in the tag value.

• timestamp: The exact time when the tag event was recorded.

• virtual: A boolean flag indicating whether the tag event is virtual. Virtual events did not occur within the current interval; they are pulled from the last interval or represent the last sample in the current interval.

Alias

Aliases are used to reference other source tags in the expression of an Expression Tag, as well as triggers for Expression Tags whose trigger is set to “On change”. A tag can have aliases that are not used in the expression. This allows for tags to trigger whenever those aliases change in order to update a value, even if they don’t depend directly on the alias.

Aliases can be configured with the following options:

• Input tag: Provides the tag path to the source tag linked to this alias.

The tag path cannot be used directly in the expression. Instead, the alias must be used. The value, timestamp, quality and initial of the source tag can be accessed using the following syntax (using data1 as the alias):

• Value: $.input.data1.value

• Timestamp: $.input.data1.ts

• Quality: $.input.data1.quality

• Initial: $input.data1.initial

Using Relative and Absolute Tag Paths

Note:

This feature is available from N3uron version 1.21.5.

Tag paths that begin with /... are known as absolute paths. Absolute paths are useful when the path of the source tags might change in reference to the Derived Tag (for example, the Derived Tag can be in different nested levels, /Derived/Nested/Tag_example). 

Paths that don't begin with /... are relative paths (for example, Tag1 or ./Tag2). These paths are relative to the group that contains the Derived Tag. The relative path can begin either with the name of the target tag (For example, Tag1), with a reference to the local tag group followed by the tag name (./Tag1, which has the same meaning as the previous example), or with a reference to the parent group (../Tag2). When targeting a group, multiple of these references can be used (For example, ../../Group1/Group2/Tag3 goes up two levels from the current group, then into Group1, next into Group2, and finally selects Tag3 in that group).

Derived Tags Full Product Details