Configuration

Upon selecting Scripting in the configuration menu, the following options will be shown:

Figure 3. Scripting options

As shown in the above example, the base configuration settings display the module’s internal scan rate. This is how often the module checks the different conditions in order to execute the configured scripts.

Libraries

This section allows users to create shared libraries that will be used by all tasks in this Scripting instance. These libraries will be pre-loaded upon start-up so that the user doesn’t have to manually load them upon every use.  

Figure 4. Internal library configuration

Figure 5. External library configuration 

Each library should be named accordingly, as this name will later be used to reference the library from the scripts. Libraries can be one of the following two types:

• Internal: These libraries are usually included with the N3uron installation, and as such, can be loaded straight-away without pre-installation. Available internal libraries include:
  • JSZip: This library is used to read and write .zip files. The included version is 3.1.4. More information can be found at JSZip.  
  • LZ4: This library is used to compress data using the LZ4 algorithm. The included version is 0.5.3. More information can be found at LZ4.  
  • Moment.js: This library is used to parse and format dates & times. This library version includes both moment (version 2.23.0) and moment-timezone (version 0.5.23). More information can be found at Moment and Moment Timezone.
  • MongoDB: This library is used to connect and execute queries to a MongoDB database. The included version is 2.1.10. More information can be found at MongoDB.
  • MQTT.js: This library is used to communicate with a MQTT broker using the MQTT protocol. The included version is 2.2.1. More information can be found at MQTT.js.
  • MySQL: This library is used to connect to a MySQL database and execute queries. The included version is 2.17.1. More information can be found at MySQL.
  • PostgreSQL: This library is used to connect to a PostgreSQL database and execute queries. The included version is 6.4.2. More information can be found at PostgreSQL.
  • Protobuf.js: This library is used to serialize and parse messages using Google’s https://developers.google.com/protocol-buffers format. The included version is 6.8.0. More information can be found at Protobuf.js.
  • SQL Server: This library is used to connect to a SQL Server database and execute queries. The included version is 3.3.0. More information can be found at SQL Server o WebSockets: This library is used to create a WebSocket client and server. The included version is 1.1.0. More information can be found at WebSockets.
  • Xml2Js: This library is used to serialize and parse XML. The included version is 0.4.16. More information can be found at Xml2Js.
• External: These libraries do not come bundled with N3uron and must be installed separately by the user. They can either be installed manually, or through the Node Package Manager. More information about how to install libraries using NPM can be found here. When using external libraries, a path must be provided for the data folder being used for the current Scripting instance. For example, if using the default windows installation path and a Scripting instance named as “Scripting”, the data folder would be:   

    C:\Program Files (x86)\N3uron\data\Scripting  

    This path should either point to the folder containing the library (e.g. node_modules/name), or to the file       containing the module.exports object (for user made libraries).  

The above screenshot shows 5 libraries, 4 of which are internal (mongo, mqtt, mysql and ws) and one external library (request).

Tasks

A task is a collection of different actions, each with its own trigger, which can execute one or several scripts. Each task is independent from the others, and all tasks are scanned in alphabetical order. Finally, despite being independent, they can also share data between tasks using a global object, as detailed in $.global:

Figure 6. Task options

Each Task can be individually enabled or disabled by configuring the “Enabled” option. If the task is disabled, none of the actions in the task will be triggered and the scripts will not be executed. Each task can have an unlimited number of actions.

Actions

An action is an object that can have several scripts, as well as a trigger, which will kick-start the execution of these scripts. There are 5 different types of actions, each with their own configuration settings:

• Start-up: Executes the scripts when the module starts.
• Shutdown: Executes the scripts when the module shuts down.
• Periodic: Executes the scripts after a configurable period.
• Change: Executes the scripts when the specified tag changes.
• Condition: Executes the scripts when the specified tag fulfils a condition.

Start-up and shutdown do not require any specialized configuration, whilst the others require different configuration settings to be applied.

Periodic 

Periodic actions offer the following configuration options:

Figure 7. Periodic options

The period is used to specify how often the action is triggered.

The period type can be either of the following options:

• Fixed delay: The action triggers after period ms have passed since the scripts have completely finished executing. For example, if the scripts take 250 ms to complete execution, the period is set to 10000 ms, and the current time is 00:00:00.000, the first execution will be at 00:00:10.000, the second execution at 00:00:20:250, and the third at 00:00:30.500 and so on.
• Fixed rate: The action triggers after period ms have passed since the last trigger, whether there are any active scripts still running or not. For example, if the scripts take 250 ms to complete execution, the period is set to 10000 ms, and the current time is 00:00:00.000, the first execution will be at 00:00:10.000, the second execution at 00:00:20:000, and the third at 00:00:30.000 and so on.

Change 

Tag change actions offer the following configuration options:

Figure 8. Tag change options

• Tag: selects which tag to use as the trigger for this action. Each action can only have one assigned tag (tag groups are not valid).
• Property: selects which of the tag’s properties should be monitored for changes. It can be any property, or alternatively, the value, quality or timestamp.
• Initial change: specifies whether the initial tag subscription should trigger the scripts.
• Maximum event buffer size: When tag events occur faster than the scan rate, for example, if several events are received from a S&F mechanism, these events are buffered up to the maximum buffer size, and the action will be triggered each scan cycle, until the buffer is empty again. If the buffer becomes full, old events are replaced by newer events. Setting the buffer to 0 disables it, meaning that the action will only be triggered when a tag changes after each scan cycle.

Condition 

Condition actions offer the following configuration options:

Figure 9. Condition options

• Tag: Selects which tag will be used to check the condition.
• Property: Selects which tag property will be used to check the condition. It can be the value, the quality or the timestamp.
• Initial change: Selects whether the value from the initial subscription should be checked or not.
• Maximum event buffer size: When tag events occur faster than the scan rate, for example, if several events are received from a S&F mechanism, these events are buffered up to the maximum buffer size, and the action will be triggered upon each scan cycle until the buffer is empty again. If the buffer becomes full, old events are replaced by newer events. Setting the buffer to 0 disables it, meaning that the action will only be triggered when a tag changes after each scan cycle.
• Condition: The evaluation settings used to check whether the action is true or false. It can be any of the following:
  • Less than: The tag property must be less than a fixed value.
  • Less than or equal: The tag property must be less or equal to a fixed value.
  • Equal to: The tag property must be equal to a fixed value.
  • Not equal to: The tag property must be different to a fixed value.
  • Greater than: The tag property must be greater than a fixed value.
  • Greater than or equal: The tag property must be greater or equal to a fixed value.

Value: This value is compared to the selected tag property to check if the condition is true or false

• Condition type determines how the action will be triggered. Valid values are: 
  • If true: The action will trigger when the condition is true. 
  • If false: The action will trigger when the condition becomes false.
  • While true: The action will trigger once, when the condition becomes true, and then trigger again after the specified period passes while the condition remains true.
  • While false: The action will trigger once when the condition becomes false, and then trigger again after the specified period passes while the condition remains false.
• Trigger on update is only available when the condition is either “If true” or “If false”. When enabled, the action will trigger every time there is a new tag update matching this condition. Otherwise, the action will only trigger the first time the condition matches, and won’t trigger again until the condition is cleared and subsequently matches again
• Period: the amount of time between successive triggers when using either “while true” or “while false” conditions.  
• Period type: Selects the behaviour of the timer.
  • Fixed delay: The timer starts after the last script triggered by this action has finished. For example, if the scripts take 250ms to complete execution, the period is set to 10000ms, and the current time is 00:00:00.000, the first execution will be at 00:00:10.000, the second execution at 00:00:20:250, and the third at 00:00:30.500 and so on.
  • Fixed rate: The timer starts as soon as possible after the last trigger, whether there are active scripts still running or not. This ensures that the scripts execute at a fixed rate every time. For example, if the scripts take 250ms to complete execution, the period is set to 10000ms and the current time is 00:00:00.000, the first execution will be at 00:00:10.000, the second execution at 00:00:20:000, and the third at 00:00:30.000 and so on.

Scripts 

A script is JavaScript code that will execute every time the actions triggers. Each action can have one or more scripts, and will be executed in alphabetical order. 

Each script has access to several objects and functions that are used to interface with N3uron and to share data between different scripts in the same task or between different tasks. All of these objects are detailed in the API section of this manual.

 Scripts also have access to all Node.js native libraries, and some of these libraries are loaded upon start-up, so they don’t need to be explicitly requested. Node.js libraries available at start-up are fs, net, http, EventEmitter, os, path, crypto and zlib.

Each script has the following options: 

Figure 10. Script options

• Enabled: Scripts are only executed if enabled.
• Script: The script itself is defined by clicking on the symbol in the script field, which will subsequently open a popup with a text field where the script can be entered. This multi-line editor area includes function folding and keyword highlighting.
• If running: Defines the action to be taken if the action is triggered again while the script is still running. There are three different options:
  • Continue current execution: The new trigger is ignored, and the script will continue the current execution.
  • Abort previous execution: The new trigger overwrites the old execution, so the old execution is terminated and the script starts again.
  • Start a new instance: The script begins a new execution while the old one is still active. This option is usually not recommended, since having various scripts active can result in race conditions if shared resources are used. If this option is used, the maximum limit of concurrent executions is used to limit the number of executions running at the same time.          
• Retry options: Controls the behaviour of a script when an error is encountered.
  • Retry count: Selects how many times the script will retry, before aborting
  • Retry delay: The delay of the scripts between retries.
• Auto-demotion: Used to stop execution of the script if it runs out of retries in the same execution. If this happens, all instances of that script will be terminated, and the script won’t trigger again until after the demotion time passes.

Figure 11. Multi-line editor for writing the script’s JavaScript code

Source

Scripting can also act as a data provider for tags. To do this, all new tags will need to be configured with Scripting as their source, as seen in the following screenshot:

Figure 12. Scripting source tag configuration

Scripting source tags accept a single optional parameter in the form of an alias that will be used to reference the tag when providing data for that tag. If provided, the tag can be updated using said alias, otherwise, the full path will need to be used. The full path can be used regardless of whether a tag has an alias or not. In order to update a tag, $.api.tag.update or $.api.tag.updateAlias must be called.

Source tags can also accept write commands. By default, they are set to have no write handler and therefore, any write command will return an error. Handlers needs to be manually registered by calling $.api.tag.onWrite or $.api.tag.onWriteAlias, depending on whether the tag has an associated alias or not. After a handler has been registered, this handler will be called whenever a write command is issued to a source tag. If one of the handlers is not present, any write commands targeting that tag will return an error (e.g. if a tag has an alias but the WriteAlias is not registered, writes to that tag will fail).

Each write command can only have one handler at any time. If a new handler is registered, this will overwrite any previous handlers. Handlers can also be removed by calling the respective function again using a null argument.