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

# System Integrators' Guide

- Introduction
- Getting Qtopia Running
  - Customizing power, backlighting control and keyboard scancodes
  - Create a keyboard handler in Qt
  - Compiling required libs for yor device.
    - Compiling libjpeg for your device
    - Compiling libuuid for your device
  - Configuring Qt/Embedded to suit device
  - Configuring Qtopia to suit device
  - Create and install the Qtopia image for the target device
  - Configuring environment variables on the device to suit Qtopia
  - Initial tests on Qtopia on the device
  - Customize Qtopia to suit GSM module (Qtopia Phone edition only)
  - Selecting components to install
  - Configure serial proxy (Qtopia Phone only)
  - Install extra fonts
  - Customize apprearance

## Introduction

This document is for System Integrators and those who who are going to install Qtopia onto a new device. The various aspects of device integration are drawn together in one place and a suggested order of progression is provided.

See Also:

- devices.html located at devices.html and at $QPEDIR/doc/html/devices.html.
- features.html located at features.html and at $QTEDIR/doc/html/features.html.
- meeting Qtopia prerequists see : Qtopia Dependencies / Prerequisites

## Getting Qtopia Running

This following lists the suggested order in which to work on the various aspects of device integration:

1. Create custom configuration files
2. Customizing power, backlighting control and keyboard scancodes
3. Create a keyboard handler in Qt
4. Configuring Qt/Embedded to suit device
5. Configuring Qtopia to suit device
6. Create and install the Qtopia image for the target device
7. Configuring environment variables on the device to suit Qtopia
8. Initial tests of Qtopia on the device
9. Selecting storage devices
10. Customize Qtopia to suit GSM module (Qtopia Phone only)
11. Selecting components to install
12. Create plugins needed
13. Install extra fonts
14. Customize appearance

### Customizing power, backlighting control and keyboard scancodes

There are several choices on what to base a new custom.cpp. These choices include:

- generic
- innovator
- ipaq
- sharp

The following example creates a new custom.cpp based on the one that supports the ipaq platform.

    cp $QPEDIR/src/libraries/qtopia/custom-linux-ipaq-g++.cpp $QPEDIR/src/libraries/qtopia/custom-linux-myarm-g++.cpp
    cp $QPEDIR/src/libraries/qtopia/custom-linux-ipaq-g++.h $QPEDIR/src/libraries/qtopia/custom-linux-myarm-g++.h

For more details on keyboard scancode and button support see devices-keys-buttons.html

Hints

- To support a calibrated touch screen QPE_NEED_CALIBRATION must be defined by your custom.h

### Create a keyboard handler in Qt

For an oveview on character input in Qt/Embedded see : charinput-qws.html

To add a new driver it is necessary to modify : `$QTDIR/src/kernel/qkeyboard_qws.cpp` see : qwskeyboardhandler.html

### Compiling required libs for yor device.

These instructions are a guide only. Your device may require specific options not mentioned here. Please see the documentation for each package to determine how it is best configured.

Note: You should ensure that the correct compiler is used when building these libraries. Checking the output of the build stage will verify that the correct compiler was used. You can also use the `file` utility to show the architecture fro which a particular library is compiled.

#### Compiling libjpeg for your device

JPEG source can be downloaded from http://www.ijg.org/

You should configure libjpeg with the `--target=arch` option. If `libjpeg.so` is not copied to `$QTDIR` you will need to use the `-L` option when running Qt/Embedded's configure. For example:

    cd $QTDIR
    ./configure -L/path/that/libjpeg/lives/in

#### Compiling libuuid for your device

libuuid is part of the e2fsprogs package which can be downloaded from http://e2fsprogs.sourceforge.net/

You should configure libuuid with the `--target=arch` and `--enable-elf-shlibs` options. If `libuuid.so` is not copied to `$QTDIR` or `$QPEDIR` you will need to use the `-L` option when running Qtopia's configure. For example:

    cd $QPEDIR
    ./configure -L/path/that/libuuid/lives/in

### Configuring Qt/Embedded to suit device

Following on from the above, it is necessary to have added

     -xplatform linux-myarm-g++

as parameters to Qt/Embedded's configure.

Hints

- It is a good idea to have Qte for x86 and Qte for target device in different directories
- For a list of compile time options to Qte run

       $QTDIR/configure --help

Macros defined at Qte compile time | Mouse device used
--- | ---
`QT_QWS_IPAQ` and `QT_QWS_IPAQ_RAW` | `/dev/h3600_tsraw`
`QT_QWS_IPAQ` | `/dev/h3600_ts`
`QT_QWS_SL5XXX` | `/dev/ts`

Hints

- For information about adding a new mouse driver see : pointer-qws.html

### Configuring Qtopia to suit device

Continuing the example above there is need to have added:

     -xplatform linux-myarm-g++

as parameters to Qtopia's configure.

Hints

- For a list of compile time options to Qtopia run

       $QPEDIR/configure --help

- When cross compiling it is preferable to use different directories to keep the x86 and cross complied files.
- To support a calibrated touch screen PrimaryInput=Touchscreen must included in the [Device] group of the $QPEDIR/etc/default-buttons.conf
- To start the calibration process on Qtopia phone device using a calibrated touchscreen driver run:

       qcop "QPE/System" "execute(QString)" "calibrate"

### Create and install the Qtopia image for the target device

When configuring Qtopia for the target device the $QPEDIR/image is the default prefix for the image that Qtopia will create. After building Qtopia and running make install an example of getting the image onto the device is to:

- tar up $QPEDIR/image on the compilation host eg:

              cd $QPEDIR/image
              tar -cf   $HOME/qtopiaimage.tar .

- copy/mount the file onto the target device eg:

              mount -t nfs myhost:/home/myuser /mnt/tmp

- extra the image on target device

              cd /
              tar xf /mnt/tmp/qtopiaimage.tar

### Configuring environment variables on the device to suit Qtopia

Set QPEDIR and QTDIR to where Qtopia was installed, and add Qtopia's programs and libraries to the system paths eg:

            export QPEDIR=/opt/Qtopia
            export QTDIR=$QPEDIR
            export QTEDIR=$QTDIR
            export PATH=$QPEDIR/bin:$PATH
            export LD_LIBRARY_PATH=$QPEDIR/lib:$LD_LIBRARY_PATH

See also running-qtopia.html

### Initial tests on Qtopia on the device

Run the following command : `textedit` -qws

Confirm that:

- the framebuffer is used
- no warnings are shown indicate file reading/writing problems
- Qtopia is working with the installed keyboard. For Qtopia Phone edition check that any softkeys defined work
- run `qpe` and confirm that a program can launched eg: Notes . When using Notes check that new text documents can be created and created appear in the "Documents" tab.

Hints

- For running Qtopia

  See also running-qtopia.html.

### Customize Qtopia to suit GSM module (Qtopia Phone edition only)

Before starting this step ensure that Qtopia is able to communicate to your GSM module and that you can dial and connect normal calls. Also it is highly recommended that you first test your modems ability make GRPS calls just using pppd.

The following is the suggested order in integrating a GSM module into Qtopia

1. GSM module integratation
2. WAP stack integration
3. Configure the serial proxy

### Selecting components to install

Choosing not to build a component, eg Todo, can easily be done via editing $QPEDIR/src/custom.pri and re-configuring Qtopia. For example add the following to the custom.pri `APP_PROJECTS-=applications/todo`

See $QPEDIR/src/custom.pri for extra hints, see also buildsystem.html

### Configure serial proxy (Qtopia Phone only)

Most modern phones have an external serial interface, which is used to connect to a computer for the purposes of data calls, FAX transmissions, or synchronization with desktop applications.

The SerialProxy class assists with this process. It sets up a proxy connection between the external serial interface and an internal GSM 07.10 capable modem. The serial interface may be RS-232, USB, Bluetooth, or any other suitable connection protocol.

We assume that the cable that connects the phone to the computer is wired like a null modem, even if the "cable" is USB, Bluetooth, etc:

TD | --> | RD
RD | <-- | TD
DTR | --> | DSR, DCD
CTS | <-- | RTS
RTS | --> | CTS
DSR, DCD | <-- | DTR

If the cable isn't wired in this fashion, then the SerialProxy code may need to be modified for a specific device.

The external device must be configured in the `Phone.conf` file. For example:

    [SerialDevices]
    ExternalAccessDevice=/dev/ttyS1
    ExternalAccessSpeed=115200

The `Phone.conf` file needs to be placed under the "etc/default" directory on a vendor's system.

Warning

Using a serial proxy is not possible when connecting Qtopia to a serial port on a phone such as the T39M. In such a case ensure that `Phone.conf` file does not contain an entry for "ExternalAccessDevices".

### Install extra fonts

To make extra fonts available to Qtopia it is likely that the makeqpf ultility will need to be run. For more details see : makeqpf

### Customize apprearance

Qtopia's appearance can be modified on several ways

- Customizing the current theme see : qtopiathemeing.html
- Modifying color schemes : see $QPEDIR/etc/colors/*.scheme
- Changing icons : see $QPEDIR/pics
- Selecting a different font and color : Changed by running the Appearance application