v2.0.0

Informally:

• Sessions, subscriptions and service calls can now be configured and controlled more easily.
  Basically, all Config classes (like SessionConfig, SubscriptionConfig, ReadConfig, ...)
  have disappeared. This means that the config arguments (e.g. read(..., sessionConfig=None, ...))
  have disappeared as well! Instead of using configs, you can now:

  • easily configure default SessionSettings, SubscriptionSettings, ReadSettings, etc.:

    clientSettings = ClientSettings()
    clientSettings.defaultSessionSettings.sessionTimeoutSec = 100.0
    clientSettings.defaultReadSettings.callTimeoutSec = 2.0
    myClient.setClientSettings(clientSettings)
    myClient.read(addresses) # this will use the above defaults

  • easily configure SessionSettings, SubscriptionSettings, ReadSettings, etc. per service call:

    myClient.read(addresses = myAddresses,
    ... serviceSettings = myReadSettings, # optional *_kwarg
    ... sessionSettings = mySessionSettings) # optional *_kwarg
    myClient.createMonitoredData(addresses = myAddresses,
    ... serviceSettings = myCreateMonitoredDataSettings, # optional *_kwarg
    ... sessionSettings = mySessionSettings, # optional *_kwarg
    ... subscriptionSettings = mySubscriptionSettings) # optional **kwarg

  • easily keep full control over sessions, subscriptions and services (only if you know
    what you're doing):

    myClient.read(addresses, clientConnectionId = 3)
    myClient.createMonitoredData(addresses, clientConnectionId = 3, clientSubscriptionHandle = 1)

  Check the examples/pyuaf/client/how_to_configure_all_settings.py example or the API docs for
  more detailed information!

  This is a breaking change that may affect existing code!!!
  Check your code for any occurrences of the word "config" (case insensitive) and check with the API
  documentation to spot any changes!

• OpenSSL security is now supported. See the example how_to_connect_to_a_secured_endpoint.py.

• Everything related to status/error handling has changed significantly:

  • Many more error types are now defined, so errors can now be handled much more "fine grained".
    For instance, in addition to the old "SecurityError", you can now also catch a
    "OpenSSLStoreInitializationError". The former is a superclass of the latter, so if you're
    handling SecurityErrors, you'll also handling all "fine grained" security related errors.
    To maintain backwards compatibility, no errors have been removed from the framework. If an
    error has become obsolete, it is now a subclass of the "BackwardsCompatibilityError", and it
    will never be raised.
    For PyUAF, see the documentation on pyuaf.util.errors to get an overview of all errors.
    For the C++ UAF, see the errors in the headers of src/uaf/errors/*.h.
  • The newly defined errors often have diagnostic attributes. For instance, the
    "ConnectionFailedError" has an "endpointUrl" string attribute, so you'll know for which
    endpoint the connection failed. It also has a "sdkStatus" attribute of the new type SdkStatus.
    SdkStatus instances hold the low-level statuscode and status description from the Unified
    Automation SDK. In other words, you can use the sdkStatus attribute to know what caused the
    ConnectionFailedError at the SDK level.
    Again, see the documentation of pyuaf.util.errors (or the C++ error headers) to know which
    attributes are defined for each error.
  • Since individual error classes now have diagnostic attributes, the StatusDiagnostics class
    (which previously held all diagnostic info) has been removed from the framework. Consequently,
    the "statusDiagnostics()" method of the Status class has been removed. Search through your
    existing code for "statusdiagnostics" (case insensitive) to detect problems due to backwards
    incompatibility. Especially watch out when creating monitored items: diagnostics are often
    used there to store clientHandles even if the monitored items could not be created. Check out
    the documentation on the "createMonitoredData()" or "createMonitoredEvents()" methods of the
    pyuaf.client.Client class to see how to adapt your code.

• Relevant for the C++ side only: the uafc:: namespace has been removed and all code is now part of
  the uaf:: namespace. We did this because SWIG apparently has problems with namespaces in certain
  cases (e.g. subclasses of an abstract class of another namespace may give problems when used in
  wrapped vectors).

• ExtensionObjects are now supported, and so are model change events.
  See example how_to_monitor_model_changes.py.

• The endpoint descriptions of the discovered servers can now be accessed via Client::getEndpoints().

• SessionInformation and SubscriptionInformation contains more diagnostic info.

• Bugfixes: see #62 and #80

v1.10

Important notice
This version will be the last version before version 2.0.0, which will contain a few rather drastic
API changes, affecting poorly designed parts of the UAF (see the plans for version 2.0.0 below).
The goal is to turn this version (1.10) into a "long-term" supported one, by maintaining it in a
different branch from version 2.0.0, which will receive an updated API and new features.

So there will be two main branches:

• long-term:
  • based on version 1.10 (this one)
  • tested and production-ready at any time
  • API and feature set are frozen, but bugfixes are applied.
• master:
  • will start with version 2.0.0, and will then adhere to semantic versioning
  • tested and production-ready at any time
  • contains latest API and latest features, is actively developed.

Plans for version 2.0.0:

• simplify the API related to session/subscription management. Get rid of concepts like
  "SessionConfig", "SubscriptionConfig", "manuallyConnect", ... and simply provide functions
  like "createSession", "createSubscription", etc.
  Session and subscription management remains optional for the user (as it's easier to let the
  UAF handle that), but those users that want to keep full control over their sessions and
  subscriptions will have a much easier API to work with.
• support security
• fix some small API inconsistencies so that the remaining missing OPC UA services
  (such as ModifyMonitoredItems) can be implemented easily, and so that the API can remain
  more stable while the first attempts to implement the server-side are carried out...

New in this version:

Informally:

• Updated the README.md to explain the intent and the added value of (Py)UAF a bit better
  (section "Why?").

• The monitoring mode (Disabled/Sampling/Reported) can now be set for monitored items via
  the SetMonitoringMode service. This is the preferred way to temporarily disable monitored items
  from being reported, e.g. when the tab of a graphical user interface is not visible.
  The newly added method "setMonitoringMode" will find out to which sessions and subscriptions
  your specified monitored items belong to: you only have to provide their client handles.
  This means that you can code your application against the specification of some nodes,
  without worrying about questions like "which node is currently hosted by which server?" or
  "which monitored item currently belongs to which subscription?".

• Connections and subscriptions can now be monitored much better because the following events
  are now exposed to the user (via callback functions):

  • ConnectionStatusChanged
  • SubscriptionStatusChanged
  • NotificationsMissing

• !!! breaking change !!!

  By default, when you create monitored items, the queue size is now 1 and the discard policy
  is set to "discard oldest". The default queue size used to be 0, which meant that servers
  always had to revise this number and correct it to 1. The default discard policy used to be
  "discard newest", which meant that the most recent data got lost in case a variable changed
  too rapidly. With the new defaults, clients are now always notified of the most recent data
  changes and events. For most applications, this makes a lot more sense.

• Bugfix: the value returned by pyuaf.util.Status.opcUaStatusCode() was sometimes wrong: SWIG
  converted the value into a signed 'long' which numerically (but not always bitwise!) corresponds
  to the 32-bit code defined by the OPC UA standard. Since pyuaf.util.opcuastatuscodes contains
  'int's that correspond bitwise (but not always numerically!) to the status codes defined by the
  OPC UA standard, there was a mismatch between the output of pyuaf.util.Status.opcUaStatusCode()
  and the contents of pyuaf.util.opcuastatuscodes. This is now fixed: both correspond now
  bitwise to the OPC UA status codes, so they can be compared with each other.

• Fixed a bug that caused the UAF to crash when providing Namespace URIs and Server URIs that
  contain percentage (%) signs. The bug occurred when trying to connect to the
  Ignition OPC UA server by Inductive Automation.
  See http://github.com/uaf/uaf/issues/30

• Microsoft VS2008 is now supported (credits to robi-wan @ GitHub).
  The VS2008 compiler requires the third-party "msinttypes" C++ headers, which are shipped with
  the UAF. If you don't want these headers to be included automatically by the CMake build script,
  set the NO_THIRD_PARTY_MSINTTYPES option to ON (see install_windows.rst.txt).
  See http://github.com/uaf/uaf/issues/29

• Python primitives such as pyuaf.util.primitives.Bool, UInt32 etc. now also accept strings, which
  they automatically cast to the correct datatype.
  For example, besides IUnt64(42) you can now also write UInt64("42").
  See http://github.com/uaf/uaf/issues/27

Formally:

• The following methods were added:
  • uafc::Client::setMonitoringMode (pyuaf.client.Client.setMonitoringMode)
• On the C++ side, the following methods were added to uafc::ClientInterface:
  • connectionStatusChanged
  • subscriptionStatusChanged
  • notificationsMissing
• On the Python side, the following methods were added to pyuaf.client.Client:
  • connectionStatusChanged() and registerConnectionStatusCallback()
  • subscriptionStatusChanged() and registerSubscriptionStatusCallback()
  • notificationsMissing() and registerNotificationsMissingCallback()
  • registerKeepAliveCallback() (note: keepAliveReceived() existed already)
• The following method may produce a different output in some cases (Python only):
  • pyuaf.util.Status.opcUaStatusCode()
    (the output now always corresponds to the numbers defined in pyuaf.util.opcuastatuscodes)
• The following attributes have different default value:
  • uafc::CreateMonitoredDataRequest::queueSize
    (pyuaf.client.requests.CreateMonitoredDataRequest.queueSize)
    --> now 1 instead of 0
  • uafc::CreateMonitoredDataRequest::discardOldest
    (pyuaf.client.requests.CreateMonitoredDataRequest.discardOldest)
    --> now true instead of false
  • uafc::CreateMonitoredEventsRequest::queueSize
    (pyuaf.client.requests.CreateMonitoredEventsRequest.queueSize)
    --> now 1 instead of 0
  • uafc::CreateMonitoredEventsRequest::discardOldest
    (pyuaf.client.requests.CreateMonitoredEventsRequest.discardOldest)
    --> now true instead of false

v1.9

This version doesn't really add more features to the UAF. It mostly fixes some not-so-critical problems that have been known for a long while, but were cumbersome to solve.

v1.8

The client can now manually connect to an endpoint, without using the discovery services.

v1.7

Version 1.7, which implements the setPublishingMode service, and which removes the redundant "notification handle" concept in favor of the "client handle" concept.

v1.6

This release requires the Unified Automation SDK v1.4 or higher.

v1.5

This release is still compatible with the Unified Automation SDK version 1.3.*.