========== Data Types ========== This page summarizes the Lua representations used by the OPC UA stack. Values are ordinary Lua values unless a table structure is shown. Built-in Types -------------- .. _SByte: .. _Byte: .. _Int16: .. _UInt16: .. _Int32: .. _UInt32: .. _Int64: .. _UInt64: .. _Float: .. _Double: .. _DateTime: .. _String: .. _ByteString: .. _Guid: .. _StatusCode: .. list-table:: :header-rows: 1 :widths: 18 25 57 * - OPC UA type - Lua representation - Notes * - ``SByte`` - number - Signed 8-bit integer. * - ``Byte`` - number - Unsigned 8-bit integer. * - ``Int16`` - number - Signed 16-bit integer. * - ``UInt16`` - number - Unsigned 16-bit integer. * - ``Int32`` - number - Signed 32-bit integer. * - ``UInt32`` - number - Unsigned 32-bit integer. * - ``Int64`` - number - Signed 64-bit integer. * - ``UInt64`` - number - Unsigned 64-bit integer. * - ``Float`` - number - 32-bit floating-point value. * - ``Double`` - number - 64-bit floating-point value. * - ``DateTime`` - number - Unix timestamp in seconds, usually from ``compat.gettime()`` or ``os.time()``. Encoders convert this to the OPC UA wire format. * - ``String`` - string - UTF-8 string. * - ``ByteString`` - string - Binary byte sequence stored in a Lua string. * - ``Guid`` - string - GUID string, for example ``12345678-1234-1234-1234-123456789012``. * - ``StatusCode`` - number - OPC UA status code, for example ``ua.StatusCode.Good``. .. _localized_text_type: LocalizedText ------------- Localized text is represented as a table. .. list-table:: :header-rows: 1 :widths: 20 20 60 * - Field - Type - Description * - ``Locale`` - string, optional - Locale name such as ``"en-US"``. If omitted, the default locale is used. * - ``Text`` - string - Localized text content. .. code-block:: lua local text = {Locale = "en-US", Text = "This is localized text"} local textDefaultLocale = {Text = "This is localized text"} .. _qualified_name_type: QualifiedName ------------- A QualifiedName is the service identifier of a node. It combines a namespace index with a name. .. list-table:: :header-rows: 1 :widths: 20 20 60 * - Field - Type - Description * - ``ns`` - number - Namespace index. * - ``Name`` - string - Name within the namespace. .. code-block:: lua local qualifiedName = {ns = 1, Name = "Node Name"} .. _node_id_type: NodeId ------ A NodeId is encoded as a string: .. code-block:: text [ns=;]= .. list-table:: :header-rows: 1 :widths: 24 28 48 * - Part - Value - Description * - ``namespace_index`` - unsigned 16-bit integer - Optional. Omit when the namespace index is ``0``. * - ``type`` - ``i``, ``s``, ``g``, or ``b`` - Identifier type: integer, string, GUID, or opaque byte string. * - ``value`` - type-specific string - Decimal integer, UTF-8 string, lowercase GUID, or base64 byte string. .. list-table:: :header-rows: 1 :widths: 15 25 60 * - Type code - Identifier type - Example * - ``i`` - Integer - ``i=85`` or ``ns=2;i=1001`` * - ``s`` - String - ``ns=2;s=Temperature`` * - ``g`` - GUID - ``ns=2;g=12345678-1234-1234-1234-123456789012`` * - ``b`` - Opaque byte string - ``ns=2;b=AQIDBA==`` Additional examples are available in :example:`node_id.lua `. The official syntax is described in the OPC Foundation `NodeId reference `__. NodeId helpers ~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 32 43 25 * - Function - Parameters - Return value * - ``toString(id, ns)`` - ``id`` is a number, string, GUID, byte array, or bytes. ``ns`` is a namespace index or ``nil``. - Encoded NodeId string. * - ``toString({id = value, ns = number})`` - Table form of the same parameters. - Encoded NodeId string. * - ``fromString(string)`` - Encoded NodeId string. - Table with ``ns`` and ``id`` fields. .. _variant_type: Variant ------- A Variant wraps a value with an OPC UA type. It can represent a scalar or an array. .. list-table:: :header-rows: 1 :widths: 24 24 52 * - Field - Type - Description * - ``Type`` - ``ua.VariantType`` - Type of the stored value. * - ``Value`` - any supported Lua value - Value to encode. * - ``IsArray`` - boolean, optional - Set to ``true`` when ``Value`` is an array. * - ``ArrayDimensions`` - number array, optional - Dimensions for array values. .. code-block:: lua local uint32 = {Type = ua.VariantType.UInt32, Value = 0} local uint32Array = { Type = ua.VariantType.UInt32, Value = {1, 2, 3, 4}, IsArray = true, ArrayDimensions = {4} } VariantType constants ~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 35 15 35 15 * - Name - Value - Name - Value * - ``Null`` - 0 - ``Boolean`` - 1 * - ``SByte`` - 2 - ``Byte`` - 3 * - ``Int16`` - 4 - ``UInt16`` - 5 * - ``Int32`` - 6 - ``UInt32`` - 7 * - ``Int64`` - 8 - ``UInt64`` - 9 * - ``Float`` - 10 - ``Double`` - 11 * - ``String`` - 12 - ``DateTime`` - 13 * - ``Guid`` - 14 - ``ByteString`` - 15 * - ``XmlElement`` - 16 - ``NodeId`` - 17 * - ``ExpandedNodeId`` - 18 - ``StatusCode`` - 19 * - ``QualifiedName`` - 20 - ``LocalizedText`` - 21 * - ``ExtensionObject`` - 22 - ``DataValue`` - 23 * - ``Variant`` - 24 - ``DiagnosticInfo`` - 25 .. _data_value_type: DataValue --------- A DataValue is a Variant value plus optional status and timestamp fields. .. list-table:: :header-rows: 1 :widths: 25 25 50 * - Field - Type - Description * - ``Type`` - ``ua.VariantType`` - Type of ``Value``. * - ``Value`` - any supported Lua value - Value to encode. * - ``StatusCode`` - status code, optional - Value status, for example ``ua.StatusCode.Good``. * - ``SourceTimestamp`` - DateTime, optional - Source timestamp. * - ``ServerTimestamp`` - DateTime, optional - Server timestamp. * - ``SourcePicoseconds`` - UInt16, optional - Fractional source timestamp precision. * - ``ServerPicoseconds`` - UInt16, optional - Fractional server timestamp precision. .. code-block:: lua local dataValue = { Type = ua.VariantType.UInt32, Value = 100, StatusCode = ua.StatusCode.Good, SourceTimestamp = os.time() } .. _timestamps_to_return_type: TimestampsToReturn ------------------ ``ua.TimestampsToReturn`` selects which timestamps the Server includes in returned DataValues. .. list-table:: :header-rows: 1 :widths: 30 15 55 * - Constant - Value - Description * - ``ua.TimestampsToReturn.Source`` - 0 - Return the source timestamp only. * - ``ua.TimestampsToReturn.Server`` - 1 - Return the server timestamp only. * - ``ua.TimestampsToReturn.Both`` - 2 - Return both source and server timestamps. * - ``ua.TimestampsToReturn.Neither`` - 3 - Do not return source or server timestamps. .. _monitoring_mode_type: MonitoringMode -------------- ``ua.MonitoringMode`` controls whether a MonitoredItem samples and reports values. .. list-table:: :header-rows: 1 :widths: 30 15 55 * - Constant - Value - Description * - ``ua.MonitoringMode.Disabled`` - 0 - Do not sample or report values. * - ``ua.MonitoringMode.Sampling`` - 1 - Sample and queue values without reporting them. * - ``ua.MonitoringMode.Reporting`` - 2 - Sample, queue, and report values through Publish responses. .. _data_change_trigger_type: DataChangeTrigger ----------------- ``ua.DataChangeTrigger`` selects which DataValue changes create notifications. .. list-table:: :header-rows: 1 :widths: 34 15 51 * - Constant - Value - Description * - ``ua.DataChangeTrigger.Status`` - 0 - Report changes to the StatusCode. * - ``ua.DataChangeTrigger.StatusValue`` - 1 - Report changes to the StatusCode or value. * - ``ua.DataChangeTrigger.StatusValueTimestamp`` - 2 - Report changes to the StatusCode, value, or source timestamp. .. _deadband_type: DeadbandType ------------ ``ua.DeadbandType`` selects how a DataChangeFilter suppresses small value changes. .. list-table:: :header-rows: 1 :widths: 30 15 55 * - Constant - Value - Description * - ``ua.DeadbandType.None`` - 0 - Do not apply a deadband. * - ``ua.DeadbandType.Absolute`` - 1 - Require an absolute difference greater than ``DeadbandValue``. * - ``ua.DeadbandType.Percent`` - 2 - Require a percentage difference based on the Variable's engineering range. The compact Server does not support this mode. .. _extension_object_type: ExtensionObject --------------- An ExtensionObject represents a structured value. It is also used when a field can contain one of several structure types, such as node attributes for ``AddNodes``. .. list-table:: :header-rows: 1 :widths: 22 28 50 * - Field - Type - Description * - ``TypeId`` - :ref:`NodeId` - NodeId of the structure type. This is the decoded structure NodeId, not the binary, XML, or JSON encoding NodeId. * - ``Body`` - table, ByteString, XML string, or JSON string - Decoded body table when the structure is known. Otherwise, the body is left opaque and must be decoded by application code. .. code-block:: lua local extensionObject = { TypeId = "i=338", -- BuildInfo Body = { ProductUri = ua.Version.ProductUri, ManufacturerName = ua.Version.ManufacturerName, ProductName = ua.Version.ProductName, SoftwareVersion = ua.Version.Version, BuildNumber = ua.Version.BuildNumber, BuildDate = compat.gettime() } } Service Structures ------------------ .. _notification_data_type: NotificationData ~~~~~~~~~~~~~~~~ ``NotificationMessage.NotificationData`` is an array of :ref:`ExtensionObject` notification payloads returned by both Publish and Republish responses. The array is empty when the ``NotificationMessage`` is a keep-alive. A data-change notification is an ExtensionObject with ``TypeId = "i=811"``. Its ``Body`` contains: .. list-table:: :header-rows: 1 :widths: 38 25 37 * - Field - Type - Description * - ``MonitoredItems[]`` - array - Values reported for the MonitoredItems that produced notifications. * - ``MonitoredItems[].ClientHandle`` - UInt32 - Application-defined handle supplied in the MonitoredItem's ``RequestedParameters``. * - ``MonitoredItems[].Value`` - :ref:`DataValue` - Sampled value, StatusCode, and requested timestamps. * - ``DiagnosticInfos[]`` - array - Optional diagnostics corresponding to ``MonitoredItems``. .. _response_header_type: ResponseHeader ~~~~~~~~~~~~~~ Every OPC UA service response contains a ResponseHeader with service-level status and diagnostic information. .. list-table:: :header-rows: 1 :widths: 28 25 47 * - Field - Type - Description * - ``Timestamp`` - DateTime - Server time when the response was created. * - ``RequestHandle`` - UInt32 - Handle copied from the corresponding request. The Client uses it to associate asynchronous responses with callbacks. * - ``ServiceResult`` - StatusCode - Overall result of the service call. Per-operation failures can still be present in a successful response's ``Results`` array. * - ``ServiceDiagnostics`` - DiagnosticInfo - Service-level diagnostic details. String indexes in this structure refer to entries in ``StringTable``. * - ``StringTable[]`` - String array - Strings referenced by indexes in ``ServiceDiagnostics`` and other diagnostic structures in the response. * - ``AdditionalHeader`` - :ref:`ExtensionObject` - Additional service-defined response data. A null ExtensionObject means that no additional header was supplied. ActivateSessionResponse ~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 28 25 47 * - Field - Type - Description * - ``ServerNonce`` - ByteString - Random value that should not be reused. * - ``Results`` - StatusCode array - User identity token validation results. AddNodesResponse ~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 28 25 47 * - Field - Type - Description * - ``Results[]`` - array - One result per requested node. * - ``Results[].StatusCode`` - StatusCode - Status of the add operation. * - ``Results[].AddedNodeId`` - :ref:`NodeId` - Server-assigned NodeId, or ``nil`` if the operation failed. BrowseParameters ~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 32 25 43 * - Field - Type - Description * - ``RequestedMaxReferencesPerNode`` - UInt32 - Maximum number of references to return. ``0`` means unlimited. * - ``NodesToBrowse[]`` - array - Nodes to browse. * - ``NodesToBrowse[].NodeId`` - :ref:`NodeId` - Node to browse. * - ``NodesToBrowse[].ReferenceTypeId`` - :ref:`NodeId` - Reference type to follow. * - ``NodesToBrowse[].BrowseDirection`` - ``ua.BrowseDirection`` - Browse direction. * - ``NodesToBrowse[].NodeClassMask`` - ``ua.NodeClass`` - Node classes to include. * - ``NodesToBrowse[].ResultMask`` - ``ua.BrowseResultMask`` - Fields to include in the response. * - ``NodesToBrowse[].IncludeSubtypes`` - boolean - Include subtypes of ``ReferenceTypeId``. BrowseResult ~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 32 25 43 * - Field - Type - Description * - ``Results[]`` - array - One result per requested node. * - ``Results[].StatusCode`` - StatusCode - Browse status for the requested node. * - ``Results[].References[]`` - array - References returned by the browse operation. * - ``References[].NodeId`` - :ref:`NodeId` - Target node identifier. * - ``References[].ReferenceTypeId`` - :ref:`NodeId` - Reference type identifier. * - ``References[].IsForward`` - boolean - Reference direction. * - ``References[].BrowseName`` - :ref:`QualifiedName` - Service name of the node. * - ``References[].DisplayName`` - :ref:`LocalizedText` - User-facing node label. * - ``References[].NodeClass`` - Int32 - Node class. * - ``References[].TypeDefinition`` - :ref:`NodeId` - Node type definition. CloseSecureChannelResponse ~~~~~~~~~~~~~~~~~~~~~~~~~~ Empty table. CloseSessionResponse ~~~~~~~~~~~~~~~~~~~~ Empty table. CreateSessionResponse ~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 30 25 45 * - Field - Type - Description * - ``ResponseHeader`` - :ref:`ResponseHeader` - Standard OPC UA response header. * - ``SessionId`` - :ref:`NodeId` - Unique NodeId assigned by the server to the session. * - ``AuthenticationToken`` - :ref:`NodeId` - Unique token assigned by the server to the session. * - ``RevisedSessionTimeout`` - Double - Actual maximum session idle time in milliseconds. * - ``ServerNonce`` - ByteString - Random value that should not be reused in another request. * - ``ServerCertificate`` - ByteString - Server application instance certificate. * - ``ServerEndpoints`` - array - Endpoint descriptions supported by the server. * - ``ServerSignature`` - table - Signature generated with the server certificate private key. * - ``MaxRequestMessageSize`` - UInt32 - Maximum request body size in bytes. FindServersResponse ~~~~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 30 25 45 * - Field - Type - Description * - ``Servers[]`` - array - Servers that match the request criteria. * - ``ApplicationUri`` - string - Application URI. * - ``ProductUri`` - string - Product URI. * - ``ApplicationName`` - :ref:`LocalizedText` - Human-readable application name. * - ``ApplicationType`` - number - OPC UA application type. * - ``GatewayServerUri`` - string - Gateway server URI, if used. * - ``DiscoveryProfileUri`` - string - Discovery profile URI, if used. * - ``DiscoveryUrls`` - string array - Discovery endpoint URLs. GetEndpointsResponse ~~~~~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 30 25 45 * - Field - Type - Description * - ``Endpoints[]`` - array - Endpoint descriptions. * - ``EndpointUrl`` - string - Endpoint URL. * - ``Server`` - table - Server application description. * - ``ServerCertificate`` - ByteString - Server certificate. * - ``SecurityMode`` - number - Message security mode. * - ``SecurityPolicyUri`` - string - Security policy URI. * - ``UserIdentityTokens`` - array - Supported user identity token policies. * - ``TransportProfileUri`` - string - Transport profile URI. * - ``SecurityLevel`` - Byte - Relative endpoint security level. OpenSecureChannelResponse ~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 32 25 43 * - Field - Type - Description * - ``ResponseHeader`` - :ref:`ResponseHeader` - Standard OPC UA response header. * - ``SecurityToken`` - table - Secure channel token. * - ``SecurityToken.ChannelId`` - UInt32 - Unique SecureChannel identifier. * - ``SecurityToken.TokenId`` - UInt32 - Unique token identifier within the channel. * - ``SecurityToken.CreatedAt`` - DateTime - Token creation time. * - ``SecurityToken.RevisedLifetime`` - UInt32 - Token lifetime in milliseconds. ReadResponse ~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 28 25 47 * - Field - Type - Description * - ``Results[]`` - :ref:`DataValue` array - Attribute values returned by the server. WriteResponse ~~~~~~~~~~~~~ .. list-table:: :header-rows: 1 :widths: 28 25 47 * - Field - Type - Description * - ``Results[]`` - StatusCode array - Results for the nodes written by the request.