D 2022-11-12T05:48:14.453
L topcua
P c22ee6563ec3d8a11649bdbdf5e5fcf25d5ca24e
U chw
W 62853
<h2>opcua command</h2>
<h3>Name</h3>
<b>opcua</b> - Tcl binding to the OPC/UA implementation of <b>http://www.open62541.org</b>
<h3>Synopsis</h3>
<tt>package require topcua</tt><br>
<tt>opcua <i>cmd</i> ?<i>arg</i>?</tt><br>
<h3>Description</h3>
This command provides several operations to manage and communicate using the OPC/UA implementation of <b>http://www.open62541.org</b>. It is available on common POSIX and Windows platforms. <tt><i>cmd</i></tt> indicates which operation to carry out. Any unique abbreviation for <tt><i>cmd</i></tt> is acceptable. The valid commands are:
<tt>opcua acl <i>handle ?user pass ...?</i></tt>
Modifies the user/password based access control list of the server object <tt><i>handle</i></tt>. This command must be called after the server object has been created (see <tt>opcua new server</tt>) and before it is put into operation (see <tt>opcua start</tt>).
<tt>opcua add <i>handle</i> DataType <i>nodeid parent reftype brname ?attrs?</i></tt>
Adds an new node of node class <tt>DataType</tt> in the object <tt><i>handle</i></tt> and returns the node identifer. The parameter <tt><i>nodeid</i></tt> is the requested new node identifier of the node to be created. <tt><i>parent</i></tt> is the parent node identifier and <tt><i>reftype</i></tt> the reference type or node identifier of the reference between the parent and the new node. <tt><i>brname</i></tt> is the browse name (see section <b>Qualified Names</b>) of the new node. The optional <tt><i>attrs</i></tt> parameter specifies attributes for the new node in form of a dictionary (see <tt>opcua attr default</tt>). If it is omitted, default values are used. The <tt><i>DisplayName</i></tt> attribute if left empty is preset to the name part of the browse name parameter.
<tt>opcua add <i>handle</i> Method|SimpleMethod <i>nodeid parent reftype outargs brname inargs cmd ?attrs?</i></tt>
Adds an new node of node class <tt>Method</tt> in the object <tt><i>handle</i></tt> and returns the node identifer. In the <tt>SimpleMethod</tt> command form the parameter <tt><i>outargs</i></tt> describes the output arguments of the method as a list of zero or more pairs of data type and argument names. To force an argument to be a scalar, the argument name must be prefixed with an exclamation mark. To force an argument to be an array, the argument name must be prefixed with an asterisk. Likewise, <tt><i>inargs</i></tt> describes the input arguments of the method with identical prefix rules. In the <tt>Method</tt> command form, both <tt><i>outargs</i></tt> and <tt><i>inargs</i></tt> must be provided as lists of dicts with the template obtained from <tt>opcua types empty <i>Argument</i></tt>. The parameter <tt><i>cmd</i></tt> is the Tcl callback to handle the method invocation, see section <b>Method Callbacks</b> for more information. For the other parameters, refer to <tt>opcua add DataType</tt>.
<tt>opcua add <i>handle</i> Namespace <i>name</i></tt>
Adds the new namespace <tt><i>name</i></tt> to the server object <tt><i>handle</i></tt> and returns a numeric identifier for this namespace.
<tt>opcua add <i>handle</i> Object <i>nodeid parent reftype brname ?typeid attrs?</i></tt>
Adds an new node of node class <tt>Object</tt> in the object <tt><i>handle</i></tt> and returns the node identifer. The optional parameter <tt><i>typeid</i></tt> must be a known data type name (see <tt>opcua types</tt>) or a node identifier of a data type. For the other parameters, refer to <tt>opcua add DataType</tt>.
<tt>opcua add <i>handle</i> ObjectType <i>nodeid parent reftype brname ?attrs?</i></tt>
Adds an new node of node class <tt>ObjectType</tt> in the object <tt><i>handle</i></tt> and returns the node identifer. For the other parameters, refer to <tt>opcua add DataType</tt>.
<tt>opcua add <i>handle</i> Reference <i>srcid reftype target ?forward?</i></tt>
Adds a reference of type <tt><i>reftype</i></tt> (see <tt>opcua reftype</tt>) between the node identifiers <tt><i>srcid</i></tt> and <tt><<i>target</i></tt> on the object <tt><i>handle</i></tt>. The optional parameter <tt><i>forward</i></tt> must be a boolean indicating the direction of the reference (true, the default, is forward, false is inverse).
<tt>opcua add <i>handle</i> ReferenceType <i>nodeid parent reftype brname ?attrs?</i></tt>
Adds an new node of node class <tt>ReferenceType</tt> in the object <tt><i>handle</i></tt> and returns the node identifer. For the other parameters, refer to <tt>opcua add DataType</tt>.
<tt>opcua add <i>handle</i> Variable <i>nodeid parent reftype brname ?typeid attrs cmd?</i></tt>
Adds an new node of node class <tt>Variable</tt> in the object <tt><i>handle</i></tt> and returns the node identifer. The optional parameter <tt><i>typeid</i></tt> must be a known data type name (see <tt>opcua types</tt>) or a node identifier of a data type or an empty string for a default value. Parameter <tt><i>cmd</i></tt> is an optional data source callback which produces (read operation) or consumes (write operation) the variable's value. See section <b>Data Source Callbacks</b> for more information. For the other parameters, refer to <tt>opcua add DataType</tt>.
<tt>opcua add <i>handle</i> VariableType <i>nodeid parent reftype brname ?typeid attrs?</i></tt>
Adds an new node of node class <tt>VariableType</tt> in the object <tt><i>handle</i></tt> and returns the node identifer. The optional parameter <tt><i>typeid</i></tt> must be a known data type name (see <tt>opcua types</tt>) or a node identifier of a data type or an empty string for a default value. For the other parameters, refer to <tt>opcua add DataType</tt>.
<tt>opcua add <i>handle</i> View <i>nodeid parent reftype brname ?attrs?</i></tt>
Adds an new node of node class <tt>View</tt> in the object <tt><i>handle</i></tt> and returns the node identifer. For the other parameters, refer to <tt>opcua add DataType</tt>.
<tt>opcua appdesc <i>handle ?description?</i></tt>
Queries or sets the application description of the object <tt><i>handle</i></tt>. For a query, the current application description is returned as a a dictionary. This dictionary can be used as basis for modification and further to set a new application <tt><i>description</i></tt>. The set operation
can be performed only on stopped server objects and unconnected client objects. Note, that the <tt>ApplicationUri</tt> component of the application description must match the corresponding information in certificates.
<tt>opcua attrs ?list|default|numeric? <i>?name?</i></tt>
Without further parameters returns a list of attribute names the <tt>opcua read</tt> and <tt>opcua write</tt> commands support, e.g. <tt>Value</tt>, <tt>NodeClass</tt>, etc. With the <tt>list</tt> keyword a list of the data types used as attributes for creation of nodes with the <tt>opcua add</tt> command is returned. With the <tt>default</tt> keyword combined with the <tt><i>name</i></tt> of the data type a dictionary describing the default attributes of this type is returned, e.g <tt>opcua attrs default <i>DataTypeAttributes<i></tt> yields a default dictionary for creation of a <tt>DataType</tt> node. With the <tt><i>numeric</i></tt> keyword combined with the <tt><i>name</i></tt> of the data type, the numeric value of the attribute is returned.
<tt>opcua attr_init <i>name body ...</i></tt>
Helper function to create and return a dictionary for the attribute type <tt><i>name</i></tt> which is initially filled with defaults from <tt>opcua attrs default...</tt> and finally modified by the Tcl code
in <tt><i>body</i></tt> with the same rules as in the <tt>dict with</tt> command. The parameters following <tt><i>body</i></tt> are assigned to the list <tt><i>args</i></tt> as in a <tt>proc</tt>. In contrast to <tt>dict with</tt>, <tt><i>body</i></tt> is executed in a call frame of its own.
<tt>opcua browse <i>handle nodeid ?dir refid mask ...?</i></tt>
Performs a browse operation on the client or server object <tt><i>handle</i></tt> starting at the node <tt><i>nodeid</i></tt>. The browse direction can be specified with the <tt><i>dir</i></tt> parameter as <tt>Forward</tt>, <tt>Inverse</tt>, or <tt>Both</tt>. <tt>Forward</tt> is the default direction. The optional <tt><i>mask</i></tt> and following parameters select specific node classes <tt>Object</tt>, <tt>Variable</tt>, <tt>Method</tt>, <tt>ObjectType</tt>, <tt>VariableType</tt>, <tt>ReferenceType</tt>, <tt>DataType</tt>, and <tt>View</tt>. The result of the browse operation is a list where each item is made up of node identifier, browse name (qualified name), display name (locale and text), node class, reference node identifier, and type node identifier.
<tt>opcua call <i>handle nodeid methodid ?type value ...? ?</i>-async <i>cmd?</i></tt>
Calls the method with node identifier <tt><i>methodid</i></tt> on the object with node identifier <tt><i>nodeid</i></tt> on the client or server object <tt>handle</i></tt> with parameters described by pairs of <tt><i>type</i></tt> (data type, e.g. <tt>Int32</tt> or <tt>String</tt>) and value (the parameter's value). The method's result is returned. The method is carried out on the server, i.e. when directly used with a server handle there's no network traffic since the method is run locally. The <tt><i>type</i></tt> parameters should be prefixed with an asterisk or an exclamation mark in order to achieve the same semantic as in a method definition with <tt>opcua add SimpleMethod</tt>. Otherwise, array vs. scalar interpretion is automatically performed, i.e. when the corresponding <tt><i>value</i></tt> is a list, it is used as an array. For client objects, asynchronous operation is carried out when the last two parameters are <tt>-async</tt> and a (possibly empty) callback command <tt><i>cmd</i></tt>. In case of a non-empty callback the command returns an integer request identifier, which can be used to cancel the asynchronous operation. Otherwise the call is performed but the result is ignored. See section <b>Asynchronous Operations</b> for more information.
<tt>opcua cancel <i>handle reqid ...</i></tt>
Cancels one or more asynchronous requests on the client object <tt><i>handle</i></tt>. The requests to be cancelled are identified by their integer identifiers <tt><i>reqid</i></tt>. The associated callbacks are evaluated with a timeout status code.
<tt>opcua cert <i>handle cert pkey ?trust ...?</i></tt>
Loads the certificate <tt><i>cert</i></tt> and public key <tt><i>pkey</i></tt> into the client or server object <tt><i>handle</i></tt>. Both must be byte arrays. The optional parameters <tt><i>trust</i></tt> are zero or more byte arrays
with certicates which are added to the object's trust list. If the underlying open62541 library does not support encryption, this command fails with an appropriate error message. If it succeeds, it forces a server object to only allow encrypted sessions. Similarly, a client object tries to use a sign-and-encrypt endpoint of a server.
<tt>opcua children <i>handle nodeid</i></tt>
Returns the child node identifiers of the given node identifier <tt><i>nodeid</i></tt> on the client or server object <tt><i>handle</i></tt>.
<tt>opcua connect <i>handle url ?user password?</i></tt>
Connects the client object <tt><i>handle</i></tt> to the URL <tt><i>url</i></tt> using the optional credentials <tt><i>user</i></tt> and <tt><i>password</i></tt>.
<tt>opcua connect <i>handle url</i> -async</tt>
Connects the client object <tt><i>handle</i></tt> to the URL <tt><i>url</i></tt>. The operation is asynchronous, i.e. the connection establishment takes place in background. It can be observed with the optional <tt>onclientstate</tt> callback of the client object.
<tt>opcua const ?<i>name</i> ...?</tt>
Without optional parameters returns a list of names for which mappings to numerical values are known. If <tt><i>name</i></tt> is provided, the numerical value for the name is returned. When more than one <tt><i>name</i></tt> is given, a bitwise OR of the values for the names is returned. <tt><i>name</i></tt> can be optionally prefixed with <tt>UA_</tt>, i.e. <tt>ACCESSLEVELMASK_READ</tt> and <tt>UA_ACCESSLEVELMASK_READ</tt> are mapped to the same numerical value.
<tt>opcua datasources <i>handle</i></tt>
Returns information on data sources (variable nodes with callbacks) for the server object <tt><i>handle</i></tt>. For each data source two list elements with node identifier and callback command are added to the result.
<tt>opcua datetime ?seconds|...|utc <i>?value?</i>?</tt>
Returns either POSIX or OPC/UA timestamps as <b>Tcl_WideInt</b> values. If called without further parameters the current OPC/UA local <tt>DateTime</tt> is returned. If called with the single keyword <tt>utc</tt> the current OPC/UA <tt>UtcTime</tt> is returned. Otherwise, <tt><i>value</i></tt> is required and converted from POSIX to OPC/UA <tt>UtcTime</tt> for the keywords <tt>seconds</tt>, <tt>milliseconds</tt>, and <tt>microseconds</tt>, and from OPC/UA <tt>UtcTime</tt> to POSIX for the keywords <tt>unixseconds</tt>, <tt>unixmillis</tt>, and <tt>unixmicros</tt>, respectively.
<tt>opcua deftypes <i>handle nsuri defs</i></tt>
Defines custom datatypes (currently only structures) in the server object <tt><i>handle</i></tt> and namespace URI <tt><i>nsuri</i></tt>. The namespace is created with the <tt>opcua add Namespace</tt> command and must exist before the <tt>opcua deftypes</tt> command is called. The parameter <tt><i>defs</i></tt> describes the structures to be created. The command does all necessary steps to create the required nodes in the server object's address space and to store an XML bytestring describing the (de)serialization for the structures as extension objects. That XML is later to be reparsed with the <tt>opcua gentypes</tt> command. For details refer to section <b>Defining Custom Data Structures</b> below.
<tt>opcua delete <i>handle</i> Node <i>nodeid ?withrefs?</i></tt>
Deletes the node with identifier <tt><i>nodeid</i></tt> on the server object
<tt><i>handle</i></tt>. If <tt><i>withrefs</i></tt> is true, the references of the node are deleted, too.
<tt>opcua delete <i>handle</i> Reference <i>srcid reftypeid targetid ?forward? ?bidir?</i></tt>
Deletes the reference described by <tt><i>srcid</i></tt>, <tt><i>reftypeid</i></tt>, and <tt><i>targetid</i></tt> on the server object <tt><i>handle</i></tt>. The boolean flag <tt><i>forward</i></tt> selects forward or inverse direction of the reference to be deleted. The boolean flag <tt><i>bidir</i></tt> requests a bidirectional reference to be deleted. The default is to delete in forward direction only.
<tt>opcua destroy <i>handle</i></tt>
Destroys the client or server object <tt><i>handle</i></tt> and releases its resources, e.g. closes network connections, tears down the handle specific namespace, etc.
<tt>opcua dict_init <i>name body ...</i></tt>
Helper function to create and return a dictionary for the data type <tt><i>name</i></tt> which first is primed with <tt>opcua types empty...</tt> and finally modified by the Tcl code in <tt><i>body</i></tt> with the same rules as in the <tt>dict with</tt> command. The parameters following <tt><i>body</i></tt> are assigned to the list <tt><i>args</i></tt> as in a <tt>proc</tt>. In contrast to <tt>dict with</tt>, <tt><i>body</i></tt> is executed in a call frame of its own.
<tt>opcua disconnect <i>handle ?</i>-async<i>?</i></tt>
Disconnects the client object <tt><i>handle</i></tt>. If the optional parameter <tt>-async</tt> is specified, the operation is carried out in asynchronous mode.
<tt>opcua endpoints <i>?url?</i></tt>
Queries the local OPC/UA server <tt>opc.tcp://localhost:4840</tt> or the server specified by the <tt><i>url</i></tt> parameter for endpoints and returns a list of URLs describing the endpoints found.
<tt>opcua genstubs <i>handle ?strip stubsts ...?</i></tt>
Generates stubs for methods in the handle specific address space derived from the client or server object <tt><i>handle</i></tt>. The address space is traversed and browse paths and node class paths are accumulated. The resulting browse paths optionally get the prefix <tt><i>strip</i></tt> stripped off from the beginning and optionally filtered using the glob patterns following the <tt><i>strip</i></tt> parameter. If <tt><i>substs</i></tt> is not empty it
specifies pairwise regexps and substitutions which are applied on the browse
paths for the final procedure names. For all nodes matching the node class path pattern <tt>Object</tt>/<tt>Method</tt> the optional <tt>InputArguments</tt> and <tt>OutputArguments</tt> child nodes are retrieved and stub procedures are written using the browse path and argument information.
<tt>opcua gentypes <i>handle</i></tt>
Generates custom data type mappings using information obtained from analyzing the address space derived from the client or server object <tt><i>handle</i></tt>. This feature is highly experimental and requires the tDOM package for parsing XML. It can create encoders/decoders for simple structure data types defined in the address space which perform a mapping from/to Tcl dictionaries. For further information, see the <b>server_types.tcl</b> and <b>client_types.tcl</b> scripts in the examples directory. If this command is used, it should be invoked prior to creating method stubs, since methods may require custom data types in their arguments.
<tt>opcua info <i>?handle?</i></tt>
Returns the object type of <tt><i>handle</i></tt>, either <tt>client</tt> or <tt>server</tt>. If <tt><i>handle</i></tt> is omitted, a list of all known client and server object handles is returned.
<tt>opcua loader <i>handle xml ?evar rvar?</i></tt>
Imports a node set from an XML string <tt><i>xml</i></tt> into the server <tt><i>handle</i></tt>. The amount of imported information highly depends on the build options of the underlying open62541 library. Node descriptions which can't be supported are ignored and internally accumulated. For analysis, that information is made available by the <tt><i>evar</i></tt> and <tt><i>rvar</i></tt> result variables, which receive a list in <tt>array set</tt> form with each key being the node identifier and each value a dictionary with node information (for <tt><i>evar</i></tt>) including an error description, and reference information (for <tt><i>rvar</i></tt>). A result is returned which is a list in <tt>array set</tt> form with each key being the method's implementation proc name and each value a list of node identifiers which will invoke the respective implementation.
<tt>opcua log <i>?command?</i></tt>
Retrieves or sets the callback <tt><i>command</i></tt> for open62541 log messages. When a log message is issued, <tt><i>command</i></tt> is invoked with three parameters appended: the log level, e.g. <tt>info</tt>, <tt>warning</tt>, the category, e.g. <tt>network</tt>, <tt>client</tt>, and the text of the log message.
<tt>opcua mapstruct <i>handle ?nodeid destid member ...?</i></tt>
Adds variable nodes with an internal data source mapping to the members of the structure identified by <tt><i>nodeid</i></tt> in the server <tt><i>handle</i></tt>. It allows clients to read the structure element wise even when there's no client support for deserialization of the whole structure. Alternatively, if pairs of <tt><i>destid</i></tt> and <tt><i>member</i></tt> are provided, no additional variable nodes are created but the mapping is established between the variable identified by <tt><i>destid</i></tt> and the structure field <tt><i>member</i></tt> of structure <tt><i>nodeid</i></tt>. If <tt><i>nodeid</i></tt> and following parameters are left out, the current mappings are returned as a list where each three elements are made up of destination node identifier, structure node identifier, and structure member name. <b>Warning:</b> no logic is built in to prevent from creating multiple mappings, when variable nodes are to be added. Thus, the user should ensure in this case to call the <tt>mapstruct</tt> subcommand only once per <tt><i>nodeid</i></tt>. Since a node only supports a single data source, an error is raised when a node already has a callback installed from the <tt>add</tt> or <tt>datasources</tt> subcommand.
<tt>opcua methods <i>handle ?nodeid outtype cmd</i></tt>
Returns information on methods for the server object <tt><i>handle</i></tt>. Without optional parameters, for each known method three list elements with node identifier, result type information, and callback command are added to the result. With <tt><i>nodeid</i></tt> information for the specified node is returned. With <tt><i>outtype</i></tt> which must be a list of dicts of serialized <tt><i>Argument</i></tt> structs the method's mapping of result values is modified. With <tt><i>cmd</i></tt>, the Tcl callback is changed. If <tt><i>cmd</i></tt> is given as an empty list, that callback is deleted and the method node will report an error upon call from the OPC/UA side.
<tt>Bopcua monitor <i>handle</i> configure 0 <i>monid ?cmd?</i></tt>
Configures the monitor <tt><i>monid</i></tt> on the server object <tt><i>handle</i></tt> with the provided parameters, see <tt>opcua monitor new</tt> for further information.
<tt>opcua monitor <i>handle</i> configure <i>subid monid ?cmd mode interval?</i></tt>
Configures the monitor <tt><i>monid</i></tt> in subscription <tt><i>subid</i></tt> on the client object <tt><i>handle</i></tt> with the provided parameters, see <tt>opcua monitor new</tt> for further information.
<tt>opcua monitor <i>handle</i> destroy <i>subid monid</i></tt>
Destroys the monitor <tt><i>monid</i></tt> in subscription <tt><i>subid</i></tt> on the object <tt><i>handle</i></tt> and releases all its resources. If <tt><i>handle</i></tt> is a server object, <tt><i>subid</i></tt> must be specified as zero.
<tt>opcua monitor <i>handle</i> info <i>subid ?monid?</i></tt>
Returns information on monitor <tt><i>monid</i></tt> in subscription <tt><i>subid</i></tt> on the <tt><i>handle</i></tt>. If <tt><i>handle</i></tt> is a server object, <tt><i>subid</i></tt> must be specified as zero. The result is a list of monitor type (<tt>data</tt> or <tt>event</tt>) when <tt><i>handle</i></tt> refers to a client object (otherwise the list element is left out), the node identifier,
the callback command, the attribute, the monitor's mode (only for client handles), and the interval. If <tt><i>monid</i></tt> is omitted, a list of all monitor identifers registered in the subscription or in the server object is returned.
<tt>opcua monitor <i>handle</i> new 0 <i>cmd nodeid ?attr interval?</i></tt>
Creates a monitored item of the data value for the node identifier <tt><i>nodeid</i></tt> on the server object <tt><i>handle</i></tt>. The optional parameter <tt><i>attr</i></tt> selects the attribute of the node to be monitored (<tt>Value</tt> is the default). The monitoring interval <tt><i<>interval</i></tt> must be given as number of milliseconds. The callback command parameter <tt><i>cmd</i></tt> isdiscussed in section <b>Monitor Callbacks</b> below. The command returns a numeric identifier of the newly created monitor.
<tt>opcua monitor <i>handle</i> new <i>subid type cmd nodeid ?filter attr mode interval?</i></tt>
Creates a monitored item of <tt><i>type</i></tt> (<tt>data</tt> or <tt>event</tt>) for the node identifier <tt><i>nodeid</i></tt> in the subscription <tt><i>subid</i></tt> on the client object <tt><i>handle</i></tt>. The parameter <tt><i>filter</i></tt> must be specified for <tt><i>event</i></tt> monitors only and must be a list made up of type identifiers, qualified names, and attributes, e.g. <tt>{<i>BaseEventType</i> Message Value ...}</tt>, where <tt><i>BaseEventType</i></tt> must be given as node identifier by look up per <tt>opcua translate</tt>. The optional parameter <tt><i>attr</i></tt> selects the attribute of the node to be monitored (<tt>Value</tt> is the default for <tt>data</tt> monitors, <tt>EventNotifier</tt> for <tt>event</tt> monitors). The monitor mode <tt><i>mode</i></tt> must be one of <tt>Disabled</tt>, <tt>Sampling</tt>, and <tt>Reporting</tt>. The monitoring interval <tt><i>interval</i></tt> must be given as number of milliseconds, if omitted its value is derived from the subscription. The callback command parameter <tt><i>cmd</i></tt> is discussed in section <b>Monitor Callbacks</b> below. The command returns a numeric identifier of the newly created monitor.
<tt>opcua mread <i>handle cmd nodeid ...</i></tt>
Similar to <tt>opcua read</tt> this command carries out a multi read operation of value attributes on <tt><i>nodeid</i></tt> and following node identifiers. If <tt><i>cmd</i></tt> is given as empty string, the operation is synchronous and a list of value attributes is returned. For asynchronous operation see <tt>opcua call</tt> and section <b>Aynchronous Operations</b>.
<tt>opcua mreadx <i>handle cmd nodeid attr index ...</i></tt>
Similar to <tt>opcua mread</tt> this command carries out a multi read operation of attribute <tt><i>attr</i></tt> with <tt><i>index</i></tt> on <tt><i>nodeid</i></tt> and following parameters. Each single read is described by note identifier, attribute, and index. The <tt><i>index</i></tt> parameter must be an empty string or a valid OPC/UA index range. If <tt><i>cmd</i></tt> is given as empty string, the operation is synchronous and a list of attributes is returned. For asynchronous operation see <tt>opcua call</tt> and section <b>Aynchronous Operations</b>.
<tt>opcua mwrite <i>handle cmd nodeid type value ...</i></tt>
Similar to <tt>opcua write</tt> this command carries out a multi write operation of value attributes on <tt><i>nodeid</i></tt> and following node identifiers. Each single write is described by node identifier, data type, and value. If <tt><i>cmd</i></tt> is given as empty string, the operation is synchronous. For asynchronous operation see <tt>opcua call</tt> and section <b>Asynchronous Operations</b>. In contrast to the <tt>opcua write</tt> command this operation transfers all values with their source timestamp set to the current time.
<tt>opcua mwritex <i>handle cmd nodeid attr index type value ...</i></tt>
Similar to <tt>opcua mwrite</tt> this command carries out a multi write operation of attribute <tt><i>attr</i></tt> with <tt><i>index</i></tt> on <tt><i>nodeid</i></tt> given <tt><i>type</i></tt> and <tt><i>value</i></tt>. Each single write is described by note identifier, attribute, index, data type and value. The <tt><i>index</i></tt> parameter must be an empty string or a valid OPC/UA index range. If <tt><i>cmd</i></tt> is given as empty string, the operation is synchronous. For asynchronous operation see <tt>opcua call</tt> and section <b>Aynchronous Operations</b>. In contrast to the <tt>opcua write</tt> command this operation transfers all values with their source timestamp set to the current time.
<tt>opcua namespace <i>handle ?uri?</i></tt>
Returns the namespace index for the namespace <tt><i>uri</i></tt> of the client or server object <tt><i>handle</i></tt> (or throws an error e.g. when the namespace doesn't exist). If <tt><i>uri</i></tt> is omitted, a list of all known namespace indices and corresponding URIs is returned.
<tt>opcua new ?client? <i>?name?</i></tt><br>
<tt>opcua new server <i>port name</i></tt>
Creates a new client or server object and returns its handle. The <tt><i>port</i></tt> parameter must be present for server objects and specifies the server's TCP port. The optional <tt><i>name</i></tt> is the object name (the handle). If no parameters are given to <tt>opcua new</tt> a client object with an automatic name is created. During that process the Tcl namespace <tt>::opcua::<i>name</i></tt> is created which later is used to hold method stub procedures and other information. That namespace is tied to the life time of the client or server object. The initial access control list of a server object is empty.
<tt>opcua onclientstate <i>handle ?cmd?</i></tt>
Returns or sets the callback for client connection state changes for the client object <tt><i>handle</i></tt>. The parameter <tt><i>cmd</i></tt> is the Tcl callback to receive connection state information; it is invoked with three added parameters: 1. the connection state as numeric OPC/UA status code, 2. the secure channel state as a string, and 3. the session state as a string. Possible secure channel states are <tt>closed</tt>, <tt>hel_sent</tt>, <tt>hel_received</tt>, <tt>ack_sent</tt>, <tt>ack_received</tt>, <tt>opn_sent</tt>, <tt>open</tt>, and <tt>closing</tt>. Possible session states are <tt>closed</tt>, <tt>create_requested</tt>, <tt>created</tt>, <tt>activate_requested</tt>, <tt>activated</tt>, and <tt>closing</tt>.
<tt>opcua onfinalize <i>handle ?cmd?</i></tt>
Returns or sets the callback for node finalization events on the server object <tt><i>handle</i></tt>. The parameter <tt><i>cmd</i></tt> is the Tcl callback to handle the finalization event; it is invoked when a node in the server's address space is deleted with one additional parameter which is the node identifier of the node being deleted. <tt><i>cmd</i></tt> must have proper list format. If specified as an empty list, no callback on node finalization is carried out.
<tt>opcua oninitialize <i>handle ?cmd?</i></tt>
Returns or sets the callback for node initialization events on the server object <tt><i>handle</i></tt>. The parameter <tt><i>cmd</i></tt> is the Tcl callback to handle the initialization event; it is invoked when a new node is added in
the server's address space with two additional parameter which are the node identifier of the new node and its node class. <tt><i>Cmd</i></tt> must have proper list format. If specified as an empty list, no callback on node initialization is carried out.
<tt>opcua parent <i>handle nodeid</i></tt>
Returns the parent node identifier of the given node identifier <tt><i>nodeid</i></tt> on the client or server object <tt><i>handle</i></tt>.
<tt>opcua ptree <i>handle ?nodeid?</i></tt>
Returns information similar to <tt>opcua tree</tt> using the client or server object <tt><i>handle</i></tt>. The address space is traversed starting at the node identifier <tt><i>nodeid</i></tt> (the root node if omitted). The result list is made up of browse path name, node identifier, node class path, reference node identier, type node identifier, and parent node identifier. The browse path name is a path name like notation made up of the browse names pointing to the final node as seen from the starting node. Browse names are written as qualified names, i.e. including the numeric namespace index if not in root namespace. Similarly, the node class path is a path name like notation made up of the node classes of all nodes along the path. The <tt>opcua ptree</tt> command is used internally by the <tt>opcua genstubs</tt> command in order to filter out objects and methods when creating stub Tcl commands to invoke methods on objects.
<tt>Bopcua pubsub <i>handle</i> AddConnection <i>config</i></tt>
Adds a new <tt>PubSubConnection</tt> with the parameters from <tt><i>config</i></tt>, which must be a dictionary of type <tt>PubSubConnectionDataType</tt>. The operation is carried out on the server given the client or server object <tt><i>handle<i></tt>. The node identifier of the new <tt>PubSubConnection</tt> is returned.
<tt>opcua pubsub <i>handle</i> AddDataSetFolder <i>name</i></tt>
Adds a new <tt>DataSetFolder</tt> object with name <tt><i>name</i></tt> in the server given the client or server object <tt><i>handle</i></tt>. The operation is carried out on the server given the client or
server object <tt><i>handle</i></tt>. The node identifier of the new <tt>DataSetFolder</tt> is returned.
<tt>opcua pubsub <i>handle</i> AddDataSetReader <i>groupId readerData</i></tt>
Adds a new <tt>DataSetReader</tt> object with information from <tt><i>readerData</i></tt> which must be a dictionary of type <tt>DataSetReaderDataType</tt> on the <tt>ReaderGroup</tt> with node identifier <tt><i>groupId</i></tt>. The operation is carried out on the server given the client or server object <tt><i>handle</i></tt>. The node identifier of the new <tt>DataSetReader</tt> is returned.
<tt>opcua pubsub <i>handle</i> AddDataSetWriter <i>groupId writerData</i></tt>
Adds a new <tt>DataSetWriter</tt> object with information from <tt><i>writerData</i></tt> which must be a dictionary of type <tt>DataSetWriterDataType</tt> on the <tt>WriterGroup</tt> with node identifier <tt><i>groupId</i></tt>. The operation is carried out on the server given the client or server object <tt><i>handle</i></tt>. The node identifier of the new <tt>DataSetWriter</tt> is returned.
<tt>opcua pubsub <i>handle</i> AddPublishedDataItems <i>name aliases flags vars</i></tt>
Adds a new <tt>PublishedDataSet</tt> with name <tt><i>name</i></tt> and the information contained in the three parameters <tt><i>aliases</i></tt> (list of <tt>String</tt> type), <tt><i>flags</i></tt> (list of <tt>UInt16</tt> type), and <tt><i>vars</i></tt> (list of <tt>PublishedVariableDataType</tt>). The three lists must have the same number of elements. The operation is carried out on the server given the client or server object <tt><i>handle</i></tt>. The node identifier of the new <tt>PublishedDataSet</tt> is returned.
<tt>opcua pubsub </i>handle</i> AddReaderGroup <i>connId readerGroupData</i></tt>
Adds a new <tt>ReaderGroup</tt> object with information from <tt><i>readerGroupData</i></tt> which must be a dictionary of type <tt>ReaderGroupDataType</tt> on the <tt>PubSubConnection</tt> with node identifier <tt><i>connId</i></tt>. The operation is carried out on the server given the client or server object <tt><i>handle</i></tt>. The node identifier of the new <tt>ReaderGroup</tt> is returned.
<tt>opcua pubsub <i>handle</i> AddWriterGroup <i>connId writerGroupData</i></tt>
Adds a new <tt>WriterGroup</tt> object with information from <tt><i>writerGroupData</i></tt> which must be a dictionary of type <tt>WriterGroupDataType</tt> on the <tt>PubSubConnection</tt> with node identifier <tt><i>connId</i></tt>. The operation is carried out on the server given the client or server object <tt><i>handle</i></tt>. The node identifier of the new <tt>WriterGroup</tt> is returned.
<tt>opcua pubsub <i>handle</i> DeletePubSubConfiguration</tt>
Removes all currently configured PubSub components (<tt>PubSubConnections</tt>, <tt>ReaderGroups</tt>, <tt>WriterGroups</tt>, <tt>PublishedDataSets</tt>, <tt>DataSetReaders</tt>, and <tt>DataSetWriters</tt>) in the server given the client or server object <tt><i>handle</i></tt>.
<tt>opcua pubsub <i>handle</i> LoadPubSubConfigurationFile <i>bytes</i></tt>
This subcommand is identical to <tt>opcua pubsubcfg load</tt> but can be invoked from a client object <tt><i>handle</i></tt>, too.
<tt>opcua pubsub <i>handle</i> RemoveConnection <i>connId</i></tt>
Removes the <tt>PubSubConnection</tt> with node identifier <tt><i>connId</i></tt>. The operation is carried out on the server given the client or server object <tt><i>handle</i></tt>.
<tt>opcua pubsub <i>handle</i> RemoveDataSetFolder <i>folderId</i></tt>
Removes the <tt>DataSetFolder</tt> object with node identifier <tt><i>folderId</i></tt> and all contained <tt>PublishedDataSets</tt>. The operation is carried out on the server given the client or server object <tt><i>handle</i></tt>.
<tt>opcua pubsub <i>handle</i> RemoveDataSetReader <i>groupId readerId</i></tt>
Removes the <tt>DataSetReader</tt> with node identifier <tt><i>readerId</i></tt> on the <tt>ReaderGroup</tt> with node identifier <tt><i>groupId</i></tt>. The operation is carried out on the server given the client or server object <tt><i>handle</i></tt>.
<tt>opcua pubsub <i>handle</i> RemoveDataSetWriter <i>groupId writerId</i></tt>
Removes the <tt>DataSetWriter</tt> with node identifier <tt><i>writerId</i></tt> on the <tt>WriterGroup</tt> with node identifier <tt><i>groupId</i></tt>. The operation is carried out on the server given the client or server object <tt><i>handle</i></tt>.
<tt>opcua pubsub <i>handle</i> RemoveGroup <i>connId groupId</i></tt>
Removes the <tt>ReaderGroup</tt> or <tt>WriterGroup</tt> with node identifier <tt><i>groupId</i></tt> on the <tt>PubSubConnection</tt> with node identifier <tt><i>connId</i></tt>. The operation is carried out on the server given the client or server object <tt><i>handle</i></tt>.
<tt>opcua pubsub <i>handle</i> RemovePublishedDataSet <i>pdsId</i></tt>
Removes the <tt>PublishedDataSet</tt> object with node identifier <tt><i>pdsId</i></tt>. The operation is carried out on the server given the client or server object <tt><i>handle</i></tt>.
<tt>opcua pubsubcfg <i>handle</i> load|save <i>?bytes</i>?</i></tt>
Performs a serialization (<tt>save</tt>) or deserialization (<tt>load</tt>) of the PubSub configuration of the server object <tt><i>handle</i></tt>. For the <tt>load</tt> operation, <tt><i>bytes</i></tt> must contain a byte array of the serialization, for <tt>save</tt> a serialization is returned as result. The deserialization operation reconstructs the PubSub components in the server described by <tt><i>bytes</i></tt>.
<tt>opcua read <i>handle nodeid ?attr cmd?</i></tt>
Performs a read operation on the client or server object <tt><i>handle</i></tt> and returns the value of attribute <tt><i>attr</i></tt> of the node identifier <tt><i>nodeid</i></tt>. If <tt><i>attr</i></tt> is omitted, it defaults to the <tt>Value</tt> attribute. The optional parameter <tt><i>cmd</i></tt> can be specified on client objects in order to carry out the read operation in asynchronous mode. See <tt>opcua call</tt> and section <b>Asynchronous Operations</b> for more information.
<tt>opcua reftype <i>?name?</i></tt>
Returns the node identifier for the reference type <tt><i>name</i></tt>. When <tt><i>name</i></tt> is omitted, a list of all reference type names is returned.
<tt>opcua register <i>handle nodelist</i></tt>
Registers the node identifiers from <tt><i>nodelist</i></tt> in the server to which <tt><i>handle</i></tt> is connected. If the operation succeeds, another list of node identifiers is returned which provides aliases to the node identifiers passed to the command during the life time of the session. Using the aliases instead of the original node identifiers can improve performance of subsequent <tt>read</tt> and <tt>write</tt> operations.
<tt>opcua request <i>handle ?reqid?</i></tt>
Returns information on pending asynchronous operations of the client object <tt><i>handle</i></tt>. If a numeric request identifier <tt><i>reqid</i></tt> is given, a two element list for this request is returned made up of the operation type (<tt>call</tt>, <tt>read</tt>, or <tt>write</tt>) and the callback command which receives the response. If <tt><i>reqid</i></tt> is omitted, a list of all known pending request identifiers is returned.
<tt>opcua root</tt>
Returns the node identifier of the root node.
<tt>opcua run <i>handle ?ms?</i></tt>
Runs asynchronous operations (subscriptions, monitored items) on the client object <tt><i>handle</i></tt> for <tt><i>ms</i></tt> milliseconds. If <tt><i>ms</i></tt> is omitted, that duration defaults to zero. Normally, this operation is carried out by the Tcl event loop. Still, this command can be used to test if the client object is in the connected state.
<tt>opcua sc2str <i>?</i>-short<i>? code</i></tt>
Translates the numeric status code <tt><i>code</i></tt> to an error message string. A single word error string such as <tt>BadTimeout</tt> is produced when the <tt>-short</tt> option is specified.
<tt>opcua servers <i>?url?</i></tt>
Queries the local OPC/UA server <tt>opc.tcp://localhost:4840</tt> or the server specified by the <tt><i>url</i></tt> parameter for server information and returns a list made up of deserialized dictionaries based on the <tt>UA_ServerOnNetwork</tt> structure. Consult the open62541 documention for more information.
<tt>opcua start <i>handle</i></tt>
Starts the server object <tt><i>handle</i></tt>. See section <b>Server Object And Event Loop</b> below for further information.
<tt>opcua state <i>handle</i></tt>
Reports the current state of <tt><i>handle</i></tt>. If <tt><i>handle</i></tt> refers to a client, the result is a three element list with the identical information as passed in the additional parameters to the <tt>onclientstate</tt> callback. Otherwise, the result is a two element list. The first element is either <tt>stopped</tt> or <tt>running</tt> indicating the server state. The second element is a dictionary with statistic counters for connections, secure channels, and sessions.
<tt>opcua stop <i>handle</i></tt>
Stops the server object <tt><i>handle</i></tt>.
<tt>opcua subscription <i>handle</i> configure <i>id ?interval lifetime keepalive max prio?</i></tt>
Configures the subscription <tt><i>id</i></tt> on the client object <tt><i>handle</i></tt>. See <tt>opcua subscription new</tt> for the optional parameters.
<tt>opcua subscription <i>handle</i> destroy <i>id</i></tt>
Destroys the subscription <tt><i>id</i></tt> on the client object <tt><i>handle</i></tt>.
<tt>opcua subscription <i>handle</i> info <i>?id?</i></tt>
Returns information about subscription <tt><i>id</i></tt> on the client object <tt><i>handle</i></tt> as a list of enable flag, interval, lifetime, keepalive, and maximum counters, and the priority value. If <tt><i>id</i></tt> is omitted, a list of all subscription identifiers of the client object is returned.
<tt>opcua subscription <i>handle</i> new <i>?flag interval lifetime keepalive max prio?</i></tt>
Creates a new subscription (a container for monitored items, see <tt>opcua monitor</tt>) on the client object <tt><i>handle</i></tt> and returns a numeric identifier of it. The following optional parameters control properties of the subscription: <tt><i>flag</i></tt> is the initial enable state (on by default), <tt><i>interval</i></tt>, <tt><i>lifetime</i></tt>, <tt><i>keepalive</i></tt>, and <tt><i>max</i></tt> the timing and queuing parameters, and <tt><i>prio</i></tt> the subscription's priority.
<tt>opcua subscription <i>handle</i> off <i>id</i></tt>
Disables the subscription <tt><i>id</i></tt> on the client object <tt><i>handle</i></tt>.
<tt>opcua subscription <i>handle</i> on <i>id</i></tt>
Enables the subscription <tt><i>id</i></tt> on the client object <tt><i>handle</i></tt>.
<tt>opcua translate <i>handle nodeid reftype target ...</i></tt>
Performs a translate operation on the client or server object <tt><i>handle</i></tt>. The operation starts at node identifier <tt><i>nodeid</i></tt> and traverses the object tree along the references <tt><i>reftype</i></tt> and browse name <tt><i>target</i></tt>. A list made up of the node identifier, namespace URI, and server index of the final target is returned as the result. References can be preceeded with an exclamation mark in order to reverse their direction. A reference may be abbreviated as slash for <tt>HierarchicalReferences</tt> or as dot for <tt>Aggregates</tt>.
<tt>opcua tree <i>handle ?nodeid?</i></tt>
Returns information similar to <tt>opcua browse</tt> using the client or server object <tt><i>handle</i></tt>. The address space is traversed starting at the node identifier <tt><i>nodeid</i></tt> (the root node if omitted). The result list is made up of tree level (0-based), node identifier, browse name (qualified name), display name (locale and text), node class, reference node identifier, type node identifier, and parent node identifier.
<tt>opcua type <i>handle nodeid ?attr?</i></tt>
Performs a read operation on the client or server object <tt><i>handle</i></tt> like <tt>opcua read</tt> but instead of the attribute's value returns the type name of attribute <tt><i>attr</i></tt> of the node identifier <tt><i>nodeid</i></tt>. If <tt><i>attr</i></tt> is omitted, it defaults to the <tt>Value</tt> attribute.
<tt>opcua types basic|builtin|empty|list|name|nodeid <i>?handle name?</i></tt>
Returns a list of OPC/UA type names for the <tt>basic</tt> and <tt>list</tt> subcommands. Basic types are primitives (e.g. integer numbers) for which a mapping to Tcl objects is provided. The <tt><i>empty</i></tt> subcommand requires <tt><i>name</i></tt> to be a known OPC/UA type name and produces and returns an empty value of this type, e.g. 0.0 for a floating point type. The <tt><i>nodeid</i></tt> subcommand returns the node identifier for the type name. The <tt>name</tt> subcommand is the reverse operation of the <tt>nodeid</tt> subcommand and reports the type name for node identifier in <tt><i>nodeid</i></tt>. For the command forms where a <tt><i>handle</i></tt> can be specified, this allows to deal with additional custom data types (see e.g. <tt>opcua deftypes</tt>) which where loaded into the client or server object <tt><i>handle</i></tt>. The <tt>builtin</tt> subcommand returns the numeric value of the data type <tt><i>name</i></tt> for primitive types of namespace zero.
<tt>opcua unregister <i>handle nodelist</i></tt>
Unregisters the node identifiers from <tt><i>nodelist</i></tt> in the server to which <tt><i>handle</i></tt> is connected. This is the reverse of the <tt>register</tt> subcommand which removes the aliases to the node identifiers in <tt><i>nodelist</i></tt>.
<tt>opcua version</tt>
Returns the major and minor version numbers of the integrated open62541 library, e.g. "1.0".
<tt>opcua write <i>handle nodeid ?attr? type value ?cmd?</i></tt>
Performs a write operation on the client or server object <tt><i>handle</i></tt> writing <tt><i>value</i></tt> with type <tt><i>type</i></tt> into the attribute <tt><i>attr</i></tt> of the node identifier <tt><i>nodeid</i></tt>. If <tt><i>attr</i></tt> is omitted, it defaults to <tt>Value</tt>. The operation is performed without setting an explicit source timestamp. The optional parameter <tt><i>cmd</i></tt> can be specified on client objects in order to carry out the write operation in asynchronous mode. See <tt>opcua call</tt> and section <b>Asynchronous Operations</b> for more information.
<tt>opcua xcall <i>handle nodeid methodid ?type value ...?</i></tt>
This is the coroutine aware version of <tt>opcua call</tt>. If called with a client <tt><i>handle</i></tt> in a coroutine context it uses an asynchronous call operation with <tt>yield</tt> as callback, i.e. automatically suspends the coroutine and resumes it again when the result becomes available.
<tt>opcua xgenstubs <i>handle ?strip substs ...?</i></tt>
This is the coroutine aware version of <tt>opcua genstubs</tt>. Instead of procedure bodies using <tt>opcua call</tt> it writes coroutine aware procedure bodies using <tt>opcua xcall</tt>.
<tt>opcua xmread <i>handle nodeid ...</i></tt>
This is the coroutine aware version of <tt>opcua mread</tt>. If called with a client <tt><i>handle</i></tt> in a coroutine context it uses an asynchronous read operation with <tt>yield</tt> as callback, i.e. automatically suspends the coroutine and resumes it again when the result becomes available.
<tt>opcua xmreadx <i>handle nodeid attr index ...</i></tt>
This is the coroutine aware version of <tt>opcua mreadx</tt>. If called with a client <tt><i>handle</i></tt> in a coroutine context it uses an asynchronous read operation with <tt>yield</tt> as callback, i.e. automatically suspends the coroutine and resumes it again when the result becomes available.
<tt>opcua xmwrite <i>handle nodeid type value ...</i></tt>
This is the coroutine aware version of <tt>opcua mwrite</tt>. If called with a client <tt><i>handle</i></tt> in a coroutine context it uses an asynchronous write operation with <tt>yield</tt> as callback, i.e. automatically suspends the coroutine and resumes it again when the result becomes available.
<tt>opcua xmwritex <i>handle nodeid attr index type value ...</i></tt>
This is the coroutine aware version of <tt>opcua mwritex</tt>. If called with a client <tt><i>handle</i></tt> in a coroutine context it uses an asynchronous write operation with <tt>yield</tt> as callback, i.e. automatically suspends the coroutine and resumes it again when the result becomes available.
<tt>opcua xread <i>handle nodeid ?attr?</i></tt>
This is the coroutine aware version of <tt>opcua read</tt>. If called with a client <tt><i>handle</i></tt> in a coroutine context it uses an asynchronous read operation with <tt>yield</tt> as callback, i.e. automatically suspends the coroutine and resumes it again when the result becomes available.
<tt>opcua xsleep <i>ms</i></tt>
This is a coroutine aware convenience function which delays execution for <tt><i>ms</i></tt> milliseconds by using the <tt>after</tt> command with a callback in order to service events, if invoked in a coroutine context.
<tt>opcua xwrite <i>handle nodeid ?attr? type value</i></tt>
This is the coroutine aware version of <tt>opcua write</tt>. If called with a client <tt><i>handle</i></tt> in a coroutine context it uses an asynchronous write operation with <tt>yield</tt> as callback, i.e. automatically suspends the coroutine and resumes it again when the result becomes available.
<h3>OPC/UA Ensemble</h3>
The current implementation uses an ensemble and namespace <tt>opcua</tt>, i.e.
the command <tt>opcua info</tt> can be alternatively written as <tt>opcua::info</tt>. Some more complex subcommands of the <tt>opcua</tt> namespace are implemented in Tcl, namely the <tt>opcua tree</tt> and <tt>opcua genstubs</tt> procedures.
<h3>Node Identifiers</h3>
Numeric node identifiers can be written as <tt>ns=N;i=I</tt> where <tt>N</tt> is the numeric namespace, and <tt>I</tt> the numeric identifier. Likewise, string node identifiers are written as <tt>ns=N;s=S</tt> with <tt>S</tt> being the string identifier. GUID node identifiers are written as <tt>ns=N;g=G</tt> where the GUID is <tt>G</tt> with the usual format as sequence of hexadecimal numbers and dashes. The namespace part can be left out when namespace zero is addressed. Currently, byte string node identifiers are not supported. If the format cannot be determined (e.g. since the equal sign is missing) the fallback chosen is string node identifier in namespace zero. String named namespaces are not supported.
<h3>Qualified Names</h3>
Qualified names are used for example in the <tt>opcua browse</tt> and <tt>opcua translate</tt> operations as so called browse names. These are made up of an optional numeric namespace prefix (a number followed by a colon) and a name, e.g. <tt><i>2:MyObject</i></tt>. The namespace prefix is left out if the name refers to namespace zero.
<h3>Localized Text</h3>
The data type <tt>LocalizedText</tt> is represented as a dict with the keys <tt>locale</tt> and <tt>text</tt>. When converting a Tcl value to a <tt>LocalizedText</tt> item, these keys are tried to be associated. If this operation fails, the Tcl value is used as the <tt>text</tt> part of the <tt>LocalizedText</tt> item and the <tt>locale</tt> part is left empty.
<h3>Supported Data Types</h3>
Currently, most of the data types of namespace zero are supported and can be mapped to/from Tcl, i.e. integral and floating point numbers, strings, GUIDs, and interal extension objects (similar to structures). For the latter, dictionaries are used in both directions, i.e. for encoding, a dictionary is searched for the respective member names, for decoding, a dictionary is created from the internal representation using the member names of the data type, see <tt>opcua attrs default</tt> for example. Support for custom data types is highly experimental and underdocumented (see <tt>opcua gentypes</tt>).
<h3>Monitor Callbacks</h3>
Monitor callbacks are invoked when a monitored item (data or event) is received. The callback parameter given in <tt>opcua monitor new</tt> must have proper list format and gets a single value (data) or a list of values (event) appended prior to invocation.
<h3>Data Source Callbacks</h3>
Data source callbacks are invoked when a <tt><i>DataValue</i></tt> is read or written to. The callback parameter given in the node creation (<tt>opcua add Variable</tt>) must have proper list format and gets the following parameters appended prior to invocation: the node identifier of the <tt>DataValue</tt>, the operation (either <tt>read</tt> or <tt>write</tt>), and the value attribute for write operations. If the read or write operation specifies a numeric range, the range description is added as the last parameter. It is expressed as a Tcl list with even number of integer elements. Each pair describes the start and end elements of a dimension. For read operations the callback must return a two element list of the data type (e.g. <tt>String</tt> or <tt>Int32</tt>) and the value itself. If the callback returns the <b>TCL_BREAK</b> return code, the value is assumed to be an array and splitted into list elements which then are converted to OPC/UA data in an OPC/UA array.
<h3>Method Callbacks</h3>
Method callbacks are invoked when a <tt><i>Method</i></tt> node is called. The callback parameter given in the node creation (<tt>opcua add Method</tt>) must have proper list format and gets the following parameters appended prior to invocation: the object node identifier, the method node identifier, and a list of type names derived from the method's output arguments. This list may be used in the method's implementation to form the result. The callback must return a single value which must be a list with the same number of items of the output argument's
type list. Each item gets converted to the respective OPC/UA data value according to the output argument information of the <tt>Method</tt> node. I.e. for simple types, a list item may be a single integer e.g. for a single <tt>UInt16</tt>, a list of integers for an array of <tt>UInt16</tt>'s, a single dict for a structure type, or a list of dicts for an array of structured types.
<h3>Client Object And Event Loop</h3>
A client object obtained with <tt>opcua new client</tt> requires a running
event loop only when subscriptions/monitored items are involved. Most
other operations are performed synchronously (and thus blocking).
<h3>Asynchronous Operations</h3>
Asynchronous mode of operation is supported for client objects and their <tt>opcua call</tt>, <tt>opcua read</tt>, and <tt>opcua write</tt> subcommands. The callback parameter must have proper list format and gets a single value appended prior to invocation which carries the deserialized response message corresponding to the operation. It is made up as a nested <tt>dict</tt> which contains a <tt>ResponseHeader</tt> with the status code of the operation and depending on the operation the method call result(s) or the value of the attribute read plus additional diagnostic information. That <tt>dict</tt> gets an extra key named <tt>RequestId</tt> appended which is the integer request identifier of the operation which was returned by the command initiating the request. If the callback parameter is specified as empty list, the response is discarded, i.e. no Tcl code is evaluated and the operation appears as a one way request.
<h3>Client Example</h3>
<verbatim>
package require topcua
# create client
opcua new client C
# connect to server
opcua connect C opc.tcp://localhost:4840 user pass
# get MyNamespace
set ns [opcua namespace C MyNamespace]
# generate stub procs to methods in server
# these are created in the client specific ::opcua::C namespace
opcua genstubs C /Root/Objects/${ns}:MyObject/${ns}:
# list all procs in client specific namespace
puts stderr [info procs ::opcua::C::*]
# call stubs
puts stderr [::opcua::C::Reverse esreveR]
puts stderr [::opcua::C::WordSplit "word\n\nsplit"]
# read a variable
puts stderr [opcua read C "ns=${ns};ItsTclTime"]
# monitor callback proc
proc monitor {data} {
puts stderr "Monitor: $data"
}
# make a subscription
set sub [opcua subscription C new 1 1000.0]
# make a monitor
set mon [opcua monitor C new $sub data monitor "ns=${ns};ItsTclTime"]
puts stderr "Subscription: $sub"
puts stderr "Monitor: $mon"
# handle monitors for a few seconds
set done 0
after 10000 {set done 1}
vwait done
# delete monitor and subscription
opcua monitor C destroy $sub $mon
opcua subscription C destroy $sub
# shut down the server using a method call
::opcua::C::Exit
# destroy the client
opcua destroy C
</verbatim>
<h3>Server Object And Event Loop</h3>
A server object obtained with <tt>opcua new server</tt> requires a running event loop as long as it is in running state (started with <tt>opcua start</tt>). Depending on the support of the underlying open62541 library, the opcua server's network handler re-dispatches itself using a Tcl timer callback whose interval is controlled by the protocol timers of the OPC/UA stack implementation, or it spins up a dedicated thread which deals with the network traffic. In the latter case, a running event loop is required, too, for processing method and datasource callbacks.
<h3>Server Example</h3>
<verbatim>
package require topcua
# create server
opcua new server 4840 S
# setup access control
opcua acl S user pass
# implementations of methods etc.
namespace eval ::opcua::S {
# method callback
proc _reverse {obj meth string} {
return [string reverse $string]
}
# method callback
proc _wordsplit {obj meth string} {
set w [regexp -all -inline {\S+} $string]
# return code break makes into an array result
return -code break $w
}
# method callback
proc _exit {obj meth} {
after 1000 [namespace current]::_real_exit
return {}
}
# helper proc
proc _real_exit {} {
catch {
::opcua::stop S
::opcua::destroy S
}
exit 0
}
# data source callback
proc _its_tcl_time {node op {value {}}} {
if {$op eq "read"} {
return [list String [clock format [clock seconds]]]
}
return {}
}
}
# create our OPC/UA namespace
set ns [opcua add S Namespace MyNamespace]
# get Objects folder
set OF [lindex [opcua translate S [opcua root] / Objects] 0]
# create an object in our namespace in Objects folder
set obj [opcua add S Object "ns=$ns;s=MyObject" $OF Organizes \
"$ns:MyObject"]
# create methods on object
set meth [opcua add S Method "ns=$ns;s=Reverse" \
$obj HasComponent \
{String !out} "$ns:Reverse" {String !in} \
::opcua::S::_reverse]
set meth [opcua add S Method "ns=$ns;s=WordSplit" \
$obj HasComponent \
{String !out} "$ns:WordSplit" {String !in} \
::opcua::S::_wordsplit]
set meth [opcua add S Method "ns=$ns;s=Exit" \
$obj HasComponent \
{} "$ns:Exit" {} \
::opcua::S::_exit]
# create a variable in our namespace in Objects folder
set var [opcua add S Variable "ns=$ns;s=ItsTclTime" \
$OF Organizes \
"$ns:ItsTclTime" {} {} \
::opcua::S::_its_tcl_time]
# dump methods
puts stderr [opcua methods S]
# generate stubs to methods in server
# these are created in the server specific ::opcua::S namespace
opcua genstubs S /Root/Objects/${ns}:MyObject/${ns}:
# list all procs in server specific namespace
puts stderr [info procs ::opcua::S::*]
# call stubs directly on server
puts stderr [::opcua::S::Reverse esreveR]
puts stderr [::opcua::S::WordSplit "word\n\nsplit"]
# read our variable
puts stderr [opcua read S $var]
# start server
opcua start S
# enter event loop
vwait forever
</verbatim>
<h3>Defining Custom Data Structures</h3>
<verbatim>
package require topcua
# create server
opcua new server 4840 S
# create our namespace
set NS http://www.androwish.org/TestNS/
set nsidx [opcua add S Namespace $NS]
# create structs etc., field names prefixed with '*' are arrays
# CAUTION: no comments allowed in the definition list
opcua deftypes S $NS {
struct KVPair {
String name
String value
}
struct RGB {
UInt16 red
UInt16 green
UInt16 blue
}
struct NamedColor {
String name
RGB color
}
struct WithArray {
String name
String *values
}
enum SimpleEnum { Red Green Blue }
}
# import type defs
opcua gentypes S
# make some variables using the structs from above
set OF [lindex [opcua translate S [opcua root] / Objects] 0]
foreach {name type} {
X1 KVPair
X2 RGB
X3 NamedColor
X4 WithArray
} {
set att [opcua attrs default VariableAttributes]
dict set att dataType [opcua types nodeid S $type]
dict set att value [list $type [opcua types empty S $type]]
opcua add S Variable "ns=${nsidx};s=$name" $OF Organizes \
"${nsidx}:$name" {} $att
}
opcua write S "${nsidx}:X4" Value WithArray {
name {A B C D E}
values {A B C D E}
}
# start server
opcua start S
# enter event loop
vwait forever
</verbatim>
Z 55628ee03dfd2279958a646ae9dcca7f