path: root/src/doc/src/b2qt.qdoc

/****************************************************************************
**
** 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{Customization}}
        \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 Bootloader

    The Nexus 7 Bootloader has to be unlocked to allow custom software
    to be installed. This has to be done only once.

    \list 1
        \li Power down the device.
        \li Connect it to the development host with a USB cable.
        \li Start the Nexus up in \e{fastboot} mode: Press the power button for a second, and then keep the Volume Down key pressed, until you see a screen with a green robot with its front panel open. Note: If you get the ordinary startup screen instead, just power it down and try again.
        \li On the development host, give the command
        \code
            sudo <SDK_INSTALL_DIR>/targets/android-utils/bin/fastboot oem unlock
        \endcode
        The Nexus screen will ask if you want to unlock the bootloader. Press power button to confirm.
        \li Wait a few seconds, and check that the text line stating the \c{LOCK STATE} now says \c{UNLOCKED}.
    \endlist

    \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, first make sure that the device is in \e{fastboot} mode
    (see above), and connected to the development host via USB.

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

    \code
    cd <SDK_INSTALL_DIR>/targets
    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
    sudo ./android-utils/bin/fastboot reboot
    \endcode

    Until the next step is performed, the Nexus screen may only show
    the "Google" logo.

    \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 powered up, is \e{not} in fastboot mode,
    and 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-customization.html
    \title Customization
    \previouspage b2qt-building-and-running.html
    \nextpage b2qt-supported-platforms.html

    \section1 Environment and Input

    By default, the basic environment variables and startup options of
    \B2Q applications are set in the file \c
    {/system/bin/appcontroller.conf}.

    This file can be customized if targeting a hardware device that
    has different input devices than what the \B2Q stack is configured
    for by default.

    Note that on some devices, the root file system (where this file
    resides) is mounted read-only at boot time. It needs to be
    remounted read-write to allow modification. The following command
    does that:
    \code
    <SDK_INSTALL_DIR>/targets/android-utils/bin/adb remount
    \endcode

    In the \c{appcontroller.conf} file, the input devices are
    specified by the lines similar to these:
    \code
    append=-plugin
    append=evdevtouch:/dev/input/event0
    \endcode

    The mouse pointer can be turned on and off by removing or adding this line:
    \code
    env=QT_QPA_EGLFS_HIDECURSOR=1
    \endcode
*/

/*!
    \page b2qt-supported-platforms.html
    \title Supported Platforms
    \previouspage b2qt-customization.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

    \e {NOTE: An updated version of this information may be available in the Digia customer portal.}

    \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 deploying/launching a Qt or Qt Declarative 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.

    \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
    \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}.

    \section2 Something crashed!

    The following command shows the system log:
    \code
    <SDK_INSTALL_DIR>/targets/android-utils/bin/adb logcat
    \endcode

    \section2 Mouse or touch input does not work

    See \l{Customization}.

    Note that hotplugging does not currently work; any input device
    must be present at boot time to be recognized.

    \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
*/