OPC UA Module

OPC Unified Architecture (OPC UA) is a machine to machine communication protocol for industrial automation developed by the OPC Foundation. It provides a robust, secure, and scalable framework for communications and data exchange in the industrial automation space.

OPC UA is platform-independent, ensuring the seamless flow of information among devices from multiple vendors. It supports robust, reliable, and secure communications, providing both encryption and authentication, making it a leading choice for Industrial Internet of Things (IIoT) applications.

The OPC UA module in the context of Azure IoT Edge is a container that you deploy on your IoT Edge devices. This module is able to communicate with OPC UA servers in your industrial environment, extract data from them, and send this data to the cloud for further analysis or storage.

The OPC UA module can read data from many types of industrial equipment like PLCs, DCS, SCADA systems, and more. This is crucial because it allows for a wide variety of data to be pulled into Azure IoT Edge from industrial systems that traditionally have been difficult to integrate with modern cloud-based solutions.

In Azure IoT Edge, the OPC UA module communicates with other modules using the IoT Edge Hub, enabling complex processing and filtering of data at the edge before it's sent to the cloud. This can reduce the amount of data that needs to be sent to the cloud, lowering bandwidth requirements and improving responsiveness.

OPC UA manifest

Creating a manifest for an OPC/UA Module and configuring a template for it in Azure IoT Central involves defining the Modbus module in the manifest, setting up its Docker image and settings, and routing its messages. Then, in IoT Central, a template reflecting the Modbus module's capabilities is created and linked with the IoT Edge device. Finally, the manifest is applied to start deployment.

Step 1: Create an OPC/UA Module Manifest

The manifest is a JSON document that describes which modules to deploy to your IoT Edge device and how to configure them.

Below is a sample manifest that deploys an OPC/UA module:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "modules": {
          "OpcPublisher": {
            "settings": {
              "image": "mcr.microsoft.com/iotedge/opc-publisher:2.8.3",
              "createOptions": "{\"HostName\":\"OpcPublisher\",\"Cmd\":[\"OpcPublisher\",\"--autoaccept\",\"--trustowncert\",\"--publishfile=/iot/pn.json\",\"--diagnosticsinterval=30\",\"--iothubsendinterval=1\"],\"HostConfig\":{\"Binds\":[\"/iot:/iot\"],\"LogConfig\":{\"Config\":{\"max-size\":\"5m\",\"max-file\":\"20\"},\"Type\":\"json-file\"}}}"
            },
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "version": "1.0"
          },
          // Additional modules go here
        },
        // Additional configuration goes here
      }
    },
    // Additional module configurations go here
  }
}

"image": "mcr.microsoft.com/iotedge/opc-publisher:2.8.3": This specifies the Docker image to use for the module. In this case, it's version 2.8.3 of the OPC Publisher module from Microsoft's container registry.
"createOptions": This field contains a JSON string that specifies additional options for creating the Docker container. It includes several sub-fields:
- "HostName":"OpcPublisher": This sets the hostname of the Docker container to "OpcPublisher".
- "Cmd":["OpcPublisher","--autoaccept","--trustowncert","--publishfile=/iot/pn.json","--diagnosticsinterval=30","--iothubsendinterval=1"]: This is the command that will be run when the Docker container starts. It starts the OPC Publisher and includes several command-line arguments:
  - "--autoaccept": This option makes the OPC Publisher automatically accept all server certificates.
  - "--trustowncert": This option makes the OPC Publisher trust its own certificate.
  - "--publishfile=/iot/pn.json": This specifies the path to the publish nodes file, which contains the list of OPC UA nodes to publish.
  - "--diagnosticsinterval=30": This sets the interval in seconds at which diagnostic information should be sent.
  - "--iothubsendinterval=1": This sets the interval in seconds at which data should be sent to the IoT Hub.
- "HostConfig": This field contains additional configuration for the Docker host:
  - "Binds":["/iot:/iot"]: This binds the "/iot" directory on the host to the "/iot" directory in the Docker container.
  - "LogConfig": This field contains configuration for the Docker logs:
    - "Config":{"max-size":"5m","max-file":"20"}: This sets the maximum size of the log file to 5 megabytes and the maximum number of log files to 20.
    - "Type":"json-file": This sets the format of the log files to JSON.
"type": "docker": This specifies that the module is a Docker module.
"status": "running": This sets the desired status of the module to "running", meaning that it should be started as soon as it's deployed.
"restartPolicy": "always": This sets the restart policy for the module to "always", meaning that it should be restarted whenever it stops, regardless of the reason for stopping.

Step 2: Upload the Manifest to Azure IoT Central

Now, you can upload this manifest to Azure IoT Central:

In your Azure IoT Central application, go to Device Templates, and select the appropriate template for your IoT Edge device.
Go to Edge Manifests.
Click + New to add a new manifest.
Enter a name for the manifest, and paste the manifest JSON in the Manifest field.
Click Create.

Step 3: Deploy the OPC/UA Module

Finally, you can deploy your OPC/UA module to your IoT Edge device:

In your Azure IoT Central application, go to Devices, and select your IoT Edge device.
Go to Configuration.
In the Configuration Manifests section, select the manifest you created in the previous step.
Click Save.

important

An Azure IoT Edge device can host multiple modules, each serving a distinct function or process. It's important to understand that we don't deploy these modules individually; rather, we deploy a complete manifest. This manifest is a comprehensive description of all the modules to be installed, their configurations, and the inter-module communication routes. When the manifest is deployed, all of the outlined modules are deployed and configured together on the IoT Edge device.

Your IoT Edge device will now start deploying the OPC/UA module according to the manifest. This might take a few minutes. After the deployment is complete, the OPC/UA module will start running on your IoT Edge device, and you can start interacting with it through Azure IoT Central.

Step 4: Create OPC UA module configuration

Create a JSON file that will contain all the necessary configuration information required by the OPC UA module. For example, you can create a file named configuration.json.
Populate the configuration file with the basic settings, including the OPC UA server endpoint URL, whether to use security, and the OPC UA nodes to be published.

  {
    "EndpointUrl": "opc.tcp://testserver:62541/Quickstarts/ReferenceServer",
    "UseSecurity": true,
    "OpcNodes": [
      {
        "Id": "i=2258",
        "OpcSamplingInterval": 2000,
        "OpcPublishingInterval": 5000,
        "DisplayName": "Current time"
      }
    ]
  }

note

Please note that an individual object {} should be used for the final configuration file, not an array [].

If required, add additional paramaters to the configuration file. These parameters can relate to data set writing, messaging mode, batching, and details of the OPC nodes. A typical configuration schema with both the file-based and API-based configuration could look like this:

{
  "EndpointUrl": "string",
  "UseSecurity": "bool",
  "EndpointSecurityMode": "string",
  "EndpointSecurityPolicy": "string",
  "OpcAuthenticationMode": "string",
  "OpcAuthenticationUsername": "string",
  "OpcAuthenticationPassword": "string",
  "UseReverseConnect": "bool",
  "DataSetWriterId": "string",
  "DataSetClassId": "guid",
  "DataSetName": "string",
  "DataSetDescription": "string",
  "DataSetPublishingInterval": "integer",
  "DataSetPublishingIntervalTimespan": "string",
  "DataSetKeyFrameCount": "integer",
  "DataSetExtensionFields": "object",
  "MetaDataUpdateTime": "integer",
  "MetaDataUpdateTimeTimespan": "string",
  "SendKeepAliveDataSetMessages": "boolean",
  "DataSetWriterGroup": "string",
  "MessageEncoding": "string",
  "MessagingMode": "string",
  "WriterGroupTransport": "string",
  "BatchSize": "integer",
  "BatchTriggerInterval": "integer",
  "BatchTriggerIntervalTimespan": "string",
  "OpcNodes":
  [
    {
      "Id": "string",
      "ExpandedNodeId": "string",
      "AttributeId": "string",
      "IndexRange": "string",
      "UseCyclicRead": "boolean",
      "RegisterNode": "boolean",
      "FetchDisplayName": "boolean",
      "OpcSamplingInterval": "integer",
      "OpcSamplingIntervalTimespan": "string",
      "OpcPublishingInterval": "integer",
      "OpcPublishingIntervalTimespan": "string",
      "DataSetFieldId ": "string",
      "DataSetClassFieldId ": "Guid",
      "DisplayName": "string",
      "SkipFirst": "boolean",
      "DiscardNew": "boolean",
      "HeartbeatInterval": "integer",
      "HeartbeatIntervalTimespan": "string",
      "QueueSize": "integer",
      "DataChangeTrigger": "string",
      "DeadbandType": "string",
      "DeadbandValue": "decimal",
      "EventFilter": {
        (*)
      }
    }
  ],
  "Version": "integer",
  "LastChangeTimespan": "string",
}

Published Nodes Entry Models have the following attributes:

Attribute	Mandatory	Type	Default	Description
`Version`	No	Integer	`null`	A monotonically increasing number identifying the change version. NOTE: At this point the version number is informational only, but should be provided in API requests if available. It is not used inside file based configuration.
`LastChangeTimespan`	No	String	`null`	The time the Publisher configuration was last updated. Read only and informational only.
`EndpointUrl`	Yes	String	N/A	The OPC UA server endpoint URL
`UseReverseConnect`	No	Boolean	`false`	Controls whether to use OPC UA reverse connect to connect to the OPC UA server. A publisher wide default value can be set using the command line.
`UseSecurity`	No	Boolean	`false`	Controls whether to use a secure OPC UA mode to establish a session to the OPC UA server endpoint. `true` corresponds to `EndpointSecurityMode` = `SignAndEncrypt`, `false` to `EndpointSecurityMode` = `None`
`EndpointSecurityMode`	No	Enum	`null`	Enum to specify a requested security mode of the chosen session endpoint. Overrides `UseSecurity` value.Options: `Sign`, `SignAndEncrypt`, `None`, and `Best` (security mode possible which might include `None`)
`EndpointSecurityPolicy`	No	String	`null`	String to specify a security policy the chosen endpoint must meet. Refines the endpoint chosen through `EndpointSecurityMode` and overrides `UseSecurity` value.
`OpcAuthenticationMode`	No	Enum	`Anonymous`	Enum to specify the session authentication. Options: `Anonymous`, `UsernamePassword`
`OpcAuthenticationUsername`	No	String	`null`	The username for the session authentication if OpcAuthentication mode is `UsernamePassword`.
`OpcAuthenticationPassword`	No	String	`null`	The password for the session authentication if OpcAuthentication mode is `UsernamePassword`.
`DataSetWriterGroup`	No	String	`"<<UnknownWriterGroup>>"`	The data set writer group collecting datasets defined for a certain endpoint uniquely identified by the above attributes. This attribute is used to identify the session opened into the server. The default value consists of the EndpointUrl string, followed by a deterministic hash composed of the EndpointUrl, UseSecurity, OpcAuthenticationMode, UserName and Password attributes.
`DataSetWriterId`	No	String	`"<<UnknownDataSet>>"`	The unique identifier for a data set writer used to collect OPC UA nodes to be semantically grouped and published with the same publishing interval. When not specified a string representing the common publishing interval of the nodes in the data set collection. This attribute uniquely identifies a data set within a DataSetWriterGroup. The uniqueness is determined using the provided DataSetWriterId and the publishing interval of the grouped OpcNodes. An individual subscription is created for each DataSetWriterId.
`DataSetName`	No	String	`null`	The optional name of the data set as it will appear in the dataset metadata.
`DataSetDescription`	No	String	`null`	The optional description for the data set as it will appear in the dataset metadata.
`DataSetClassId`	No	Guid	`Guid.Empty`	The optional dataset class id as it shall appear in dataset messages and dataset metadata.
`DataSetExtensionFields`	No	Object	`null`	An optional JSON object with key value pairs where the value is a Variant in JSON encoding. This can be used to contextualize data set messages produced by the writer. Each item is added to key frame and meta data messages in the same data set, or in the extension section of samples messages (in samples messages the value is stringified).
`DataSetPublishingInterval`	No	Integer	`null`	The publishing interval used for a grouped set of nodes under a certain DataSetWriter. Value expressed in milliseconds. Ignored when `DataSetPublishingIntervalTimespan` is present. Note: When a specific node underneath DataSetWriter defines `OpcPublishingInterval` (or Timespan), its value will overwrite publishing interval for the specified node.
`DataSetPublishingIntervalTimespan`	No	String	`null`	The publishing interval used for a grouped set of nodes under a certain DataSetWriter.>Value expressed as a Timespan string `(d.hh:mm:dd.fff)`. When both Intervals are specified, the Timespan will win and be used for the configuration. Note: When a specific node underneath DataSetWriter defines `OpcPublishingInterval` (or Timespan), its value will overwrite publishing interval for the specified node.
`DataSetKeyFrameCount`	No	Integer	`null`	The optional number of messages until a key frame is inserted. Only valid if messaging mode supports key frames
`MetaDataUpdateTime`	No	Integer	`null`	The optional interval at which meta data messages should be sent even if the meta data has not chnaged. Only valid if messaging mode supports metadata or metadata is explicitly enabled.
`MetaDataUpdateTimeTimespan`	No	String	`null`	Same as `MetaDataUpdateTime` but expressed as duration string. Takes precedence over the Integer value.
`SendKeepAliveDataSetMessages`	No	Boolean	`false`	Whether to send keep alive data set messages for this data set when a subscription keep alive notification is received. Only valid if messaging mode supports keep alive messages.
`MessageEncoding`	No	String	`null`	The message encoding to use when publishing the data sets.
`MessagingMode`	No	String	`null`	The messaging mode to use when publishing the data sets.
`WriterGroupTransport`	No	String	`null`	The transport technology to use when publishing messages.
`BatchSize`	No	Integer	`null`	The optional number of notifications that are queued before a network message is generated. For historic reasons the default value is 50 unless otherwise configured via `--bs` command line option.
`BatchTriggerInterval`	No	Integer	`null`	The network message publishing interval. Network and meta data messages are published cyclically from the notification queue when the specified duration has passed (or when the batch size configuration triggered a network message). For historic reasons the default value is 10 seconds unless otherwise configured via the `--bi` command line option.
`BatchTriggerIntervalTimespan`	No	String	`null`	Same as `BatchTriggerInterval` but expressed as duration string. Takes precedence over the Integer value.
`OpcNodes`	No	`List<OpcNode>`	empty	The DataSet collection grouping the nodes to be published for the specific DataSetWriter defined above.

Note: OpcNodes field is mandatory for PublishNodes_V1. It is optional for UnpublishNodes_V1 and AddOrUpdateEndpoints_V1. And OpcNodes field shouldn't be specified for the rest of the direct methods.

Each OpcNode has the following attributes:

Attribute	Mandatory	Type	Default	Description
`Id`	Yes*	String	N/A	The OPC UA NodeId in the OPC UA server whose data value changes should be published. Can be specified as NodeId or ExpandedNodeId as per OPC UA specification, or as ExpandedNodeId IIoT format `{NamespaceUi}#` `{NodeIdentifier}`. Note*: `Id` field may be omitted when `ExpandedNodeId` is present.
`ExpandedNodeId`	No	String	`null`	Enables backwards compatibility. Must be specified as ExpandedNodeId as per OPC UA specification. Note*: when `ExpandedNodeId` is present `Id` field may be omitted.
`AttributeId`	No	String	`Value`	The node attribute to sample in case the node is a variable value (data item). The allowed values are defined in the OPC UA specification. Ignored when subscribing to events.
`IndexRange`	No	String	`null`	The index range of the value to publish. Value expressed as a numeric range as defined in the OPC UA specification. Ignored when subscribing to events.
`OpcSamplingInterval`	No	Integer	`1000`	The sampling interval for the monitored item to be published. Value expressed in milliseconds. The value is used as defined in the OPC UA specification. Ignored when `OpcSamplingIntervalTimespan` is present.
`OpcSamplingIntervalTimespan`	No	String	`null`	The sampling interval for the monitored item to be published. Value expressed in Timespan string(d.hh:mm:dd.fff). The value is used as defined in the OPC UA specification.
`OpcPublishingInterval`	No	Integer	`null`	The publishing interval for the monitored item to be published. Value expressed in milliseconds. This value will overwrite the publishing interval defined in the DataSetWriter for the specified node. The value is used as defined in the OPC UA specification. Ignored when `OpcPublishingIntervalTimespan` is present.
`OpcPublishingIntervalTimespan`	No	String	`null`	The publishing interval for the monitored item to be published. Value expressed in Timespan string(d.hh:mm:dd.fff). This value will overwrite the publishing interval defined in the DataSetWriter for the specified node. The value is used as defined in the OPC UA specification.
`DataSetFieldId`	No	String	`null`	A user defined tag used to identify the field in the DataSet telemetry message when publisher runs in PubSub message mode.
`DataSetClassFieldId`	No	Guid	`Guid.Empty`	A user defined Guid that identifies the field in the data set class of the DataSet telemetry message when publisher runs in PubSub message mode. This value is ignored when subscribing to events, in which case a `DataSetClassFieldId` can be applied to each select clause that select the content of the event dataset.
`DisplayName`	No	String	`null`	A user defined tag to be added to the telemetry message when publisher runs in Samples message mode.
`HeartbeatInterval`	No	Integer	`0`	The interval used for the node to publish a value (a publisher cached one) even if the value hasn't been changed at the source. Value expressed in seconds. 0 means the heartbeat mechanism is disabled. This value is ignored when `HeartbeatIntervalTimespan` is present.
`HeartbeatIntervalTimespan`	No	String	`null`	The interval used for the node to publish a value (a publisher cached one) even if the value hasn't been changed at the source. Value expressed in Timespan string(d.hh:mm:dd.fff).
`SkipFirst`	No	Boolean	`false`	Whether the first received data change for the monitored item should not be sent. This can avoid large initial messages since all values are sent by a server as the first notification. If an `EventFilter` is specified, this value is ignored
`QueueSize`	No	Integer	`1`	The desired QueueSize for the monitored item to be published.
`FetchDisplayName`	No	Boolean	`false`	Whether the server shall fetch display names of monitored variable nodes and use those inside messages as field names. Default is to use the `DisplayName` value if provided even if this option is set to `true`, if not provided or `false`, and no `DisplayName` specified, the node id is used.
`DiscardNew`	No	Boolean	`false`	Whether the server shall discard new values when the queue is full. Default is false, it will discard values that have not been sent yet.
`UseCyclicRead`	No	Boolean	`false`	Read the value periodically at the sampling rate insteead of subscribing through subscriptions. Ignored when subscribing to events.
`RegisterNode`	No	Boolean	`false`	Register the node to sample using the Register service call before accessing. Some servers then support faster reads, but this is not guaranteed. The service is defined in the OPC UA specification. Ignored when subscribing to events.
`DataChangeTrigger`	No	String	`null`	The data change trigger to use. The default is `"StatusValue"` causing telemetry to be sent when value or statusCode of the DataValue change. `"Status"` causes messages to be sent only when the status code changes and `"StatusValueTimestamp"` causes a message to be sent when value, statusCode, or the source timestamp of the value change. A publisher wide default value can be set using the command line. This value is ignored if an EventFilter is configured.
`DeadbandType`	No	String	`1`	The type of deadband filter to apply. `"Percent"` means that the `DeadbandValue` specified is a percentage of the EURange of the value. The value then is clamped to a value between 0.0 and 100.0 `"Absolute"` means the value is an absolute deadband range. Negative values are interpreted as 0.0. This value is ignored if an `EventFilter` is present.
`DeadbandValue`	No	Decimal	`1`	The deadband value to use. If the `DeadbandType` is not specified or an `EventFilter` is specified, this value is ignored.
`EventFilter`	No	EventFilter	`null`	An event filter configuration to use when subscribing to events instead of data changes.

Step 5: Add the configuration to Facts

Log in to Inimco.facts. You will be taken to the Manage Devices screen.
Navigate to Devices.
Select a device that you need to add the configuration to.
Navigate to the Modules tab.
Click the ellipsis (...) next to the module that you need to add the configuration to.
Select Edit configuration.
Add the configuration file to the Configuration OpcPublisher.

note

Please note that an individual object ``should be used for the final configuration file, not an array [].

Click Save.
Click the ellipsis (...) next to the module you added the configuration to.
Select Publish configuration.

Please note that the exact steps and the specifics of the manifest might differ based on your particular use case and the specifics of your OPC/UA module.

OPC UA manifest

Step 1: Create an OPC/UA Module Manifest​

Step 2: Upload the Manifest to Azure IoT Central​

Step 3: Deploy the OPC/UA Module​

Step 4: Create OPC UA module configuration​

Step 5: Add the configuration to Facts​

Contents

Step 1: Create an OPC/UA Module Manifest

Step 2: Upload the Manifest to Azure IoT Central

Step 3: Deploy the OPC/UA Module

Step 4: Create OPC UA module configuration

Step 5: Add the configuration to Facts