path: root/src/opcua/doc/src/qtopcua.qdoc

/****************************************************************************
**
** Copyright (C) 2015 basysKom GmbH, info@basyskom.com
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \module QtOpcUa
    \title Qt OPC UA C++ Classes
    \ingroup modules
    \qtvariable opcua
    \since 5.11
    \brief List of C++ classes that provide the Qt OPC UA functionality.

    To link against the module, add this line to your \l qmake \c .pro file:

    \code
    QT += opcua
    \endcode
*/

/*!
    \qmlmodule QtOpcUa
    \title Qt OPC UA QML Types
    \brief Provides QML types for Qt OPC UA.
    \ingroup qmlmodules

    The QML types can be imported into your application using the following
    import statements in your .qml file:

    \badcode
    import QtOpcUa 5.12 as QtOpcUa
    \endcode

    To link against the module, add the following QT variable to your qmake .pro
    file:

    \badcode
    QT += opcua
    \endcode
*/

/*!
    \page qtopcua-index.html
    \since 5.7
    \title Qt OPC UA
    \brief Implements OPC UA connectivity through a Qt API.
    \preliminary

    The Qt \l{Qt OPC UA#A short introduction to OPC UA}{OPC UA} module
    implements a Qt API to interact with OPC UA on top of a 3rd party
    OPC UA stack.

    The stacks are connected via plugins and can be selected/switched at runtime.
    Currently, the following implementations are supported

    \list
    \li Open62541 v0.3, MPLv2
    \li Unified Automation C++ SDK (UACpp), Commercial
    \endlist

    This module is still in development but is available as a technology preview.
    This means it is unstable, likely to change and provided as a convenience only.

    \section1 Getting started

    Add the following line to your .pro file
    \code
        QT += opcua
    \endcode
    and include the Qt OPC UA headers into your files using
    \code
       #include <QtOpcUa>
    \endcode

    The \l{Qt OPC UA Examples}{examples} demonstrate how to use Qt OPC UA API to interact with an OPC UA server.

    \section1 A short introduction to OPC UA
    OPC UA is a protocol for data modelling and exchange of data in industrial applications.

    An OPC UA server offers access to data which is organized in a mesh of nodes connected by references.
    The use of different reference types and nodes containing metadata enable a client to navigate and interpret
    the data without knowing their structure in advance.

    Each node has a unique identifier and attributes that can be read and written.
    Among others, there are Variable nodes which store values and callable Method nodes with attached nodes describing
    parameters and return values. Notifications in case of events and monitoring of Variable nodes for value changes are offered too.

    Complex objects can be created by combining nodes using references, inheritance is also possible.
    OPC UA offers support for pre-made models which can be extended to fit special needs.

    OPC UA is the platform-independent successor of OPC Classic intended for usage on all levels,
    from embedded sensors up to manufacturing execution and enterprise resource planning systems.
    It has a service-oriented architecture based on standardized messages for service requests and responses.
    There are different ways for these messages to be encoded and transported over the network. The most common way
    is binary encoding over TCP.

    \section1 Implemented features from the OPC UA protocol

    The following features of OPC UA are supported by Qt OPC UA:

    \table
    \header
    \li Feature
    \li Open62541 plugin
    \li UACpp plugin
    \row
    \li Read
    \li X
    \li X
    \row
    \li Batch read
    \li X
    \li
    \row
    \li Write
    \li X
    \li X
    \row
    \li Batch write
    \li X
    \li
    \row
    \li Multidimensional arrays
    \li X
    \li
    \row
    \li Browse
    \li X
    \li X
    \row
    \li Data change subscriptions
    \li X
    \li X
    \row
    \li Event subscriptions
    \li X
    \li X
    \row
    \li Modify subscriptions / monitored Items
    \li X
    \li X
    \row
    \li Method calls
    \li X
    \li X
    \row
    \li Browse path resolution
    \li X
    \li X
    \row
    \li GetEndpoints
    \li X
    \li X
    \row
    \li FindServers
    \li X
    \li
    \row
    \li NodeManagement
    \li X
    \li
    \endtable

    \section1 Data types
    A subset of the OPC UA data types is currently supported in Qt OPC UA.
    Most of them are available with all backends.

    \table
    \header
    \li Data type
    \li Open62541 plugin
    \li UACpp plugin
    \li Qt OPC UA data type
    \row
    \li Int16, Int32, Int64
    \li X
    \li X
    \li Directly used
    \row
    \li UInt16, UInt32, UInt64
    \li X
    \li X
    \li Directly used
    \row
    \li Byte
    \li X
    \li X
    \li quint8
    \row
    \li SByte
    \li X
    \li X
    \li qint8
    \row
    \li Boolean
    \li X
    \li X
    \li Directly used
    \row
    \li Double
    \li X
    \li X
    \li Directly used
    \row
    \li Float
    \li X
    \li X
    \li Directly used
    \row
    \li String
    \li X
    \li X
    \li QString
    \row
    \li LocalizedText
    \li X
    \li X
    \li \l QOpcUa::QLocalizedText
    \row
    \li DateTime
    \li X
    \li X
    \li QDateTime
    \row
    \li ByteString
    \li X
    \li X
    \li QByteArray
    \row
    \li XmlElement
    \li X
    \li X
    \li QString
    \row
    \li NodeId
    \li X
    \li X
    \li QString
    \row
    \li GUID
    \li X
    \li X
    \li QUuid
    \row
    \li QualifiedName
    \li X
    \li X
    \li \l QOpcUa::QQualifiedName
    \row
    \li StatusCode
    \li X
    \li X
    \li \l QOpcUa::UaStatusCode
    \row
    \li Range
    \li X
    \li X
    \li \l QOpcUa::QRange
    \row
    \li EUInformation
    \li X
    \li X
    \li \l QOpcUa::QEUInformation
    \row
    \li ComplexNumber
    \li X
    \li X
    \li \l QOpcUa::QComplexNumber
    \row
    \li DoubleComplexNumber
    \li X
    \li X
    \li \l QOpcUa::QDoubleComplexNumber
    \row
    \li AxisInformation
    \li X
    \li X
    \li \l QOpcUa::QAxisInformation
    \row
    \li XV
    \li X
    \li X
    \li \l QOpcUa::QXValue
    \row
    \li Argument
    \li X
    \li
    \li QOpcUa::QArgument
    \row
    \li ExpandedNodeId
    \li X
    \li X
    \li QOpcUa::QExpandedNodeId
    \row
    \li ExtensionObject
    \li X
    \li
    \li QOpcUa::QExtensionObject
    \endtable

    \section1 Classes and ownership
    Two important classes are exposed to the user: QOpcUaClient and QOpcUaNode.

    Objects of both classes are owned by the user and must be deleted when they are no longer needed.

    \section1 Logging categories
    The following logging categories are used by Qt OPC UA
    \table
    \header
    \li Logging Category
    \li Description
    \row
    \li qt.opcua
    \li Plugin independent messages generated by \l QOpcUaProvider and \l QOpcUaClient
    \row
    \li qt.opcua.plugins.open62541
    \li Messages generated by the open62541 plugin
    \row
    \li qt.opcua.plugins.uacpp
    \li Messages generated by the UACpp plugin
    \endtable

    \section1 Licenses

    The Qt OPC UA module is available under commercial licenses from \l{The Qt Company}.
    In addition, it is available under free software licenses.
    These free software licenses are
    \l{GNU Lesser General Public License, version 3}, or
    the \l{GNU General Public License, version 2}.
    See \l{Qt Licensing} for further details.

    Furthermore Qt OPC UA contains plugins under following licenses:

    \section2 Open62541

    The Open62541 plugin is available under the same licenses as Qt OPC UA. The Open62541 library itself
    is licensed under \l {https://open62541}{Mozilla Public License v2.0}.

    \section2 UA CPP

    The UA CPP plugin is available under commercial licenses from \l{The Qt Company}.
    The UA CPP library itself is available under commercial licenses from \l {https://www.unified-automation.com}{Unified Automation}.

    \section1 Related Information

    \list
    \li \l{Building Qt OPC UA Open62541 Plugin}
    \li \l{Building Qt OPC UA UACPP Plugin}
    \li \l{Qt OPC UA C++ Classes}{C++ Classes}
    \li \l{Qt OPC UA QML Types}{QML Types}
    \li \l{Qt OPC UA Examples}{Examples}
    \li \l{https://opcfoundation.org/about/opc-technologies/opc-ua/}{OPC UA at the OPC foundation}
    \endlist

*/

/*!
    \page qtopcua-build-open62541.html
    \title Building Qt OPC UA Open62541 Plugin
    \brief Build instructions for the Qt OPC UA Open62541 plugin.

    The Open62541 plugin requires Open62541 v0.3 built with UA_ENABLE_AMALGAMATION=ON.

    When building at the top level, you have to specify the path to the Open62541 SDK:

    \code
        configure OPEN62541_PREFIX=/path/to/sdk
    \endcode

    If you are not building at the top level, this setting has to be given to qmake:

    \code
        qmake </path/to/qtopcua> -- OPEN62541_PREFIX=/path/to/sdk
    \endcode

    If the open62541 header and library files are located in a custom path, different settings must be used:

    \table
    \header
    \li Setting
    \li Value
    \row
    \li OPEN62541_INCDIR
    \li The directory which contains open62541.h
    \row
    \li OPEN62541_LIBDIR
    \li The directory which contains the library file
    \endtable

    For example, the following settings can be used for building the open62541 plugin using a static build
    directly from its build directory without installing it:
    \code
        OPEN62541_INCDIR=/path/to/open62541/build OPEN62541_LIBDIR=/path/to/open62541/build/bin
    \endcode

    The output of the configuration step indicates whether the detection was successful:

    \code
        Open62541 .............................. yes
    \endcode

*/

/*!
    \page qtopcua-build-uacpp.html
    \title Building Qt OPC UA UACPP Plugin
    \brief Build instructions for the Qt OPC UA UACPP plugin.

    When building at the top level, you have to specify the path to the UACPP SDK:

    \code
        configure UACPP_PREFIX=/path/to/sdk
    \endcode

    If you are not building at the top level, this setting has to be given to qmake:

    \code
        qmake </path/to/qtopcua> -- UACPP_PREFIX=/path/to/sdk
    \endcode

    The output of the configuration step indicates whether the detection was successful:

    \code
        Unified Automation C++ SDK ............. yes
    \endcode
*/