Tag configuration

In order to configure a tag as a DerivedTag, the source must be set to Derived Tags. Users will first need to create a tag, enable it, and then select the module instance as the source, as shown in the below screenshot:Figure 7: Setting the tag source

Figure 8: Tag configuration

After setting the source to Derived Tags, the following options will appear:

• Mode: This is used to select whether the tag is an Aggregated Tag, whose value is the result of an aggregation of values from a different tag, or an Expression Tag, which can execute code using values from other input tags, and subsequently set its value based on this code.
• 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:Figure 9: Aggregated Tags options

• Aggregation method: Selects which aggregation to use in order to calculate the value for this tag. The valid values are:
  • Average: Time weighted average of the values received in the interval.
  • Minimum: Lowest value received in the interval.
  • Maximum: Highest value received in the interval.
  • First: The first value in the interval.
  • Last: Last value in the interval.
  • Count: Total number of events received in the interval. 
  • Good: Ratio of good quality events to total received events, expressed as a decimal. 1 means all events displayed good quality, 0 means all events displayed bad quality.
• Aggregation period: Specifies the aggregation period. The minimum value is 10000ms. 
• Source Tag: Specifies the tag used as source for the aggregation. It can be a local tag or a tag from a remote node.

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: Figure 10: Expression Tag options

• 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 passes.
• Period: The time period between executions, displayed in milliseconds. Only applies when the Trigger is set to “Periodic”.
• 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.

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, and timestamp of the destination tag, expressed as a JSON object with value, quality, and ts properties and assigned to $.output. 

Quality and timestamp properties are optional. If quality is omitted then 192 - Good Quality is assigned automatically 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 by their alias instead of the tag path. The properties of the aliases are accessed using value, quality, and ts. For example, accessing the value, quality, and timestamps of a tag with alias "tag1" is done in the following way: tag1.value, tag1.quality, and tag1.ts. More information about tag aliases and their properties can be found at Alias.  

Expressions also have access to 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;

Besides the $ object provides access to the following properties:

$.input

This object contains the values of all the input tag aliases defined for this tag. Each input contains the value, quality, and ts. For example, for a tag with alias name tag1:  $.input.tag1.value provides the value, $.input.tag1.quality provides the quality, and $.input.tag1.ts provides the timestamp in UNIX Epoch with milliseconds format.

$.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, and ts (timestamp displayed in UNIX Epoch with milliseconds). 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.  

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}; assigns the value, quality, and timestamp 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 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}.

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.

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 which 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.

Figure 11: Alias options

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, and quality 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