diff options
Diffstat (limited to 'examples/knx/doc/knxeditor.qdoc')
-rw-r--r-- | examples/knx/doc/knxeditor.qdoc | 229 |
1 files changed, 224 insertions, 5 deletions
diff --git a/examples/knx/doc/knxeditor.qdoc b/examples/knx/doc/knxeditor.qdoc index 11e2906..f72d4e1 100644 --- a/examples/knx/doc/knxeditor.qdoc +++ b/examples/knx/doc/knxeditor.qdoc @@ -29,12 +29,231 @@ \example knxeditor \title KNX Editor Example \ingroup qtknx-examples - \brief A simple KNX client. - \e {KNX Editor} shows how to discover a KNX netIP server, configure a - connection, and construct a frame. + \brief A KNX client for handling KNX local device management and + tunneling. - The output shows the traffic moving over the connection between the client - and the server. + \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 /^\}/ */ |