summaryrefslogtreecommitdiffstats
path: root/src/doc/src/qtee-troubleshooting.qdoc
blob: dc8a5fc9e57bc8fea29d8fc85337491f980e7cc9 (plain)
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
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
/****************************************************************************
**
** Copyright (C) 2014 Digia Plc
** All rights reserved.
** For any questions to Digia, please use the contact form at
** http://www.qt.io
**
** This file is part of Qt Enterprise Embedded.
**
** Licensees holding valid Qt Enterprise licenses may use this file in
** accordance with the Qt Enterprise License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.
**
** If you have questions regarding the use of this file, please use
** the contact form at http://www.qt.io
**
****************************************************************************/

/*!
    \page qtee-troubleshooting.html
    \title Troubleshooting
    \previouspage qtee-changelog.html
    \nextpage qtee-known-issues.html

    See also the list of \l {Known Issues}.

    \table
    \header \li \b {General Issues}
    \row \li \l{ts-01}{I have problems deploying/launching the application in Qt Creator}
    \row \li \l{ts-02}{I have problems deploying/launching a Qt or Qt Quick example application}
    \row \li \l{ts-03}{I have problems launching or running applications on hardware after updating the SDK}
    \row \li \l{ts-04}{Booting BD-SL-i.MX6 stops with '6x_bootscript not found' error}
    \row \li \l{ts-07}{How do I get HDMI output working properly on BeagleBone Black?}
    \row \li \l{ts-09}{Something crashed!}
    \row \li \l{ts-10}{Mouse or touch input does not work}
    \row \li \l{ts-11}{Application stops with 'EGLFS: OpenGL windows cannot be mixed with others.'}
    \row \li \l{ts-12}{I cannot edit the contents of appcontroller.conf on the device}
    \row \li \l{ts-13}{How to enable C++11 features}
    \header \li \b {Connectivity Issues}
    \row \li \l{ts-14}{I cannot connect to my hardware device via USB}
    \row \li \l{ts-15}{adb fails with "error: more than one device and emulator"}
    \row \li \l{ts-16}{The emulator cannot connect to the Internet}
    \row \li \l{ts-17}{The emulator is stuck in \e{Waiting for display data} or fails to start properly}
    \row \li \l{ts-18}{What are the user and password to access my embedded Linux device?}
    \endtable

    \section1 General Issues

    \target ts-01
    \b{I have problems deploying/launching the application in Qt Creator}

    Check that the device is properly connected to the development host via USB
    or Ethernet (depending on the device).
    See \l{Connectivity Issues}.

    If using the emulator, see \l{Installing VirtualBox}.

    \target ts-02
    \b{I have problems deploying/launching a Qt or Qt Quick example application}

    Because of a technical peculiarity in \c{qmake}, it is not
    possible to get correct deployment setup for any application that
    is placed inside a Qt source code tree.

    The workaround is to copy the example sources to a location
    outside the Qt source tree, and open this copy of the example
    application instead.

    \target ts-03
    \b{I have problems launching or running applications on hardware after updating the SDK}

    Remember to repeat the process of updating also your device with the latest
    version of \B2Q. See \l{Installing Boot to Qt on Target Devices}.

    \target ts-04
    \b{Booting BD-SL-i.MX6 stops with '6x_bootscript not found' error}

    Check the U-Boot version number. It should start with either \c{2012} or \c{2013}.
    If it is \c{2009.xx}, an upgrade of the bootloader is required. For more
    information, see:

    \list
        \li \l http://boundarydevices.com/6q_bootscript/
        \li \l http://boundarydevices.com/switching-u-boot-versions-on-i-mx6/
    \endlist

    \target ts-07
    \b{How do I get HDMI output working properly on BeagleBone Black?}

    Depending on the HDMI monitor, the cable, and the build variant of
    the BeagleBone Black device, it may not be able to drive an HDMI display in a
    stable way; the image may disappear or stutter. These issues are not caused by
    the \B2Q stack.

    More details and possible solutions can be found
    \l {http://www.elinux.org/Beagleboard:BeagleBoneBlack_HDMI}{here}.

    \target ts-09
    \b{Something crashed!}

    The following command shows the system log:
    \badcode
        <INSTALL_DIR>/Tools/b2qt/adb logcat
    \endcode

    \note When terminating an application from Qt Creator, you may see the
    message \e {Terminating application. Error running process: Process crashed}.
    This is normal and does not indicate a problem in your code; a SIGTERM
    signal is sent to the application, and Qt interprets it as a crash.

    \target ts-10
    \b{Mouse or touch input does not work}

    See \l{Customization}.

    \note On Embedded Linux hotplugging is usually supported for mouse and
    keyboard devices.

    \target ts-11
    \b{Application stops with 'EGLFS: OpenGL windows cannot be mixed with others.'}

    OpenGL and Qt Quick 2 applications can only have one
    fullscreen window existing at a time. Trying to create another
    OpenGL window, or trying to mix an OpenGL window with a raster one
    will display the above message and abort the application.

    \note For raster windows (software rendered content based on QWidget or
    QPainter), there is no such limitation.

    \target ts-12
    \b{I cannot edit the contents of appcontroller.conf on the device}

    The file system where this file is located may be mounted as read-only.

    See \l{Customization}.

    \target ts-13
    \b{How to enable C++11 features}

    To enable C++11 features in the compiler, add \e{CONFIG += c++11} to the .pro file.

    \section1 Connectivity Issues
    \target ts-14
    \b{I cannot connect to my hardware device via USB}

    See \l{5. Setting up USB Access to Embedded Devices}.

    \target ts-15
    \b{adb fails with "error: more than one device and emulator"}

    You have to specify which device you want \c{adb} to talk
    to, using adb's \c{-s <serial-number>} option. Use the following
    command to find to see the serial number of the connected
    devices:

    \badcode
        <INSTALL_DIR>/Tools/b2qt/adb devices
    \endcode

    \target ts-16
    \b{The emulator cannot connect to the Internet}

    By default, the VirtualBox is configured to use a host-only network, so external
    connections do not work in the emulator.

    You may be able to enable Internet connectivity with another
    virtual network adapter in NAT mode by adapting
    \l{http://askubuntu.com/questions/293816/in-virtualbox-how-do-i-set-up-host-only-virtual-machines-that-can-access-the-in}{these}
    instructions.

    \target ts-17
    \b{The emulator is stuck in \e{Waiting for display data} or fails to start properly}

    Check the output of the following command:

    \badcode
        <INSTALL_DIR>/Tools/b2qt/adb devices
    \endcode

    If the emulator (192.168.56.101) is not listed there, try connecting to it:

    \badcode
        <INSTALL_DIR>/Tools/b2qt/adb connect 192.168.56.101
    \endcode

    If the emulator is already listed, try disconnecting it:
    \badcode
        <INSTALL_DIR>/Tools/b2qt/adb disconnect 192.168.56.101
    \endcode

    And then close the emulator and retry.

    \target ts-18
    \b{What are the user and password to access my embedded Linux device?}

    Embedded Linux devices can be accessed using user \c{root} and an empty password.
*/

/*!
    \page qtee-known-issues.html
    \title Known Issues
    \previouspage qtee-troubleshooting.html
    \nextpage qtee-licenses.html

    \table
    \header \li \b {Common Issues}
    \row \li \l{ki-01}{Qt Sensors: Sensor Support Depends on Hardware}
    \row \li \l{ki-02}{Qt WebEngine: Widget-based Web View not Available}
    \row \li \l{ki-05}{Limited Support for Multiple Top-Level Windows}
    \row \li \l{ki-06}{QML Debugging not Functional with Qt Quick Compiler}
    \row \li \l{ki-18}{Multi-process Support with the Wayland Windowing System}
    \header \li \b {Device-Specific Issues}
    \row \li \l{ki-07}{BD-SL-i.MX6: Device Stops Working After Disconnecting the Micro-USB Cable}
    \row \li \l{ki-11}{BeagleBone Black: Unstable HDMI output}
    \header \li \b {Emulator-Specific Issues}
    \row \li \l{ki-13}{Qt WebEngine not Available for Emulator}
    \row \li \l{ki-15}{Switching Between Emulators from Different Boot to Qt Versions}
    \endtable

    \section1 Common Issues

    \target ki-01
    \b{Qt Sensors: Sensor Support Depends on Hardware}

    With the sole exception of Nexus 7, reference devices have no built-in sensor hardware.
    \note Sensors can be tested on emulator targets.

    \target ki-02
    \b{Qt WebEngine: Widget-based Web View not Available}

    The \l{Qt WebEngine} API are available only for Qt Quick 2 based applications at the moment.
    The QWidget-based equivalent, such as QWebEngineView, will become supported in a future
    release. For the time being, use the WebEngineView QML type.

    \target ki-05
    \b{Limited Support for Multiple Top-Level Windows}

    OpenGL and Qt Quick 2 applications can only have one full screen window existing at a time.
    Trying to create another OpenGL window, or trying to mix an OpenGL window with a raster one
    will display an error message and abort the application.

    \note Raster windows (software rendered content based on \c QWidget or \c QPainter) do not
          have this limitation.

    \target ki-06
    \b{QML Debugging not Functional with Qt Quick Compiler}

    QML debugging is not fully functional when Qt Quick Compiler is enabled. Support
    for this is planned for a later release.

    \section1 Device-Specific Issues

    \target ki-07
    \b{BD-SL-i.MX6: Device Stops Working After Disconnecting the Micro-USB Cable}

    The device does not respond to touch input after connecting to a host computer via USB, and
    then disconnecting the Micro-USB cable.

    \target ki-11
    \b{BeagleBone Black: Unstable HDMI output}

    Depending on the HDMI monitor, the cable used, and the build variant of the BeagleBone Black
    device, it may not be able to drive the an HDMI display in a stable way; the image may
    disappear or stutter. These issues are not caused by the Boot to Qt stack. More details and
    possible solutions can be found at \l {http://elinux.org/Beagleboard:BeagleBoneBlack_HDMI}.

    \section1 Emulator-Specific Issues

    \target ki-13
    \b{Qt WebEngine not Available for Emulator}

    \l{Qt WebEngine} will not be available on the emulator.

    \target ki-15
    \b{Switching Between Emulators from Different Boot to Qt Versions}

    Switching between multiple Boot to Qt virtual machines is likely to introduce instability,
    emulator startup problems and graphical issues. To avoid these problems, close the previous
    emulator before launching a new one.

    \target ki-18
    \b{Multi-process Support with the Wayland Windowing System}

    Wayland support is currently in an experimental stage. On i.MX6-based devices it is
    possible to run the Weston compositor and run Qt applications as Wayland clients. The
    main limitations are:

    \list 1
        \li Graphical performance is limited. This is especially true when running
        multiple applications at the same time. Tearing and various rendering glitches can
        also be expected. Future versions of the vendor-provided graphics drivers and
        board support packages are expected to improve on this.

        \li Touch input will not be functional in Qt applications. This will be corrected
        in the upcoming releases.

        \li The Qt Virtual Keyboard is fully functional but will show up on a per-window
        basis inside the application window. A global virtual keyboard solution using
        Wayland's text input protocol will be available in the future.

        \li The compositor will likely crash in certain situations. The stability is
        expected to be improved in newer versions of Weston and the vendor-provided BSP.

        \li Tooling: running and especially debugging applications from Qt Creator may
        have issues when the applications are running as Wayland clients. Support for this
        will be improved in future releases.
    \endlist
*/