Configuration API Service — UA Gateway

 

UA Gateway Status

The UA Gateway status and other properties can be accessed by performing the following GET request:

 

Endpoint (GET)

{{host}}:{{port}}/config/v1/project/_ua_gateway

 

Configuring Internal Communications

The Kepware server communicates internally with the UA Gateway service using two ports: for inbound and outbound communication. These values should only need to be changed if they conflict with ports already in use on the machine where the server is running. To change the ports, update the value for UAG_PLUGIN_IPC_PORT or UAG_SERVER_IPC_PORT by performing the following PUT request:

 

Endpoint (PUT)

{{host}}:{{port}}/config/v1/project/_ua_gateway

 

Message body

{    "PROJECT_ID": <project-id-number>,    "ua_gateway.UAG_PLUGIN_IPC_PORT": <desired-port-value>,    "ua_gateway.UAG_SERVER_IPC_PORT": <desired-port-value> }

 

Server Interface

The UA Gateway server interface is used to configure how UA clients connect to the UA Gateway. The UA Gateway Server Interface contains configuration settings common to all UA server endpoints, such as authentication options and encryption settings.

 

Server Interface Settings

The server interface settings set the security used when a UA client connects to the UA Gateway and Local Discovery Server. These settings can be queried through the REST API at the following endpoint:

 

Endpoint (GET):

{{host}}:{{port}}/config/v1/project/_ua_gateway/ua_server_interfaces/Server Interface

 

This should return a result similar to the following:

 

Response:

{    "PROJECT_ID": <project-id-number>,    "common.ALLTYPES_NAME": "Server Interface",    "common.ALLTYPES_DESCRIPTION": "The server interface of the OPC UA Gateway. Configuring this interface and adding server endpoints will allow other OPC UA clients to connect to the OPC UA Gateway.",    "ua_gateway.UA_SERVER_INTERFACE_CONCURRENT_SESSIONS": 0,    "ua_gateway.UA_SERVER_INTERFACE_USER_IDENTITY_POLICY_ANONYMOUS": false,    "ua_gateway.UA_SERVER_INTERFACE_USER_IDENTITY_POLICY_USERNAME_PASSWORD": true,    "ua_gateway.UA_SERVER_INTERFACE_USER_IDENTITY_POLICY_X509": true,    "ua_gateway.UA_SERVER_INTERFACE_SECURITY_POLICIES_NONE": false,    "ua_gateway.UA_SERVER_INTERFACE_SECURITY_POLICIES_BASIC256SHA256": 2,    "ua_gateway.UA_SERVER_INTERFACE_SECURITY_POLICIES_AES128_SHA256_RSAOAEP": 0,    "ua_gateway.UA_SERVER_INTERFACE_SECURITY_POLICIES_AES256_SHA256_RSAPSS": 0,    "ua_gateway.LDS_REGISTRATION_ENABLED": true,    "ua_gateway.LDS_MAX_REGISTRATION_INTERVAL": 30000,    "ua_gateway.UA_SERVER_INTERFACE_MAX_SUBSCRIPTION_LIFETIME": 3600000,    "ua_gateway.UA_SERVER_INTERFACE_MIN_SUBSCRIPTION_LIFETIME": 10000    "ua_gateway.UA_SERVER_INTERFACE_MAX_SESSION_TIMEOUT": 3600000,    "ua_gateway.UA_SERVER_INTERFACE_MIN_SESSION_TIMEOUT": 10000,    "ua_gateway.UA_SERVER_INTERFACE_MAX_NOTIFICATIONS_PER_PUBLISH": 1000,    "ua_gateway.UA_SERVER_INTERFACE_MAX_NOTIFICATION_QUEUE_SIZE": 100 }

 

 

Server Interface Properties

To obtain more information on each server interface property, perform a GET with the following endpoint url:

 

Endpoint (GET):

{{host}}:{{port}}/config/v1/project/_ua_gateway/ua_server_interfaces/Server Interface?content=property_definitions

 

Concurrent Sessions Property:

"ua_gateway.UA_SERVER_INTERFACE_CONCURRENT_SESSIONS"

 

 

Server Interface Enumeration Values:

For the server interface properties titled “UA_SERVER_INTERFACE_SECURITY_POLICIES_<TYPE>,” the enumeration values either disable the security policy or set the desired Message Mode for connecting with the given security policy. The enumeration values are as follows:

 

Server Interface — Local Discovery Server Connectivity Options

The UA Gateway can connect with an OPC application, called Local Discovery Server, which maintains a list of OPC UA servers running on the same host.

 

When set to true, the LDS_REGISTRATION_ENABLED property of the server interface indicates that the UA Gateway should attempt to register with a Local Discovery Server.

When set to false (default), the Local Discovery Server registration is disabled.

 

The LDS_MAX_REGISTRATION_INTERVAL_PROPERTY of the server interface specifies the maximum interval (in milliseconds) to register with the LDS.

 

Server Endpoint

A Server Endpoint represents the endpoint which a client connects to in order to communicate with the UA Gateway Service.

 

To create a new Server Endpoint, use the following rest request:

 

Endpoint POST

{{host}}:{{port}}/config/v1/project/_ua_gateway/ua_server_interfaces/Server Interface/ua_server_endpoints

 

Message body:

{      "common.ALLTYPES_NAME": "Server Endpoint12",      "common.ALLTYPES_DESCRIPTION": "",      "ua_gateway.UA_SERVER_ENDPOINT_NETWORK_ADAPTER": “All”,      "ua_gateway.UA_SERVER_ENDPOINT_PORT": 6000,      "ua_gateway.UA_SERVER_ENDPOINT_PROTOCOL": 0,      "ua_gateway.UA_SERVER_ENDPOINT_ENABLED": true }

 

Server Endpoint Properties

To get the list of currently configured endpoints use the following request:

 

Endpoint GET

{{host}}:{{port}}/config/v1/project/_ua_gateway/ua_server_interfaces/Server Interface/ ua_server_endpoints

 

Example network adapter enum values:

 

UA Gateway supports only a single UA server endpoint protocol value:

To query the available parameters for a server endpoint, configure a Server Endpoint and then perform a GET request on it with the following endpoint URL:

 

Endpoint GET

{{host}}:{{port}}/config/v1/project/_ua_gateway/ua_server_interfaces/Server Interface/ua_server_endpoints/<configured endpoint name>?content=property_definitions

 

Client Interface

Configuring the client interface and adding client connections allows communication between the UA Gateway and other OPC UA servers.

 

Client Connections

To connect the UA Gateway to a new server, a new client-connection must be created using the following endpoint:

 

Endpoint POST

{{host}}:{{port}}/config/v1/project/_ua_gateway/ua_client_interfaces/Client Interface/ua_client_connections

 

Message body:

{      "common.ALLTYPES_NAME": "Connection1",      "common.ALLTYPES_DESCRIPTION": "",      "ua_gateway.UA_CLIENT_CONNECTION_URL_NAME": "opc.tcp://<network-adapter>:<port>",      "ua_gateway.UA_CLIENT_CONNECTION_IDENTITY_POLICY": 1,      "ua_gateway.UA_CLIENT_CONNECTION_USER_NAME": "<User>",      "ua_gateway.UA_CLIENT_CONNECTION_USER_PASSWORD": "<Password>",      "ua_gateway.UA_CLIENT_CONNECTION_SECURITY_POLICY": 2,      "ua_gateway.UA_CLIENT_CONNECTION_MESSAGE_MODE": 1,      "ua_gateway.UA_CLIENT_CONNECTION_ENABLED": true,      "ua_gateway.UA_CLIENT_CONNECTION_PUBLISHING_INTERVAL": 500,      "ua_gateway.UA_CLIENT_CONNECTION_SUBSCRIPTION_LIFETIME": 500000,      "ua_gateway.UA_CLIENT_CONNECTION_SESSION_TIMEOUT": 60000,      "ua_gateway.UA_CLIENT_CONNECTION_MAX_MONITORED_ITEMS_PER_SUBSCRIPTION": 2147483647,      "ua_gateway.UA_CLIENT_CONNECTION_PASSTHROUGH_ENABLED": true,      "ua_gateway.UA_CLIENT_CONNECTION_MONITORED_ITEM_QUEUE_SIZE_OVERRIDE": 1,      "ua_gateway.UA_CLIENT_CONNECTION_DISCARD_POLICY": 0 }

 

To get a list of existing client connections, query the ua_client_connections collection endpoint:

 

Endpoint GET

{{host}}:{{port}}/config/v1/project/_ua_gateway/ua_client_interfaces/Client Interface/ua_client_connections

 

Performing a GET on this ua_client_connections endpoint returns the property values of each server, as well as the connection status.

 

To change a property value of a connection, perform a PUT on the connection endpoint:

 

Endpoint PUT

{{host}}:{{port}}/config/v1/project/_ua_gateway/ua_client_interfaces/Client Interface/ua_client_connections<ALLTYPES_NAME of connection>

 

The body of the PUT request must contain the PROJECT_ID as returned in a GET request on the endpoint, as well as the desired endpoint properties. Properties that do not need to be changed do not need to be sent in a PUT request.

 

Client Connections Enumeration Values

UA_CLIENT_CONNECTION_IDENTITY_POLICY:

UA_CLIENT_CONNECTION_SECURITY_POLICY

UA_CLIENT_CONNECTION_MESSAGE_MODE

 

Client Connections Properties

 

To query the properties available on a client connection, perform a GET on the following endpoint:

 

Endpoint GET

{{host}}:{{port}}/config/v1/project/_ua_gateway/ua_client_interfaces/Client Interface/ua_client_connections/<client-connection-name>?content=property_definitions