summaryrefslogtreecommitdiffstats
path: root/src/doc/src/b2qt.qdoc
blob: 633f83ecabd9b30d9c968fc8d6d0a25c77b3099e (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
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
/****************************************************************************
**
** Copyright (c) 2013 Digia Plc and/or its subsidiary(-ies).
**
** Qt and Qt logos are trademarks of of Digia Corporation in Finland and/or
** other countries worldwide. All other trademarks are property of their
** respective owners.
**
**
** Licensees holding valid Qt Commercial licenses may use this document in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Digia.
**
**
****************************************************************************/

/*!
    \contentspage{index.html}{Boot to Qt}
    \page index.html
    \nextpage b2qt-installation-guide.html
    \title Boot to Qt Introduction

    \e{\b{IMPORTANT:} Make sure to follow the \l{Installation Guide}
    closely!}

    \section1 Contents

    \list
        \li \b {\l{Installation Guide}}
        \list
            \li \l{Preparing Nexus 7 for Development}
            \li \l{Preparing BeagleBoard-xM for Development}
            \li \l{Preparing Sabre Lite i.MX 6 for Development}
        \endlist
        \li \b {\l{Building and Running an Example}}
        \li \b {\l{Supported Platforms}}
        \li \b {\l{Troubleshooting}}
    \endlist


    \section1 What is \B2Q?

    \b{\B2Q} is a light-weight UI stack for embedded systems, based on the
    \l{http://qt.digia.com/}{Qt Framework} by Digia.

    \B2Q for embedded Android places Qt on top of an Android
    kernel/baselayer and offers an elegant means of developing
    beautiful and performant embedded devices. It runs on top of
    Android 4.0/4.1 baselayers and has been tested and verified on a
    number of different hardware configurations.

    \B2Q SDK provides a complete software development package for
    creating applications on embedded Android devices. It comes with
    the Qt Creator IDE with preconfigured build targets for hardware
    platforms as well as an \l{Emulator}{emulator}.


    \section1 About Qt

    \l{http://qt.digia.com/}{Qt} is a full development framework with tools
    designed to streamline the creation of applications and user interfaces
    for desktop, embedded and mobile platforms.

    \list
        \li \b{Qt Framework} - intuitive APIs for C++
            and CSS/JavaScript-like programming with
            \b{Qt Quick} for rapid UI
            creation
        \li \b{Qt Creator IDE} - powerful cross-platform integrated development
            environment, including UI designer tools and on-device debugging
        \li \b{Tools and toolchains} - internationalization support, embedded
            toolchains and more.
    \endlist

    With Qt, you can reuse code efficiently to target multiple platforms
    with one code base. The modular C++ class library and developer tools
    enables developers to create applications for one platform and easily
    build and run to deploy also on other platforms.


    \section1 \B2Q vs Qt for Android

    \image b2qt-vs-qt-for-android.png

    \b{Qt for Android} is a port of the Qt Framework to be used for application
    development on the Android platform. Its purpose is to enable development
    of applications that can run on Android devices. For developers writing
    applications for the Android ecosystem, Qt for Android is the right choice.

    \b{\B2Q} for embedded Android tries to strip down the Android
    stack to the bare minimum, relying only on basic Linux
    features. The majority of the Android stack, such as
    \e{SurfaceFlinger} or \e{DalvikVM} is not running in \B2Q,
    resulting in faster startup times, lower memory consumption and
    overall better performance.  */

/*!
    \page b2qt-installation-guide.html
    \title Installation Guide
    \previouspage index.html
    \nextpage b2qt-building-and-running.html

    \e{IMPORTANT: The \B2Q SDK requires the following installation steps to be followed closely.}

    In case of problems, see the \l{Troubleshooting} information.

    \target Requirements for Development Host
    \section1 0. Requirements for Development Host

    A 64-bit Linux system is required to install and use \B2Q
    SDK. Instructions in this documentation assume Ubuntu Linux 64-bit
    12.04 LTS or later. Other Linux distributions may work, but have
    not been tested. C/C++ build essentials must be installed.

    \target Installing 32-bit Support Libraries
    \section1 1. Installing 32-bit Support Libraries

    Some of the build tools in \B2Q are 32-bit programs, and they
    require that support libraries for running 32-bit code are present
    in the system. To install the required packages in Ubuntu, use the
    following command in a terminal:

    \code
    sudo apt-get install g++-multilib ia32-libs
    \endcode

    \target Installing VirtualBox
    \section1 2. Installing VirtualBox

    The emulator in \B2Q relies on VirtualBox virtualization software. You can
    download it from \l{https://www.virtualbox.org/wiki/Linux_Downloads} or
    install it from the command line with the following command:

    \code
    sudo apt-get install virtualbox
    \endcode

    \b{Configuring VirtualBox}

    Open VirtualBox network settings: Select \b{File > Preferences...}
    and click on the \b{Network} tab. Create a new network named
    \e{vboxnet0} and edit its properties:

    \list
        \li Change IPv4 address to 192.168.56.1 and IPv4 network mask to 255.255.255.0.
        \li Check \b{Enable Server} in \b{DCHP Server} tab.
        \li Change server address to 192.168.56.1.
        \li Change both the lower and upper address bounds to 192.168.56.101.
    \endlist

    \section1 3. Installing the \B2Q SDK

    If you have not already installed the \B2Q SDK, do it as follows.

    After downloading the \B2Q SDK binary installer (the file named
    something like \c{Boot2QtSDK-evaluation-64bit-2013xxxxxx-offline}),
    make sure it is executable either by

    \list
        \li Using \c{chmod +x <filename>} command, or
        \li Right-clicking on the file, selecting \b{Properties}, and checking
            \b{Allow executing file as program} on the \b{Permissions} tab.
    \endlist

    Run the installer and follow its instructions.

    The installer will let you select a directory where the entire,
    self-contained \B2Q SDK will be installed. In the rest of this
    documentation, that directory is referred to as
    \c{<SDK_INSTALL_DIR>}. By default, it is
    \tt{/home/\e{yourusername}/Boot2QtSDK}.

    \target Installing Boot to Qt on Target Devices
    \section1 4. Install \B2Q on Target Devices

    \e{If targeting only the emulator, this step may be skipped}

    Before deploying and testing your Qt application on hardware, the
    target device needs to be flashed with an image that contains the
    \B2Q stack. These steps vary from device to device - follow the
    instructions specific to your device:

    \list
        \li \l{Preparing Nexus 7 for Development}
        \li \l{Preparing BeagleBoard-xM for Development}
        \li \l{Preparing Sabre Lite i.MX 6 for Development}
    \endlist

    After preparing the device, power it up and confirm that it shows
    a \B2Q welcome screen and/or demo. Then go on to the installation
    steps below.

    \section1 5. Setting up USB Access to Target Devices

    \e{If targeting only the emulator, this step may be skipped}

    On Ubuntu Linux you have to grant your development user access to
    plugged in devices. This is done by creating a new \e{udev} rule
    that allows access to the device via USB. First, run the following
    command in a shell:

    \code
    echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="18d1", TAG+="udev-acl"' | sudo tee -a /etc/udev/rules.d/70-boot2qt.rules
    \endcode

    Now connect the running device to the development host with a USB
    cable. (If already connected, disconnect and reconnect the USB
    cable after running the command above). Confirm that the
    connection is working by running this shell command:

    \code
    <SDK_INSTALL_DIR>/targets/android-utils/bin/adb devices
    \endcode

    The output should be a list of connected android devices,
    identifed with a serial number and a name. Note that the emulator
    may be listed as well, its serial number will be its IP and port
    number (\c{192.168.56.101:5555}). If your device is missing from
    the list, or the serial number is \c{??????}, the connection is
    not working properly. If so, check that the device is powered up,
    and that the USB cable has been disconnected and reconnected. The
    system log files \c{/var/log/udev} and \c{/var/log/syslog} may
    provide relevant information in case of connection problems.

    \section1 6. Configuring a Device Kit in Qt Creator

    After the hardware has been prepared, there is one final step required
    to set up the development tools in Qt Creator for your device.

    A separate device \b{Kit} needs to be cloned for each hardware device
    you want to develop for.

    To do so, connect your device to your computer via USB and launch
    Qt Creator (\B2Q IDE). Then,

    \list 1
        \li Go to \b{Tools > Options > Build & Run > Kits}
        \li Select one of the predefined Kits starting with \e{Boot2QtSDK...}
        that matches the type of your device.
        \li Click \b{Clone}.
        \li (Optional) Change the name to a shorter one, for example, \e{MyBeagleBoard}.
        \li Select the correct device in the \b{Device} combobox.
        \li Click \b{Ok}.
    \endlist

    You are now ready to start developing for your device!

    See \l{Building and Running an Example}

*/

/*!
    \page b2qt-preparing-hardware-nexus-7.html
    \title Preparing Nexus 7 for Development
    \previouspage b2qt-installation-guide.html

    When using a \l{http://www.google.com/nexus/7/specs/}{Nexus 7} as a
    development device, following steps are required to prepare it for
    \B2Q.

    \section1 Unlocking Nexus 7

    The Nexus 7 has to be unlocked to allow custom software to be installed.
    This procedure can be done directly from the device UI, and needs to be
    done only once.

    \list 1
        \li Power up the device.
        \li Open \b{Settings > Developer Options} (Note: If you don't see \b{Developer Options} directly under \b{Settings}, go to \b{About Tablet}).
        \li Use the slider in the top right corner to enable developer mode. (Note: If you don't see a slider, instead tap the \b{Build Number} entry seven times. You should see a message \e{"You are now a developer!"} displayed.)
        \li In \b{Developer Options}, also enable \b{USB Debugging}.
    \endlist

    Finally, connect your Nexus 7 to your computer via USB, and run
    the following command:

    \code
    sudo <SDK_INSTALL_DIR>/targets/android-utils/bin/fastboot oem unlock
    \endcode


    \section1 Updating a Nexus 7 with \B2Q Images

    \note \b{It is important that the steps in this section are repeated
    every time after updating the \B2Q SDK.}

    An unlocked Nexus 7 device can now be updated with a \B2Q image.

    To do so, connect your Nexus 7 to your computer via USB, and run the
    commands

    \code
    cd <SDK_INSTALL_DIR>/targets/
    ./android-utils/bin/adb reboot bootloader
    \endcode

    The device will reboot into \e{fastboot} mode.

    To re-flash the \e{boot}, \e{system}, and \e{userdata} partitions on the
    device, use the following commands in the order they are listed:

    \code
    sudo ./android-utils/bin/fastboot flash boot nexus7/images/boot.img
    sudo ./android-utils/bin/fastboot flash system nexus7/images/system.img
    sudo ./android-utils/bin/fastboot flash userdata nexus7/images/data.img
    \endcode

    Once the flashing is completed successfully, reboot the device:

    \code
    ./android-utils/bin/fastboot reboot
    \endcode


    \section1 Installing Proprietary Graphics Drivers

    Download the proprietary graphics drivers for your Nexus 7
    \l{https://developers.google.com/android/nexus/drivers#grouperjzo54k}{here}.

    \note Make sure you have read the license terms at the beginning of the
    driver download page.

    Select the link in the \b{Graphics} row from the table
    \e{"Nexus 7 (Wi-Fi) binaries for Android 4.1.2"}, download and save the file
    to the installation directory of the \B2Q SDK.

    Make sure your Nexus 7 is connected to the computer via USB.

    Then, follow these steps to update the Nexus 7:

    \list 1
        \li Extract the downloaded file, and run the extracted installer. For example,
    \code
    cd <SDK_INSTALL_DIR>
    tar xf nvidia-grouper-jzo54k-56de148f.tgz
    ./extract-nvidia-grouper.sh
    \endcode
        \li Find out the serial number of the connected Nexus 7 device:
    \code
    <SDK_INSTALL_DIR>/targets/android-utils/bin/adb devices
    \endcode
        \li Deploy the drivers to your device using the following command:
    \code
    <SDK_INSTALL_DIR>/targets/android-utils/bin/deploy_tegra_drivers_to_nexus7 <serial_number>
    \endcode
    \endlist

    Now make sure to complete all the steps of the \l{Installation Guide}.
*/

/*!
    \page b2qt-preparing-hardware-beagleboard.html
    \title Preparing BeagleBoard-xM for Development
    \previouspage b2qt-installation-guide.html

    When using a \l{http://beagleboard.org/hardware-xM}{BeagleBoard-xM} as a
    development device, following steps are required to prepare it for
    \B2Q.

    \note \b{It is important that the steps in this section are repeated
    every time after updating the \B2Q SDK.}

    The image containing \B2Q stack for BeagleBoard-xM is included in the SDK,
    ready to be copied to a micro-SD card.

    \section1 Preparing a micro-SD card

    A micro-SD card of at least 2GB capacity is needed.

    Plug the micro-SD card/reader into the development host PC and use
    the following command to find out its device path
    (i.e. \c{/dev/XXX}, where \c{XXX} typically is \c{sdb}):

    \code
    df -h
    \endcode

    Alternatively, if the micro-SD card is unformatted, run the following
    command immediately after inserting the card to see its device
    path:

    \code
    dmesg | tail
    \endcode

    Now make sure the micro-SD card is not mounted:

    \code
    umount /dev/XXX
    \endcode

    \section1 Installing the \B2Q image

    Write the image to the micro-SD card:

    \code
    cd <SDK_INSTALL_DIR>
    sudo dd if=targets/beagleboard/images/sdcard.img of=/dev/XXX bs=1M
    \endcode

    \warning \b{Make very sure you select the right device. Selecting the wrong
    one can result in a wiped hard drive}.

    Now make sure to complete all the steps of the \l{Installation Guide}.
*/

/*!
    \page b2qt-preparing-hardware-imx6.html
    \title Preparing Sabre Lite i.MX 6 for Development
    \previouspage b2qt-installation-guide.html

    When using a
    \l{http://boundarydevices.com/products/sabre-lite-imx6-sbc/}{Sabre
    Lite i.MX 6} as a development device, following steps are required
    to prepare it for \B2Q.

    \note \b{It is important that the steps in this section are repeated
    every time after updating the \B2Q SDK.}

    \section1 Preparing a micro-SD card

    A micro-SD card of at least 4GB capacity is needed.

    Plug the micro-SD card/reader into the development host PC and use
    the following command to find out its device path
    (i.e. \c{/dev/XXX}, where \c{XXX} typically is \c{sdb}):

    \code
    df -h
    \endcode

    Alternatively, if the micro-SD card is unformatted, run the following
    command immediately after inserting the card to see its device
    path:

    \code
    dmesg | tail
    \endcode

    Next, make sure the micro-SD card is not mounted:

    \code
    umount /dev/XXX
    \endcode

    \section1 Installing the Android image

    Download the package \e{r13.4.1-nitrogen-20130407.tar.gz} from
    \l{http://boundarydevices.com/i-mx6-images-for-branch-r13-4-1/}{i.MX6
    images for branch r13.4-1}. This requires registration.

    Follow the instructions on the Boundary Devices web site to create
    an SD card containing the downloaded image. We recommend choosing
    the "Tar-ball installation" procedure, as it is much
    quicker. However, in case of problems, the "binary image
    installation" procedure is more failsafe.

    In either case, make sure to replace the device path
    (\c{"/dev/sdc"}) with the micro-SD card's device path that
    was found in the previous step.

    \warning \b{Make very sure you select the right device. Selecting the wrong
    one can result in a wiped hard drive.}

    \section1 Installing the \B2Q image

    Make sure you have the required tools installed in your development machine:

    \code
    sudo apt-get install u-boot-tools
    \endcode

    Then, upgrade the micro-SD Card with \B2Q:

    \code
    <SDK_INSTALL_DIR>/targets/android-utils/bin/deploy_to_iMX6 /dev/XXX
    \endcode

    \warning \b{Make very sure you select the right device. Selecting the wrong
    one can result in a wiped hard drive}.

    \section1 Upgrading the bootloader

    Now plug the micro-SD card into the board and power it up. If
    booting stops with the error message
    \code
    6x_bootscript not found
    \endcode

    check U-Boot version number. It should start with \c{2012} or
    \c{2013}. If it is \c{2009.xx}, an upgrade of the bootloader is
    required. See information and instructions here:

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

    Now make sure to complete all the steps of the \l{Installation Guide}.
*/


/*!
    \page b2qt-building-and-running.html
    \title Building and Running an Example
    \previouspage b2qt-installation-guide.html
    \nextpage b2qt-supported-platforms.html

    Once the installation and configuration steps for the SDK and the
    target device(s) are completed, it's time to test the setup.

    First, make sure your device is powered up and connected to the
    development host via USB.

    Then, follow these steps to create and run a simple \l{Qt Quick}
    application on the device:

    \list 1
        \li Open \b{File > New File or Project}, select
            \b{Qt Quick 2 Application (Built-in Elements)} and click \b{Next}.
        \li In \b{Kit Selection} dialog, select the kit(s) you cloned for your
            devices. You can also select the emulator kit to test running the
            project in the emulator.
        \li Click \b{Next} and finish the wizard.
        \li In \b{Projects > Build & Run}, select the correct kit for your
            connected device. Also, click on \b{Run} to check if the
            \b{Run configuration} of your device kit has a
            \b{Custom Executable} setting, and remove it if present.
        \li To build and run the project, click \inlineimage qtcreator-run.png
    \endlist
*/

/*!
    \page b2qt-supported-platforms.html
    \title Supported Platforms
    \previouspage b2qt-building-and-running.html
    \nextpage b2qt-troubleshooting.html

    \section1 Supported Target Devices

    \B2Q can be made to run on hardware that has support for
    the Android operating system, version 4.0 or later.

    Approximate minimal hardware requirements for running \B2Q for
    embedded Android are:
    \list
        \li 256Mb of RAM
        \li 500Mhz CPU, 1Ghz preferred for 60 FPS velvet-smooth UI
        \li OpenGL ES 2.0 support
        \li Android 4.0+ compatible hardware
    \endlist

    For the technology preview release, the following devices have
    been used as reference and are tested to work:
    \list
        \li \l{http://www.google.com/nexus/7/specs/}{Google/Asus Nexus 7}
        \li \l{http://beagleboard.org/hardware-xM}{BeagleBoard-xM}
        \li \l{http://boundarydevices.com/products/sabre-lite-imx6-sbc/}{Freescale i.MX6 Sabre Lite board (Boundary Devices)}
    \endlist

    \section1 Supported Development Environment

    The development environment supported in \B2Q Technology Preview
    release is Ubuntu Linux 64-bit (12.04 LTS or 12.10). See the
    \l{Requirements for Development Host}.

*/

/*!
    \page b2qt-troubleshooting.html
    \title Troubleshooting
    \previouspage b2qt-supported-platforms.html

    \section1 General Issues

    \section2 I have a problem deploying/launching the application in Qt Creator

    Check if the device is properly connected to the PC via USB.
    See \l{Connectivity Issues}.

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

    In addition, check if \b{Run configuration} of your device kit has a
    \b{Custom Executable} setting, and remove it if present. To see the
    run configuration, click on \b{Projects > Build & Run}, and click
    \b{Run} on the active device kit.

    \section2 I have a problem launching or running applications on hardware after updating \B2Q 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}.

    \section2 How do I restore my Nexus 7 to factory settings?

    Goto \l{https://developers.google.com/android/nexus/images} and
    download the correct file for your device. Unpack it, and then

    \code
    <SDK_INSTALL_DIR>/targets/android-utils/bin/adb reboot bootloader
    <SDK_INSTALL_DIR>/targets/android-utils/bin/fastboot -w update <image-file>.zip
    <SDK_INSTALL_DIR>/targets/android-utils/bin/fastboot reboot
    \endcode

    \section2 How do I shut down the Nexus 7?

    If the \B2Q demo launcher is running, start the "Launcher
    Settings" app, and press the "Power Off" button.

    Otherwise, make sure the Nexus 7 is connected to your PC with USB, and run
    the following command in a terminal:
    \code
    <SDK_INSTALL_DIR>/targets/android-utils/bin/adb shell reboot -p
    \endcode

    Alternatively, press and hold the power button for 10
    seconds. This will force a reboot.

    \section2 Trying to build for the emulator target fails with error message \e{make: i686-android-linux-g++: Command not found}

    You need to install proper libraries in order to run 32-bit programs in 64-bit Linux operating system.

    See \l{Installing 32-bit Support Libraries}.

    \section1 Connectivity Issues
    \section2 I cannot connect to my hardware device via USB

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

    \section2 adb fails with "error: more than one device and emulator"

    You have to specify which android 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:

    \code
    <SDK_INSTALL_DIR>/targets/android-utils/bin/adb devices
    \endcode
*/