1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
/****************************************************************************
**
** 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 /^\}/
*/
|
