Configure OPC Publisher
Important
While we update this article, see Azure Industrial IoT for the most up to date content.
You can configure OPC Publisher to specify:
- The OPC UA node data changes to publish.
- The OPC UA events to publish.
- The telemetry format.
You can configure OPC Publisher using configuration files or using method calls.
Use configuration files
This section describes to options for configuring OPC UA node publishing with configuration files.
Use a configuration file to configure publishing data changes
The easiest way to configure the OPC UA nodes to publish is with a configuration file. The configuration file format is documented in publishednodes.json in the repository.
Configuration file syntax has changed over time. OPC Publisher still reads old formats, but converts them into the latest format when it persists the configuration.
The following example shows the format of the configuration file:
[
{
"EndpointUrl": "opc.tcp://testserver:62541/Quickstarts/ReferenceServer",
"UseSecurity": true,
"OpcNodes": [
{
"Id": "i=2258",
"OpcSamplingInterval": 2000,
"OpcPublishingInterval": 5000,
"DisplayName": "Current time"
}
]
}
]
Use a configuration file to configure publishing events
To publish OPC UA events, you use the same configuration file as for data changes.
The following example shows how to configure publishing for events generated by the SimpleEvents server. The SimpleEvents server can be found in the OPC Foundation repository is:
[
{
"EndpointUrl": "opc.tcp://testserver:62563/Quickstarts/SimpleEventsServer",
"OpcEvents": [
{
"Id": "i=2253",
"DisplayName": "SimpleEventServerEvents",
"SelectClauses": [
{
"TypeId": "i=2041",
"BrowsePaths": [
"EventId"
]
},
{
"TypeId": "i=2041",
"BrowsePaths": [
"Message"
]
},
{
"TypeId": "nsu=http://opcfoundation.org/Quickstarts/SimpleEvents;i=235",
"BrowsePaths": [
"/2:CycleId"
]
},
{
"TypeId": "nsu=http://opcfoundation.org/Quickstarts/SimpleEvents;i=235",
"BrowsePaths": [
"/2:CurrentStep"
]
}
],
"WhereClause": [
{
"Operator": "OfType",
"Operands": [
{
"Literal": "ns=2;i=235"
}
]
}
]
}
]
}
]
Use method calls
This section describes the method calls you can use to configure OPC Publisher.
Configure using OPC UA method calls
OPC Publisher includes an OPC UA Server, which can be accessed on port 62222. If the hostname is publisher, then the endpoint URI is: opc.tcp://publisher:62222/UA/Publisher.
This endpoint exposes the following four methods:
- PublishNode
- UnpublishNode
- GetPublishedNodes
- IoT HubDirectMethod
Configure using IoT Hub direct method calls
OPC Publisher implements the following IoT Hub direct method calls:
- PublishNodes
- UnpublishNodes
- UnpublishAllNodes
- GetConfiguredEndpoints
- GetConfiguredNodesOnEndpoint
- GetDiagnosticInfo
- GetDiagnosticLog
- GetDiagnosticStartupLog
- ExitApplication
- GetInfo
The format of the JSON payload of the method request and responses are defined in opcpublisher/HubMethodModel.cs.
If you call an unknown method on the module, it responds with a string that says the method isn't implemented. You can call an unknown method as a way to ping the module.
Configure username and password for authentication
The authentication mode can be set through an IoT Hub direct method calls. The payload must contain the property OpcAuthenticationMode and the username and password:
{
"EndpointUrl": "<Url of the endpoint to set authentication settings>",
"OpcAuthenticationMode": "UsernamePassword",
"Username": "<Username>",
"Password": "<Password>"
...
}
The password is encrypted by the IoT Hub Workload Client and stored in the publisher's configuration. To change authentication back to anonymous, use the method with the following payload:
{
"EndpointUrl": "<Url of the endpoint to set authentication settings>",
"OpcAuthenticationMode": "Anonymous"
...
}
If the OpcAuthenticationMode property isn't set in the payload, the authentication settings remain unchanged in the configuration.
Configure telemetry publishing
When OPC Publisher receives a notification of a value change in a published node, it generates a JSON formatted message that's sent to IoT Hub.
You can configure the content of this JSON formatted message using a configuration file. If no configuration file is specified with the --tc option, a default configuration is used that's compatible with the Connected factory solution accelerator.
If OPC Publisher is configured to batch messages, then they're sent as a valid JSON array.
The telemetry is derived from the following sources:
- The OPC Publisher node configuration for the node
- The MonitoredItem object of the OPC UA stack for which OPC Publisher got a notification.
- The argument passed to this notification, which provides details on the data value change.
The telemetry that's put into the JSON formatted message is a selection of important properties of these objects. If you need more properties, you need to change the OPC Publisher code base.
The syntax of the configuration file is as follows:
// The configuration settings file consists of two objects:
// 1) The 'Defaults' object, which defines defaults for the telemetry configuration
// 2) An array 'EndpointSpecific' of endpoint specific configuration
// Both objects are optional and if they are not specified, then publisher uses
// its internal default configuration, which generates telemetry messages compatible
// with the Microsoft Connected factory Preconfigured Solution (https://github.com/Azure/azure-iot-connected-factory).
// A JSON telemetry message for Connected factory looks like:
// {
// "NodeId": "i=2058",
// "ApplicationUri": "urn:myopcserver",
// "DisplayName": "CurrentTime",
// "Value": {
// "Value": "10.11.2017 14:03:17",
// "SourceTimestamp": "2017-11-10T14:03:17Z"
// }
// }
// The 'Defaults' object in the sample below, are similar to what publisher is
// using as its internal default telemetry configuration.
{
"Defaults": {
// The first two properties ('EndpointUrl' and 'NodeId' are configuring data
// taken from the OpcPublisher node configuration.
"EndpointUrl": {
// The following three properties can be used to configure the 'EndpointUrl'
// property in the JSON message send by publisher to IoT Hub.
// Publish controls if the property should be part of the JSON message at all.
"Publish": false,
// Pattern is a regular expression, which is applied to the actual value of the
// property (here 'EndpointUrl').
// If this key is omitted (which is the default), then no regex matching is done
// at all, which improves performance.
// If the key is used you need to define groups in the regular expression.
// Publisher applies the regular expression and then concatenates all groups
// found and use the resulting string as the value in the JSON message to
//sent to IoT Hub.
// This example mimics the default behaviour and defines a group,
// which matches the conplete value:
"Pattern": "(.*)",
// Here some more exaples for 'Pattern' values and the generated result:
// "Pattern": "i=(.*)"
// defined for Defaults.NodeId.Pattern, will generate for the above sample
// a 'NodeId' value of '2058'to be sent by publisher
// "Pattern": "(i)=(.*)"
// defined for Defaults.NodeId.Pattern, will generate for the above sample
// a 'NodeId' value of 'i2058' to be sent by publisher
// Name allows you to use a shorter string as property name in the JSON message
// sent by publisher. By default the property name is unchanged and will be
// here 'EndpointUrl'.
// The 'Name' property can only be set in the 'Defaults' object to ensure
// all messages from publisher sent to IoT Hub have a similar layout.
"Name": "EndpointUrl"
},
"NodeId": {
"Publish": true,
// If you set Defaults.NodeId.Name to "ni", then the "NodeId" key/value pair
// (from the above example) will change to:
// "ni": "i=2058",
"Name": "NodeId"
},
// The MonitoredItem object is configuring the data taken from the MonitoredItem
// OPC UA object for published nodes.
"MonitoredItem": {
// If you set the Defaults.MonitoredItem.Flat to 'false', then a
// 'MonitoredItem' object will appear, which contains 'ApplicationUri'
// and 'DisplayNode' proerties:
// "NodeId": "i=2058",
// "MonitoredItem": {
// "ApplicationUri": "urn:myopcserver",
// "DisplayName": "CurrentTime",
// }
// The 'Flat' property can only be used in the 'MonitoredItem' and
// 'Value' objects of the 'Defaults' object and will be used
// for all JSON messages sent by publisher.
"Flat": true,
"ApplicationUri": {
"Publish": true,
"Name": "ApplicationUri"
},
"DisplayName": {
"Publish": true,
"Name": "DisplayName"
}
},
// The Value object is configuring the properties taken from the event object
// the OPC UA stack provided in the value change notification event.
"Value": {
// If you set the Defaults.Value.Flat to 'true', then the 'Value'
// object will disappear completely and the 'Value' and 'SourceTimestamp'
// members won't be nested:
// "DisplayName": "CurrentTime",
// "Value": "10.11.2017 14:03:17",
// "SourceTimestamp": "2017-11-10T14:03:17Z"
// The 'Flat' property can only be used for the 'MonitoredItem' and 'Value'
// objects of the 'Defaults' object and will be used for all
// messages sent by publisher.
"Flat": false,
"Value": {
"Publish": true,
"Name": "Value"
},
"SourceTimestamp": {
"Publish": true,
"Name": "SourceTimestamp"
},
// 'StatusCode' is the 32 bit OPC UA status code
"StatusCode": {
"Publish": false,
"Name": "StatusCode"
// 'Pattern' is ignored for the 'StatusCode' value
},
// 'Status' is the symbolic name of 'StatusCode'
"Status": {
"Publish": false,
"Name": "Status"
}
}
},
// The next object allows to configure 'Publish' and 'Pattern' for specific
// endpoint URLs. Those will overwrite the ones specified in the 'Defaults' object
// or the defaults used by publisher.
// It is not allowed to specify 'Name' and 'Flat' properties in this object.
"EndpointSpecific": [
// The following shows how a endpoint specific configuration can look like:
{
// 'ForEndpointUrl' allows to configure for which OPC UA server this
// object applies and is a required property for all objects in the
// 'EndpointSpecific' array.
// The value of 'ForEndpointUrl' must be an 'EndpointUrl' configured in
// the publishednodes.json confguration file.
"ForEndpointUrl": "opc.tcp://<your_opcua_server>:<your_opcua_server_port>/<your_opcua_server_path>",
"EndpointUrl": {
// We overwrite the default behaviour and publish the
// endpoint URL in this case.
"Publish": true,
// We are only interested in the URL part following the 'opc.tcp://' prefix
// and define a group matching this.
"Pattern": "opc.tcp://(.*)"
},
"NodeId": {
// We are not interested in the configured 'NodeId' value,
// so we do not publish it.
"Publish": false
// No 'Pattern' key is specified here, so the 'NodeId' value will be
// taken as specified in the publishednodes configuration file.
},
"MonitoredItem": {
"ApplicationUri": {
// We already publish the endpoint URL, so we do not want
// the ApplicationUri of the MonitoredItem to be published.
"Publish": false
},
"DisplayName": {
"Publish": true
}
},
"Value": {
"Value": {
// The value of the node is important for us, everything else we
// are not interested in to keep the data ingest as small as possible.
"Publish": true
},
"SourceTimestamp": {
"Publish": false
},
"StatusCode": {
"Publish": false
},
"Status": {
"Publish": false
}
}
}
]
}
Next steps
Now you've learned how to configure OPC Publisher, the suggested next step is to learn how to Run OPC Publisher.