diff options
Diffstat (limited to 'examples/knx/doc/feature.qdoc')
| -rw-r--r-- | examples/knx/doc/feature.qdoc | 144 |
1 files changed, 144 insertions, 0 deletions
diff --git a/examples/knx/doc/feature.qdoc b/examples/knx/doc/feature.qdoc new file mode 100644 index 0000000..8daa8e5 --- /dev/null +++ b/examples/knx/doc/feature.qdoc @@ -0,0 +1,144 @@ +/**************************************************************************** +** +** Copyright (C) 2019 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$ +** +****************************************************************************/ + +/*! + \example feature + \title KNX Tunneling Features Example + \ingroup qtknx-examples + + \brief A KNX client for handling KNXnet/IP tunneling features. + + \image features.png "KNX tunneling features example" + + The \e{KNX Tunneling Features} user interface contains various + Qt Widgets, most prominently a \l QTreeWidget to display detailed + information about sent and received KNX tunneling feature messages. + + To get started, users select one of the network interfaces on their + machine in the \uicontrol {Interface} field. Once that is done, the + application automatically performs a continuous search for available + KNXnet/IP devices and displays the results in the \uicontrol {Device} + field. + + To connect to a KKXnet/IP device, either the one preselected in the + \uicontrol {Device} can be used or a different one must be chosen from + the list of discovered devices. + + The application also supports KNXnet/IP secure devices, but to be able to + connect to such a device, a KNX ETS keyring file needs to be imported via + the \uicontrol {File} menu. + + Once a connection is successfully established, the user has the possibility + to send tunneling feature get or set commands and to monitor incoming tunnel + feature info messages. + + The application consists of two classes: + + \list + \li \c MainWindow is a \l QMainWindow that renders the general layout + of the application. + \li \c DeviceItem is a \l QStandardItem that is used to display + and store information about discovered KNXnet/IP devices. + \endlist + + \section1 Main Window Class Definition and Implementation + + \quotefromfile feature/mainwindow.h + \skipto class MainWindow : + \printuntil /^\}/ + + The \c MainWindow class uses a \l QKnxNetIpServerDiscoveryAgent instance + that allows discovering KNXnet/IP servers by sending continuous search + requests to the network that the client is connected to. It also saves an + instance of the \l QKnxNetIpTunnel used to establish the connection to the + KNX network and a list of imported KNX \l QKnxNetIpSecureConfiguration + secure configurations. + + There are signal handlers installed for every signal emitted by the + \l QKnxNetIpTunnel. Here is an example of the setup capturing the + signals emitted when an event occurs targeting the KNXnet/IP connection. + In this specific example, we will also see how to set up the KNXnet/IP + tunnel and connect to the KNXnet/IP device: + + \quotefromfile feature/mainwindow.cpp + \skipto MainWindow::MainWindow + \printuntil { + \dots + \skipto QKnxNetIpTunnel::connected + \printuntil MainWindow::onErrorOccurred); + \dots + \skipto /^\}/ + \printuntil /^\}/ + \skipto void MainWindow::on_connection_clicked + \printuntil /^\}/ + + The \c QKnxNetIpServerDiscoveryAgent is initialized and started after the + user interface has been set up and the necessary tunnel connections have + been made. Here is the code snippet doing it: + + \quotefromfile feature/mainwindow.cpp + \skipto MainWindow::MainWindow + \printuntil { + \dots + \skipto m_discoveryAgent.setTimeout + \printuntil /^\}/ + + There is a signal handler installed for the device discovered signal + emitted by the discovery agent. + When the signal \l QKnxNetIpServerDiscoveryAgent::deviceDiscovered is + triggered, the function \c MainWindow::onDeviceDiscovered() is called. + It adds a new device item to the \uicontrol {Device} if it is not already + there. + + \quotefromfile device/mainwindow.cpp + \skipto void MainWindow::onDeviceDiscovered + \printuntil /^\}/ + + At this point, users can select one of the available devices to establish + a connection, create and send the different types of frames or monitor the + KNX tunneling feature info messages. + The \c MainWindow::on_devices_currentIndexChanged method saves the selected + KNXnet/IP device in the the \c MainWindow instance. + + In this last example, after the user has triggered the \uicontrol {Read} + button and a valid tunneling feature response was received, the function + \c MainWindow::setText() is called and the frame content gets extracted + and visually processed: + + \quotefromfile feature/mainwindow.cpp + \skipto MainWindow::setText + \printuntil /^\}/ + + \section1 The Main Function + + The KNX tunneling feature example \c main() function does not have any + special handling. It looks like the main function for any Qt application: + + \quotefromfile feature/main.cpp + \skipto #include + \printuntil /^\}/ +*/ |