Configure an OPC-UA source (CLI)
You can define OPC-UA data sources for an AWS IoT SiteWise Edge gateway using the AWS CLI. To do this,
create an OPC-UA capability configuration JSON file and use the update-gateway-capability-configuration
This capability has the following namespace.
-
iotsitewise:opcuacollector:2
Request syntax
{ "sources": [ { "name": "
string
", "endpoint": { "certificateTrust": { "type": "TrustAny
" | "X509
", "certificateBody": "string
", "certificateChain": "string
", }, "endpointUri": "string
", "securityPolicy": "NONE
" | "BASIC128_RSA15
" | "BASIC256
" | "BASIC256_SHA256
" | "AES128_SHA256_RSAOAEP
" | "AES256_SHA256_RSAPSS
", "messageSecurityMode": "NONE
" | "SIGN
" | "SIGN_AND_ENCRYPT
", "identityProvider": { "type": "Anonymous
" | "Username
", "usernameSecretArn": "string
" }, "nodeFilterRules": [ { "action": "INCLUDE
", "definition": { "type": "OpcUaRootPath
", "rootPath": "string
" } } ] }, "measurementDataStreamPrefix": "string
", "typeConversions": { "array": "JsonArray
", "datetime": "ISO8601String
" }, "destination": { "type": "StreamManager
", "streamName": "string
", "streamBufferSize":integer
, }, "propertyGroups": [ { "name": "string
", "nodeFilterRuleDefinitions": [ { "type": "OpcUaRootPath
", "rootPath": "string
" } ], "deadband": { "type": "PERCENT
" | "ABSOLUTE
", "value":double
, "eguMin":double
, "eguMax":double
, "timeoutMilliseconds":integer
}, "scanMode": { "type": "EXCEPTION
" | "POLL
", "rate":integer
, "timestampToReturn": "SOURCE_TIME
" | "SERVER_TIME
" }, "dataQuality": { "allowGoodQuality":true
|false
, "allowBadQuality":true
|false
, "allowUncertainQuality":true
|false
}, "subscription": { "dataChangeTrigger": "STATUS
" | "STATUS_VALUE
" | "STATUS_VALUE_TIMESTAMP
", "queueSize":integer
, "publishingIntervalMilliseconds":integer
, "snapshotFrequencyMilliseconds":integer
} } ] } ] }
Request body
- sources
-
A list of OPC-UA source definition structures that each contain the following information:
- name
-
A unique, friendly name for the source.
- endpoint
-
An endpoint structure that contains the following information:
- certificateTrust
-
A certificate trust policy structure that contains the following information:
- type
-
The certificate trust mode for the source. Choose one of the following:
-
TrustAny
– The SiteWise Edge gateway trusts any certificate when it connects to the OPC-UA source. -
X509
– The SiteWise Edge gateway trusts an X.509 certificate when it connects to the OPC-UA source. If you choose this option, you must definecertificateBody
incertificateTrust
. You can also definecertificateChain
incertificateTrust
.
-
- certificateBody
-
(Optional) The body of an X.509 certificate.
This field is required if you choose
X509
fortype
incertificateTrust
. - certificateChain
-
(Optional) The chain of trust for an X.509 certificate.
This field is used only if you choose
X509
fortype
incertificateTrust
.
- endpointUri
-
The local endpoint of the OPC-UA source. For example, your local endpoint might look like
opc.tcp://203.0.113.0:49320
. - securityPolicy
-
The security policy to use so that you can secure messages that are read from the OPC-UA source. Choose one of the following:
-
NONE
– The SiteWise Edge gateway doesn't secure messages from the OPC-UA source. We recommend that you choose a different security policy. If you choose this option, you must also chooseNONE
formessageSecurityMode
. -
BASIC256_SHA256
– TheBasic256Sha256
security policy. -
AES128_SHA256_RSAOAEP
– TheAes128_Sha256_RsaOaep
security policy. -
AES256_SHA256_RSAPSS
– TheAes256_Sha256_RsaPss
security policy. -
BASIC128_RSA15
– (Deprecated) TheBasic128Rsa15
security policy is deprecated in the OPC-UA specification because it's no longer considered secure. We recommend that you choose a different security policy. For more information, see Basic128Rsa15. -
BASIC256
– (Deprecated) TheBasic256
security policy is deprecated in the OPC-UA specification because it's no longer considered secure. We recommend that you choose a different security policy. For more information, see Basic256.
Important
If you choose a security policy other than
NONE
, you must chooseSIGN
orSIGN_AND_ENCRYPT
formessageSecurityMode
. You must also configure your source server to trust the SiteWise Edge gateway. For more information, see Enabling your OPC-UA source servers to trust the SiteWise Edge gateway. -
- messageSecurityMode
-
The message security mode to use to secure connections to the OPC-UA source. Choose one of the following:
-
NONE
– The SiteWise Edge gateway doesn't secure connections to the OPC-UA source. We recommend that you choose a different message security mode. If you choose this option, you must also chooseNONE
forsecurityPolicy
. -
SIGN
– Data in transit between the SiteWise Edge gateway and the OPC-UA source is signed but not encrypted. -
SIGN_AND_ENCRYPT
– Data in transit between the gateway and the OPC-UA source is signed and encrypted.
Important
If you choose a message security mode other than
NONE
, you must choose asecurityPolicy
other thanNONE
. You must also configure your source server to trust the SiteWise Edge gateway. For more information, see Enabling your OPC-UA source servers to trust the SiteWise Edge gateway. -
- identityProvider
-
An identity provider structure that contains the following information:
- type
-
The type of authentication credentials required by the source. Choose one of the following:
-
Anonymous
– The source doesn't require authentication to connect. -
Username
– The source requires a user name and password to connect. If you choose this option, you must defineusernameSecretArn
inidentityProvider
.
-
- usernameSecretArn
-
(Optional) The ARN of an AWS Secrets Manager secret. The SiteWise Edge gateway uses the authentication credentials in this secret when it connects to this source. You must attach secrets to your SiteWise Edge gateway's IoT SiteWise connector to use them for source authentication. For more information, see Configuring data source authentication.
This field is required if you choose
Username
fortype
inidentityProvider
.
- nodeFilterRules
-
A list of node filter rule structures that define the OPC-UA data stream paths to send to the AWS Cloud. You can use node filters to reduce your SiteWise Edge gateway's startup time and CPU usage by only including paths to data that you model in AWS IoT SiteWise. By default, SiteWise Edge gateways upload all OPC-UA paths except those that start with
/Server/
. To define OPC-UA node filters, you can use node paths and the*
and**
wildcard characters. For more information, see Using OPC-UA node filters.Each structure in the list must contain the following information:
- action
-
The action for this node filter rule. You can choose the following option:
-
INCLUDE
– The SiteWise Edge gateway includes only data streams that match this rule.
-
- definition
-
A node filter rule structure that contains the following information:
- type
-
The type of node filter path for this rule. You can choose the following option:
-
OpcUaRootPath
– The SiteWise Edge gateway evaluates this node filter path against the root of the OPC-UA path hierarchy.
-
- rootPath
-
The node filter path to evaluate against the root of the OPC-UA path hierarchy. This path must start with
/
.
- measurementDataStreamPrefix
-
A string to prepend to all data streams from the source. The SiteWise Edge gateway adds this prefix to all data streams from this source. Use a data stream prefix to distinguish between data streams that have the same name from different sources. Each data stream should have a unique name within your account.
- typeConversions
-
The types of conversions available for unsupported OPC-UA data types. Each data type is converted to strings. For more information, see Converting unsupported data types.
- array
-
The simple array data type that is converted to strings. You can choose the following option:
-
JsonArray
– Indicates that you choose to convert your simple array data types to strings.
-
- datetime
-
The DateTime data type that is converted to strings. You can choose the following option:
-
ISO8601String
– Indicates that you choose to convert ISO 8601 data types to strings.
-
- destination
-
Configuration for the destination of the data stream.
- type
-
The type of the destination.
- streamName
-
The name of the stream. The stream name should be unique.
- streamBufferSize
-
The buffer size of the stream. This is important for managing the flow of data from OPC-UA sources.
- propertyGroups
-
(Optional) The list of property groups that define the
deadband
andscanMode
requested by the protocol.- name
-
The name of the property group. This should be a unique identifier.
- deadband
-
The
deadband
value defines the minimum change in a data point's value that must occur before the data is sent to the cloud. It contains the following information:- type
-
The supported types of deadband. You can choose the following options:
-
ABSOLUTE
– A fixed value that specifies the minimum absolute change required to consider a data point significant enough to be sent to the cloud. -
PERCENT
– A dynamic value that specifies the minimum change required as a percentage of the last sent data point's value. This type of deadband is useful when the data values vary significantly over time.
-
- value
-
The value of the deadband. When
type
isABSOLUTE
, this value is a unitless double. Whentype
isPERCENT
, this value is a double between1
and100
. - eguMin
-
(Optional) The engineering unit minimum when using a
PERCENT
deadband. You set this if the OPC-UA server doesn't have engineering units configured. - eguMax
-
(Optional) The engineering unit maximum when using a
PERCENT
deadband. You set this if the OPC-UA server doesn't have engineering units configured. - timeoutMilliseconds
-
The duration in milliseconds before timeout. The minimum is
100
.
- scanMode
-
The
scanMode
structure that contains the following information:- type
-
The supported types of
scanMode
. Accepted values arePOLL
andEXCEPTION
. - rate
-
The sampling interval for the scan mode.
- timestampToReturn
-
The source of the timestamp. You can choose the following options:
-
SOURCE_TIME
– Uses the timestamp from your device. -
SERVER_TIME
– Uses the timestamp from your server.
-
- nodeFilterRuleDefinitions
-
(Optional) A list of node paths to include in the property group. Property groups can't overlap. If you don't specify a value for this field, the group contains all paths under the root, and you can't create additional property groups. The
nodeFilterRuleDefinitions
structure contains the following information:- type
-
OpcUaRootPath
is the only supported type. This specifies that the value ofrootPath
is a path relative to the root of the OPC-UA browsing space. - rootPath
-
A comma-delimited list that specifies the paths (relative to the root) to include in the property group.