.. _client_subscriptions: ================================= Subscriptions and Monitored Items ================================= An OPC UA Subscription lets a Client receive changes without repeatedly calling :ref:`client:read`. A Subscription defines when the Server may publish notifications. One or more MonitoredItems select the nodes and attributes to sample and report. Use a Subscription for values that must be observed continuously, such as temperatures, counters, alarms, or server status. Use Read when only a current snapshot is needed. Classic Subscriptions are part of the Client/Server model; they are different from OPC UA PubSub over MQTT. The Lua client exposes the Subscription and MonitoredItem services directly. The application therefore manages this lifecycle: #. Create a Subscription in an active Session. #. Create one or more MonitoredItems in that Subscription. #. Keep sending Publish requests and process the returned notifications. #. Acknowledge notification sequence numbers so the Server can release them. #. Delete MonitoredItems and the Subscription when they are no longer needed. The current compact implementation supports data-change notifications. Event MonitoredItems are not supported. Subscribe to Server Time ######################## Every OPC UA Server exposes ``ServerStatus.CurrentTime`` as NodeId ``i=2258``. The following example creates a Subscription and monitors the Value attribute of that node. Create a Subscription --------------------- Create the Subscription after connecting, opening a SecureChannel, and activating a Session. The Server may revise the requested publishing interval, lifetime count, and keep-alive count. Their revised values are returned in the CreateSubscription response. .. literalinclude:: ../examples/client/client_subscribe_current_time.lua :language: lua :lines: 49-60 :example:`Full source ` The most important settings are: ``RequestedPublishingInterval`` Minimum interval, in milliseconds, between publishing cycles. ``RequestedMaxKeepAliveCount`` Number of publishing cycles without notifications before the Server sends a keep-alive response. ``RequestedLifetimeCount`` Number of publishing cycles without an available Publish request before the Subscription expires. The Server revises this to at least three times the revised keep-alive count. ``MaxNotificationsPerPublish`` Maximum number of notifications in one Publish response. Zero means no client-requested limit. ``PublishingEnabled`` Whether the Server may report queued notifications. Create a MonitoredItem ---------------------- A MonitoredItem identifies an attribute to sample. ``ClientHandle`` is chosen by the application and is returned with each value, allowing notifications to be associated with application state without comparing NodeIds. .. literalinclude:: ../examples/client/client_subscribe_current_time.lua :language: lua :lines: 89-114 :example:`Full source ` ``SamplingInterval`` is the requested interval, in milliseconds, at which the Server checks the value. Zero requests the fastest practical sampling, and a negative value requests the Subscription publishing interval. ``QueueSize`` controls how many changed values the Server retains, and ``DiscardOldest`` selects which value is removed if that queue is full. :ref:`TimestampsToReturn ` selects the timestamps included in each DataValue. Use ``ua.TimestampsToReturn.Source``, ``Server``, ``Both``, or ``Neither``. When no filter is supplied, a value is queued when its StatusCode or value changes. A ``DataChangeFilter`` can instead select status-only or status/value/timestamp triggering and can apply an absolute deadband. Percent deadband and event filters are not supported by the compact server. :ref:`MonitoringMode ` controls sampling and reporting: ``ua.MonitoringMode.Disabled`` Do not sample or report the item. ``ua.MonitoringMode.Sampling`` Sample and queue changes, but do not add them to Publish responses. ``ua.MonitoringMode.Reporting`` Sample, queue, and report changes through Publish responses. Always inspect each entry in ``response.Results``. A service call can succeed while an individual MonitoredItem fails, for example because its NodeId or AttributeId is invalid. Receive Changed Values ---------------------- Publish is initiated by the Client. The Server holds a Publish request until a notification or keep-alive is ready. A synchronous client normally sends the next request after processing the previous response. Applications using callback mode can keep multiple Publish requests outstanding. .. literalinclude:: ../examples/client/client_subscribe_current_time.lua :language: lua :lines: 153-177 :example:`Full source ` ``NotificationData`` is empty for a keep-alive. A data-change notification contains ``Body.MonitoredItems``. Each entry contains the configured ``ClientHandle`` and a ``Value`` DataValue. A non-empty NotificationMessage has a sequence number. Include that number in ``SubscriptionAcknowledgements`` on a later Publish request. Until it is acknowledged, the message may be recovered with :ref:`client:republish` if it was lost in transit. Delete the Resources -------------------- Delete MonitoredItems when the application no longer needs their values, then delete the Subscription. Closing a Session with subscriptions deleted also releases them, but explicit deletion makes the resource lifetime clear. .. literalinclude:: ../examples/client/client_subscribe_current_time.lua :language: lua :lines: 179-196 :example:`Full source ` Manage Subscriptions #################### Change the negotiated parameters with :ref:`modifySubscription `. The response contains the revised values: .. literalinclude:: ../examples/client/client_subscribe_current_time.lua :language: lua :lines: 62-71 :example:`Full source ` Temporarily stop or resume notification publishing with :ref:`setPublishingMode ` without deleting queued MonitoredItem values: .. literalinclude:: ../examples/client/client_subscribe_current_time.lua :language: lua :lines: 73-87 :example:`Full source ` Delete one or more Subscriptions with :ref:`deleteSubscriptions `. Its ``Results`` array contains one StatusCode for every requested SubscriptionId. Manage Monitored Items ###################### Change sampling and queue parameters with :ref:`modifyMonitoredItems ` without recreating a MonitoredItem: .. literalinclude:: ../examples/client/client_subscribe_current_time.lua :language: lua :lines: 116-133 :example:`Full source ` Pause sampling or reporting with :ref:`setMonitoringMode `: .. literalinclude:: ../examples/client/client_subscribe_current_time.lua :language: lua :lines: 135-151 :example:`Full source ` As with creation and deletion, inspect every StatusCode in ``response.Results`` after modifying modes or parameters.