Azure-Samples / iot-edge-opc-plc

Sample OPC UA server with nodes that generate random and increasing data, anomalies and much more ...
MIT License
218 stars 94 forks source link

page_type: sample description: "Industrial IoT - Sample OPC UA server that generates random data and anomalies." languages:

OPC PLC server

Implements an OPC-UA server with different nodes generating random data, anomalies and configuration of user defined nodes.

Deploy to Azure

Features

The following nodes are part of the PLC simulation:

By default everything is enabled, use command line options to disable certain anomaly or data generation features. Additionally to those nodes with simulated data, a JSON configuration file allows nodes to be created as specified. Finally, the simulation supports a number of nodes of specific types that can change at a configurable rate.

Getting Started

Prerequisites

The implementation is based on .NET Core so it is cross-platform. The recommended hosting environment is Docker.

Quickstart

A Docker container of the component is hosted in the Microsoft Container Registry (MCR) and can be pulled by:

docker pull mcr.microsoft.com/iotedge/opc-plc:<See version.json>

The tags of the container match the tags of this repository and the containers are available for Windows and Linux.

Sample start command for Docker:

docker run --rm -it -p 50000:50000 -p 8080:8080 --name opcplc mcr.microsoft.com/iotedge/opc-plc:latest --pn=50000 --autoaccept --sph --sn=5 --sr=10 --st=uint --fn=5 --fr=1 --ft=uint --gn=5

Sample start command for Windows:

dotnet opcplc.dll --pn=50000 --at X509Store --autoaccept --sph --sn=5 --sr=10 --st=uint --fn=5 --fr=1 --ft=uint --gn=5

Note: Make sure that your OPC UA client uses security policy Basic256Sha256 and message security mode Sign & Encrypt to connect.

User node configuration via JSON configuration file

If the module (application) is started with the argument --nodesfile then the specified JSON configuration file is loaded. Nodes defined in the JSON file will be published by the server. This enables another OPC-UA client application to set the state/value of the node. Please note that nodes specified in the JSON file are NOT part of the simulation. They remain visible in an unchanged state until an OPC UA client changes their status.

The following command shows how to use a configuration file on Windows:

dotnet opcplc.dll --at X509Store --nodesfile nodesfile.json

Here's a sample node configuration file:

{
  "Folder": "MyTelemetry",
  "FolderList": [
    {
      "Folder": "Directory",
      "NodeList": [
        {
          "NodeId": "ChildNode"
        },
      ]
    }
  ],
  "NodeList": [
    {
      "NodeId": 1023,
      "Name": "ActualSpeed",
      "Description": "Rotational speed"
    },
    {
      "NodeId": "aRMS"
    },
    {
      "NodeId": "1025",
      "Name": "DKW",
      "DataType": "Float",
      "ValueRank": -1,
      "AccessLevel": "CurrentReadOrWrite",
      "Description": "Diagnostic characteristic value"
    }
  ]
}

Slow and fast changing nodes

A number of changing nodes can be simulated with the following options. The nodes are categorized into slow and fast only for convenience.

Data types

OPC Publisher file (pn.json)

The options --sph and --sp show and dump an OPC Publisher configuration file (default name: pn.json) that matches the configuration. In addition, a web server hosts the file on a configurable port (--wp, default 8080): e.g. http://localhost:8080/pn.json Additionally, you can set the configuration file name via the option --spf.

Complex type (Boiler #1)

Adds a simple boiler to the address space.

Features:

Boiler #2 derived from the Device Information (DI) companion spec

Adds a configurable boiler that exposes DI properties such as AssetId (ITagNameplate, IVendorNameplate) and DeviceHealth.

Features:

Simulation details:

DeviceHealth (DeviceHealthEnumeration) details:

Temperature DeviceHealth
< BaseTemperature OFF_SPEC
>= BaseTemperature NORMAL
<= TargetTemperature NORMAL
> TargetTemperature CHECK_FUNCTION
>= OverheatThresholdTemperature FAILURE
> OverheatThresholdTemperature + 5 OFF_SPEC

Simple Events

The option --ses enables simple events from the quickstart sample from OPC Foundation.

Simple Events defines four new event types. SystemCycleStatusEventType is inherited from the SystemEventType and SystemCycleStartedEventType, SystemCycleAbortedEventType, SystemCycleFinishedEventType from SystemCycleStatusEventType.

Every 3000 ms a new SystemCycleStartedEventState is triggered. (The other event types are not used.) Two messages are generated with a counter "The system cycle '{counter}' has started." for each event, one has severity 1 and the other one severity 2.

A structure of type CycleStepDataType is added to SystemCycleStartedEventState event. The values in that structure is hard coded to Name: Step 1 and Duration: 1000.

Alarms and Condition

The option --alm enables Alarm and Condition quickstart sample from OPC Foundation.

It creates a hierarchical folder structure from Server, starting with Green and Yellow. The leaf nodes SouthMotor, WestTank, EastTank and NorthMotor are sources for the alarms.

The alarms are of different types:

All these alarms will update on a regular interval. It is also possible to Acknowledge, Confirm and add Comment to them.

This simulation also emits two types of system events: SystemEventType and AuditEventType, every 1000 ms.

Deterministic Alarms testing

The option --dalm=<file> enables deterministic testing of Alarms and Conditions.

More information about this feature can be found here.

Other features

OPC UA Methods

Name Description Prerequisite
ResetTrend Reset the trend values to their baseline value Generate positive or negative trends activated
ResetStepUp Resets the StepUp counter to 0 Generate data activated
StopStepUp Stops the StepUp counter Generate data activated
StartStepUp Starts the StepUp counter Generate data activated
StopUpdateSlowNodes Stops the increase of value of slow nodes slow nodes activated
StopUpdateFastNodes Stops the increase of value of fast nodes fast nodes activated
StartUpdateSlowNodes Start the increase of value of slow nodes slow nodes activated
StartUpdateFastNodes Start the increase of value of fast nodes fast nodes activated

NuGet

Build

The build scripts are for Azure DevOps and the container build is done in ACR. To use your own ACR you need to:

Using <reporoot>/tools/scripts/build.ps1 you can also build with Docker Desktop locally. The sample below builds a debug container and is started at the root of the repository:

.\tools\scripts\build.ps1 -Path . -Debug

If you want to build using Docker yourself, it is a bit more complicated, since the dockerfile is generated by the scripts. So first run the build.ps1 script as above, then locate the dockerfile for your configuration and target runtime under <reporoot>/src/bin/publish. Next, make your modifications and publish the opc-plc project in Visual Studio. Ensure that you have chosen "Self-Contained" as "Deployment Mode" and the correct "Target runtime" in the Visual Studio Publish configuration. Finally, run the docker build command in the folder you published to using the dockerfile of your configuration and target runtime.

Building with PowerShell is even simpler. Here's an example for a linux-x64 build:

.\tools\scripts\docker-source.ps1 .\src
docker build -f .\src\bin\publish\Release\linux-x64\Dockerfile.linux-amd64 -t iotedge/opc-plc .\src\bin\publish\Release\linux-x64

Notes

X.509 certificates:

Resources

Command-line reference

Usage: dotnet opcplc.dll [<options>]

OPC UA PLC for different data simulation scenarios.
To exit the application, press CTRL-C while it's running.

Use the following format to specify a list of strings:
"<string 1>,<string 2>,...,<string n>"
or if one string contains commas:
""<string 1>","<string 2>",...,"<string n>""

Options:
      --lf, --logfile=VALUE  the filename of the logfile to use.
                               Default: './hostname-port-plc.log'
      --lt, --logflushtimespan=VALUE
                             the timespan in seconds when the logfile should be
                               flushed.
                               Default: 00:00:30 sec
      --ll, --loglevel=VALUE the loglevel to use (allowed: critical, error,
                               warn, info, debug, trace).
                               Default: info
      --sc, --simulationcyclecount=VALUE
                             count of cycles in one simulation phase.
                               Default: 50 cycles
      --ct, --cycletime=VALUE
                             length of one cycle time in milliseconds.
                               Default: 100 msec
      --ei, --eventinstances=VALUE
                             number of event instances.
                               Default: 0
      --er, --eventrate=VALUE
                             rate in milliseconds to send events.
                               Default: 1000
      --pn, --portnum=VALUE  the server port of the OPC server endpoint.
                               Default: 50000
      --op, --path=VALUE     the endpoint URL path part of the OPC server
                               endpoint.
                               Default: ''
      --ph, --plchostname=VALUE
                             the fully-qualified hostname of the PLC.
                               Default: hostname
      --ol, --opcmaxstringlen=VALUE
                             the max length of a string OPC can transmit/
                               receive.
                               Default: 4194304
      --otlpee, --otlpendpoint=VALUE
                             the endpoint URI to which the OTLP exporter is
                               going to send information.
                               Default: ''
      --otlpei, --otlpexportinterval=VALUE
                             the interval for exporting OTLP information in
                               seconds.
                               Default: 60
      --otlpep, --otlpexportprotocol=VALUE
                             the protocol for exporting OTLP information.
                               (allowed values: grpc, protobuf).
                               Default: grpc
      --otlpub, --otlpublishmetrics=VALUE
                             how to handle metrics for publish requests.
                               (allowed values: disable=Always disabled, enable=
                               Always enabled, auto=Auto-disable when sessions >
                                40 or monitored items > 500).
                               Default: auto
      --lr, --ldsreginterval=VALUE
                             the LDS(-ME) registration interval in ms. If 0,
                               then the registration is disabled.
                               Default: 0
      --aa, --autoaccept     all certs are trusted when a connection is
                               established.
                               Default: False
      --drurs, --dontrejectunknownrevocationstatus
                             Don't reject chain validation with CA certs with
                               unknown revocation status, e.g. when the CRL is
                               not available or the OCSP provider is offline.
                               Default: False
      --ut, --unsecuretransport
                             enables the unsecured transport.
                               Default: False
      --to, --trustowncert   the own certificate is put into the trusted
                               certificate store automatically.
                               Default: False
      --msec, --maxsessioncount=VALUE
                             maximum number of parallel sessions.
                               Default: 100
      --mset, --maxsessiontimeout=VALUE
                             maximum time that a session can remain open
                               without communication in milliseconds.
                               Default: 3600000
      --msuc, --maxsubscriptioncount=VALUE
                             maximum number of subscriptions.
                               Default: 100
      --mqrc, --maxqueuedrequestcount=VALUE
                             maximum number of requests that will be queued
                               waiting for a thread.
                               Default: 2000
      --at, --appcertstoretype=VALUE
                             the own application cert store type.
                               (allowed values: Directory, X509Store,
                               FlatDirectory)
                               Default: 'Directory'
      --ap, --appcertstorepath=VALUE
                             the path where the own application cert should be
                               stored.
                               Default (depends on store type):
                               X509Store: 'CurrentUser\UA_MachineDefault'
                               Directory: 'pki\own'
                               FlatDirectory: 'pki\own'
      --tp, --trustedcertstorepath=VALUE
                             the path of the trusted cert store.
                               Default 'pki\trusted'
      --rp, --rejectedcertstorepath=VALUE
                             the path of the rejected cert store.
                               Default 'pki\rejected'
      --ip, --issuercertstorepath=VALUE
                             the path of the trusted issuer cert store.
                               Default 'pki\issuer'
      --csr                  show data to create a certificate signing request.
                               Default 'False'
      --ab, --applicationcertbase64=VALUE
                             update/set this application's certificate with the
                               certificate passed in as base64 string.
      --af, --applicationcertfile=VALUE
                             update/set this application's certificate with the
                               specified file.
      --pb, --privatekeybase64=VALUE
                             initial provisioning of the application
                               certificate (with a PEM or PFX format) requires
                               a private key passed in as base64 string.
      --pk, --privatekeyfile=VALUE
                             initial provisioning of the application
                               certificate (with a PEM or PFX format) requires
                               a private key passed in as file.
      --cp, --certpassword=VALUE
                             the optional password for the PEM or PFX or the
                               installed application certificate.
      --tb, --addtrustedcertbase64=VALUE
                             adds the certificate to the application's trusted
                               cert store passed in as base64 string (comma
                               separated values).
      --tf, --addtrustedcertfile=VALUE
                             adds the certificate file(s) to the application's
                               trusted cert store passed in as base64 string (
                               multiple comma separated filenames supported).
      --ib, --addissuercertbase64=VALUE
                             adds the specified issuer certificate to the
                               application's trusted issuer cert store passed
                               in as base64 string (comma separated values).
      --if, --addissuercertfile=VALUE
                             adds the specified issuer certificate file(s) to
                               the application's trusted issuer cert store (
                               multiple comma separated filenames supported).
      --rb, --updatecrlbase64=VALUE
                             update the CRL passed in as base64 string to the
                               corresponding cert store (trusted or trusted
                               issuer).
      --uc, --updatecrlfile=VALUE
                             update the CRL passed in as file to the
                               corresponding cert store (trusted or trusted
                               issuer).
      --rc, --removecert=VALUE
                             remove cert(s) with the given thumbprint(s) (comma
                               separated values).
      --daa, --disableanonymousauth
                             flag to disable anonymous authentication.
                               Default: False
      --dua, --disableusernamepasswordauth
                             flag to disable username/password authentication.
                               Default: False
      --dca, --disablecertauth
                             flag to disable certificate authentication.
                               Default: False
      --au, --adminuser=VALUE
                             the username of the admin user.
                               Default: sysadmin
      --ac, --adminpassword=VALUE
                             the password of the administrator.
                               Default: demo
      --du, --defaultuser=VALUE
                             the username of the default user.
                               Default: user1
      --dc, --defaultpassword=VALUE
                             the password of the default user.
                               Default: password
      --alm, --alarms        add alarm simulation to address space.
                               Default: False
      --ses, --simpleevents  add simple events simulation to address space.
                               Default: False
      --dalm, --deterministicalarms=VALUE
                             add deterministic alarm simulation to address
                               space.
                               Provide a script file for controlling
                               deterministic alarms.
      --sp, --showpnjson     show OPC Publisher configuration file using IP
                               address as EndpointUrl.
                               Default: False
      --sph, --showpnjsonph  show OPC Publisher configuration file using
                               plchostname as EndpointUrl.
                               Default: False
      --spf, --showpnfname=VALUE
                             filename of the OPC Publisher configuration file
                               to write when using options sp/sph.
                               Default: pn.json
      --wp, --webport=VALUE  web server port for hosting OPC Publisher
                               configuration file.
                               Default: 8080
      --cdn, --certdnsnames=VALUE
                             add additional DNS names or IP addresses to this
                               application's certificate (comma separated
                               values; no spaces allowed).
                               Default: DNS hostname
  -h, --help                 show this message and exit
      --b2ts, --boiler2tempspeed=VALUE
                             Boiler #2 temperature change speed in degrees per
                               second.
                               Default: 1
      --b2bt, --boiler2basetemp=VALUE
                             Boiler #2 base temperature to reach when not
                               heating.
                               Default: 10
      --b2tt, --boiler2targettemp=VALUE
                             Boiler #2 target temperature to reach when heating.

                               Default: 80
      --b2mi, --boiler2maintinterval=VALUE
                             Boiler #2 required maintenance interval in seconds.

                               Default: 300
      --b2oi, --boiler2overheatinterval=VALUE
                             Boiler #2 overheat interval in seconds.
                               Default: 120
      --nv, --nodatavalues   do not generate data values.
                               Default: False
      --gn, --guidnodes=VALUE
                             number of nodes with deterministic GUID IDs.
                               Default: 1
      --nd, --nodips         do not generate dip data.
                               Default: False
      --fn, --fastnodes=VALUE
                             number of fast nodes.
                               Default: 1
      --fr, --fastrate=VALUE rate in seconds to change fast nodes.
                               Default: 1
      --ft, --fasttype=VALUE data type of fast nodes (UInt|Double|Bool|
                               UIntArray).
                               Default: UInt
      --ftl, --fasttypelowerbound=VALUE
                             lower bound of data type of fast nodes (UInt|
                               Double|Bool|UIntArray).
                               Default: min value of node type.
      --ftu, --fasttypeupperbound=VALUE
                             upper bound of data type of fast nodes (UInt|
                               Double|Bool|UIntArray).
                               Default: max value of node type.
      --ftr, --fasttyperandomization=VALUE
                             randomization of fast nodes value (UInt|Double|
                               Bool|UIntArray).
                               Default: False
      --fts, --fasttypestepsize=VALUE
                             step or increment size of fast nodes value (UInt|
                               Double|Bool|UIntArray).
                               Default: 1
      --fsi, --fastnodesamplinginterval=VALUE
                             rate in milliseconds for pn.json client to sample
                               fast nodes.
                               Default: 0
      --vfr, --veryfastrate=VALUE
                             rate in milliseconds to change fast nodes.
                               Default: 1000
      --nn, --nonegtrend     do not generate negative trend data.
                               Default: False
      --ns2, --nodeset2file=VALUE
                             the *.NodeSet2.xml file that contains the nodes to
                               be created in the OPC UA address space (multiple
                               comma separated filenames supported).
      --np, --nopostrend     do not generate positive trend data.
                               Default: False
      --sn, --slownodes=VALUE
                             number of slow nodes.
                               Default: 1
      --sr, --slowrate=VALUE rate in seconds to change slow nodes.
                               Default: 10
      --st, --slowtype=VALUE data type of slow nodes (UInt|Double|Bool|
                               UIntArray).
                               Default: UInt
      --stl, --slowtypelowerbound=VALUE
                             lower bound of data type of slow nodes (UInt|
                               Double|Bool|UIntArray).
                               Default: min value of node type.
      --stu, --slowtypeupperbound=VALUE
                             upper bound of data type of slow nodes (UInt|
                               Double|Bool|UIntArray).
                               Default: max value of node type.
      --str, --slowtyperandomization=VALUE
                             randomization of slow nodes value (UInt|Double|
                               Bool|UIntArray).
                               Default: False
      --sts, --slowtypestepsize=VALUE
                             step or increment size of slow nodes value (UInt|
                               Double|Bool|UIntArray).
                               Default: 1
      --ssi, --slownodesamplinginterval=VALUE
                             rate in milliseconds for pn.json client to sample
                               slow nodes.
                               Default: 0
      --ns, --nospikes       do not generate spike data.
                               Default: False
      --unf, --uanodesfile=VALUE
                             the binary *.PredefinedNodes.uanodes file that
                               contains the nodes to be created in the OPC UA
                               address space (multiple comma separated
                               filenames supported), use ModelCompiler.cmd <
                               ModelDesign> to compile.
      --nf, --nodesfile=VALUE
                             the filename that contains the list of nodes to be
                               created in the OPC UA address space.
      --vf1k, --veryfast1knodes=VALUE
                             number of very fast 1 kB nodes (Deprecated: Use
                               veryfastbsnodes).
                               Default: 1
      --vf1kr, --veryfast1krate=VALUE
                             rate in ms to change very fast 1 kB nodes (
                               Deprecated: Use veryfastbsrate).
                               Default: 1000
      --vfbs, --veryfastbsnodes=VALUE
                             number of very fast ByteString nodes.
                               Default: 1
      --vfbss, --veryfastbssize=VALUE
                             size in bytes to change very fast ByteString nodes
                               (min. 1).
                               Default: 1024
      --vfbsr, --veryfastbsrate=VALUE
                             rate in ms to change very fast ByteString nodes.
                               Default: 1000