Doc: Add and overview of Qt KNX tunneling classes

Change-Id: Iea63c5f2e48a7822fc327ea87411888a2b1f6e23
Reviewed-by: Karsten Heimrich <karsten.heimrich@qt.io>

9 files changed, 129 insertions, 5 deletions

diff --git a/src/knx/doc/images/qtknx-tunneling-classes.png b/src/knx/doc/images/qtknx-tunneling-classes.png
new file mode 100644
index 0000000..fefdac2
--- /dev/null
+++ b/src/knx/doc/images/qtknx-tunneling-classes.png
diff --git a/src/knx/doc/src/index.qdoc b/src/knx/doc/src/index.qdoc
index 3530a61..b567d8f 100644
--- a/src/knx/doc/src/index.qdoc
+++ b/src/knx/doc/src/index.qdoc
@@ -70,6 +70,7 @@
     \section1 Reference
     \list
     \li \l{Qt KNX Device Management Classes}{Device Management Classes}
+    \li \l{Qt KNX Tunneling Classes}{Tunneling Classes}
     \li \l{Qt KNX C++ Classes}{All C++ Classes}
     \endlist
 
diff --git a/src/knx/doc/src/tunneling.qdoc b/src/knx/doc/src/tunneling.qdoc
new file mode 100644
index 0000000..0c15065
--- /dev/null
+++ b/src/knx/doc/src/tunneling.qdoc
@@ -0,0 +1,109 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** 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$
+**
+****************************************************************************/
+
+/*!
+    \page qtknx-tunneling.html
+    \title Qt KNX Tunneling Classes
+    \brief C++ classes that enable tunneling connections.
+
+    \e Tunneling refers to point-to-point exchange of KNX telegrams over an IP
+    network between a KNXnet/IP server and a KNXnet/IP client for configuration
+    and diagnostics. KNX frames are encapsulated inside IP datagrams. A tunnel
+    is created when Engineering Tool Software (ETS) sends a single KNX frame in
+    a KNXnet/IP frame and waits until the response arrives or a time-out is
+    reached.
+
+    Tunneling is implemented at the KNX data link layer by transferring link
+    layer frames. The KNX application service and data are encapsulated in
+    the transport protocol data unit (TPDU) included in the frame.
+
+    The following diagram shows the main Qt KNX module classes that enable
+    tunneling:
+
+    \image qtknx-tunneling-classes.png
+
+    \section1 Creating Tunneling Connections
+
+    The \l QKnxNetIpTunnel class is used to establish a functional connection
+    from a KNXnet/IP client to the endpoint of a KNXnet/IP server for sending
+    a KNX frame. For more information, see \l{Tunnel Client Example}.
+
+    As an alternative, the QKnxNetIpTunnelingRequestProxy class can be
+    used to read a tunneling request from the generic \l QKnxNetIpFrame
+    class and to create a KNXnet/IP tunneling request frame. Similarly,
+    the \l QKnxNetIpTunnelingAcknowledgeProxy class can be used to create
+    a KNXnet/IP tunneling acknowledgment frame to confirm the reception
+    of the request.
+
+    \section1 Sending Frames Through Tunnels
+
+    \l QKnxLinkLayerFrame objects are sent to the KNX devices on the bus,
+    behind the KNXnet/IP server. In accordance with the KNXnet/IP tunneling
+    specifications, only the \l QKnxLinkLayerFrame::MessageCode values listed
+    below are valid link layer frame message codes to be sent via a KNXnet/IP
+    tunnel connection:
+
+    \list
+        \li \c DataRequest (\c {L_Data.req})
+        \li \c DataConfirmation (\c {L_Data.con})
+        \li \c DataIndication (\c {L_Data.ind})
+        \li \c BusmonitorIndication (\c {L_Busmon.ind})
+        \li \c RawRequest (\c {L_Raw.req})
+        \li \c RawIndication (\c {L_Raw.ind})
+        \li \c RawConfirmation (\c {L_Raw.con})
+        \li \c ResetRequest (\c {M_Reset.req})
+    \endlist
+
+    Each KNXnet/IP tunneling connection corresponds to a KNX individual address
+    (\l QKnxAddress) that is assigned to the connection by the server. The
+    individual address must be unique within the open tunneling connections of
+    the device. A server cannot open two or more tunneling connections with the
+    same individual address.
+
+    The individual address is returned in a connection response data (CRD)
+    structure with the connect response \l QKnxNetIpFrame. The CRD structure
+    is constructed from the generic \l QKnxNetIpCrd class by using the
+    \l QKnxNetIpCrdProxy class. The contents of the KNXnet/IP frame can be
+    read by using the \l QKnxNetIpConnectResponseProxy view class.
+
+    If the KNXnet/IP server has no free addresses available, the connection
+    response contains the error code \l QKnx::NetIp::NoMoreUniqueConnections.
+
+    In addition to the individual address, link layer frames
+    contain the KNX application service the client wants to
+    use (\l QKnxTpdu::ApplicationControlField) and the data
+    (\l QKnxDatapointType, for write services).
+
+    The \l QKnxLinkLayerFrame::Builder class can be used to create valid link
+    layer frames. It is set up with default values to create a common external
+    message interface (cEMI) group value read frame, except for the destination
+    address, which needs to be specified during the creation of the frame.
+
+    \section1 List of Tunneling Classes
+
+    \annotatedlist qtknx-tunneling
+*/
diff --git a/src/knx/netip/qknxnetiptunnel.cpp b/src/knx/netip/qknxnetiptunnel.cpp
index e21b19b..8303235 100644
--- a/src/knx/netip/qknxnetiptunnel.cpp
+++ b/src/knx/netip/qknxnetiptunnel.cpp
@@ -38,6 +38,8 @@ QT_BEGIN_NAMESPACE
     \class QKnxNetIpTunnel
 
     \inmodule QtKnx
+    \ingroup qtknx-tunneling
+
     \brief The QKnxNetIpTunnel class enables the opening and handling
     of a KNXnet/IP client connection to a KNXnet/IP server.
 
@@ -62,7 +64,7 @@ QT_BEGIN_NAMESPACE
         tunnel.sendFrame(frame);
     \endcode
 
-    \sa QKnxLinkLayerFrame
+    \sa QKnxLinkLayerFrame, {Qt KNX Tunneling Classes}
 */
 
 /*!
diff --git a/src/knx/netip/qknxnetiptunnelingacknowledge.cpp b/src/knx/netip/qknxnetiptunnelingacknowledge.cpp
index 1cdef43..f6f55d3 100644
--- a/src/knx/netip/qknxnetiptunnelingacknowledge.cpp
+++ b/src/knx/netip/qknxnetiptunnelingacknowledge.cpp
@@ -35,6 +35,8 @@ QT_BEGIN_NAMESPACE
     \class QKnxNetIpTunnelingAcknowledgeProxy
 
     \inmodule QtKnx
+    \ingroup qtknx-tunneling
+
     \brief The QKnxNetIpTunnelingAcknowledgeProxy class provides the means to
     read a tunneling acknowledgment from the generic \l QKnxNetIpFrame class
     and to create a KNXnet/IP frame based on the information.
@@ -76,7 +78,7 @@ QT_BEGIN_NAMESPACE
         auto tunnelStatus = tunnelAck.status();
     \endcode
 
-    \sa builder(), QKnxNetIpTunnelingRequestProxy
+    \sa builder(), QKnxNetIpTunnelingRequestProxy, {Qt KNX Tunneling Classes}
 */
 
 /*!
diff --git a/src/knx/netip/qknxnetiptunnelingrequest.cpp b/src/knx/netip/qknxnetiptunnelingrequest.cpp
index 57ccc98..4c2a20d 100644
--- a/src/knx/netip/qknxnetiptunnelingrequest.cpp
+++ b/src/knx/netip/qknxnetiptunnelingrequest.cpp
@@ -36,6 +36,8 @@ QT_BEGIN_NAMESPACE
     \class QKnxNetIpTunnelingRequestProxy
 
     \inmodule QtKnx
+    \ingroup qtknx-tunneling
+
     \brief The QKnxNetIpTunnelingRequestProxy class provides the means to read
     a tunneling request from the generic \l QKnxNetIpFrame class and to create
     a KNXnet/IP frame based on the information.
@@ -77,7 +79,8 @@ QT_BEGIN_NAMESPACE
         auto knxLinkFrame = tunnelRequest.cemi();
     \endcode
 
-    \sa builder(), QKnxNetIpTunnelingAcknowledgeProxy
+    \sa builder(), QKnxNetIpTunnelingAcknowledgeProxy,
+    {Qt KNX Tunneling Classes}
 */
 /*!
     \fn QKnxNetIpTunnelingRequestProxy::QKnxNetIpTunnelingRequestProxy()
diff --git a/src/knx/qknxlinklayerframe.cpp b/src/knx/qknxlinklayerframe.cpp
index b5173fe..059bdf9 100644
--- a/src/knx/qknxlinklayerframe.cpp
+++ b/src/knx/qknxlinklayerframe.cpp
@@ -38,6 +38,8 @@ QT_BEGIN_NAMESPACE
     \class QKnxLinkLayerFrame
 
     \inmodule QtKnx
+    \ingroup qtknx-tunneling
+
     \brief The QKnxLinkLayerFrame class is a frame that is sent over a
     communication channel established between a KNXnet/IP client and a
     KNXnet/IP server.
@@ -64,6 +66,8 @@ QT_BEGIN_NAMESPACE
     (encoded with the \l QKnxTpdu::ApplicationControlField) held in \l QKnxTpdu.
     The application services are split into categories according to the
     addressing method.
+
+    \sa {Qt KNX Tunneling Classes}
 */
 
 /*!
diff --git a/src/knx/qknxlinklayerframebuilder.cpp b/src/knx/qknxlinklayerframebuilder.cpp
index e13e773..70bbeb6 100644
--- a/src/knx/qknxlinklayerframebuilder.cpp
+++ b/src/knx/qknxlinklayerframebuilder.cpp
@@ -42,6 +42,7 @@ QT_BEGIN_NAMESPACE
 
     \inmodule QtKnx
     \inheaderfile QKnxLinkLayerFrameBuilder
+    \ingroup qtknx-tunneling
 
     \brief The QKnxLinkLayerFrame::Builder class provides the means to create a
     KNX link layer frame.
@@ -80,7 +81,7 @@ QT_BEGIN_NAMESPACE
         tunnel.sendFrame(frame);
     \endcode
 
-    \sa QKnxLinkLayerFrame
+    \sa QKnxLinkLayerFrame, {Qt KNX Tunneling Classes}
 */
 
 /*!
diff --git a/src/knx/qknxtpdu.cpp b/src/knx/qknxtpdu.cpp
index a67ec5f..69edb5c 100644
--- a/src/knx/qknxtpdu.cpp
+++ b/src/knx/qknxtpdu.cpp
@@ -198,6 +198,8 @@ public:
     \class QKnxTpdu
 
     \inmodule QtKnx
+    \ingroup qtknx-tunneling
+
     \brief The QKnxTpdu class represents a TPDU, which is the part of a link
     layer frame to be read by the network, transport, and application layers.
 
@@ -217,7 +219,7 @@ public:
     KNXNet/IP clients and servers to make sure the all packages are received
     and that they arrive in the correct order.
 
-    \sa QKnxLinkLayerFrame
+    \sa QKnxLinkLayerFrame, {Qt KNX Tunneling Classes}
 */
 
 /*!