Client API reference

Creating a Client

Constructor

A client is created by calling:

ua.newClient(config)
config
Configuration table

Example:

local ua = require("opcua.api")

local config = {
  applicationName = 'RealTimeLogic example',
  applicationUri = "urn:opcua-lua:example",
  productUri = "urn:opcua-lua:example",
  securityPolicyUri = ua.Types.SecurityPolicy.None,
}

local client = ua.newClient(config)

Full source

Client configuration table

config - a table with the following:
applicationName (string)
The client’s application name
applicationUri (string)
application URI
productUri
Product URI
securityPolicyUri (string)
Public known URI of a policy that is used to secure messages
cosocketMode (bool)
Flag that sets client in cosockets mode aka asynchronous mode.
bufferSize (uint32, optional,default=8192)
Size of internal buffer used for sending and receiving messages.
logging (table, optional)
Optional client logging. No logging is performed if not set. See the Configuration table for details.

Example:

local config = {
  applicationName = 'RealTimeLogic example',
  applicationUri = "urn:opcua-lua:example",
  productUri = "urn:opcua-lua:example",
  securityPolicyUri = ua.Types.SecurityPolicy.None,
}

Full source

Methods

A client created by calling ua.newClient() has the following methods:

client:connect(endpointUrl[, connectCallback])
endpointUrl (string)
OPCUA server endpoint URL.
connectCallback
function that will be called on success or error.
Result:
error

Example:

local client = ua.newClient(config)
local function connectCallback(err)
  done = true
  if err ~= nil then
    trace("connection failed: "..err)
    return
  end
  trace("Connected sucessfully")
  client:disconnect()
end

local function connectToServer()
  trace("connecting to server")
  local endpointUrl = "opc.tcp://localhost:4841"
  client:connect(endpointUrl, connectCallback)
end

Full source

Example without callback:

local err = client:connect(endpointUrl)
if err ~= nil then
  trace("connection failed: "..err)
else
  trace("Connected sucessfully")
end

Full source

client:openSecureChannel(timeout[, msgCallback])

Open new secure channel. The client must open at least one channel.

timeout
How long a channel should be alive/active (in milliseconds).
msgCallback
Message callback
Result
openSecureChannelResponse, error

The client will automatically refresh when the channel has been established.

Callback example:

local client = ua.newClient(config)

local function onChannelOpened(resp, err)
  if err ~= nil then
    trace("Secure channel error: "..tostring(err))
    return
  end
  trace("Opened secure channel with id: "..resp.securityToken.channelId)
  client:disconnect()
  done = true
end

local function connectCallback(err)
  if err == nil then
    local secureChannelTimeout = 60000 -- ms
    client:openSecureChannel(secureChannelTimeout, onChannelOpened)
  end
end

Full source

Blocking example (no callback):

local err = client:connect(endpointUrl)
if err ~= nil then
  trace("connection error: "..err)
  return
end

-- Open secure channel with timeout 120 seconds
local resp, err = client:openSecureChannel(120000)
if err ~= nil then
  trace("Opening secure channel failed: "..err)
end
trace("Opened secure channel with id: "..resp.securityToken.channelId)

Full source

client:findServers(params[, msgCallback])
Get the list of the servers known to a Server or Discovery Server
params table with fields:
endpointUrl (string, optional)
Endpoint URL.
localeIds[] (string, optional)
List of locales to use. The Server should return the applicationName in the ApplicationDescription using one of locales specified.
serverUris[] (string, optional)
The List of servers to return. All known servers are returned if the list is empty.

msgCallback - Message callback

Result: findServersResponse, error

Example:

-- Select known servers
local params = {
  endpointUrl = "opc.tcp://localhost:4841"
}

local resp, err = client:findServers(params)
if err ~= nil then
  trace("Find servers error: "..err)
else
  if not resp.servers[0] then
    trace("No servers found.")
  end
  for i,srv in ipairs(resp.servers) do
    trace("server #"..i)
    trace("  "..srv.applicationUri)
    trace("  "..srv.productUri)
    trace("  "..srv.applicationName.text)
  end
end

Full source

client:getEndpoints(params[, msgCallback])

Returns the Endpoints supported by a Server and all of the configuration information required to establish a SecureChannel and a Session.

params a table with the following fields:
endpointUrl (string, optional)
The network address the Client used when accessing the DiscoveryEndpoint.
localeIds[] (string, optional)
List of locales to use. Specifies the locale to use when returning human readable strings.
profileUris[] (string, optional)
List of Transport Profiles that the returned Endpoints support.
msgCallback
Message callback
Result
getEndpointsResponse,error

Example:

-- Select endpoints
local params = {
  endpointUrl = "opc.tcp://localhost:4841"
}

local resp, err = client:getEndpoints(params)
if err ~= nil then
  trace("Get endpoints error: "..err)
else
  if not resp.endpoints[0] then
    trace("No endpoints found.")
  end
  for i,endpoint in ipairs(resp.endpoints) do
    trace("enspoint #"..i)
    trace("  "..endpoint.endpointUrl)
    trace("  "..endpoint.transportProfileUri)
    trace("  "..endpoint.securityPolicyUri)
  end
end

Full source

client:createSession(name, timeoutMs[, msgCallback])

This Service is used by an OPC UA Client when creating a Session. The Server returns two values which uniquely identifies the Session.

params a table with the following fields:
name (string)
Human readable string identifying the Session.
timeoutMs (double)
Requested maximum number of milliseconds that a Session should remain open without activity.

msgCallback Message callback

Result createSessionResponse, error

Example:

resp, err = client:createSession("test_session", 3600000)
if err ~= nil then
  trace("Creating session failed: "..err)
  return
end

trace("created session:")
trace("  sessionId='"..resp.sessionId.."'")
trace("  authenticationToken='"..resp.authenticationToken.."'")
trace("  revisedSessionTimeout='"..resp.revisedSessionTimeout.."'")

Full source

client:activateSession([msgCallback])

Activate previously created session.

msgCallback
Message callback
Result
activateSessionResponse, error

Example:

resp, err = client:activateSession()
if err ~= nil then
  trace("Activating session failed: "..err)
  return
end

Full source

client:browse([params| nodeId | nodeId[]] [, msgCallback])

This Service is used for discovering the References of a specified Node.

nodeId (NodeId)
id of the node to browse.
nodeId[] (NodeId)
list of node IDs to browse
params (table)
browseParameters
msgCallback
Message callback
Result
Browsing Result,error

Example:

resp, err = client:browse({nodeIds.RootFolder, nodeIds.TypesFolder})
if err ~= nil then
  return
end

for _,res in ipairs(resp.results) do
  if res.statusCode ~= ua.StatusCode.Good then
    trace(string.format("Cannot browse node: 0x%X", res.statusCode))
  else
    trace("References:")
    for i,ref in ipairs(res.references) do
      trace(string.format("%d: NodeId=%s Name=%s", i, ref.nodeId, ref.displayName.text))
    end
  end
end

Full source

client:read(params[, msgCallback])

Read one or more Attributes of one or more Nodes.

params (table)
nodesToRead[]: (table)
nodeId (NodeId) node identifier attributeId (Node Attribute) attribute to read
msgCallback
Message callback
Result
readResponse,error

Example:

local readParams = {
  nodesToRead = {
    {nodeId=nodeIds.ObjectsFolder, attributeId=ua.Types.AttributeId.DisplayName},
    {nodeId=nodeIds.ObjectsFolder, attributeId=ua.Types.AttributeId.BrowseName},
    {nodeId=nodeIds.ObjectsFolder, attributeId=ua.Types.AttributeId.NodeId},
  }
}

local resp,err = client:read(readParams)
for i,result in ipairs(resp.results) do
  if result.statusCode == 0 then
    ua.Tools.printTable("result", result.value)
  else
    trace(string.format("Read value '%s' error: 0x%X", nodes.nodesToRead[i].nodeId, result.statusCode))
  end
end

Full source

client:write(params[, msgCallback])

This Service is used when writing values to one or more Attributes of one or more Nodes.

params (table)
nodesToWrite[] (table)
nodeId (NodeId) node identifier attributeId (Node Attribute) attribute to read value (DataValue) New value of attribute
msgCallback
Message callback
Result
writeResponse,error

Example:

local nodes = {
  nodesToWrite = {
    {
      nodeId = nodeIds.Server_ServerStatus_StartTime,
      attributeId = ua.Types. AttributeId.Value,
      value = {   -- DataValue
        value = { -- Variant
          dateTime = 0.0
        }
      }
    }
  }
}

local resp,err = client:write(nodes)
if resp.results[1] ~= 0 then
  trace(string.format("Changing attribute value failed: 0x%X", resp.results[1]))
else
  trace(string.format("Attribute value changed sucessfully"))
end

Full source

client:addNodes(params[, msgCallback])

Add one or more Nodes into the AddressSpace hierarchy.

params (table)
nodesToAdd[] (table)
parentNodeId (NodeId)
Parent’s node identifier.
referenceTypeId (NodeId)
Parent’s reference type identifier.
requestedNewNodeId (NodeId)
NodeID for the new node. The actual identifier will be automatically assigned by server if NodeId equals ua.NodeId.Null.
browseName (QualifiedName)
Internal name for the node. This name is used in the TranslateBrowsePathsToNodeIdsservice to resolve NodeId by path from some nodes.
nodeClass (ua.Types.NodeClass)
Node class: Variable, Object, DataType. Only Variable node class is currently supported.
displayName (LocalizedText)
Clients use this attribute if they want to display the name of the node to the user. Can be localized.
description (LocalizedText)
The optional description attribute explains the meaning of the node using localised text.
writeMask (UInt32)
Bit mask. Every bit defines ability to change corresponding attribute.
userWriteMask (UInt32)
Bit mask. Every bit defines ability to change corresponding attribute for current user.
value (Variant)
Initial value of a variable node.
dataType (:ref:node_id_type)
Identifier of a node of type NodeClass DataType that describes the structure of a value. For example encoding/decoding in binary, json, xml formats. This may be an ID of a node of simple type (Int32, UInt,Float, etc), or complex structures (for example certificate, ApplicationDescription, BuildInfo).
valueRank (Int32)
Possible values: scalar, array. More information can be found in section :ref:ValueRank
arrayDimensions[] (UInt32)
Array dimensions of the value. For example: {2,2} describes square matrix with size 2*2.
accessLevel (type Byte)
Defines the node attributes access mask.
userAccessLevel (type Byte)
Current user’s write mask.
minimumSamplingInterval (type Double)
TODO
historizing (boolean)
TODO
msgCallback
Message callback
Result
addNodesResponse,error

Example:

local folderParams = {
  parentNodeId = nodeIds.ObjectsFolder,
  referenceTypeId = nodeIds.Organizes,
  requestedNewNodeId = ua.NodeId.Null,
  browseName = {name="TestFolder", ns=3},
  nodeClass = ua.Types.NodeClass.Object,
  displayName = {text="Folder"},
  description = {text="Folder Example"},
  writeMask = 0,
  userWriteMask = 0,
  eventNotifier = 0,
  typeDefinition = nodeIds.FolderType
}

local request = {
  nodesToAdd = {folderParams}
}

local resp, err = client:addNodes(request)
for i,res in ipairs(resp.results) do
  if res.statusCode ~= 0 then
    trace(string.format("Adding folder node failed: 0x%X", res.statusCode))
  else
    trace(string.format("Added new folder node with Id: '%s'", res.addedNodeId))
  end
end

Full source

client:translateBrowsePaths(params[, msgCallback])

This Service is used when requesting that the Server translates one or more browse paths to NodeIds.

msgCallback
Message callback
client:closeSession([msgCallback])

Terminate an active Session.

msgCallback
Message callback
Result
closeSessionResponse,error

Example:

resp, err = client:closeSession()
if err == nil then
  trace("Session closed")
end

Full source

client:closeSecureChannel()

Terminate a SecureChannel.

Result
closeSecureChannelResponse,error
client:disconnect()

Close the client’s server socket connection. Calling this method also closes any open channel.

Result
error

Message callback

msgCallback(response, err)

Callback function that is called when the request has been completed.

response
Data received from server in response to corresponding request.
err
Any error that occured during processing of request.