Nerve Data Services Gateway

The Gateway is the central application of the Data Services. Its purpose is receiving data from a source via a certain protocol on an input interface and forwarding it to a destination using a different protocol on an output interface. This behavior is reflected in the user configuration as well. In general, the configuration file consists of inputs, outputs and connections between them:

• Inputs are collection interfaces where data is received.
• Outputs are providing interfaces where data can be received from.
• Connections are logical links between inputs and outputs.

Each input and output provides connectors where a connection can be attached to. A connector is a subset of the data available at an input. This subset is forwarded to the connector of an output where it is distributed further to the data receiver. On an abstract level, this concept is illustrated in the figure below.

Inputs and outputs hold general configuration data for the protocol they implement. This can be a URL to a server, a port number or something related to timing. A connector of an input or output holds more specific information on how to get or where to send data, for example the node IDs of an OPC UA Server an OPC UA Client input connects to, or the name of a topic for an MQTT Publisher. Each input and output can provide multiple connectors at a time. Data from an input connector can also be connected to multiple output connectors at the same time to distribute data to multiple data consumers. The figure below shows a more specific example of that concept.

Data Gateway UI

The Data Gateway UI is the landing page of the Data Services and will be displayed by default after selecting Data > CONFIGURATION in the navigation on the left in either Local UI or Management System. The editor in the middle is used to apply Gateway configurations in the JSON format.

Applying a configuration to the Gateway

The configuration of the Gateway is applied in the editor in the Gateway section of the Data Services UI. The current configuration of the Gateway is loaded into the JSON editor if there is a configuration present in the Gateway. However, the editor will be empty on initial startup. A new configuration can be entered into the editor directly or imported from an existing JSON file.

• Upload existing JSON files using the Upload button.
• Apply the configuration in the editor by selecting Apply. When the configuration is successful, the status in the upper-right corner will display running.
• Check the Logs tab for any warnings or errors.

The basic structure of the configuration consist of a list of inputs such as an OPC UA server or an MQTT subscriber, outputs such as a Timescale database or an MQTT publisher, and connections between these inputs and outputs. Refer to Gateway configuration file syntax below for the exact syntax.

The examples in the Examples section show step by step applications in common use cases.

Gateway configuration file syntax

The following list gives additional clarification about how to set parameters with the JSON editor. The Gateway configuration JSON file includes sections, which are defined as main sections (inputs, outputs, connections). The main sections may contain one set of subsections or an array of items, which in this case are defined as an array of subsection sets.

Subsections can also include additional subsections. A section is defined as an array if the section contains two or more subsections. Subsection keys are defined as parameters. Every parameter has its field for a value. The main sections can contain the same and different parameters as other sections.

The syntax of the various inputs and outputs of the Gateway available in its configuration file is illustrated below for the available protocols.

Inputs

In the tables below, fields in bold are mandatory and fields in italics are optional when writing a configuration for the corresponding protocol.

OPC UA Client

MQTT Subscriber

OPC UA PubSub Subscriber

S7 Client

Modbus Client

Outputs

In the tables below, fields in bold are mandatory and fields in italics are optional when writing a configuration for the corresponding protocol.

TimescaleDB

InfluxDB

MQTT Publisher

OPC UA PubSub Publisher

OPC UA Server

ZeroMQ Publisher

Connections

Gateway configuration file keywords

Parts of the Gateway configuration are eased by the use of keywords. Keywords can be used on both Gateway instances on the node and in the Management System. However, the keyowrds that can be used differ. All keywords must be put in angled brackets, for example <SN>. To be able to use keywords. the node must be registered in the Management System.

Refer to the list below for keywords that can be used with usage examples right after.

Supported on the node

Supported in the Management System

Examples of keyword usage

SN:<nodename>

{
    "name": "cloud_timescale",
    "type": "DB_TIMESCALE",
    "url": "localhost",
    "port": 5432,
    "connectors": [
        {
            "name": "EXAMPLE-NODE",
            "dbName": "<SN:EXAMPLE-NODE>"
        }
    ]
}

SN, SID, MGMT-SYS

{
    "name": "ms_mqtt_broker",
    "type": "MQTT_SUBSCRIBER",
    "serverUrl": "wss://<MGMT-SYS>:443/dp/mqtt/wss",
    "username": "<SN>",
    "password": "<SID>",
    "keepAliveInterval_s": 20,
    "qos": 1,
    "cleanSession": true,
    "sslOptions": {
        "serverAuthRequired": false
    },
    "connectors": [
        {
            "name": "demo_sensor_connector_0",
            "topic": "<SN>/demo_sensor_topic_0",
            "variables": [
                {
                    "name": "temperature",
                    "type": "int64"
                }
            ]
        }
    ]
}

LOCAL

{
    "type": "DB_TIMESCALE",
    "name": "timescaledb_0",
    "url": "<LOCAL>"
}

SN:<nodename>, MS-MQTT-BROKER

{
    "name": "ms_mqtt_broker",
    "type": "MQTT_SUBSCRIBER",
    "serverUrl": "<MS-MQTT-BROKER>",
    "keepAliveInterval_s": 20,
    "qos": 1,
    "cleanSession": true,
    "connectors": [
        {
            "name": "demo_sensor_connector_1",
            "topic": "<SN:EXAMPLE-NODE>/demo_sensor_topic_1",
            "variables": [
                {
                    "name": "humidity",
                    "type": "uint64"
                }
            ]
        }
    ]
}