diff options
-rw-r--r-- | src/knx/doc/images/qtknx-tunneling-classes.png | bin | 0 -> 9732 bytes | |||
-rw-r--r-- | src/knx/doc/src/index.qdoc | 1 | ||||
-rw-r--r-- | src/knx/doc/src/tunneling.qdoc | 109 | ||||
-rw-r--r-- | src/knx/netip/qknxnetiptunnel.cpp | 4 | ||||
-rw-r--r-- | src/knx/netip/qknxnetiptunnelingacknowledge.cpp | 4 | ||||
-rw-r--r-- | src/knx/netip/qknxnetiptunnelingrequest.cpp | 5 | ||||
-rw-r--r-- | src/knx/qknxlinklayerframe.cpp | 4 | ||||
-rw-r--r-- | src/knx/qknxlinklayerframebuilder.cpp | 3 | ||||
-rw-r--r-- | src/knx/qknxtpdu.cpp | 4 |
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 Binary files differnew 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} */ /*! |