lib-opc 库参考

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34794340353/FIN+5.3.1+lib-opc 中文整理基于 FIN 5.3.1

导读： OpcExt 实现了对 OPC UA 协议的连接器支持。

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

---

目录（导读）

• lib
• meta
• docs
• tags
• funcs
• Overview
• Endpoint Connectivity
  • Security Policy
• Certificates
• NodeIds
• Current Points
• Historical Points
• Writable Points
  • def
• opcGenCert(subject, alias: ...)
  • supertypes
• opcPing(conn)
• opcSyncCur(points)
• opcSyncHis(points, span: null)
  • usage
  • tags
  • enum

---

概述（中译）

OPC-UA 连接器

---

API 正文（英文）

docs

Overview • Endpoint Connectivity • Certificates • NodeIds • Current Points • Historical Points • Writable Points

---

tags

opcCertAlias	Used on an opcConn to indicate which certificate and key pair to use for asymmetric message security
opcConn	Marker tag for OPC connector record which stores the configuration for connectivity to an OPC UA endpoint
opcConnRef	Used on a proxy object to reference its parent opcConn
opcCur	OPC UA encoded address to use for current value subscriptions
opcHis	OPC UA encoded address to use for a historized proxy point
opcPoint	Point which synchronizes data via an OPC connector
opcSecurity	Defines a security policy and security mode pair to use for OPC UA messages
opcType	The NodeId of the point's OPC type
opcUserAuthMode	How the client should authenticate with the OPC-UA server
opcWrite	OPC UA encoded address to use for writing a point

---

funcs

opcGenCert	Generate a client certificate to use for an OPC connector
opcPing	Deprecated - use connPing()
opcSyncCur	Deprecated - use connSyncCur()
opcSyncHis	Deprecated - use connSyncHis()

---

lib opc

Overview

The OpcExt implements connector support for the OPC UA protocol.

Endpoint Connectivity

All OPC UA connections require a suitable server endpoint to connect to. The OPC foundation defines the following information for each endpoint:

• Endpoint URL: The uri for the endpoint.
• Security Policy: A security policy is made up of a set of signing and encryption algorithms and parameters.
• Security Mode: Either None, Sign or SignAndEncrypt to define how secure messages are passed back and forth.
• Server Urn: A unique name for a server instance that identifies it on the remote host.
• Authentication Mode: Currently, only Anonymous and UserName are supported

This connector requires the following tags:

• uri: The endpoint URL for the intended endpoint. This include the scheme which defines the method for which the connection will attempt to use. Only opc.tcp:// is currently supported.

• opcUserAuthMode: the authentication mode to use. If not specified, defaults to Anonymous.

  • Anonymous: connect using the client certificate only. The OPC-UA server must approve the client certificate before a connection can be authenticated.
  • UserName: Authenticate using a username and password. The username and password tags must be specified for this mode.

• opcSecurity: Composed of a security policy and security mode pair.

  See Security Policy for details.

• opcCertAlias: The alias in the key store of the client certificate to use for

  cryptographic functions. This is required if the security mode is not None. See certificates for more details.

On connecting, the connector will attempt to find an endpoint on the remote host that matches these tags.

Note, this method of connection is subject to change.

Security Policy

The following values are supported for the opcSecurity tag. The easiest way to configure this tag value is to edit the connector record within the Connector App.

• None
• Basic128Rsa15 Sign
• Basic128Rsa15 SignAndEncrypt
• (*) Basic256 Sign
• (*) Basic256 SignAndEncrypt
• (*) Basic256Sha256 Sign
• (*) Basic256Sha256 SignAndEncrypt

In older version of Java, the starred (*) security configurations may require you to install the Unlimited Strength Java Cryptography Extension Policy Files. The policy files and installation instructions can be downloaded from Oracle's website, (you can also find them by doing a web search for jce unlimited strength java 8).

In newer installations of Java (including latest Java 8), these cryptographic operations are enabled by default and don't require any special installation or configuration.

If you get an exception like the following, then you haven't installed the JCE Unlimited Strength policy files, or they are installed incorrectly. Note: a restart of SkySpark is necessary after you install the files.

sys::Err: java.security.InvalidKeyException: Illegal key size

Certificates

A client certificate is required when using any security mode besides None. When the extension is first enabled, a default, self-signed certificate will be added to the crypto store for SkySpark. It will have alias opc.default. This is the value that should be configured for the opcCertAlias tag on the connector.

You can add your certificates to the crypto store for SkySpark using the crypto tool. You would then configure the opcCertAlias tag to whatever alias you used when adding your certificate.

The default certificate's subject DN is auto-generated and includes the hostname of the device running SkySpark in an effort to make them unique. If you need to generate your client certificiate, use the opcGenCert() function.

NodeIds

NodeIds (for referencing nodes on a server) are composed of a namespace (a 16-bit integer) and a value. The value may be an integer, a string, a uuid or a bytestring.

All references to nodes on an OPC UA server must use the encoded form of that NodeId. Bytestrings must be encoded in base64. A namespace of 0 may be omitted.

The follow are example of how each encoding might look:

n=3;s=Test.Point                            => String "Test.Point" in the 3 namespace
n=15;i=2459                                 => Integer 2459 in the 15 namespace
i=348                                       => Integer 348 in the 0 namespace
n=1;b=YmxvYg==                              => A bytestring in the 1 namespace
n=7;g=03f0e2bb-8f1a-c800-e1f8-00623f7473c4  => A Uuid in the 7 namespace

Most built-in nodes are predefined NodeIds. It is recommended to use connector learn to add and bind points.

This table specifies the built-in OPC datatypes that are supported:

DateType          NodeId         Haystack
--------          ------         --------
Boolean           i=1            Bool
SByte             i=2            Number
Byte              i=3            Number
Int16             i=4            Number
UInt16            i=5            Number
Int32             i=6            Number
UInt32            i=7            Number
Int64             i=8            Number
UInt64            i=9            <NOT SUPPORTED>
Float             i=10           Number
Double            i=11           Number
String            i=12           Str
LocalizedText     i=21           Str

Current Points

OPC UA proxy points are configured with the opcCur tag, which maps to the NodeId for the node in server. For example, this point maps the current time on the server:

point
opcConnRef: @myOpcConn
opcCur: "i=2258"
kind: "DateTime"

Historical Points

OPC UA proxy points may be used to collect stored history from the remote server. The format is similar to current points. For example, this point will collect history on the running state of the server:

point
opcConnRef: @myOpcConn
opcHis: "i=2259"
opcType: "i=12"
kind: "Str"
enum: "Running,Failed,NoConfiguration,Suspended,Shutdown,Test,CommunicationFault,Unknown"

Writable Points

OPC UA proxy points are configured to write remote points via the opcWrite tag. Only OPC UA points that have a Value attribute can be written. For example, this point will write a Int16 OPC point type:

point
opcConnRef: @myOpcConn
opcWrite: "ns=2;s=Modbus Channel.ModbusSim.ModKepReg1"
opcType: "i=4"
kind: "Number"

---

---

def

func:opcGenCert

opcGenCert(subject, alias: ...)

Generate a client certificate to use for an OPC connector. Use the opcCertAlias tag to on the connector to configure a specific cert to use.

Examples:

// use the default alias opc.default
opcGenCert("dc=fooCustom, cn=FooCustom")

// create an cert with alias "opc.custom"
opcGenCert("dc=barCustom, cn=BarCustom", "opc.custom")

---

meta

admin	✓
def	func:opcGenCert
is	func
lib	lib:opc
name	opcGenCert

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:opcPing

opcPing(conn)

Deprecated - use connPing()

---

meta

admin	✓
def	func:opcPing
deprecated	✓
is	func
lib	lib:opc
name	opcPing

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:opcSyncCur

opcSyncCur(points)

Deprecated - use connSyncCur()

---

meta

admin	✓
def	func:opcSyncCur
deprecated	✓
is	func
lib	lib:opc
name	opcSyncCur

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:opcSyncHis

opcSyncHis(points, span: null)

Deprecated - use connSyncHis()

---

meta

admin	✓
def	func:opcSyncHis
is	func
lib	lib:opc
name	opcSyncHis

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

opcCertAlias

Used on an opcConn to indicate which certificate and key pair to use for asymmetric message security. See Certs

---

meta

def	opcCertAlias
is	str
lib	lib:opc
tagOn	opcConn

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

opcConn

Marker tag for OPC connector record which stores the configuration for connectivity to an OPC UA endpoint. The connector must also minimally define the following tags: uri and opcSecurity. Only the opc.tcp scheme for the uri is currently supported.

The username and password tag are not required. Only anonymous authentication is supported presently so these tags are ignored.

---

meta

connFeatures
def	opcConn
icon	opc
is	conn
lib	lib:opc

---

usage

opcConn  conn

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier
conn	Connector for communication to a remote system

---

tags

actorTimeout	Timeout for messages send to the connector's actor thread
connErr	Error message associated when connStatus indicates an error condition
connLinger	Linger timeout used to keep a connector open
connOpenRetryFreq	Duration used for connector open retries
connPingFreq	Duration used to configure the auto-ping feature on a given connector
connState	Current connection state of a connector as one of the predefined strings
connStatus	Current status of a connector as one of the predefined strings See Connectors
connTuningRef	Reference to a tuning configuration defined by a connTuning rec
dis	Display name for an entity
disabled	Indicates the entity is in a disabled state
id	Defines the unique identifier of an entity in system using a ref value type
opcCertAlias	Used on an opcConn to indicate which certificate and key pair to use for asymmetric message security
opcSecurity	Defines a security policy and security mode pair to use for OPC UA messages
opcUserAuthMode	How the client should authenticate with the OPC-UA server
password	Manages password which is hashed/stored to the password store
uri	Universal resource identifier
username	Username for an authentication account

---

---

def

opcConnRef

Used on a proxy object to reference its parent opcConn

---

meta

def	opcConnRef
is	ref
lib	lib:opc
of	opcConn
tagOn	opcPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
ref	Reference to an entity

---

---

def

opcCur

OPC UA encoded address to use for current value subscriptions. See NodeIds

---

meta

def	opcCur
is	str
lib	lib:opc
tagOn	opcPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

opcHis

OPC UA encoded address to use for a historized proxy point. See NodeIds

---

meta

def	opcHis
is	str
lib	lib:opc
tagOn	opcPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

opcPoint

Point which synchronizes data via an OPC connector.

---

meta

def	opcPoint
is	connPoint
lib	lib:opc

---

usage

opcPoint  point

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier
point	Data point such as a sensor or actuator
connPoint	Point associated with a connector for data synchronization with a remote system

---

tags

connTuningRef	Reference to a tuning configuration defined by a connTuning rec
cur	Supports current value
curCalibration	Calibration value to apply to adjust the value read from the connector before updating curVal
curConvert	Conversion to apply when reading curVal from connector
dis	Display name for an entity
disMacro	Display name using macro syntax
disabled	Indicates the entity is in a disabled state
enum	Defines an eumeration of string key names
equipRef	Reference to equip which contains this entity
ghgFactorHis	Identifies point record with interval emission factor data that the Greenhouse Gas Emission Engine uses to calculate emissions
his	Supports historization of data
hisConvert	Conversion to apply when reading history data from connector
id	Defines the unique identifier of an entity in system using a ref value type
kind	Kind name used to identity a value data type
maxVal	Inclusive maximum for a numeric value
minVal	Inclusive minimum for a numeric value
navName	Navigation name commonly used with disMacro to create computed display strings
opcConnRef	Used on a proxy object to reference its parent opcConn
opcCur	OPC UA encoded address to use for current value subscriptions
opcHis	OPC UA encoded address to use for a historized proxy point
opcType	The NodeId of the point's OPC type
opcWrite	OPC UA encoded address to use for writing a point
pointFunction	Classifies the point as a sensor, command, or setpoint
pointQuantity	Quantity the point senses or controls
pointSubject	What the point senses or controls
siteRef	Reference to site which contains the entity
spaceRef	Reference to space which contains this entity
systemRef	Reference to system
tz	Timezone identifier from standard timezone database
unit	Unit identifier from standard unit database
writable	Supports writing data
writeConvert	Conversion to apply when writing writeVal to the connector

---

---

def

opcSecurity

Defines a security policy and security mode pair to use for OPC UA messages. Use the connector app to configure this tag. See Security for supported values.

---

meta

def	opcSecurity
enum	See below
is	str
lib	lib:opc
tagOn	opcConn

---

enum

None
Basic128Rsa15 Sign
Basic128Rsa15 SignAndEncrypt
Basic256 Sign
Basic256 SignAndEncrypt
Basic256Sha256 Sign
Basic256Sha256 SignAndEncrypt

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

opcType

The NodeId of the point's OPC type.

---

meta

def	opcType
is	str
lib	lib:opc
tagOn	opcPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

opcUserAuthMode

How the client should authenticate with the OPC-UA server. See Endpoint Connectivity for more details.

---

meta

def	opcUserAuthMode
enum	See below
is	str
lib	lib:opc
tagOn	opcConn

---

enum

Anonymous
UserName

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

opcWrite

OPC UA encoded address to use for writing a point. See NodeIds

---

meta

def	opcWrite
is	str
lib	lib:opc
tagOn	opcPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters