/**************************************************************************** ** ** 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$ ** ****************************************************************************/ /*! \example knxeditor \title KNX Editor Example \ingroup qtknx-examples \brief A KNX client for handling KNX local device management and tunneling. \image editor-main.png "KNX editor" The KNX Editor user interface contains a \uicontrol Communication group, tabs for different KNX functionalities, and an \uicontrol Output panel. To get started, users select one of the network interfaces on their machine in the \uicontrol {Local IP Address} field, and then select \uicontrol Scan to find any neighbouring KNX routers. Once the client discovers KNX routers, information about them is displayed in the \uicontrol Output panel. Users must select a router to enable the tab views. In the \uicontrol {Local Device Management} tab, users can customize the KNX frame and some parameters. They can choose the local management service type request to send and attach data values to it. The request is sent after the users select \uicontrol Connect. The received response is displayed in the tab. The following image shows an M_PropRead.req request that was sent and the response that was received. \image editor-devman.jpg "local device management tab" The \uicontrol Tunneling tab allows establishing a KNXnet/IP tunnel connection to a KNX router. The tunnel is established by selecting \uicontrol Connect. It is then possible to send data link layer service requests and customize the parameters contained in the requests. The following image shows an example of sending an L_Data.req request. \image tunnel-tab.jpg The \uicontrol {Tunneling Features} tab requires a KNX router that supports tunneling version 2. It allows accessing information such as the device descriptor of the host device and other properties. It is an extension that enables users to access the required management information over their authorized tunneling connection only. The \uicontrol Output panel shows the traffic moving over the connection between the client and the server. The application consists of four classes: \list \li \c MainWindow is a \l QMainWindow that renders the general layout of the application. \li \c LocalDeviceManagement is a \l QWidget connected to the \uicontrol {Local Device Management} tab. \li \c Tunneling is a \l QWidget asociated with the \uicontrol Tunneling tab. \li \c TunnelingFeatures is a \l QWidget linked to the \uicontrol {Tunneling Features} tab. \endlist Each of the above classes stores a reference to the class definition generated by \c qmake for every designer UI file. Through that reference, the above classes can interact with the graphical components of the application. \section1 Main Window Class Definition and Implementation \quotefromfile knxeditor/mainwindow.h \skipto class MainWindow : \printuntil /^\}/ The \c MainWindow class uses a \l QKnxNetIpServerDiscoveryAgent instance that allows discovering KNXnet/IP servers by sending a search request in the network that the client is connected to. It also saves an instance of QKnxNetIpServerInfo for storing information about the current KNXnet/IP server (router) selected by the user. The \c QKnxNetIpServerDiscoveryAgent is initiated when the \uicontrol Scan button is clicked. Here is the code snippet doing it: \quotefromfile knxeditor/mainwindow.cpp \skipto MainWindow::MainWindow \printuntil { \dots \skipto QPushButton::clicked \printuntil ); \dots There are signal handlers installed for every signal emitted by the discovery agent. Here is an example of one of the setups capturing the \l QKnxNetIpServerDiscoveryAgent::deviceDiscovered signal emitted when a server is found: \quotefromfile knxeditor/mainwindow.cpp \skipto MainWindow::MainWindow \printuntil { \dots \skipto QKnxNetIpServerDiscoveryAgent::deviceDiscovered \printuntil ); \dots In this last example, when \l QKnxNetIpServerDiscoveryAgent::deviceDiscovered is triggered, the function \c MainWindow::showServerAndServices() is called. It displays information about the routers in the \uicontrol Output panel. At this point, users can select one of the available routers to establish a connection, and send the different types of frames using the different features available in the tabs: \quotefromfile knxeditor/mainwindow.cpp \skipto MainWindow::MainWindow \printuntil { \dots \skipto QKnxNetIpServerDiscoveryAgent::finished \printuntil }); \dots \skipto /^\}/ \printuntil /^\}/ \skipto void MainWindow::newServerSelected \printuntil auto info \dots \skipto info.endpoint \printuntil /^\}/ The \c MainWindow::newServerSelected method saves the selected server in the \c MainWindow instance. \section1 Local Device Management Class Definition and Implementation \quotefromfile knxeditor/localdevicemanagement.h \skipto class LocalDeviceManagement : \printuntil /^\}/ Local device management uses an instance of \l QKnxNetIpDeviceManagement for the opening and handling of a device management connection to a KNXnet/IP router. The tunnel is created when the \uicontrol Connect button is clicked. \quotefromfile knxeditor/localdevicemanagement.cpp \skipto LocalDeviceManagement::LocalDeviceManagement \printuntil { \dots \skipto QPushButton::clicked \printuntil }); \dots \skipto /^\}/ \printuntil /^\}/ The \l QKnxNetIpDeviceManagement instance is instructed to connect to the server host that was previously selected. Once the \l QKnxNetIpDeviceManagement::connected signal is triggered, the \uicontrol {Send Request} button gets enabled and the client can begin sending customized device management service requests. The code snippet below shows the handler set up for the \c clicked signal of the \uicontrol {Send Request} button (\c deviceManagementSendRequest): \quotefromfile knxeditor/localdevicemanagement.cpp \skipto LocalDeviceManagement::LocalDeviceManagement \printuntil { \dots \skipto QKnxNetIpDeviceManagement::connected \printuntil }); \dots \skipto deviceManagementSendRequest, &QPushButton::clicked \printuntil }); \dots \skipto /^\}/ \printuntil /^\}/ \section1 Tunneling Class Definition and Implementation \quotefromfile knxeditor/tunneling.h \skipto class Tunneling : \printuntil /^\}/ The \c Tunneling class holds a \l QKnxNetIpTunnel that enables the opening and handling of a KNXnet/IP client connection to a KNXnet/IP server. Once the class is instantiated, the client establishes the connection when the \uicontrol Connect button is clicked: \quotefromfile knxeditor/tunneling.cpp \skipto Tunneling::Tunneling \printuntil { \dots \skipto QPushButton::clicked \printuntil }); \dots \skipto /^\}/ \printuntil /^\}/ The received KNX frames are decoded and handled here: \quotefromfile knxeditor/tunneling.cpp \skipto Tunneling::Tunneling \printuntil { \dots \skipto QKnxNetIpTunnel::frameReceived \printuntil }); \dots \skipto /^\}/ \printuntil /^\}/ \section1 TunnelingFeatures Class Definition and Implementation \quotefromfile knxeditor/tunnelingfeatures.h \skipto class TunnelingFeatures : \printuntil /^\}/ Similarly to the \c Tunneling class, the \c TunnelingFeatures class uses a \l QKnxNetIpTunnel for opening and handling a KNXnet/IP client connection. However, it makes use of some additional methods for sending the tunneling feature version 2 frames: \l QKnxNetIpTunnel::sendTunnelingFeatureGet and \l QKnxNetIpTunnel::sendTunnelingFeatureSet. Here is the handler for the \c clicked singal of the \uicontrol {Send Message} button (\c tunnelingSend): \quotefromfile knxeditor/tunnelingfeatures.cpp \skipto tunnelingSend, &QPushButton::clicked \printuntil }); \section1 The Main Function The KNX editor \c main() function does not have any special handling. It looks like the main function for any Qt app: \quotefromfile knxeditor/main.cpp \skipto #include \printuntil /^\}/ */