This topic shows the basic steps to create an OPC Unified Architecture (UA) application by retrieving current and historical data from the OPC Foundation Quickstart Historical Access Server.
To run the sample code in the following steps you need the OPC Foundation Quickstart Historical Access Server running on your local machine. For installation details, see Install an OPC UA Simulation Server for OPC UA Examples. The code requires only minor changes to work with other servers.
In this step, you obtain information that the toolbox needs to uniquely identify the OPC UA server that you want to connect to. You use this information when creating an OPC UA client object, described in Step 2: Create an OPC UA Client Object.
The first piece of information is the host name of the server computer. The host name (a descriptive name like "HistorianServer" or an IP address such as 192.168.16.32) qualifies that computer on the network, and is used by the OPC protocols to determine the available OPC servers on that computer. In any OPC Toolbox™ application, you must know the name of the OPC server's host, so that a connection with that host can be established. Your network administrator can provide a list of host names that provide OPC servers on your network. In this example, you will use localhost as the host name, because you will connect to the OPC server on the same machine as the client.
OPC UA servers are uniquely identified by Universal Resource Locations. Similar to
web addresses, a URL for an OPC UA server starts with
and then provides an address of the server as a hostname, port, and address in
standard ASCII text. For example, the URL for the OPC Foundation Quickstart
Historical Access Server is
OPC UA Server URLs are advertised through an OPC UA Discovery Service, available on every OPC UA server host machine. Your system administrator can provide a list of server URLs for a particular host, or you can query the host for all available OPC UA servers.
opcuaserverinfo function to query hosts
from the command line.
serverList = opcuaserverinfo('localhost')
serverList = 1x2 OPC UA ServerInfo array: index Description Hostname Port ----- ----------------------------------- -------- ----- 1 Quickstart Historical Access Server ons-dean 62550 2 UA Sample Server ons-dean 51210
Locate the server of interest by using the
findDescription function to search for a specific character vector.
In this example you connect to the Historical Access Server.
hsInfo = findDescription(serverList, 'Historical')
hsInfo = OPC UA ServerInfo 'Quickstart Historical Access Server': Connection Information Hostname: 'ons-dean' Port: 62550
From this discovery process, you can identify the port (62550) on which the OPC UA server listens for connections.
After locating your OPC UA server, you create an OPC UA Client to manage the connection to the server, obtain key server characteristics, and read and write data from the server. You can use the OPC UA ServerInfo result to construct an OPC UA client directly. (You could also create a client using the hostname and port provided by the OPC UA ServerInfo properties.)
uaClient = opcua(hsInfo)
uaClient = OPC UA Client Quickstart Historical Access Server: Hostname: ons-dean Port: 62550 Timeout: 10 Status: Disconnected
The client is initially disconnected from the server, as shown by the Status property. After you connect to the server, additional properties are shown in the client display.
uaClient uaClient = OPC UA Client Quickstart Historical Access Server: Hostname: ons-dean Port: 62550 Timeout: 10 Status: Connected ServerState: Running MinSampleRate: 0 secs MaxHistoryReadNodes: 0 MaxHistoryValuesPerNode: 0 MaxReadNodes: 0 MaxWriteNodes: 0
The additional properties describe capabilities of the server, notably limits for various read and write operations. A limit value of 0 means the server does not impose a direct limit on that capability.
OPC UA servers provide a single namespace for you to read and write both current data and historical data. The namespace is organized as a hierarchy of nodes. Each node has attributes which describe that node. A node is uniquely identified by two elements: A namespace index (numeric integer) and a node identifier (numeric integer, character vector, or Globally Unique Identifier or GUID). To uniquely describe a node, you have to provide both the namespaceindex and the identifier; you cannot provide only the identifier because that might be repeated for different namespace indexes.
Toolbox exposes the hierarchy of nodes through the namespace property of the
OPC UA client. Each element of the namespace property is a node at the top-most
level of the server. Every node in the namespace has a
property which exposes the subnodes contained in that node. You can browse the
namespace graphically using the
browseNamespace function. The resulting dialog
box allows you to select nodes from the hierarchy and return them in the output from
serverNodes = browseNamespace(uaClient)
When you click OK, the selected items are returned in the output.
serverNodes = 1x2 OPC UA Node array: index Name NsInd Identifier NodeType Children ----- ---------------------- ----- ---------- -------- -------- 1 MinSupportedSampleRate 0 2272 Variable 0 2 MaxArrayLength 0 11702 Variable 0
Nodes can have data values associated with them or can simply be containers for other nodes. The NodeType property of a node identifies the node as an object node (container) or variable node (data). For more information on how to programmatically search the server namespace, see "Browse OPC UA Server Namespace"
OPC UA servers provide access to both current and historical values of their Variable nodes. With OPC Toolbox you use arrays of Nodes to read current values from the server. Current data includes the value, a timestamp that the server received the data value from the sensor, and a quality describing the accuracy and source of the data value.
[val, ts, qual] = readValue(uaClient, serverNodes)
val = [0 secs] [ 0] ts = 30-Jun-2015 05:05:13 30-Jun-2015 05:05:13 qual = OPC UA Quality ID: 'Good' 'Good'
For more information on reading and writing current values, see "Read and Write Current OPC UA Server Data".
Historical data is stored for selected nodes on the OPC UA server. The server nodes retrieved in the previous step will not be archived by the server because the values do not generally change. You can query the Historizing property of a Node to determine if the server is currently archiving data for that node.
Because the serverNode list is an array, you must collect the outputs using concatenation.
ans = 0 0
None of the server nodes are currently being historized. In addition, the server does not allow historical access to these nodes, as evidenced by the AccessLevelHistory property of the nodes.
ans = 'none' 'none'
To locate nodes with history, query the server for the Double and Int32 nodes in the Sample parent node.
sampleNode = findNodeByName(uaClient.Namespace, 'Sample')
sampleNode = OPC UA Node object: Name: Sample Description: NamespaceIndex: 2 Identifier: Sample NodeType: Object Parent: Archive Children: 14 nodes.
The Sample node is an Object node, so it has no Value. However, it has 14 Children. Locate the Double and Int32 child nodes.
doubleNode = findNodeByName(sampleNode, 'Double'); int32Node = findNodeByName(sampleNode, 'Int32')
int32Node = OPC UA Node object: Name: Int32 Description: NamespaceIndex: 2 Identifier: 1:Quickstarts.HistoricalAccessServer.Data.Sample.Int32.txt NodeType: Variable Parent: Sample Children: 2 nodes. ServerDataType: Int32 AccessLevelCurrent: read AccessLevelHistory: read/write Historizing: 0
Although the Int32 (and Double) nodes are not currently being archived (Historizing is false) you can read history data from the nodes (the history was logged at startup, and then turned off). To read all data stored on the server within a specified time range, use the readHistory function, passing the nodes to read and the time range over which to read the data.
dataToday = readHistory(uaClient, [doubleNode, int32Node], datetime('today'), datetime('now'))
dataToday = 1-by-2 OPC UA Data object: Name Value Start Timestamp End Timestamp Quality ------ --------------- ----------------------- ----------------------- ------------------ Double 9 double values 2015-06-30 04:00:10.000 2015-06-30 04:01:30.000 3 unique qualities Int32 12 int32 values 2015-06-30 04:00:02.000 2015-06-30 04:01:30.000 3 unique qualities
You can plot the data directly from the resulting OPC UA Data object.
plot(dataToday) legend show
You can also convert the data into MATLAB® native data types for further processing. For information on processing data, see "Visualize and Preprocess OPC UA Data".
When you have finished exchanging data with the OPC server, you should disconnect from the server.
You can then clear the OPC UA variables from MATLAB memory. Note that if you clear an OPC UA Client from memory, the connection to the server is automatically closed.