Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded |

# Running Qtopia

- Introduction
- Using Qvfb to run Qtopia
- The location of the binaries
  - Why is there an image directory?
- Running Qtopia PDA on the desktop
- Running Qtopia Phone on the desktop
  - The Script
  - The Manual Process
- Running Qtopia on an embedded device
  - Using an NFS mount partition
    - Step 1: Setting up the device
    - Step 2: Exporting the Qtopia image directory to the device
    - Step 3: Connecting to the device
  - Using a binary flashed onto the device
- Connecting Qtopia Phone to a phone device
  - Using a phone simulator
  - Using a phone device
  - Using a real phone
- How do I switch between Qtopia PDA and Qtopia Phone?

## Introduction

This document describes the commands required to run Qtopia PDA and Phone. It is assumed that you have the Qtopia binaries available. These will have been installed when the developer sdk, commercial sdk, or demo package (all .rpm packages) was installed.

Note that if you are using a Qtopia source package you will have to build the Qtopia binaries before proceeding.

To avoid some possible confusion: in this document we are referring to the desktop in several occasions. When we say "desktop" we mean your desktop computer running a Linux distribution. There is also an application named "Qtopia Desktop" and this application is either installed as part of the package you have, or you can get it from the Trolltech website. But in any case, in this document we are NOT referring to this "Qtopia Desktop" application.

Qtopia can be run both in an emulated environment on your desktop and on an embedded device. Running Qtopia on the desktop isn't the real thing of course, but it's great for developing, debugging and for demoing your product. Running Qtopia on the desktop has some consequences. To name just two issues: it is running in an emulated environment and it is using the processor power of your desktop so performance may be better or worse than on a real device.

Running Qtopia (or any other application for that matter) on an embedded device requires different binaries then the ones being used for running Qtopia on the desktop. Creating binaries for an embedded device is not difficult and is done using a so called cross-compiler. This is handled in detail in the "Building and Compiling" section of the reference documentation. If you have installed an .rpm package (demo, developer-sdk or commercial-sdk) then you will find pre build binaries for an ARM based embedded device in the arm subdir. For a Qtopia source package you will have to build them yourself (and have the freedom to tweak the configuration).

If you just want to run Qtopia on your desktop machine at this time, then the existance of ARM binaries is irrelevant. If you do want to run Qtopia on a device then it is assumed that you have the binaries for that specific type of device 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 confortable with that start running Qtopia on a device.

## Using Qvfb to run Qtopia

Qvfb is the Qt Virtual Frame Buffer application. It runs as a normal X application on your desktop machine (just like basically any other application runs on that machine) but it provides a so called virtual framebuffer to Qt/Embedded applications. Embedded linux devices write to their screen using a framebuffer, so Qvfb emulates this behaviour by providing a "virtual" framebuffer.

When you start Qvfb it creates some files that the Qt/Embedded application (e.g. Qtopia) detects and by which it can connect to Qvfb, just like it would look for those files on a real device and get connection to it's framebuffer. So to the application running on Qvfb (e.g. Qtopia) there is no difference.

If you try to run an embedded application on your desktop without using Qvfb you'll get a funny behaviour. Your whole screen will look like it's being attacked by a virus and you won't be able to make sense out of it. If this happens, don't freak. Just use Ctrl-C or whatever is available on your machine to close Qtopia and try again but don't forget to start Qvfb first this time.

## The location of the binaries

The location of the Qtopia binaries is dependent on the package being used. The demo package and both the developer and commercial sdk packages place the binaries in `/opt/Qtopia/bin`. If you have build the binaries yourself using a source package you will find (by default) the binaries in `your-qpe-source-dir/image/opt/Qtopia/bin`, but you may change the image directory to your own needs using the -prefix configure option.

For example, if you have installed `qtopia-phone-source-2.1.1` in `~/dev/qtopia-phone-2.1.1` then your binaries will be in `~/dev/qtopia-phone-2.1.1/image/opt/Qtopia/bin` and you have to set QPEDIR to `~/dev/qtopia-phone-2.1.1/image/opt/Qtopia` (please note the missing bin at the end) to be able to run Qtopia. If however you have configued Qtopia with "-prefix ~/myimage" then QPEDIR must be set to "~/myimage" to execute Qtopia.

### Why is there an image directory?

The reason for the image directory is that this contains everything that should go onto the real device. It's a prepared package that contains just the right files in the right places and with the right relative links between them. This should make your packaging and deployment efforts to install Qtopia + your own applications onto a device a lot easier.

## Running Qtopia PDA on the desktop

Running Qtopia PDA on the desktop is pretty straightforward. All you need to do is define where the binaries can be found, start the virtual framebuffer (to simulate an embedded device on your desktop) and then run Qtopia.

- First set QPEDIR
  - For a demo, developer-sdk or commercial-sdk package: `export QPEDIR=/opt/Qtopia`
  - For a source package: `export QPEDIR=your-qpe-source-dir/image/opt/Qtopia`
- Then set the following variables:

         export QTDIR=$QPEDIR
         export PATH=$QPEDIR/bin:$PATH
         export LD_LIBRARY_PATH=$QPEDIR/lib:$LD_LIBRARY_PATH

- run qvfb:

          qvfb &

- and finally run Qtopia:

          qpe

You can quit Qtopia by right clicking on the outside area of Qvfb and selecting File->Quit.

## Running Qtopia Phone on the desktop

When Qtopia is installed using an rpm you can run Qtopia Phone either from a script or by manually working through the steps.

If you have compiled Qtopia yourself you always have to run through the manual steps. The reason for this is that you most likely want to tweak the startup commands anyway, and writing a script yourself will probably take you five seconds.

### The Script

For the convenience of the script type:

`/opt/Qtopia/bin/startphonedemo`

You can quit Qtopia by right clicking on the outside area of Qvfb and selecting File->Quit.

### The Manual Process

In this procedure we assume that the SmartPhone.skin is available in $QPEDIR/bin. This will always be the case if you are using a demo, developer-sdk or commercial-sdk Phone package. If you have build Qtopia using a source package you may want to copy the SmartPhone.skin from the QTEDIR/tools/qvfb directory or maybe you prefer to create your own.

To work through the mechanics yourself:

- First set QPEDIR
  - For a demo, developer-sdk or commercial-sdk package:

                export QPEDIR=/opt/Qtopia
                export QTDIR=$QPEDIR

  - For a Qtopia source package:

                export QPEDIR=your-qpe-source-dir/image/opt/Qtopia
                export QTDIR=your-qte-source-dir

- Then set the following variables:

         export PATH=$QPEDIR/bin:$QTDIR/bin:$PATH
         export LD_LIBRARY_PATH=$QPEDIR/lib:$QTDIR/lib:$LD_LIBRARY_PATH

- Run Qvfb. For a phone you might appreciate something that looks like a phone, so instead of the standard qvfb look and feel we specify a skin.

         qvfb -skin $QPEDIR/bin/SmartPhone.skin &

- Next we start a phone simulator. Please note that there are also ways to connect to a real phone (modem) device instead of the simulator. To connect to a real phone device you have to modify the QTOPIA_PHONE_DEVICE variable and you DON'T want to start phonesim (as described in detail in a later section).

         export QTOPIA_PHONE_DEVICE=sim:localhost
         your-qpe-source-dir/bin/phonesim $QPEDIR/etc/troll.xml &

  The reason we used "your-qpe-source-dir/bin" here is that the phonesim application isn't copied into the image/bin dir. It shouldn't run on a real device and therefore doesn't belong in the image/bin dir.
- Finally run qpe:

         qpe

You can quit Qtopia by right clicking on the outside area of Qvfb and selecting File->Quit.

## Running Qtopia on an embedded device

This section will no longer make a difference between running Qtopia Phone and Qtopia PDA. The basics for running both packages are exactly the same and we trust that you will be able to solve issues that might be different for one package or the other.

### Using an NFS mount partition

This section describes how you can run Qtopia on a device using a NFS mount partition.

The basic idea is that your device has a network connection with your desktop machine and accesses Qtopia binaries on the desktop machine. The binaries must be cross-compiled for the kind of device you want to run them on (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 rebuild and the application under test can be restarted almost instantly. This allows for a much more efficient work process as opposed to the delays introduced by the building of packages (initrd.bin) and usually very slow upload and flash process that are required to run Qtopia from a standalone device.

#### Step 1: Setting up the device

You should use command line tools (or whatever is available on the device) to setup the network configuration and use ifconfig to determine the IP address. You could use the Network settings in Qtopia to do this, but then you would need to exit that Qtopia in order to run the one you are trying to use over the network!

#### Step 2: Exporting the Qtopia image directory to the device

The following commands are to be executed on your desktop machine.

First verify that NFS is running:

        ps aux | grep nfs

You should get an output that looks 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 you have to start it.
To start nfs you should do something like "/etc/init.d/nfsserver start" as root.

Next we have to tell NFS that we want to export a directory.
To do this edit the /etc/exports file (as root) and add the following line:

        your-qpe-source-dir/image/opt/Qtopia/ *(ro)

This basically means you export the your-qpe-source-dir/image/opt/Qtopia/bin directory (and all it's subdirectories), you give access from any computer and the access is read only. In this procedure we assume this is the directory you want to export.

Next you have to tell NFS (again as root) that the configuration has changed:

        exportfs -a

Your Qtopia binaries in your-qpe-source-dir/image/opt/Qtopia/bin should now be accessible from the network.

#### Step 3: Connecting to the device

- login to the connected device via telnet or ssh (using the IP address displayed in the current tab)
- enter your password as root and create the directory on the device that you can link to your desktops file system.

          mkdir -p /opt/Qtopia

- mount/assign your local file system to the device by mounting the created folder using the following command:

          mount desk:your-qpe-source-dir/image/opt/Qtopia -orsize=8192,wsize=8192 /opt/Qtopia

- You should now be able to fill your-qpe-source-dir/image/opt/Qtopia on your desktop machine (named "desk") with files that are accessible from the device.

### Using a binary flashed onto the device

This is obviously the ultimate goal and it is just mentioned here to be complete but 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 (e.g. image/opt/Qtopia) must first be packed into a 'special' file (and get a funny name like initrd.bin). This file is then uploaded and flashed into the devices flash memory. The correct procedure is entirely dependant on the used device and cannot be described here. Consult the device manufacturers documentation for details on how to install Qtopia on the device.

Once the software is installed on the device the general rule might be to reboot the device and the Linux boot script should make sure that Qtopia is started automatically. If this doesn't work it is a system integrators task to modify the responsible boot scripts.

So from Qtopia point of view, running Qtopia on a device means: power on the device and there you go!

For more information about system integrator work please go to the "Integration and Installation" section of the reference documentation.

## Connecting Qtopia Phone to a phone device

Qtopia Phone is the phone GUI software that runs on a mobile phone. To make a 'real' phonecall you will need the electronics 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 Qtopia Phone's functionality. It simulates part of the phone's modem functionality and can be the first step in debugging software. The simulator has been included this 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 that is provided as is.

You can connect Qtopia Phone to the simulator using the following command:

       export QTOPIA_PHONE_DEVICE=sim:localhost

This must be set before Qtopia AND the simulator are started. It is also 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.

You can find more information about the phone simulator in the tools section of the reference documentation. To be able to 'call' to peers in the same network you have to modify the `peers.xml` file and enter machine names that are valid within your network environment.

### Using a phone device

You can also connect Qtopia Phone 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:

- ttyS1 = the serial port
- 115200 = the baudrate

This env variable must be set before qtopia phone is started. Entering a baud rate after the serial port name is optional and depends on the actual modem being used. In this case it is not necessary to start the phonesim application (although it doesn't cause problems if it does run).

### Using a real phone

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

        export QTOPIA_PHONE_DEVICE=/dev/ttyS1:115200

where:

- ttyS1 = the serial port
- 115200 = the baudrate

This env variable must be set before qtopia phone is started. In this case it is not necessary to start the phonesim application (although it doesn't cause problems if it does run).

## How do I switch between Qtopia PDA and Qtopia Phone?

The answer is simple: you can't. So 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 demo, commercial-sdk or binary-sdk (.rpm) package then the package is pre build for either Phone or PDA, and if you have a Qtopia source package then the package is either suitable for building Qtopia Phone or for building Qtopia PDA (but not for both).

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