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

Qtopia - Customizing Qtopia for a Device

Introduction

This document sets out the implementation requirements for specific devices and makes recommendations for the optimal installation of Qtopia on a handheld device. How you install Qtopia on a given device will be determined by the functionality of that device.

See Also Qtopia - Customizing Qtopia for a Device: Keys and Buttons.

Custom Qtopia Launcher User Interface

In some cases it is desirable to have a customized launcher interface that better suits the intended application of the target device. Qtopia supports custom laucher user interfaces via the ServerInterface. This interface provides all of the infrastructure necessary to implement a launcher while maintaining compatibility with the Qtopia application and document models.

The launcher user interface is part of the Qtopia server ($QPEDIR/src/server) which provides services such as syncing and filesystem management.

Launcher

The first step when writing a user interface is to implement a class derived from ServerInterface. This interface provides the functionality necessary to show the available applications and documents available on a Qtopia device.

The createGUI() and destroyGUI() functions must be implemented to create and show the launcher and any other user interface components.

Most of the functions provided by the ServerInterface are to manage adding and removing applications and documents as necessary. The ServerInterface documentation describes each one in detail.

The default Qtopia launcher is implemented by the Launcher class.

Other User Interface Components

In addition to the launcher itself, it is usually necessary to provide some system components, such as input methods and status display.

There are several classes in the default Qtopia user interface that may be reused in a custom interface. Most user interfaces will make use of some of these classes to ensure a useable system:

An interface providing these components will support most of the default Qtopia launcher functionality.

The Qtopia libraries also assume that QPE/Taskbar QCOP channel is available and supports the following functions:

The default Qtopia launcher uses the TaskBar class to encapsulate the above functionality.

Device Hardware Factors

When planning to customize and install Qtopia on a specific device, there are a number of factors that must be taken into consideration. The following is a list of typical factors:

All of the changes required to add these device specific customizations are centralized in Qtopia and involve a small number of files (described below). This document should make it easy for OEMs and system integrators to understand how to make Qtopia aware of any special hardware that a device might have.

Device-Specific Code

During configure, the -platform option is used to select which custom-<platform-spec>.h file will be used when compiling Qtopia. The following macros can be defined or undefined in a custom.h file to customize Qtopia for the specific hardware. The associated custom-<platform-spec>.cpp file will be compiled and linked to provide any custom functions that are required.

In addition to the above macros and defines, the following three functions must be implemented in the custom-<platform-spec>.cpp file.

For reference implementations of the device specific code, the existing custom-*.* files found in src/libraries/qtopia/ may be of guidance.

Non-installed Components

There are a number of applications/features supplied with Qtopia that are not intended to be shipped with production devices:

Unsupported Components

The following applications are unsupported 3rd party applications/ports intended purely to demonstrate the flexibility of Qtopia:

Required Plugins

If Qtopia crashes twice in quick succession "Safe Mode" will be entered and no plugins will be loaded in case the crash was caused by a misbehaving plugin. In some cases there are plugins that are required for correct operation of the device. These plugins can be specified in the .directory file in $QPEDIR/plugins/<type>/.directory. For example, if the simple8 text codec is always required:

[Desktop Entry]
Name=Text Codecs
Comment=Provides support for various international languages.
Required=simple8
Apply=QPE/System restart()

Power Management

A number of points should be considered when integrating Qtopia with a device that has power management.

Technical Details

Qtopia's power management is handled by Qt embedded. The QWSServer uses the QWSScreenSaver interface in order to decide what to do. Qtopia provides the screensaver behaviour by extending from QWSScreenSaver. This screensaver (QPEScreenSaver) is implemented in qpeapplication.cpp and provides the following three screensaver levels:

Qtopia will call the platform-specific function qpe_setBrightness(int) in order to adjust the light for the display.

The last level depends on the specific version of Qtopia. The PDA version will use the APM daemon and suspends the execution of Qtopia whereas the phone editon closes open applications and returns to the home screen. For further information please refer to: For PDA Edition and For Phone Edition.

The QWSServer provides the following interface which allows the registration and customization of arbitrary screensavers:

\list
\i - void setScreenSaver ( QWSScreenSaver * )
\i - void setScreenSaverIntervals ( int * ms )
\i - void screenSaverActivate ( bool )
\endlist

Qtopia's screensaver can be adjusted by the user via the power management (Light & Power) application.

For PDA Edition

Qtopia runs the 'apm' command to suspend. The system's AT daemon is used to unsuspend upon RTC alarms. The system's AT daemon is used to write the RTC clock (because on some systems only one process can manipulate the RTC).

The system's "Power" key or the third screensaver level just sends a key (Qt::KeyF34) to Qtopia, which then does the actual suspend. It triggers the execution of ServerApplication::togglePower(). All CPU functions are suspended once

 system("apm --suspend"); 

is executed. Normal operation will resume once a "Wake up" event comes from apmd.

For Phone Edition

Suspension is not enabled in the phone edition.

 "apm --suspend" 
would suspend the CPU and shutdown the device. This behaviour is acceptable for PDA's because they don't need to listen for incoming calls. However, the qpe server must be running in order to receive calls. If Qtopia shuts down the power, everything would stop working. We will assume that Qtopia Phone does not do that (or that if it does, Linux ensures resume on modem activity).

Rather than suspending the device the number of CPU cycles has been minimized while the qpe server is showing the home screen. In addition to the first and second screensaver level (already known from the PDA edition) Qtopia Phone automatically closes applications and returns to the home screen. Background activities (like time/date updates and the execution of the battery monitor) are reduced to ensure that the CPU consumption is at the lowest possible level.

Removable Storage Cards

Files from external devices such as SD and CF cards are scanned on insertion and supported documents are mapped in to Qtopia's document view.

The scanning is triggered when the Qtopia library receives one of the following messages via the QPE/Card QCOP channel:

If QPE_SYSTEM_SYSFILEMONITOR (see above) is defined, Qtopia assumes that the surrounding system generates these messages (eg. by using the qcop command in the system HotPlug scripts). Otherwise, Qtopia polls every few seconds (wasting CPU).

When Qtopia scans for external devices such as SD and CF cards, it uses an heuristic to work out what is an external card. If this automatic detection is inadequate due to the specifics of your device, you may alternatively provide the file /opt/Qtopia/etc/default/Storage.conf, with a group for each relevant device in /etc/mtab, with settings of this form:

[/dev/hda1]
Name = Internal Storage
Removable = 0
[/dev/sda1]
Name = Card
Removable = 1

With the above, /dev/hda1 will be internal storage, and when /dev/sda1 is mounted (eg. by Linux Hotplug system), a storage location named "Card" will be available to the user: any documents there will appear on the Documents page. This file can be translated as with any Qtopia Config file.

I18N

Qtopia uses UTF8 for all file formats. System functions are also expected to use UTF8 encoding. For example, with $LANG set to "ja", strftime() must return a string in UTF8 encoding. Depending on the underlying operating system, this may require "ja" to be an alias for the "ja_JP.utf8" locale.

Note that Qtopia expects all file systems to use utf8 encoding. This usually requires attention in /etc/mtab and /usr/share/locale. Particular attention should be paid to removable media.

Access Permissions and Read-only Filesystems

Qtopia can run as any user, provided that user has read and write permissions to certain file areas for certain functionality:

If a read-only filesystem is used, such as cramfs, then a symlink shadow should be created such that the above directories are writeable, but those files that are to be storeda in the cramfs filesystem are symbolic links to the actual files. For example, /opt/Qtopia/apps/Applications/calculator.desktop would be a symbolic link to /opt/Qtopia-ROM/apps/Applications/calculator.desktop.

As an alternative to the single directory specified by $QPEDIR, most Qtopia components support $QTOPIA_PATH, with is a colon-separated list of directories. By setting this variable (to, for example, "/opt/Qtopia:/opt/Qtopia-ROM"), and setting $PATH and $LD_LIBRARY_PATH appropriately, the following component directories can be searched in multiple places:

This greatly reduces the overhead of using symbolic links.

MMS Client

The Qtopia Phone Edition includes MMS functionality in the messages client.

WAP Stack Integration

Qtopia does not include a WAP stack with the MMS client. Instead, an interface is provided which allows any WAP stack to be integrated. The MmsComms class must be subclassed and the virtual functions implemented and signals emitted as appropriate. The MmsCommsHttp class provides a sample implementation using HTTP over TCP/IP see : $QPEDIR/src/applications/qtmail/mmscomms_http.{cpp,h}

To choose an alternate WAP stack connection method

AMR Encoder

The AMR encoder included with Qtopia is a reference implementation only. It is recommended that an encoder optimized for the target platform be installed. The media recorder plugin interface provides a convenient method of integrating the codec. See MediaRecorderEncoder class.

GSM Module Integratation

We have found that the implementation of the GSM specification varies from GSM module to GSM module. It is therefore highly likely that there will be a need to modify at least $QPEDIR/src/libraries/qtopiaphone/{muxdevice.*, atchat.*} to ensure that the GSM subset that the module supports is being used.

To support a GSM module the follow guide may be used:

  1. Check the AT commands that Qtopia requires (see phonelibrary.html ) and determine which ones your GSM module does and does not support.
  2. Determine the appropriate alternative AT commands suited to your GSM module and modify the phonelibrary as required.
  3. Run Qtopia.
  4. Check the error/message log for commands that are reported as error.
  5. Using the error log modify the phonelibrary so that the modem's supported AT command parameters are used. For example, AT+CMUX=1,0,5 vs AT+CMUX=0,0,5 .
  6. Repeat from step 3 until GSM calls are possible, SIM details are being read etc ...


Copyright © 2001-2005 Trolltech Trademarks
Qtopia version 2.1.1