Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference

Running Qtopia

Introduction

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

For the purpose of this document, the term, desktop refers to a desktop computer running a Linux distribution. There is also an application named Qtopia Desktop and this application is either installed as part of the downloaded package or is available from the Trolltech website.

Qtopia can be run in both an emulated environment on a desktop and on an embedded device. Running Qtopia on the desktop is not the real thing of course, but it is great for developing, debugging and demonstrating a product. Running Qtopia on the desktop has some consequences, such as, having better performance than on a real device as Qtopia is running using the processor power of the desktop.

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 detail in the Build Instructions section of the reference documentation. If you have installed an SDK package (SDK Light or SDK Professional) then you will find pre-built binaries for an ARM based embedded device in the arm or arm-debug sub-directories. In a 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 (ARM) binaries are irrelevant. However 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.

The Location of the Binaries

The location of the Qtopia binaries is dependent on the package being used. The following table displays the default locations:

Package Location
Source package $QPEDIR/image/opt/Qtopia/bin
SDK package /opt/Qtopia/bin.

The image directory for source packages may be changed to meet your requirements by using the -prefix option with the configure script.

For example, if you have installed qtopia-phone-src-2.2.0 in ~/build/qtopia-phone-2.2.0 then your binaries will be in ~/build/qtopia-phone-2.2.0/qtopia/image/opt/Qtopia/bin. If however you have configured Qtopia with -prefix ~/myimage then the binaries will be found in the directory ~/myimage.

Why an Image Directory?

The image directory is provided to contain everything that should go onto the real device. It is a prepared package containing all the files and relative links in the correct places. This will make packaging and deployment efforts to install Qtopia with your own applications onto a device a lot easier.

Running Qtopia on the Desktop Machine

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

package location
SDK package /opt/Qtopia/bin/startdemo
source package qtopia_root_dir/qtopia/bin/startdemo
where qtopia_root_dir is the install location of the source package.

The startdemo script performs the following:

To quit Qtopia right click the outside area of QVFb and selecting File->Quit, this closes all Qtopia applications.

QVFb is run using a specific skin depending on the package installed. 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 startdemo script can be used in all cases to conveniently start Qtopia. In exceptional cases where the script does not perform as expected, it is is advised to take the script as the starting point and modify the procedure to meet your specific requirements.

The startdemo script accepts two parameters:

    -skin skin .... The name of the skin to be used for the run.
    -home home .... The HOME path setting that is to be used by Qtopia.

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

 
    startdemo -help 

Note: To connect to a modem device instead of the simulator, modify the QTOPIA_PHONE_DEVICE variable and DO NOT start phonesim. If the startdemo script is used, it will automatically skip the phone simulator unless this variable is set to sim:localhost. This subject is discussed in more detail in one of the next sections.

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.

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

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) 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/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 desk:/path/to/image -orsize=8192,wsize=8192 /opt/Qtopia
    
  4. You should now be able to fill /path/to/image on your desktop machine (named desk) 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 clearly 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/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.

So, 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 "QPE/System" "execute(QString)" "calibrate"

This outputs calibration information to the $HOME/Settings/pointercal file which should be copied to i/etc/ to avoid repeating this process.

Note: QPE_NEED_CALIBRATION must be defined in the custom-<platform-spec>.h file. See alsa:o Qtopia - Customizing Qtopia for a Device .

Connecting Qtopia Phone to a 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 startdemo 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.

Further phone simulator information is available in the Tools section of the reference documentation. To call to peers in the same network the peers.xml file must be modified by entering valid machine names within your network environment.

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
where:

The environment variable QTOPIA_PHONE_DEVICE 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.

Using a Real Phone

Qtopia Phone is tested with real phones such as the Ericson T39M. To connect to a phone, use the serial cable provided with the phone and use the command:

     export QTOPIA_PHONE_DEVICE=/dev/ttyS1:115200
where:

This environment variable must be set before Qtopia Phone is started, however, it is not necessary to start the phonesim application.

How do I Switch between Qtopia PDA and Qtopia Phone?

The answer is simple: you can't.

There is no such thing as a command line switch to toggle between Phone and PDA. The way Qtopia looks and behaves is determined by the way it is configured at compile time. After that, the binaries are either Qtopia Phone binaries or Qtopia PDA binaries.

If you have a SDK package then the package is pre-built for either Phone or PDA, and if you have a Qtopia source package then the package is either suitable for building Qtopia Phone or Qtopia PDA, but not both.

The exception to the rule is the refboard-source package which will allow both Phone and PDA configurations.


Copyright © 2005 Trolltech Trademarks
Qtopia version 2.2.0