Difference between revisions of "Edge Gateway Adapter Common Configuration"

From Datonis
Jump to: navigation, search
 
(11 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
  inter[[Datonis Edge Gateway|Edge Gateway Home]] > '''Adapter Common Configuration'''
+
  [[Datonis Edge Gateway|Edge Gateway Home]] > '''Adapter Common Configuration'''
  
 
== Overview ==
 
== Overview ==
Line 9: Line 9:
 
*# Modbus Adapter
 
*# Modbus Adapter
 
*# OPC UA Adapter
 
*# OPC UA Adapter
 +
*# OPC DA Adapter (utgard)
 +
*# Profinet Adapter
 +
*# EtherNet/IP Adapter
 
*# MTConnect Adapter
 
*# MTConnect Adapter
 
*# Simulator Adapter (CSV)
 
*# Simulator Adapter (CSV)
 
* '''Push Data Adapter (Listening Adapter)''' These adapters listen for the changes happened at target device. They specify scan-interval while subscribing change notification but target device may not honor it. Supported Push Data Adapters are
 
* '''Push Data Adapter (Listening Adapter)''' These adapters listen for the changes happened at target device. They specify scan-interval while subscribing change notification but target device may not honor it. Supported Push Data Adapters are
−
*# OPC DA Adapter
+
*# OPC DA Adapter(ngp)(not used now)
 
*# HttpListener Adapter
 
*# HttpListener Adapter
 +
*# MQTTListener Adapter
 +
*# Script Adapter (Push)
 +
*# CSV Adapter (File Adapter)
 +
*# XML Adapter (File Adapter)
  
 
There are two ways to configure the adapter: Basic Configuration and Advanced Configuration. Basic Configuration can get start the adapter connectivity very quickly while Advanced Configuration allows finer control.
 
There are two ways to configure the adapter: Basic Configuration and Advanced Configuration. Basic Configuration can get start the adapter connectivity very quickly while Advanced Configuration allows finer control.
Line 45: Line 52:
 
| colspan="1" |String
 
| colspan="1" |String
 
|The type of the adapter, its generally a constant string and no need to modify
 
|The type of the adapter, its generally a constant string and no need to modify
 +
|-
 +
|auto_concurrency
 +
|Boolean
 +
|Concurrency mode for Pull Adapter scan tasks. If True then auto growing cached threadpool is used. If False then fixed threadpool with 'Threadpool Size' parameter is used.
 +
|-
 +
|threadpool_size
 +
|Number
 +
|Scan task fixed threadpool size. It is used in Pull Adapter when 'Auto Concurrency' parameter is set to False. It is used to determine threadpool size of Script Adapter Context var 'executor_val'.
 +
|-
 +
|schedule_delay_mills
 +
|Number
 +
|Initial delay while scheduling Pull Adapter scan tasks between subsequent thing configurations. This helps interleaving scan tasks across thing configurations and successfully establishing connections to slow data sources like Modbus slave.
 +
|-
 +
|test_timeout_secs
 +
|Number
 +
|Timeout in seconds used by Push Adapter 'Test Configuration' or 'Repeat Test' while waiting on data from source before declaring Timeout error.
 +
|-
 +
|detect_nashorn_leak
 +
|Boolean
 +
|Detects potential memory leaks because of the script.
 +
|-
 +
|global_util_expression_js
 +
|String
 +
|JavaScript expression that can be used to write reusable global scoped functions and variables.
 +
|-
 +
|tag_suffixes
 +
|tag_suffix object
 +
|Add global custom tag suffix with specified operation. Object contains 'suffix_id' and it's 'expression_js'
 
|-
 
|-
 
| colspan="1" |thing_configs
 
| colspan="1" |thing_configs
Line 68: Line 103:
 
| colspan="1" |Boolean
 
| colspan="1" |Boolean
 
| colspan="1" |Signifies whether the thing can accept instructions, Home → Things → Bi-directional
 
| colspan="1" |Signifies whether the thing can accept instructions, Home → Things → Bi-directional
 +
|-
 +
|config_mode
 +
|String
 +
|Select whether you want to use only read functionality or only write functionality or both.
 
|-
 
|-
 
| colspan="1" |send_interval_ms
 
| colspan="1" |send_interval_ms
Line 80: Line 119:
 
| colspan="1" |Number
 
| colspan="1" |Number
 
| colspan="1" |The interval (in milli seconds) at which thing heart beat will be communicated to Datonis platform.
 
| colspan="1" |The interval (in milli seconds) at which thing heart beat will be communicated to Datonis platform.
 +
|-
 +
|alert_interval_ms
 +
|Number
 +
|Interval after which alerts are generated on edge.
 +
|-
 +
|alert_message_count
 +
|Number
 +
|Count of the alerts that are generated.
 +
|-
 +
|publish_mode
 +
|String
 +
|
 +
* Event : Transmits the DataMessage to Datonis.
 +
* Scan Internal: scanned msg is available internally(to other adapters)
 +
* Send Internal: msg to be sent is available internally(to other adapters)
 +
* Scan external: scanned msg is available internally and also published to datonis under the topic '/scan'
 +
* Send external: msg to be sent is available internally and also published to datonis under the topic '/scan'
 +
* Event, scan internal: Transmits the DataMessage to Datonis and msg to sent is available internally.
 +
* Event, send internal: Transmits the DataMessage to Datonis and scan msg is available internally.
 +
* Event, scan external: Transmits the DataMessage to Datonis and scan message is available internally as well as published to Datonis under the topic '/scan'.
 +
* Event, send external: Transmits the DataMessage to AliotGateway and send message is available internally as well as published to Datonis under the topic '/scan'.
 
|-
 
|-
 
| colspan="1" |source_tags
 
| colspan="1" |source_tags
 
| colspan="1" |source_tag Array
 
| colspan="1" |source_tag Array
 
| colspan="1" |An array of source_tag object. Each source_tag object defines the source specific connection object and source specific tag object.
 
| colspan="1" |An array of source_tag object. Each source_tag object defines the source specific connection object and source specific tag object.
 +
|-
 +
|ml_tags
 +
|ml_tag Array
 +
|An array of ml_tag object.
 +
|-
 +
|slot_tags
 +
|slot_tag Array
 +
|An array of slot_tag object. (start tag and end tag) Timestamps at which start and end conditions become true get associated.
 +
(They must be placed below the read tags in the Basic Config)
 
|-
 
|-
 
| colspan="1" |derived_tags
 
| colspan="1" |derived_tags
 
| colspan="1" |derived_tag Array
 
| colspan="1" |derived_tag Array
 
| colspan="1" |An array of derived_tag object. Each derived_tag object defined the expression based tag that is derived from either source_tag value or earlier defined derived_tag value.
 
| colspan="1" |An array of derived_tag object. Each derived_tag object defined the expression based tag that is derived from either source_tag value or earlier defined derived_tag value.
 +
(They must be placed below the read tags in the Basic Config)
 +
|-
 +
|eval_order_tag_ids
 +
|String Array
 +
|An array of all the tags with the sequence in which you want the Edge to evaluate all the tags.
 
|-
 
|-
 
| colspan="1" |monitor_tag_ids
 
| colspan="1" |monitor_tag_ids
Line 96: Line 170:
  
 
any tag value change.
 
any tag value change.
 +
 +
Custom condition expression can also be set via monitor_expression_js.
 
|-
 
|-
 
| colspan="1" |scan_tag_ids
 
| colspan="1" |scan_tag_ids
Line 104: Line 180:
  
 
If specific tags are defined then those tags will be sent during scan interval rest other will be ignored. (Version 4.0.92 onwards supported)
 
If specific tags are defined then those tags will be sent during scan interval rest other will be ignored. (Version 4.0.92 onwards supported)
 +
|-
 +
|datetime_tag_id
 +
|String
 +
|Optional, an already defined tag_id which value may be used as event date time instead of system current time.
 +
|-
 +
|monitor_expression_js
 +
|String
 +
|JavaScript expression that returns Boolean value to determine send data condition for monitor tags.
 +
|-
 +
|local_util_expression_js
 +
|String
 +
|JavaScript expression that can be used to write reusable thing scoped functions and variables.
 
|-
 
|-
 
| colspan="1" |metric_mappings
 
| colspan="1" |metric_mappings
Line 109: Line 197:
 
| colspan="1" |An array of metric_mapping object. metric_mapping object defines the mapping between thing metric and source or derived tag. The mapping is kept as a separate object in order 
 
| colspan="1" |An array of metric_mapping object. metric_mapping object defines the mapping between thing metric and source or derived tag. The mapping is kept as a separate object in order 
 
to evolve source_tag and derived_tag definitions  independent of thing metric relation.
 
to evolve source_tag and derived_tag definitions  independent of thing metric relation.
 +
|-
 +
|include_prev_tags_to_scan_message
 +
|Boolean
 +
|True will include all the previous tags in the scan message JSON. Can be used to access prev tag values in other adapters using send internal.
 
|}
 
|}
  
Line 139: Line 231:
 
|In case of an expression, you can specify any simple mathematical formula. There are three context arrays available for the expression: latest, prev_scanned and prev_sent. Each context returns
 
|In case of an expression, you can specify any simple mathematical formula. There are three context arrays available for the expression: latest, prev_scanned and prev_sent. Each context returns
  
−
tag values that are computed just now, last scanned (via scan_interval_ms) or last sent (via send_interval_ms). E.g.
+
tag values that are computed just now, last scanned (via scan_interval_ms) or last sent (via send_interval_ms).
 +
|}
 +
 
 +
==== slot_tag object ====
 +
{| class="wikitable"
 +
|slot_id
 +
|String
 +
|The unique tag_id for a particular slot
 +
|-
 +
|start_tag_id
 +
|String
 +
|start slot id
 +
|-
 +
|end_tag_id
 +
|String
 +
|end slot id
 +
|-
 +
|start_expression_js
 +
|String
 +
|Condition which triggers start of the slot
 +
|-
 +
|end_expression_js
 +
|String
 +
|Condition which triggers end of the slot
 
|}
 
|}
  
Line 158: Line 273:
  
 
=== Aggregated Tag Values ===
 
=== Aggregated Tag Values ===
−
From version '''4.5.279''' onward, if '''scan_interval_ms''' is different than '''send_interval_ms''' then along with raw read tag values, below '''aggregated tag values''' are available for usage in '''metric_mappings''', '''derived_tags''', '''monitor_tag_ids''' and '''scan_tag_ids'''.
+
From version '''4.5.279''' onward, if '''scan_interval_ms''' is different than '''send_interval_ms''' then along with raw read tag values, below '''aggregated tag values''' are available for usage in '''metric_mappings''', '''derived_tags''', '''monitor_tag_ids''' and '''datetime_tag_id'''.
  
 
Suppose a '''read_tag_id''' named '''tag_temperature''' is defined under read_tags then following aggregated tag values are available
 
Suppose a '''read_tag_id''' named '''tag_temperature''' is defined under read_tags then following aggregated tag values are available

Latest revision as of 07:46, 4 February 2020

Edge Gateway Home > Adapter Common Configuration

Overview

An adapter in Datonis Edge Gateway refers to an independent module/plugin that allows data to be fetched from an environment or protocol (e.g. Modbus, OPC UA) and pushes data to Datonis platform. The various adapters are available in Services sections of Gateway interface's left pane. 

Adapter Types

There are two types of adapters:

  • Pull Data Adapter (Scanning Adapter) These adapters poll the target device at regular frequency specified via scan-interval. Any changes in the target device tag status will be known only during scan interval. Supported Pull Data Adapters are
    1. Modbus Adapter
    2. OPC UA Adapter
    3. OPC DA Adapter (utgard)
    4. Profinet Adapter
    5. EtherNet/IP Adapter
    6. MTConnect Adapter
    7. Simulator Adapter (CSV)
  • Push Data Adapter (Listening Adapter) These adapters listen for the changes happened at target device. They specify scan-interval while subscribing change notification but target device may not honor it. Supported Push Data Adapters are
    1. OPC DA Adapter(ngp)(not used now)
    2. HttpListener Adapter
    3. MQTTListener Adapter
    4. Script Adapter (Push)
    5. CSV Adapter (File Adapter)
    6. XML Adapter (File Adapter)

There are two ways to configure the adapter: Basic Configuration and Advanced Configuration. Basic Configuration can get start the adapter connectivity very quickly while Advanced Configuration allows finer control.

Basic Configuration

The Basic Configuration tab allows modifying the adapter configuration using CSV file. This is a simple way to import device tags to adapter configuration.

  • enabled - this property value is responsible for enabling or disabling an adapter. A true value enable the adapter and will start pushing data.
  • scan-interval-ms - In case of Pull Data Adapter (Modbus, OPC UA, MTConnect, Simulator), this frequency will be used to scan the target device. In case of Push Data Adapter, this frequency will be passed to target device.
  • send-interval-ms - This property will be displayed only in case of Pull Data Adapter. With this frequency data will be sent to Datonis always.
  • adapter specific connection properties - Rest of the properties are adapter specific and will be shown based on adapter selected.

Note that any change in above scan-interval-ms, send-interval-ms and adapter specific connection properties will be applied to all things.

Basic-config-edge.png

Advanced Configuration

The Advanced Configuration tab allows modifying the underlying json structure of adapter configuration. This is a powerful way to control fine aspects of configuration.

  • enabled - this property value is responsible for enabling or disabling an adapter. A true value enable the adapter and will start pushing data.
  • config-json - this property value holds actual configuration of any specific adapter. The value of this property has to be a valid json data. There is an in-built json editor embedded to modify the config-json. It has three modes - Tree, Code and View. Tree mode allows editing and searching json properties easiliy. Code mode is for advanced configuration where raw config-json can be modified. View mode is read-only where tree view of config-json can be analyzed.

Advanced-config-tree-edge.png

Generating sample config-json

To start creating a new configuration, its good idea to start with pre-populated configuration generated for all things. This is what precisely Generate config-json button does, it communicates with Datonis server, fetches all the things that belong to Cloud access key and secret key pair and creates mock configuration correctly mapped to all thing metrics.

Modifying config-json

The config-json is a special kind of property that holds entire configuration of the adapter. A valid value must be a proper JSON data structure. Elements of the JSON are described as below:

Root object

adapter_type String The type of the adapter, its generally a constant string and no need to modify
auto_concurrency Boolean Concurrency mode for Pull Adapter scan tasks. If True then auto growing cached threadpool is used. If False then fixed threadpool with 'Threadpool Size' parameter is used.
threadpool_size Number Scan task fixed threadpool size. It is used in Pull Adapter when 'Auto Concurrency' parameter is set to False. It is used to determine threadpool size of Script Adapter Context var 'executor_val'.
schedule_delay_mills Number Initial delay while scheduling Pull Adapter scan tasks between subsequent thing configurations. This helps interleaving scan tasks across thing configurations and successfully establishing connections to slow data sources like Modbus slave.
test_timeout_secs Number Timeout in seconds used by Push Adapter 'Test Configuration' or 'Repeat Test' while waiting on data from source before declaring Timeout error.
detect_nashorn_leak Boolean Detects potential memory leaks because of the script.
global_util_expression_js String JavaScript expression that can be used to write reusable global scoped functions and variables.
tag_suffixes tag_suffix object Add global custom tag suffix with specified operation. Object contains 'suffix_id' and it's 'expression_js'
thing_configs thing_config Array An array of thing_config object. Each thing_config object contains mapping required to transform source data into metric data

thing_config object

thing_key String The thing key, Datonis UI location: Home → Things → Thing Key
name String Name of the thing, Datonis UI location: Home → Things → Name
description String Optional, Description of the thing, Datonis UI location: Home → Things → {thing name} → Description
bi_directional Boolean Signifies whether the thing can accept instructions, Home → Things → Bi-directional
config_mode String Select whether you want to use only read functionality or only write functionality or both.
send_interval_ms Number In pull data adapter case, this is a minimum interval (in milli seconds) at which thing metric data will be sent to Datonis
scan_interval_ms Number In pull data adapter case, at this interval (in milli seconds) the data will be scanned from underlying source
heartbeat_interval_ms Number The interval (in milli seconds) at which thing heart beat will be communicated to Datonis platform.
alert_interval_ms Number Interval after which alerts are generated on edge.
alert_message_count Number Count of the alerts that are generated.
publish_mode String
  • Event : Transmits the DataMessage to Datonis.
  • Scan Internal: scanned msg is available internally(to other adapters)
  • Send Internal: msg to be sent is available internally(to other adapters)
  • Scan external: scanned msg is available internally and also published to datonis under the topic '/scan'
  • Send external: msg to be sent is available internally and also published to datonis under the topic '/scan'
  • Event, scan internal: Transmits the DataMessage to Datonis and msg to sent is available internally.
  • Event, send internal: Transmits the DataMessage to Datonis and scan msg is available internally.
  • Event, scan external: Transmits the DataMessage to Datonis and scan message is available internally as well as published to Datonis under the topic '/scan'.
  • Event, send external: Transmits the DataMessage to AliotGateway and send message is available internally as well as published to Datonis under the topic '/scan'.
source_tags source_tag Array An array of source_tag object. Each source_tag object defines the source specific connection object and source specific tag object.
ml_tags ml_tag Array An array of ml_tag object.
slot_tags slot_tag Array An array of slot_tag object. (start tag and end tag) Timestamps at which start and end conditions become true get associated.

(They must be placed below the read tags in the Basic Config)

derived_tags derived_tag Array An array of derived_tag object. Each derived_tag object defined the expression based tag that is derived from either source_tag value or earlier defined derived_tag value.

(They must be placed below the read tags in the Basic Config)

eval_order_tag_ids String Array An array of all the tags with the sequence in which you want the Edge to evaluate all the tags.
monitor_tag_ids String Array An array of tag_id defined in source_tags or derived_tags section. This list will be used to monitor the tag values at each scan defined by scan_interval_ms. 

If any of the tag values change during a scan then the thing metrics will be sent at that scan interval other wise thing metrics will be sent at send_interval_ms irrespective of

any tag value change.

Custom condition expression can also be set via monitor_expression_js.

scan_tag_ids String Array An array of tag_id defined in source_tags or derived_tags section. This list will be used to send the tag values at each scan defined by scan_interval_ms triggered by change in 

monitor_tag_ids. An empty array or null value means all tag values will be sent during the scan interval. It does not affect send interval tags, at send interval all tags will be sent.

If specific tags are defined then those tags will be sent during scan interval rest other will be ignored. (Version 4.0.92 onwards supported)

datetime_tag_id String Optional, an already defined tag_id which value may be used as event date time instead of system current time.
monitor_expression_js String JavaScript expression that returns Boolean value to determine send data condition for monitor tags.
local_util_expression_js String JavaScript expression that can be used to write reusable thing scoped functions and variables.
metric_mappings metric_mapping Array An array of metric_mapping object. metric_mapping object defines the mapping between thing metric and source or derived tag. The mapping is kept as a separate object in order 

to evolve source_tag and derived_tag definitions  independent of thing metric relation.

include_prev_tags_to_scan_message Boolean True will include all the previous tags in the scan message JSON. Can be used to access prev tag values in other adapters using send internal.

source_tag object

protocol_connection Object This is an adapter specific JSON object. This will have adapter specific connection properties e.g. Modbus adapter may have properties like ip_address, port while OpcUA adapter may have

server_url, cert_alias properties.

read_tags Object Array An array of read_tag objects. A read_tag object is specific to adapter only the tag_id property is common, it is used for metric mapping and must be unique within a thing_config. E.g. Modbus 

adapter properties are device_id, read_count while OPC UA adapter have properties like node_id. These read_tag objects will be polled during each scan and send interval.

write_tags Object Array An array of write_tag objects. A write_tag object is specific to adapter only the tag_id property is common, it is used for writing values to the target device. These tags must be present in the Datonis instruction

json data along with the values to be written. During the instruction execution, writable tag value will be searched in the write_tags section and corresponding adapter address will be written.

derived_tag object

tag_id String The unique tag_id within a thing_config object. This is used further in metric_mapping object to map to thing metric
expression String In case of an expression, you can specify any simple mathematical formula. There are three context arrays available for the expression: latest, prev_scanned and prev_sent. Each context returns

tag values that are computed just now, last scanned (via scan_interval_ms) or last sent (via send_interval_ms).

slot_tag object

slot_id String The unique tag_id for a particular slot
start_tag_id String start slot id
end_tag_id String end slot id
start_expression_js String Condition which triggers start of the slot
end_expression_js String Condition which triggers end of the slot

metric_mapping object

metric_id String This is metric name of the thing mentioned at thing_config level. Datonis UI location: Home → Thing Templates → {template name} → Metric (Name column)
tag_id String The unique tag_id which is defined either in source_tags or derived_tags section
type Enum Allowed values are number, boolean and string. This type has to match with Datonis metric type. Datonis UI location: Home → Thing Templates → {template name} → Metric (Data Type column)

Aggregated Tag Values

From version 4.5.279 onward, if scan_interval_ms is different than send_interval_ms then along with raw read tag values, below aggregated tag values are available for usage in metric_mappings, derived_tags, monitor_tag_ids and datetime_tag_id.

Suppose a read_tag_id named tag_temperature is defined under read_tags then following aggregated tag values are available

  • tag_temperature : raw/original scanned tag_temperature value
  • tag_temperature$max : maximum scanned tag_temperature value between successful sent values
  • tag_temperature$min : minimum scanned tag_temperature value between successful sent values
  • tag_temperature$avg : average of scanned tag_temperature values between successful sent values
  • tag_temperature$count : count of scanned tag_temperature values between successful sent values
  • tag_temperature$sum : sum of scanned tag_temperature value between successful sent values
  • tag_temperature$prev_scanned : last scanned tag_temperature value
  • tag_temperature$prev_sent : last sent tag_temperature value

For example, if tag_temperature is being scanned with 1000 ms (1 second) and sent every 20000 ms (20 second) then tag_temperature$max value is maximum value among all 20 scanned values available at each send interval. Like wise tag_temperature$avg is average of all 20 scanned values that can be sent every 20 seconds if it is mapped in metric_mappings section.

If a monitor_tag_id is defined e.g. tag_pressure which forced tag_temperature to be sent after 7000 ms (during 7th scan interval) then tag_temperature$max is maximum value among 7 scanned values, like wise tag_temperature$avg is average of 7 scanned values that will be sent.

Retrieved from "https://docs.datonis.io/mediawiki/index.php?title=Edge_Gateway_Adapter_Common_Configuration&oldid=1054"