Home · All Classes · Grouped Classes · Annotated · Functions

Running Qtopia

Introduction

This document describes the commands required to run Qtopia. It is assumed that the Qtopia binaries have been installed using either:

Qtopia can be run connected to either the Qt Virtual Framebuffer(QVFb) on a desktop or a real framebuffer on an embedded device. Running Qtopia connected to the QVFb is ideal for developing code, debugging and demonstrating a product. However Qtopia will need to be run on the embedded device to provide a clearer indication of performance and how well the embedded device's hardware interacts with Qtopia.

Running Qtopia on an embedded device requires different binaries from those used to run Qtopia on the desktop. Creating binaries for an embedded device is not difficult and is done using a cross-compiler. This is handled in the Detailed Build Instructions section of the reference documentation. If you have installed an SDK package then you will find pre-built binaries for an embedded device in specific sub-directories, for instance /opt/Qtopia/SDK/<version>/greenphone. In an SDK package these binaries cannot be rebuilt. For a Qtopia source package the binaries can be built in any configuration required.

If you only want to run Qtopia on your desktop machine at this time, then the device-specific binaries are irrelevant. If you do want to run Qtopia on a device then it is assumed that the binaries for that specific type of device are available.

If this is your first encounter with Qtopia and/or cross-compiling then it might be best to start with experimenting on the desktop and when you are comfortable with that, start running Qtopia on a device.

Prefix vs Image

Qtopia installs into the image directory but it expects to be run from the prefix directory. If you are unfamiliar with how these locations are handled, please see Image, prefix and SDK location.

If you are building against the Greenphone SDK, the image is located at /opt/Qtopia/SDK/<version>/<device>/image. Note that device is either x86 or greenphone.

If the prefix is not the same as the image, you will need to move your files before you can run them. Qtopia cannot run from a directory other than the prefix.

Environment Settings to Run Qtopia

There are no specific environment variables required to run Qtopia, however there are some that can be set to control Qtopia's features.

If you specified -no-rpath you will need to set LD_LIBRARY_PATH so that the libraries can be found.

Qtopia does not require PATH to be set but third party applications may expect it to include <prefix>/bin.

You may wish to set some environment variables to configure Qtopia Core. You may also need to set QTOPIA_PHONE_DEVICE. See Qtopia Environment Variables for details on how to set environment variables.

Running Qtopia on the Desktop Machine

To run Qtopia on the desktop a runqtopia script is provided. The exact location of the script depends on the package:

packagelocation
SDK package/opt/Qtopia/SDK/scripts/runqtopia
Source package<qtopia-root-dir>/bin/runqtopia

where <qtopia-root-dir> is the install location of the source package.

The runqtopia script is designed to ease the burden of running multiple Qtopia versions on a single machine. It launches QVFb and ensures that Qtopia can talk to it by setting QWS_DISPLAY. It also changes the value of HOME since running multiple Qtopia versions with the same HOME directory can cause problems.

To quit Qtopia and close all Qtopia applications close the virtual framebuffer.

QVFb is run using a skin to make it feel more like a real device. A skin is simply a set of XML files that define the look and feel of QVFb. You may use a different skin, or create your own to replicate your target device. If you are not familiar with QVFb please refer to: Qtopia QVFb before continuing.

In practice the runqtopia script can be used in all cases to conveniently start Qtopia. In cases where the script does not perform as expected, it is is advisable to take the script as the starting point and modify the procedure to meet your specific requirements.

For further information and a description of environment variables used by the script, use the command:

    runqtopia -help

For your convenience the options are reproduced here.

Note:

Running Qtopia on an Embedded Device

This section describes the procedure to run Qtopia on a device and is the same for all Qtopia editions.

Note: The $QWS_DISPLAY environment variable must specify a value for mmWidth and mmHeight so that the screen DPI can be correctly calculated.

Qtopia can made available into the device in the following ways:

Once that has been done it is convenient to run Qtopia using scripts see: Running Qtopia on the device using qpe.env and qpe.sh

Using an NFS Mount Partition

This section describes how to run Qtopia on a device using an NFS mount partition.

To use an NFS mount partition your device requires a network connection with the desktop machine and accesses Qtopia binaries on the desktop machine. The binaries must be cross-compiled for the device-type (e.g. ARM) and you control the start/stop of Qtopia through a terminal connection to the device.

This approach is ideal for some debugging and testing on a real device. The binaries can be quickly modified and re-built and the application under test can be restarted almost instantly. It provides an efficient work process when compared with the delays introduced by building packages and the usually very slow upload and flash process required to run Qtopia from a standalone device. Performance debugging should not be made using this technique, as the lag in network operations will hinder performace.

Step 1: Setting up the Device

To setup the device, use command line tools (or whatever is available on the device) to setup the network configuration and use ifconfig to determine the IP address. Note: Network settings in Qtopia can be used, however, you would need to exit that Qtopia in order to run over the network.

Step 2: Exporting the Qtopia Image Directory to the Device

To export the Qtopia image directory to the device, execute the following commands on the desktop machine:

  1. First verify that NFS is running:
         ps aux | grep nfs

    Output will be something like this:

        tester@desk:~> ps aux | grep nfs
        root     10661  0.0  0.0     0    0 ?        SW   16:20   0:00 [nfsd]
        root     10662  0.0  0.0     0    0 ?        SW   16:20   0:00 [nfsd]
        tester     10554  0.0  0.1  3540  564 pts/8    S    16:12   0:00 grep nfs

    If you only get the bottom line, then NFS is NOT running and needs to be started.

    To start NFS use /etc/init.d/nfsserver start (or similar command) as root.

  2. indicate to NFS to export a directory by editing the /etc/exports file (as root) and adding the following line:
             /path/to/image/ *(ro)

    This exports the /path/to/image directory (and all subdirectories), and gives read-only access from any computer. In this procedure it is assumed this is the directory you want to export.

  3. indicate to NFS (again as root) that the configuration has changed using:
             exportfs -a

    The Qtopia binaries in /path/to/image/Qtopia/bin are now accessible from the network.

Step 3: Connecting to the Device

  1. login to the connected device via telnet or ssh (using the IP address displayed in the current tab)
  2. enter your password as root and create the directory on the device that links to the desktop file system using the following command:
             mkdir -p /opt/Qtopia
  3. mount/assign the file system to the device by mounting the created folder using the following command:
            mount hostip:<path to Qtopia image> -orsize=8192,wsize=8192,ro,nolock,tcp /opt/Qtopia
  4. You should now be able to fill <path to Qtopia image> on your desktop machine (named hostip) with files that are accessible from the device.

Using a Binary Flashed onto the Device

This is the ultimate goal and is mentioned here for completeness. However, this option is device specific and not within the scope of this introduction.

As a general rule Qtopia (or any other application) can be flashed onto a device using a CF or SD card or can be uploaded onto the device using a serial connection. Usually this means the image (for example, <path to Qtopia image>) must first be packed into a special file such as initrd.bin. This file is uploaded and flashed into the device flash memory. The correct procedure is entirely dependent on the device used and cannot be described here. Please refer to the device manufacturers documentation for details of installing to the device.

Once the software is installed on the device the general rule is to reboot the device and the Linux boot script will ensure that Qtopia is started automatically. If this doesn't work it is a system integration task to modify the relevant boot scripts.

From a Qtopia perspective, running Qtopia on a device means: power on the device and off you go!

For more information about system integration refer to System Customization.

Touchscreen Phone Calibration

When building Qtopia Phone edition for a touchscreen device, the touchscreen must be calibrated manually as Calibration is not run automatically. With Qtopia Phone running, enter the following command to start calibration:

          qcop service send Launcher "execute(QString)" "calibrate"

This outputs calibration information to the /etc/pointercal file.

See also: System Customization.

Connecting Qtopia Phone to the Phone Device

Qtopia Phone provides the GUI software that runs on a mobile phone. To make a real phone call the electronics need to connect to a phone network. These electronics are assumed to be in the phone device itself. This section describes how the Qtopia Phone software can be connected to the phone device hardware.

Using a Phone Simulator

The phone simulator is an internal tool used to test part of the Qtopia Phone functionality. It simulates part of the modem functionality and is the first step in debugging software. The simulator has been included in the package because it is well suited to illustrating the capabilities of Qtopia Phone. Please be advised however that the phone simulator is an unsupported tool.

Connect Qtopia Phone to the simulator using the following command:

         export QTOPIA_PHONE_DEVICE=sim:localhost

This must be set before either Qtopia or the simulator are started. If the runqtopia script is used, the default value for the environment variable QTOPIA_PHONE_DEVICE is sim:localhost. It is possible to run Qtopia Phone on one machine (embedded device) and the phone simulator on another machine. To do this replace localhost with the name of the machine on which the phonesim is running.

Note: The phone simulator can be build for either the development host or the target.

Further phone simulator information is available in the Tools section of the reference documentation.

Using a Phone Device

Qtopia Phone can be connected to a real phone device using a serial connection. Please be advised that the phone device must support the standard AT commands. To connect use the following command:

         export QTOPIA_PHONE_DEVICE=/dev/ttyS1:115200
         export QTOPIA_PHONE_VENDOR=wavecom

where:

When using Qtopia connect to a modem the environment variables QTOPIA_PHONE_DEVICE and QTOPIA_PHONE_VENDOR must be set before Qtopia Phone is started. Entering a baud rate after the serial port name is optional and depends on the modem being used. It is not necessary to start the phonesim application.

If you wish to start Qtopia with multiplexing disabled then use the following command before starting Qtopia Phone:

         export QTOPIA_PHONE_MUX=no


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3