Home · All Classes · Grouped Classes · Annotated · Functions

Integration guide

Introduction

In general, developing a Qtopia device requires the following two processes:

  1. Integration
  2. Customization

The majority of this step-by-step guide refers to the Qtopia integration process. The target audience is system integrators and ODMs intending to integrate Qtopia with their hardware. The items in this document are ordered according to their dependencies, starting with the Linux kernel and followed by the root file system requirements, then Qtopia Core, Qtopia Platform and Qtopia Phone Edition requirements. Particular attention is paid to dependencies existing between Qtopia features and Linux kernel/file system options.

Subsequent to the integration process, the Running Qtopia section describes how to start Qtopia on different targets/platforms.

The last section of this document focuses on Qtopia's customization options. This guide refers to customization as the steps that are required to modify or extend the features and user interfaces provided by Qtopia. Therefore this part of the development process is optional but usually highly desired.

Linux

Kernel requirements

Many of the features in Qtopia are dependent on support from the underlying operating system. This section outlines the dependencies between these features and the configuration options for the Linux kernel. This list has been limited to only those configuration options explicitly required by Qtopia. It is highly likely that additional configuration options will need to be enabled in order to bring the system up.

Many kernel features can be configured to be either built into the kernel binary or built as loadable modules. If you choose to configure kernel features as modules you must ensure that the modules are loaded during system startup. This can be achieved by either manually loading the modules or by using an automatic module loading mechanism such as hotplug or udev.

Minimal configuration

Qtopia requires that the Linux kernel be configured with the following minimum configuration.

Kernel FeatureQtopia Dependency
System V IPC (Shared Memory and Semaphores)Qtopia uses System V IPC (shared memory and semaphores) to share window regions between client applications and the server. For full details on integrating this feature see Linux Framebuffer and Display Management.

The Linux kernel must be configured with the following option to enable System V IPC.

  • CONFIG_SYSVIPC
Unix-domain SocketsQtopia uses Unix-domain Sockets for Inter-process Communication (IPC) between client applications and the server. For details on the IPC mechanism used in Qtopia See Client/Server Communication and Qtopia IPC Layer.

The Linux kernel must be configured with the following options to enable Unix-domain Sockets

  • CONFIG_UNIX
Linux FramebufferQtopia uses the Linux Framebuffer to draw onto the screen of the device. For full details on integrating this feature see Linux Framebuffer and Display Management.

The Linux kernel must be configured with the following options to enable access to the Framebuffer device

  • CONFIG_FB
  • CONFIG_FB_*
  • Device specific Framebuffer driver
proc FilesystemThe proc virtual filesystem provides an interface for querying the status of and controlling certain aspect of the running system. Qtopia uses this filesystem for managing processes, authenticating IPC communication when SXE is enabled, monitoring memory use, querying mounted filesystems, managing network interfaces, power management and querying general system information.

The proc filesystem must be mounted on /proc during start-up.

The Linux kernel must be configured with the following option to enable access to the proc filesystem.

  • CONFIG_PROC_FS

Additional options and Qtopia's dependencies on them

Qtopia includes many optional features and components that may not be needed for all devices. The following table lists these optional features and components together with the Linux kernel configuration options that they depend on.

Optional Qtopia ComponentDescription
AT ModemQtopia's telephony stack includes support for AT modems. These devices are typically connected via a serial interface. If the modem is connected via a different interface, you will need to enable support for that interface. For full details on modem integration see Modem Integration.

The Linux kernel must be configured with the following options to enable access to an AT modem connected via a serial interface

  • CONFIG_SERIAL
  • Device specific serial driver
  • Device specific modem driver
BluetoothQtopia supports Bluetooth communication devices via the BlueZ API. For full details on Bluetooth integration see Bluetooth.

The Linux kernel must be configured with the following options to enable Bluetooth support

  • CONFIG_BLUEZ
  • CONFIG_BLUEZ_L2CAP
  • CONFIG_BLUEZ_SCO
  • CONFIG_BLUEZ_RFCOMM
  • CONFIG_BLUEZ_RFCOMM_TTY
  • CONFIG_BLUEZ_BNEP
  • Device specific Bluetooth driver

Depending on how the Bluetooth device is connected other configuration options may be required. For example, to support a Bluetooth device connected via a serial interface the following addition configuration options will need to be enabled

  • CONFIG_SERIAL
  • Device specific serial driver
Internet, VoIPQtopia can use a variety of network interfaces to provide Internet connectivity. For full details on integrating Internet connectivity see Networking. As Qtopia's VoIP feature routes calls over the Internet, it has the same kernel configuration requirements as Internet connectivity.

The Linux kernel must be configured with the following options to enable support for Internet connectivity

  • CONFIG_INET
  • CONFIG_NETDEVICES
  • Device specific network interface drivers

For WiFi support the following additional configuration options will also need to be enabled

  • CONFIG_NET_RADIO
  • Device specific WiFi driver

Qtopia supports Internet connectivity over GPRS. This feature requires the following additional configuration options to be enabled

  • CONFIG_PPP
  • CONFIG_PPP_ASYNC

Qtopia can connect to OpenVPN based Virtual Private Networks (VPNs). This feature requires the following kernel configuration option

  • CONFIG_TUN

Qtopia can share it's Internet connection with other devices. This feature requires the following kernel configuration option (FIXME: is this Qtopia 4.3+?)

  • CONFIG_BRIDGE
SXEQtopia provides a Safe Execution Environment (SXE) for running third party applications. The SXE environment currently uses the LIDS patch set to provide kernel level Mandatory Access Controls (MACs). For full details on SXE integration see SXE integration.

The Linux kernel must be patched and configured with the following options to fully enable SXE functionality

  • CONFIG_LIDS
  • CONFIG_LIDS_*
CameraQtopia's camera application uses the video4linux API to access the device's camera.

The Linux kernel must be configured with the following options to enable camera support

  • CONFIG_VIDEO_DEV
  • Device specific camera driver

The camera device used by the Camera application is configured in Qtopia's custom.h file as V4L_VIDEO_DEVICE.

InfraredQtopia supports Infrared devices.

The Linux kernel must be configured with the following options to enable Infrared support

  • CONFIG_IRDA
  • Device specific infrared driver
Multimedia CardsQtopia supports multimedia cards. The most common filesystems used on these devices are FAT or FAT32, although these are not the only possibility.

For maximum compatibility it is recommended that the Linux kernel be configured with the following options to enable support for multimedia cards

  • Device specific multimedia card driver
  • CONFIG_MSDOS_PARTITION
  • CONFIG_FAT_FS
  • CONFIG_VFAT_FS
  • CONFIG_NLS
  • CONFIG_NLS_DEFAULT
  • CONFIG_NLS_*
Audio Playback and RecordingQtopia can be configured to process sound either with or without the Media Server integration.

The Linux kernel provides two sets of sound drivers, the Open Sound System (OSS) and the Advanced Linux Sound Architecture (ALSA). Qtopia supports both sets of drivers when built without Media Server integration. Generally only one set of drivers will be used at a time. Check the documentation on the Media Server for it's requirements if Media Server integration is being used.

The Linux kernel must be configured with the following options to enable OSS based audio playback and recording

  • CONFIG_SOUND
  • Device specific OSS audio drivers

Alternatively the Linux kernel must be configured with the following options to enable ALSA based audio playback and recording

  • CONFIG_SOUND
  • Device specific ALSA audio drivers

Useful Debugging Options

There are a number of Linux kernel features which are generally not desirable on a production device, but may be useful during development. This section lists these options and gives examples on how to use them during development.

Useful Development OptionsDescription
NFS Filesystem SupportEnabling NFS support allows you to mount remote NFS shares onto your device. NFS shares can be used as an alternative method of accessing the Qtopia image on your device, instead of reflashing the device.

Note: The runtime performance of Qtopia may be degraded when running over NFS. This is caused by delays in transferring data over the network interface.

To enable NFS support configure the Linux kernel with the following options enabled

  • CONFIG_NFS_FS
  • CONFIG_NFS_V3
  • CONFIG_SUNRPC
  • CONFIG_LOCKD
  • CONFIG_LOCKD_V4

To run Qtopia over NFS you will first need to export the Qtopia image directory to your device. Please consult the documentation for your development system on how to achieve this. On a Linux system, the following command can be used to export the Qtopia image directory to your device. You should replace $DEVICE_ADDRESS and $PATH_TO_IMAGE with the IP address of your device and the absolute path to the Qtopia image directory you want to export.

    exportfs -o rw,no_root_squash,async $DEVICE_ADDRESS:$PATH_TO_IMAGE

To mount the exported Qtopia image on your device run the following command on your device, replacing $SERVER_ADDRESS with the IP address of the development system that is exporting the Qtopia image and $PATH_TO_IMAGE with the same absolute path you used above. If you have configured Qtopia with a different runtime prefix you will need to replace /opt/Qtopia with that prefix.

    mount -t nfs -o nolock,tcp $SERVER_ADDRESS:$PATH_TO_IMAGE /opt/Qtopia

Finally you can run Qtopia over NFS by setting up the environment variables as you normally would and running /opt/Qtopia/bin/qpe. For more details on running Qtopia via NFS see Running Qtopia using NFS

The Qtopia root file system

A typical Linux device's root file system hierarchy would be arranged as follows:

DirectoryUsage
/bincommand binaries
/bootbootloader files
/devdevice files
/etcsystem configuration files
/libsystem libraries and kernel modules
/mediamount point for removable media
/mntmount point for mounting temporary file systems
/optadd-on software packages
/procstub directory for kernel processes.
/sbinsystem binary commands
/tmptemporary files
/usrsecondary hierarchy
/varvariable data

More information is available on the Linux filesystem at Filesystem Hierarchy Standard

Qtopia has it's own file system hierarchy, which is usually mounted at /opt/Qtopia. For more details see the Qtopia File System Standards.

DirectoryUsage
/binQtopia binaries.
/etcQtopia system configuration files.
/helpQtopia html help documentation.
/i18nQtopia translation files.
/libQtopia library files.
/picsQtopia images and icons.
/pluginsQtopia plugins
/qt_pluginsQtopia Core plugins.
/servicesQtopia service task directory
/soundsQtopia sound files.

File system partitions

There are a number of ways a device may be partitioned, depending on the hardware configuration.

Generally, the bootloader, the kernel and at the root filesystem get their own partitions. The root fileystem can also be partitioned into /, /tmp and /home.

Note: If allowing the user to download and install software packages, you will need the /tmp directory or partiton to be large enough to temporarily store any downloaded application package files.

Device Partition Layout

Qtopia can run on and use a number of file systems. Some are more appropriate for NAND flash devices while others are better for more traditional hard drive devices.

File System TypeComments
ext2general read/write. no journaling. not recommended for NAND devices.
ext3general read/write. journalled ext2. not recommended for NAND devices.
cramfsread only compressed
squashfsread only compressed. requires kernel patches. See squashfs web site
jffs2read/write, compressed, journalled, NAND device only.
yaffsread/write, compressed, journalled, NAND device only. kernel patches required. See yaffs web site
ramfs or tmpfsread/write, dynamic size allocation (in RAM), for temporary files.

Qtopia may be installed to a read-only filesystem, provided a writable /tmp, /etc and $HOME is provided.

Busybox configuration

Busybox is a compact and powerful replacement for many common Linux(tm) utilities in a single executable, and is extremely configurable.

Qtopia uses a few system commands that are required to be on the filesystem.

commandQtopia ComponentsBusybox configNotes
ashStartup/scriptShells CONFIG_ASH, need bash symlink
apmsystemsuspendtask
hwclockqalarmserverLinux System Utilities CONFIG_HWCLOCK
logreadLogging viewerSystem Logging Utilities CONFIG_LOGREAD
syslogdLogging viewerSystem Logging Utilities CONFIG_SYSLOGD
echooommanagerShells CONFIG_ASH_BUILTIN_ECHOQtopia version 4.3
cpsystemtimeCoreutils CONFIG_CP
rmpackagemanager, obexservicemanagerCoreutils CONFIG_RM
mkdirobexservicemanagerCoreutils CONFIG_MKDIR

Minimal Linux Configuration

A very minimal Linux System configuration might consist of these packages:

PackageMinimum VersionDescriptionComponentNotes
binutilsBase system binary utilities
glibcEssential C library
glibc-linuxthreadsMulti-threading capability
linux kernel2.4.19 (recommend 2.6.20)linux kernel
busybox1.2.1system commands. See Busybox
libstdc++
libgcc_s
e2fsprogsfile system tools

Optional Linux Configuration

In addition to the Minimal Linux System Configuration, these optional packages may be provided, or required based upon the Qtopia Components used.

Qtopia ComponentPackage
dbus
  • D-Bus
bluetooth
  • D-Bus
  • Bluez-libs
  • Bluez-utils
  • Bluez-firmware
  • Bluez-hcidump
  • OpenObex
  • expat
Irda
Media Player
  • Helix
  • ALSA
Wireless Networking
  • wireless-tools
  • ppp
  • wpa_supplicant
Messages
SXE
  • LIDS
  • App Armor
PIM
Touchscreen
  • tslib
Camera
  • v4l (Video 4 Linux)
Image Viewer
  • ungif
  • libpng
  • libjpeg

These packages may be installed on the target device.

PackageMinimum VersionDescriptionQtopia ComponentNotes
ALSAAdvanced Linux Sound ArchitectureMedia Player
D-Bus1.0.2Message Bus system / Inter process communication D-Busdbus
DHCPDHCP serverNetworking
HelixHelix Multimedia EngineMedia PlayerHelix Integration
OpenObexObject Exchange protocolbluetooth, Irda
PPPPoint to Point ProtocolNetworking
TSLib1.0Touchscreen LibraryTSLib pluginMouse Pointer Handling
WAPIntegrator-provided componentMMS
bluez-firmware1.2bluez firmware utilitiesbluetooth
bluez-hcidump1.34bluezbluetooth
bluez-libs3.9bluez librarybluetooth
bluez-utils3.9bluez utilitiesbluetooth
dosfstoolsutilities for DOS file systems
dropbearssh service and client
expatXML Parserbluetooth
e2fsprogsUtilities for ext2 file systems
LIDS1.2.2Linux Intrusion Detection SystemSafe Execution Environment - SXE
libungifGIF library
pcmciaPCMCIA utilities
sqliteSQLite databasePIM, MessagingProvided by Qtopia Core
sysvinitsysvinit project System initializationbusybox also provides a simple init without runlevels
udevKernel device managerUdev web site
v4lVideo For Linuxcamera
wireless_tools0.28wireless utilitieswireless networking Wireless Tools
wpa_supplicant0.4.9WPA\WPA2 Authenticationwireless networking
zoneinfoTime Zone DataWorldTime, Date/TimeTime on an Embedded Device

Other tools

Other tools you may want to provide for development or general use.

PackageProvidesQtopia ComponentNotes
libelfLinux file system tools
dosfstoolsDOS file system tools
libungifgif library
zlibFile Compression UtilityPackage ManagerProvided by Qtopia Core
libjpegJPEG image libraryProvided by Qtopia Core
OpenSSHOpenSSHdeveloper tool
telnetTelnet Terminal Servicesdeveloper tool
ftpFile Transfer Protocoldeveloper tool
tarArchive Utilitydeveloper tool
freetypeFont LibraryProvided by Qtopia Core Fonts
libmngPNG animation libraryProvided by Qtopia Core
libpngProvided by Qtopia Core
md5Provided by Qtopia Core
gdb serverRemote debugging utilityRemote Debugging
prelinkBinary optimizationPrelink Tutorial

Root file system/kernel sources

There are a number of commercial companies and GPL projects that can provide an Embedded Linux distribution.

To build a cross toolchain yourself:

Qtopia Build system

The Qtopia build system has its own reference documentation which provides function and variable descriptions for the various parts of the build system. This section of the integration guide will reference various parts of it as well as additional example documentation.

How to build Qtopia

Before Qtopia can be built various prerequisites and dependencies have to be satisfied. Most of these dependencies are related to the Linux system and root filesystem that Qtopia is running on. The first part of this guide explicitly states those mandatory and optional requirements. Additional information, such as supported compilers, can be found in the Dependencies and Prerequisites documentation.

Qtopia can be built in multiple ways. In general, the build system distinguishes several ways of building a Qtopia application. They are directly related to launch methods and footprint optimizations provided by Qtopia.

Build typedescription
NormalEvery application is compiled into a binary that is executed by the Qtopia server.
QuicklauncherThis is the default mode for Qtopia. It improves the application startup time by using a stub application to preload libraries and construct classes that are common to all Qtopia applications in the background before an application is started. A quicklaunch enabled application is built as a plugin that is loaded by the stub application.
Singleexec ModeThe Qtopia server and all applications are linked together in a single large binary. A single binary is smaller in size than many separate application binaries and launch times are decreased because libraries are statically linked together with applications. The disadvantages are reduced flexibility when updating libraries and applications on already deployed devices, and the inability of user-installed applications to dynamically link against the Qtopia libraries.

Note that the various options provided in the above table can be combined. A detailed overview of the possible options are provided by Qtopia's configure script.

Configure options

The configure options allow the enabling/disabling of Qtopia features. Some features are not required for every conceivable target device and may be disabled to reduce Qtopia's filesystem and memory use. An example is the "Minimum VoIP" device profile which is part of the Qtopia source package (see $QPEDIR/devices/min_voip). The profile shows how to reduce the size of the Qtopia build as far as possible, while still providing VoIP telephony. A large part of this optimization is simply achieved by passing the right options to Qtopia's configure script:

    -xplatform min_voip -arch arm -no-qvfb
    -displaysize 320x240
    -edition phone
    -no-modem
    -voip
    -no-qtopiamedia
    -no-drm
    -no-sxe
    -prefix /opt/Qtopia
    -no-dbus
    -no-bluetooth
    -no-infrared
    -iconsize 22
    -font "dejavu_sans_condensed:16:50"
    -languages "en_US"
    -extra-qtopiacore-config "-no-freetype"
    -extra-qtopiacore-config "-qt-libjpeg"
    -extra-qtopiacore-config "-qt-libmng"
    -extra-qtopiacore-config "-qt-libpng"
    -extra-qtopiacore-config "-qt-zlib"
    -extra-qtopiacore-config "-no-accessibility"
    -release
    -silent
    -no-samples
    -no-test
    -extra-qt-config '-no-accessibility -system-sqlite -no-qt3support -no-openssl -no-nis -no-cups -no-iconv -no-qdbus -no-opengl -no-glib'
    -extra-qtopiacore-config '-no-accessibility -no-openssl -no-nis -no-cups -no-iconv -no-opengl -no-glib'

Qtopia maintains two sets of configure options. The first set is related to Qtopia's configure script and the second set is related to Qt's configure script.

Note that Qtopia Core config options are actually passed to Qtopia via the -extra-qtopiacore-config option provided by Qtopia's configure script.

Removing applications

In addition to the removal of Qtopia features, applications can be removed and added to a Qtopia build. Qtopia's project files list each individual application that is part of the build and hence enables the developer to choose among provided applications. This level of customization is also available via device profiles.

The minimal VoIP profile example excludes various applications to reduce the Qtopia footprint:

        ...
    PROJECTS-=settings/appearance
    PROJECTS-=settings/beaming
    PROJECTS-=settings/calibrate
    PROJECTS-=settings/handwriting
    PROJECTS-=settings/phonenetworks
    PROJECTS-=settings/phonesettings
    PROJECTS-=settings/callforwarding
    PROJECTS-=settings/words
    PROJECTS-=settings/packagemanager
    PROJECTS-=settings/security
    PROJECTS-=settings/serverwidgets
    PROJECTS-=settings/worldtime
        ...

whereas the greenphone profile actually adds applications to the build process:

    PROJECTS-=\
        settings/beaming
    PROJECTS*=\
        3rdparty/tools/atd\
        3rdparty/applications/target_sqlite\
        tools/startupflags\
        tools/phonebounce
    THEMES-=smudge

Device-specific Configuration

As already mentioned earlier in this guide device profiles provide a convenient way of bundling device-specific code and configurations. This removes the need for code customizations within in the main Qtopia source tree. Device Profiles may be provided by hardware manufactures and/or by Trolltech as separate packages that can easily be integrated into a Qtopia source package. Device profiles can be found in $QTOPIA_DEPOT_PATH/devices, are entirely independent of the main Qtopia source tree and are easily enabled via the build system.

The following example configures, compiles and installs the Greephone device profile which is located in $QTOPIA_DEPOT_PATH/devices/greenphone:

    cd $QPEDIR
    $QTOPIA_DEPOT_PATH/configure -device greenphone
    make
    make install

The build system will use the configure options stored in QTOPIA_DEPOT_PATH/devices/greenphone/configure to build Qtopia for the Greenphone. Note that even cross-compiling is handled by device profiles.

The device plugin tutorial may be of interest as well because it demonstrates how a new profile is created using the requirement for a device plugin, such as a keyboard plugin, as an example.

Advanced build system documentation

The Qtopia build system has a separate documentation index. Its main aim is to explain the various project file functions, variables and how they interact with the configure script. Supplemental overviews and tutorials introduce common tasks which may occur during the Qtopia development process.

Qtopia Core

Qt Feature system

Qtopia Core allows the fine-tuning of library content via the qconfig tool. QConfig provides a visual user interface that enables a convenient way of customizing library content. It presents a short dscription of particular features, can enable/disable them and resolves dependencies among these features. This allows the adjustment of Qtopia Core library sizes as needed. Qtopia uses a default configuration provided by QPEDIR/qtopiacore/qconfig-qpe.h which may be used as a starting point for further customization. Please note that the qconfig system can only be used to customize Qtopia Core libraries and not Qtopia libraries.

qconfig-qpe.h excludes the following Qt components from a standard Qtopia build:

#defineDescription
QT_NO_STLstandard template library compatibility
QT_NO_COLORDIALOGremoves QColorDialog
QT_NO_ERRORMESSAGEremoves QErrorMessage
QT_NO_FILEDIALOGremoves QFileDialog
QT_NO_INPUTDIALOGremoves QInputDialog
QT_NO_PROGRESSDIALOGremoves QProgressDialog
QT_NO_TABDIALOGremoves Q3TabDialog
QT_NO_IMAGEFORMAT_PPMremoves support for PPM images
QT_NO_IMAGE_HEURISTIC_MASKremoves support for 1-bpp heuristic mask (see QImage::createHeuristicMask() )
QT_NO_IMAGE_TEXTremoves support for image file text strings
QT_NO_BIG_CODECSno support for big codecs e.g., CJK (should be added via plug-ins when necessary)
QT_NO_CODECSno support for non-unicode text conversions
QT_NO_DIRMODELno data model support for the local filesystem (see QDirModel)
QT_NO_CURSORno mouse cursor support (see QCursor)
QT_NO_DRAGANDDROPremoves drag and drop mechanisms
QT_NO_EFFECTSremoves special widget effects (e.g., fading and scrolling)
QT_NO_SESSIONMANAGERremoves support for session management
QT_NO_NETWORKPROXYremoves network layer proxy support (see QNetworkProxy)
QT_NO_SOCKS5removes SOCKS v5 network proxy support (depends on QT_NO_NETWORKPROXY)
QT_NO_COLORNAMESremoves colar names such as "red", which are used by QColor
QT_NO_QWS_ALPHA_CURSORremoves support for alpha-blended cursors
QT_NO_QWS_CURSORremoves support for visible cursors (depends on QT_NO_CURSOR)
QT_NO_QWS_DECORATION_WINDOWSno support for "Windows" style decorations of top level windows
QT_NO_QWS_MOUSEremoves mouse driver support
QT_NO_QWS_MOUSE_AUTOremoves support for auto-detected mouse drivers
QT_NO_QWS_MOUSE_MANUALremoves support for non-autodetected mouse drivers
QT_NO_STYLE_MOTIFremoves support for Motif look and feel (see QMotifStyle)
QT_NO_STYLE_CDEremoves support for CDE look and feel (depends in QT_NO_STYLE_MOTIF)
QT_NO_STYLE_PLASTIQUEremoves support for widget style similar to the Plastik style available in KDE (see QPlastiqueStyle)
QT_NO_STYLE_WINDOWSXPremoves support for Microsoft WindowsXP look and feel (see QWindowsXPStyle)
QT_NO_CONTEXTMENUremoves support for pop-up menus on right mouse click
QT_NO_DOCKWIDGETremoves support for docking widgets inside a QMainWindow or floated as a top-level window (see QDockWidget)
QT_NO_WORKSPACEremoves QWorkSpace
QT_NO_SPLITTERremoves QSplitter
QT_NO_SIZEGRIPremoves QSizeGrip
QT_NO_DIALremoves QDial
QT_NO_SYNTAXHIGHLIGHTERremoves QSyntaxHighlighter
QT_NO_STATUSBARremoves QStatusBar
QT_NO_STATUSTIPremoves support for status tip functionality and events
QT_NO_TOOLBOXremoves QToolBox
QT_NO_TOOLTIPremoves QToolTip

Porting

The term porting is used to describe two similar processes. The first use of the term is in the context of modifying Qtopia Core to support a new hardware platform or operating system. In this case the statements "Porting Qtopia Core to a new Architecture" and "Porting Qtopia Core to another Operating System" refer to the process of adding the necessary platform dependent code to Qtopia Core to support the target hardware platform and operating system. The second use refers to the process of changing application code, for an existing application, to work with a newer version of the Qtopia API.

Qtopia Core to a New Architecture

Porting Qtopia Core to a new Architecture involves implementing device drivers for keypad input pointer input, and screen output. You must also ensure that platform dependent atomic operations are provided. These topics are covered in the Porting Qtopia Core to a New Architecture document.

To another Operating System

Porting Qtopia Core to another Operating System involves replacing all Linux specific system calls used in Qtopia Core with equivalents available on the new Operating System. Porting Qtopia Core to Another Operating System documents the Linux specific system calls that are currently used and what they are used for.

Qt Application to Qtopia Core

Existing Qt 4 applications should require no porting provided there is no platform dependent code. If platform dependent code is used, Porting Qt Applications to Qtopia Core provides information on how to manage platform dependent code within your application.

Qtopia 2.x to 4.x

Porting applications from Qtopia 2.x to Qtopia 4.x primarily involves making changes related to changes in the Qt API. Qtopia does not support the Qt 3 Support module, so the task of porting from Qtopia 2 to Qtopia 4 takes more work than porting from Qt 2 to Qt 4. An overview on the planned incompatibilities between Qtopia versions and instructions on how to update your code to the new API is described in the Porting Between Qtopia Versions document.

For Qtopia 4 applications it is no longer recommended that the main() function be written explicitly by the programmer. Instead macros are used to declare the application entry point. These macros are designed so that your application can be built for different configurations (such as singleexec, quicklaunch and standard builds) without requiring any code changes. For details on declaring the entry point for your application see Applications.

Linux Framebuffer and Display Management

Qtopia Core provides screen drivers for the Linux Framebuffer, virtual framebuffer, transformed screens, VNC servers and multiple screens. Qtopia Core's default behavior is for each client application to render its contents into an off-screen buffer. The Qtopia server process copies the memory contents onto the screen. For an overview of this process see Graphics Rendering and Drawing on Screen.

The virtual framebuffer and VNC server drivers are used predominantly during development. When Qtopia is deployed on a device the Linux framebuffer, transformed screens or multi-screen drivers are typically used. The screen driver that Qtopia uses is specified in the QWS_DISPLAY environment variable. Refer to Qtopia Core Display Management for documentation on building screen drivers and how to specify which screen driver Qtopia should use.

Most devices will use the Linux Framebuffer driver. The Qtopia Core document Testing the Linux Framebuffer includes a small test program that can be used to verify that the Linux Framebuffer is configured and works correctly.

Qtopia includes support for multiple screens and accelerated graphics drivers. For documentation on integrating these features refer to Multiple Screen Support and Accelerated Graphics Driver.

Fonts

Qtopia Core uses the FreeType 2 font engine to render fonts. In addition Qtopia Core also supports native prerendered fonts (QPF2) and legacy prerendered fonts (QPF). For full details on the font formats supported by Qtopia Core see Qtopia Core Fonts.

Qtopia Core ships with several fonts. The licensing terms for these fonts are described in Licenses for Fonts Used in Qtopia Core.

Qtopia selects the font size based on the size and resolution of the target display. Please refer to Setting the Display Size which demonstrates how the actual font size is calculated.

Keyboard/Input plug-ins

Qtopia's keyboard handling is controlled by Qtopia Core. There are a few default keyboard drivers available: tty usb sl5000 yopy vr41xx qvfb

A custom keyboard driver may be implemented through Qtopia's Device Configuration Profiles, and documentation can be found for the class QWSKeyboardHandler.

Keyboard driverSourceDescription
tty$QPEDIR/qtopiacore/qt/src/gui/embedded/qkbdtty_qws.cppStandard tty keyboard
usb$QPEDIR/qtopiacore/qt/src/gui/embedded/qkbdusb_qws.cppStandard USB keyboard
sl5000$QPEDIR/qtopiacore/qt/src/gui/embedded/qkbdsl5000_qws.cppKeyboard specific to the Sharp Zaurus 5500
yopy$QPEDIR/qtopiacore/qt/src/gui/embedded/qkbdyopy_qws.cppKeyboard specific to the Yopy
vr41xx$QPEDIR/qtopiacore/qt/src/gui/embedded/qkbdvr41xx_qws.cppKeyboard specific for the NEC Vr41XX device.
qvfb$QPEDIR/qtopiacore/qt/src/gui/embedded/qkbdvfb_qws.cppKeyboard specific for Qvfb

More information about Keyboard Plugins:

Pointer plugins

In Qtopia Core, there are built-in Mouse Pointer (touchscreen) Plugins. If none of these work, a Device Configuration may include a custom mouse pointer plugin-in.

DriverSourceDescription
pc$QPEDIR/qtopiacore/qt/src/gui/embedded/qmousepc_qws.cppStandard pc mouse
bus$QPEDIR/qtopiacore/qt/src/gui/embedded/qmousebus_qws.cppStandard bus mouse
linuxtp$QPEDIR/qtopiacore/qt/src/gui/embedded/qmouselinuxtp_qws.cppStandard Linux Touchscreen
yopy$QPEDIR/qtopiacore/qt/src/gui/embedded/qmouseyopy_qws.cppYopy device
vr41xx$QPEDIR/qtopiacore/qt/src/gui/embedded/qmousevr41xx_qws.cppvr41 device
tslib$QPEDIR/qtopiacore/qt/src/gui/embedded/qmousetslib_qws.cppUse libts for touchscreen events.
qvfb$QPEDIR/qtopiacore/qt/src/gui/embedded/qmousevfb_qws.cppMouse pointer for QVFb

More information about Mouse Pointer plug-ins:

Accelerated Graphics Driver

Qtopia's display performance can be enhanced by the use of a hardware graphics accelerator.

More information about Accelerated Graphics Drivers in Qtopia Core:

Environment Variables

Qtopia makes use of a few environment variables. These are usually set by the Qtopia startup script.

    #!/bin/sh
    export QWS_DISPLAY=LinuxFb:mmWidth34:mmHeight44:0
    /opt/Qtopia/bin/qpe

They can also be set from the defaultbuttons.conf file.

    [Environment]
    QWS_DISPLAY=LinuxFb:mmWidth34:mmHeight44:0

Note that variables set in defaultbuttons.conf do not override variables set in the environment before running Qtopia.

More Information on most Qtopia Core Environmental Variables:

In addition to the Qtopia Core specific environment variables mentioned above the following standard variables may be required:

VariableDescription
LANGSpecifies the language and codeset to be used by Qtopia Core. If problems with missing or wrong text codecs are occuring this variable should be checked. The format for this variable is:
                <language>_<country>.<codeset>

A valid example would be en_GB.utf8 (British English w/ UTF8 codeset). The codeset must always be set to utf8 for Qtopia. Refer to the Internationalization section for more details on language and translation specifc information.

Qtopia Platform

Multiple screen support

Qtopia supports multiple screens. A possible use case for such a situation might be a clamshell phone which has a small status display on the outside and a larger display on the inside. The Dual Screen guide describes the necessary setup steps for dual display development and how any application can display a widget on the secondary display. Support for more than two displays can be achieved with similar steps.

Qtopia Phone Editon provides an integrated and themeable secondary display via the server widget classes QAbstractSecondaryDisplay and ThemedSecondaryDisplay. More details can be found in the Server widgets part of this guide.

QWS connection timeout

The Qtopia server needs to launch processes during startup but it also needs to do it's own initializing which can cause the processes to die. This happens because of a 5 second timeout, QWS clients wait only 5 seconds for the server to respond after connecting to it's socket.

To avoid this problem the server sets the QWS_CONNECTION_TIMEOUT variable to 30, extending the timeout to 30 seconds. This value was chosen after testing on the Greenphone. It can be overriden by setting the variable (see Qtopia Environment Variables for how to do this).

Server Tasks

The Qtopia server application is structured as a collection of server tasks. Ideally each task would perform a small, well-defined portion of work or functionality. Server tasks allow ODMs to easily customize Qtopia by extending, replacing and removing tasks from the Qtopia server application with little or no changes required to the Qtopia server source code. This is achieved by using device profiles and the $QPEDIR/etc/Tasks.cfg configuration file. For information about particular server tasks refer to the server task class documentation.

In most cases Qtopia server tasks are implemented as QObject derived classes. An exception to this are functional tasks, which are implemented as static functions. The developer uses QTOPIA_TASK() and QTOPIA_STATIC_TASK() macros to declare server tasks. For full details see the QtopiaServerApplication documentation. The following example demonstrates how to implement a server task. First the class is declared in the header file

        // exampleservertask.h
        #include <QObject>

        class ExampleServerTask : public QObject
        {
            public:
                ExampleServerTask();
        };

Then the class is implemented and registered with the task system in the implementation file

        #include "exampleservertask.h"

        ExampleServerTask::ExampleServerTask()
        {
            ...
        }

        QTOPIA_TASK(ExampleServerTask, ExampleServerTask);

New server tasks are added by placing the source code for the server tasks into the server/ directory of the configured device profile. The Qtopia Build System automatically includes source files in this directory into the Qtopia server application.

Existing server tasks can be extended to provide additional functionality or to implement device specific code by creating subclasses of the existing server tasks. Source code for these classes should be stored in the server/ directory of the configured device profile.

Removing server tasks can be achieved by adding task names to the exclude group of the $QPEDIR/etc/Tasks.cfg configuration file.

The startup process of the Qtopia Server Application is defined by the order that tasks are listed in the Tasks.cfg configuration file. Tasks.cfg supports the definition of task groups which can be used to collect related tasks together. Except for a few reserved task group names, group names can be any alphanumeric string. For details on the format of the Tasks.cfg configuration file refer to Qtopia Server Tasks.

Qtopia supports two types of tasks: preemptive tasks and on-demand tasks. Preemptive tasks are started during the startup process as defined in the Tasks.cfg configuration file. On-demand tasks are configured as such by marking tasks to be started on demand in the Tasks.cfg configuration file. Only tasks in the reserved prestartup and startup groups are preemptively started by Qtopia.

Some server tasks provide essential functionality and their startup order must be well defined. Two such tasks are the QtopiaApplication server task (implemented in the QtopiaServerApplication class) and the QtopiaServerApplicationLauncher tasks. The startup order of the QtopiaApplication server task must be configured correctly as many other server tasks have an implicit dependency on it. This requirement is documented as part of the Tasks Startup Order. Typically Qtopia is configured to start the QtopiaApplication task from the prestartup group. To achieve this Tasks.cfg should contain a prestartup group with contents similar to

        [prestartup]
        EnvironmentSetup
        DBMigrate
        QtopiaApplication
        IpcRouter

QtopiaServerApplicationLauncher is part of the application launcher framework. It functions as a proxy for the Qtopia Server within the application launcher framework. To ensure correct behavior it is essential that the QtopiaServerApplicationLauncher task is the first task with the ApplicationTypeLauncher interface that is started. The startup sequence of the application framework is typically configured by including something similar to the following in the Tasks.cfg configuration file:

        ...
        [ApplicationLauncher]
        ApplicationMonitor
        ApplicationLauncher
        QtopiaServerApplicationLauncher
        BuiltinApplicationLauncher
        ConsoleApplicationLauncher
        QuickExeApplicationLauncher
        QuickForkedApplicationLauncher
        SandboxedExeApplicationLauncher
        SimpleExeApplicationLauncher

        [startup]
        +ApplicationLauncher
        ...

Bluetooth

Qtopia uses the official Linux Bluetooth stack, BlueZ, for Bluetooth support. The Bluetooth Support document covers the third party requirements and describes the Bluetooth functionality supported by Qtopia.

The Bluetooth Service Management Framework enables Bluetooth services to be handled consistently within Qtopia.

Qtopia supports the following Bluetooth connection sockets

Qtopia includes implementations of the following Bluetooth services.

Note: A QAudioStatePlugin must be provided that suits the device to support Bluetooth services that use the Audio Gateway.

For documentation on creating additional Bluetooth services, refer to Creating a custom Bluetooth service.

Bluetooth Software Requirements

Qtopia requires Linux kernel and additional third party software to support Bluetooth. Bluetooth Kernel Configuration describes the necessary Linux kernel configuration. Optional Linux Configuration lists the required third party packages.

Document/Content system

Qtopia has a robust Document and Content system to enable the user to easily find documents and content.

Document Storage

Documents in Qtopia are usually stored in the user's $HOME directory under the Documents directory, in a tree as such: /<file type>/<mine type>/<file name>.

For example, if a user creates a voice note, the resulting file gets stored in $HOME/Documents/audio/x-wav/June_5_2007_333_AM.wav

The content system categorizes the file and stores its location in the database. The user can then access their files from the Documents menu in the launcher.

A Storage.conf file can be supplied detailing alternate locations for documents.

SectionKeyDescription
MountTable
  • MountPoints
  • DocumentsDefault
  • ApplicationsDefault
  • Names all the mount points available.
  • Names which MountPoint Qtopia should keep user Documents by default.
  • Names which MountPoint Qtopia should install Application packages to by default.
Packages
  • MountPoint
  • Path
  • Names which MountPoint Qtopia should install user Packages to.
  • path to installed directory from Applications mount point.
HOME
  • Name[]
  • Documents
  • Applications
  • String name for home.
  • Whether Qtopia should scan HOME for Documents.
  • Whether Qtopia should scan HOME for applications.
MountPoint0
  • Name[]
  • Path
  • Removable
  • Applications
  • Documents
  • ContentDatabase
  • User string
  • Path to device node of storage device.
  • Whether MountPoint is removable media.
  • Whether Qtopia should scan this MountPoint for documents.
  • Whether Qtopia should scan this MountPoint for applications.
  • Whether Qtopia should store content in a database on the MountPoint or in the system database.

DRM integration

Qtopia is able to handle Digital Rights Management. See Document System: DRM for general details on how the document system handles DRM protected files and refer to DRM Agent Integration if more information on integrating a particular drm agent is required.

Memory management

General information

Qtopia performs adequately with 64 MB of RAM. However the best value may depend on the actual device and most importantly the size of the display. A significant proportion of memory is used for the shared pixmap cache. More details on how to influence the size of the pixmap cache can be found in the Managing Memory Usage documentation.

If it is necessary to debug various memory related problems, profiling tools like valgrind and gprof should be used to determine potential bottlenecks. The Qtopia documentation provides a quick introduction (using valgrind as an example) to how memory related performance issues might be detected.

Out of memory management

Qtopia 4.3 introduces the concept of an Out-Of-Memory (OOM) management. The Qtopia management system consists of four parts:

  1. OOM Data Manager
  2. Application Launcher integration
  3. Memory Monitor
  4. Low Memory Handler

Together these four components are responsible for the avoidance of OOM situation and if it should become necessary for the detection of immanent problems and the subsequent handling of these situations. The Memory Monitor and the Low Memory Handler can be customized by subclassing/replacing certain Qtopia server interface/tasks. The various management classes are part of the Qtopia server.

Qtopia Hardware

Accessories

The Qtopia Accessory System is used to access hardware devices from Qtopia applications. The accessory system provides a standard method of querying for available accessories and a standard interface for accessing those accessories. Currently the Qtopia Accessory System defines hardware interfaces for the following devices

The system integrator adds device-specific code for their device by creating a new accessory class that inherits from one of the base accessory provider classes and overrides the member functions with device-specific implementations. Alternatively the base accessory provider classes can be instantiated directly, connecting the appropriate signals and slots to provide the necessary device-specific functionality.

Accessories are made available to the system when an accessory provider object is instantiated. Typically this is done during system startup from a server task.

Boot Source

Boot source accessories are used to query the event that triggered the last boot sequence. Typically a device has only a single boot source accessory. For documentation on how to implement a boot source accessory see QBootSourceAccessoryProvider. For documentation on how to use boot source accessories from a Qtopia application see QBootSourceAccessory.

Keypad Light

Keypad light accessories are used to control the state of the keypad light on the device. Typically a device has only a single keypad light accessory. For documentation on how to implement a keypad light accessory see QKeypadLightAccessoryProvider. For documentation on how to use the keypad light accessory from a Qtopia application see QKeypadLightAccessory.

Power Source

Power source accessories are used to query information about the available power sources. Power sources describe both batteries and wall power sources. For documentation on how to implement a power source accessory see QPowerSourceProvider. Qtopia provides two methods of accessing power source accessories. The first method uses the standard Qtopia Accessory System API, for details refer to QPowerSource. The second method is a simplified interface provided by QPowerStatus.

Qtopia supports multiple power source accessories on a single device. See QPowerSource for details on how to specify a default power sources accessory.

Signal Source

Signal source accessories are used to query information about the available signal sources. For documentation on how to implement a signal source accessory see QSignalSourceProvider. For documentation on how to use signal source accessories from a Qtopia application see QSignalSource.

Qtopia supports multiple signal sources on a single device. See QSignalSource for details on how to specify a default signal source.

Vibration

Vibration accessories are used to alert the user. Typically a device has only a single vibration accessory. For documentation on how to implement a vibration accessory see QVibrateAccessoryProvider. For documentation on how to use a vibration accessory from a Qtopia application see QVibrateAccessory.

Qtopia Phone uses the vibrate accessory to alert the user to a variety of conditions.

Device indicators

Devices such as Mobile Phones often have indication lights, for things such as charging status, or new email indicators. The QDeviceIndicators class may be used to control an arbitrary number of LED's on the device.

Networking

Qtopia uses network plug-ins to enable new types of network bearer. At present the following network types are supported:

network typerelated plug-in
Local Area Network (LAN)QPEDIR/src/plugins/network/lan
Wireless Local Area Network (WLAN)QPEDIR/src/plugins/network/lan
Dial-up via analog modem, GPRS or UMTSQPEDIR/src/plugins/network/dialing
Bluetooth Dial-up Networking (DUN)QPEDIR/src/plugins/network/bluetooth
Bluetooth Personal Area Networking (PAN)planned for future relases of Qtopia

In general each plug-in provides three components. The GUI component allows the user to configure each network connection via the Settings -> Internet application or any other application that wants to do so. The second component initiates and publishes state changes such as the starting/stopping of the physical network device and the change of routes. The third part is a network script that abstracts the OS/distribution specific network interface configuration from Qtopia. This is done via shell scripts.

Due to the different types of supported network interfaces, the script interfaces are different for each plug-in. It is required to implement these scripts as part of the integration process. To ease the initial development process all plug-in's ship with sample scripts demonstrating the expected functionality. The (W)LAN plug-in for example provides a SuSE 9.3 and a busybox implementation. They may be used as a starting point for the integration process. The exact script parameters and configuration file formats are described in the Network Services documentation.

If it is necessary to support a network bearer that is not yet supported by Qtopia, new plug-ins can be added by implementing the abstract QtopiaNetworkPlugin and QtopiaNetworkInterface interfaces. An overview of network related classes and how they interact with each other can be found in the QNetworkDevice class documentation.

Input methods

Qtopia's input method handling consists of two parts. The IM backend is provided by the Qtopia server which is responsible for the loading of input method plug-ins and input/output related Qtopia classes. These classes build the framework for input method plug-ins.

The front-end implementation for Qtopia's IM support is provided via plug-ins. By default Qtopia provides a few reference implementations which demonstrate certain IM capabilities:

Input methodsourceDescription
Phone keys$QPEDIR/src/3rdparty/plugins/inputmethods/pkimThe Phone key input method is intended for use with keypad buttons with the common 0-9, # and * buttons. It uses a dictionary lookup system to guess the most likely input, as well as a multitap system.
FullScreen Handwriting$QPEDIR/src/3rdparty/plugins/inputmethods/pkim and $QPEDIR/src/libraries/handwritingThis IM can be used when using a pointing device such as a touchscreen or mouse. It composes characters out of multiple strokes. It uses the same dictionary as the Phone keys
Keyboard$QPEDIR/src/plugins/inputmethods/keyboardThe Keyboard input method demonstrates widget based pop up text input.
Docked Keyboard$QPEDIR/src/plugins/inputmethods/dockedkeyboardThe Docked Keyboard provides widget based input methods not unlike the Keyboard. However the difference is the presentation of the input widget. Using the same popup widget as the normal keyboard, this input method docks itself along side other widgets on the display (instead of on top of them), reducing the available display space for normal widgets.

As stated earlier, Qtopia's input methods are reference implementations. Their purpose is to demonstrate and test certain capabilities of Qtopia's back-end implementation as well as providing sample code for new plug-in development. The input method tutorial describes the steps required for plug-in development.

SXE integration

Qtopia sandbox based security mechanism called the Safe Execution Environment (SXE) Safe Execution Environment, which supports the download and secure execution of 3rd party native applications.

The SXE consists of several major components working together in tandem.

Internationalization

Qtopia can be translated into several languages. By default, Qtopia only provides an English user interface. However user interfaces have been designed and tested with a variety of European and Asian languages to ensure that Qtopia can handle the various layout and space issues caused by most languages.

The Qtopia Internationalization guide explains the fundamental details of Qtopia's i18n support, such as how the build system can support the process and how to generate translations for new (not yet) supported languages. The build system documentation has some additional documentation which covers Non-code Translatable (translations required for settings and xml files) related information:

It is possible to purchase translations for selected languages from Trolltech. For more details please contact qt-sales@nokia.com.

The number of supported languages is limited by Qt. Please consult the Internationalization with Qt guide to obtain an overview.

Application services

Services are a standardized way of accessing functionality supplied by other applications. Any application can utilize these services via the QtopiaService* classes. Messages between applications are delivered via Qtopia IPC.

Qtopia services are documented in the service documentation. It explains what services are provided by Qtopia, how they can be accessed and the steps required to add new services. The various meta-information describing a service can be found in $QPEDIR/services and each service is documented like any other Qtopia class (see the ClockService as an example).

Qtopia Environment variables

Qtopia uses various environmental variables to facilitate various settings, which are documented in:

In addition to Qtopia Core's environment variables Qtopia uses the following variables to further specify its behavior:

VariableDescription
QTOPIA_PHONE_DEVICESpecifies the phone device and speed. Qtopia will use a default device if this variable is not set. The default value is set in custom.h.

See also Modem Integration and Using a phone device

QTOPIA_PHONE_DUMMYIf this Variable is set to 1 Qtopia uses a telephony dummy implementation which does not require a real serial device. However its capabilities are limited as well.
QTOPIA_PHONE_MUXIf this variable is set to no disables multiplexing in Qtopia.

See also GSM Modem Integration

QTOPIA_PHONE_VENDORSpecifies the multiplexer plug-in that Qtopia uses.

See also Multiplexer plug-in tutorial

Miscellaneous steps

StepDescription
Device-specific codeQtopia expects device-specific code to be implemented by the system integrator. See <custom.h> for the required and available functions/macros.
Setting time on a deviceQtopia requires /sbin/hwclock to update the system time and zone information for time conversion purposes.
Removable Media and DevicesQtopia must be notified when a removable media or a PCMCIA card is connected to the device. Note that the StabMonitor server task can provide such notifications for PCMCIA cards (for details refer to the class documentation).

Qtopia Phone Edition

Telephony

Qtopia Phone Edition provides Telephony support that enables Qtopia devices to use GSM and Voice over IP (VoIP) functionality. The Telephony Documentation provides the main entry page into the telephony parts of Qtopia.

Modem Integration

Qtopia Phone supports vendor-specific modem commands through the use of plug-ins to the Qtopia Phone Modem Library. The process of implementing a vendor-specific phone-vendor plug-in and multiplexer plug-in is covered in GSM Modem Integration and Tutorial: Writing a Multiplexer Plug-in respectively. Before starting it may be necessary to configure the Linux kernel to support the modem device. See AT Modem for details on what is required for modems connected via a serial interface.

The QTOPIA_PHONE_DEVICE macro in custom.h is used to specify the modem device. QTOPIA_PHONE_DEVICE can also be set as an environment variable. The format of QTOPIA_PHONE_DEVICE is

        <device>:<baud rate>

For example to specify /dev/ttyS0 as the modem device with a baud rate of 115200, add the following preprocessor define to custom.h

        #define QTOPIA_PHONE_DEVICE "/dev/ttyS0:115200"

or alternatively the QTOPIA_PHONE_DEVICE environment variable could be set. For Bourne compatible shells

        export QTOPIA_PHONE_DEVICE="/dev/ttyS0:115200"

VoIP integration

Qtopia's main telephony components are based on GSM/UMTS networks. However many other communication bearers require similar if not even identicial infrastructure support. Therefore new bearers can easily be integrated into Qtopia's telephony API. In fact Qtopia's higher API layers are almost agnostic in regards to the actual communication protocol.

One additional communication bearer that is directly supported by Qtopia is Voice over IP (VoIP). The VoIP Overview describes the main VoIP components used by Qtopia's reference implementation and demonstrates how they interact with Qtopia's phone user interface. The reference implementation uses the open source library libdissipate2 which provides simple SIP functionality.

Note: Currently due to licensing inconsistencies libdissipate2 cannot be shipped with Qtopia.

If the hardware platform already features its own SIP implementation Qtopia's VoIP implementation can easily be replaced as described by Qtopia's general VoIP Integration guide. It describes the necessary steps to integrate new SIP clients as well as new telephony services in general.

Phone keypad

Qtopia's defaultbuttons.conf file provides integrators a way to map the devices keypad to certain actions, map out characters to be generated and specify details for Qtopia's ui. The relevant sections:

SectionDetailsPossible settings.
[Translation]
  • File=
  • Context=
[Menu]Specifies details for Qtopia's main 'grid'
  • Rows=<number>
  • Columns=<number>
  • Map=<characters(123456789*0#)> - Maps grid to keypad shortcuts.
  • Default=<number> - Which in map should Qtopia default to.
  • <number (from Map)>=<apps.desktop> - Specifies an application desktop file to handle.
  • Animator=Bounce
[SoftKeys]Provides assignments for Qtopia softkeys at the botton of the screen
  • Count=<number> - number of buttons to display
  • KeyX=<Qt Key> - assign Qt Keycode to this button. Where X is a number starting with 0. Possible codes: Context1, Select, Back.
[SystemButtons]Provides Qt keycode assignments for physical buttons.
  • Count=<number> - number of physical buttons
  • KeyX=<Qt keycode> - assign Qt Keycode to this button. Where X is a number starting with 0. Possible codes: Context1, Select, Back, Call, Hangup
[TextButtons]Maps physical buttons to hold and tab actions.
  • Buttons=<characters(123456789*0#)> - which buttons to map
  • HoldX=<'Y> - Specifies hold actions, where X is button specifier and Y is a character to send, ie. 0-9,*,# or mode|shift|symbol
  • TapX=<"string"> - Specifies tap actions, where X is button specifier, and string is characters, i.e "wxyz9"
[LocaleTextButtons]
  • TapX[]=<'string> - Specifies tap action, where X is button specifier and string is characters
[PhoneTextButtons]
  • Buttons=<button specifier>
  • TapX=<characters> - Specifies tap action, where X is button specifier
  • HoldX=<characters> - Specifies hold actions, where X is buttons specifier
[Device]Provides device information.PrimaryInput=(Keypad|Touchscreen) - Tells Qtopia to use keypad or touchscreen.
[Button]Tells Qtopia number of physical buttons to provide mapping for.Count=<number>
[ButtonX]Specifies a physical button and mapping its actions. X being a number starting at 0 to the number specified in [Button]/Count.
  • Name=<string>
  • Key=<Qt Key>, i.e. F7
  • HeldActionService=<Service>
  • HeldActionMessage=<QCop message>
  • PressedActionService=<Service>
  • PressedActionMessage=<QCop message>
[Environment]Specifies environmental configuration.QWS_DISPLAY=<gfx driver><:driver specific options><:display number>
[InputMethods]Specifies default InputMethod to be usedDefaultIM=<string:Identifier>

Messaging

Qtopia Phone Edition provides Messaging functionality that enables Qtopia devices to support SMS, MMS and electronic mail messaging. The Messaging Documention provides the main entry page into the messaging parts of Qtopia.

Multimedia Messaging

Qtopia includes MMS functionality in the Messages client but does not include a WAP stack implementation that would be needed to send or receive such messages.

Multimedia Messaging Viewer (SMIL)

Qtopia includes a SMIL 2.0 parser/viewer in directory: $QPEDIR/src/libraries/qtopiasmil/.

This SMIL viewer is intended for use with an MMS viewer and is currently only used by the Messages application.

The SMIL viewer:

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.

Refer to: $QPEDIR/src/applications/qtmail/mmscomms_http.cpp and $QPEDIR/src/applications/qtmail/mmscomms_http.h.

To choose an alternate WAP stack connection method:

  1. to choose the MmsComms implementation:
  2. to list the source/header files for the Mmscomms implementation:
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 plug-in interface provides a convenient method of integrating the codec.

Running Qtopia

The Running Qtopia reference documentation describes how to run Qtopia on desktop machines as well as running Qtopia on a target device (directly flashed onto the device or via NFS).

In order to test Qtopia Phone functionality Qtopia provides a Phone simulator (see $QTOPIA_DEPOT_PATH/src/tools/phonesim) which simulates a significant subset of the GSM 27.007 AT command set. This may be used if a real modem is not available for testing purposes.

The Qtopia Core documentation also contains a Running Qtopia Core Applications help which shows the qws command line supported by Qtopia Core.

Building and running outside of Qtopia build tree

In addition to standard Qtopia applications and libraries which are already incorporated into the build system it may be necessary to add more (including 3rdparty) applications to a Qtopia build. For this purpose the Qtopia build system provides qtopiamake which allows development from outside of the main build tree. Please refer to the following documents for further information:

Debugging Qtopia (local and remote)

Debugging Qtopia applications is an important part of the development process. The Debugging Qtopia Applications guide provides a basic introduction showing how to use gdb and Qtopia's internal logging mechanisms.

In some situation it may be necessary to debug Qtopia running on a remote device because a particular bug may only happen on the target device but not on a desktop machine. This imposes further restriction upon the debugging process because the target device may not have sufficient memory to hold a complete debug build of Qtopia. This situation can be solved by using gdb's remote debugging facilities. The Qtopia Remote Debugging guide provides a quick demonstration how Qtopia may be remotely debugged.

Qtopia customizations

UI customization

Styles

Qtopia uses the Qt Style framework to define the look and feel of the common widgets used by Qtopia applications. Qtopia provides a default style, Qtopia, which is implemented in QPhoneStyle and QtopiaStyle. The look and feel of Qtopia applications can be changed by implementing new styles. New styles are created by deriving new classes from QStyle. Refer to Creating a custom style and Styles Example documentation on creating custom styles. Custom styles are loaded using the plug-in system. For details on creating a style plug-in and registering the custom style with the QStyleFactory refer to Writing Qt Extensions.

If your device will be used with both left-to-right and right-to-left layouts you should consider the implications this has when designing custom styles.

When creating custom widgets it is important to make them style-aware, doing so will allow you to maintain a consistent look and feel.

In Qtopia, styles are linked to themes, which the user can select in the Appearance Settings application. The following segment of $QPEDIR/etc/themes/qtopia.conf demonstrates how a widget style is associated with a given theme. In this example the Qtopia style is used when the user selects the Qtopia theme.

        [Theme]
        Name[] = Qtopia
        Style = Qtopia
        ...

In addition Qtopia's applications follow a style guide which describes the guide lines for user interfaces. The focus is on consistency.

Theming

Integrators can extend Qtopia's look and feel by customizing the theme. Several themes are shipped with Qtopia (see QPEDIR/etc/themes for details) and may serve as examples.

Server widgets

Qtopia's Server widget concept is the user interface customization with the most flexibility. It enables the replacement of widget components via abstract widget classes which define how the various main user interface components interact with each other.

"Server Widgets UML"

The following table describes the purpose of the various abstract server widget:

Abstract widgetDescription
QAbstractServerInterfaceThis is the main UI widget instantiated by the Qtopia server that is common to all Qtopia editions. The PhoneLauncher class implements this interface for the Qtopia Phone edition. The remaining abstract server widgets in this table are part of the Qtopia Phone edition and are expected by the PhoneLauncher.
QAbstractBrowserScreenThis abstract server widget is Qtopia Phone specific and provides the main application browser. Users use it to navigate through and launch applications. The PhoneBrowserScreen class implements Qtopia's default behaviour.
QAbstractDialerScreenThis abstract server widget is Qtopia Phone specific and provides the dialer screen. Qtopia Phone provides two implementation for this server widget (PhoneQuickDialerScreen and PhoneTouchDialerScreen). The decision which class is instanciated depends on whether Qtopia is used on a touchscreen or a keypad phone.
QAbstractSecondaryDisplayThis abstract server widget is Qtopia Phone specific and provides the secondary screen display. A secondary display is used by e.g., Clamshell phones which provide a small status display on the outside. The ThemedSecondaryDisplay class implements the default widget for Qtopia Phone.
QAbstractMessageBoxThis abstract server widget is Qtopia Phone specific and provides an interface for message boxes. This allows the easy replacement of message boxes. The PhoneMessageBox class implements Qtopia's default message box.

The main benefits of server widgets are their flexibility and configurability. Large UI parts can be exchanged against alternative implementations by changing a confguration file. However unlike themes the Qtopia server must be restarted in order to update the user interface. Besides the default implementations Qtopia ships with a couple of sample server widgets which demonstrate the possibilities. The server widget settings application (see $QPEDIR/src/settings/serverwidgets) is a reference application that allows the user to change the server appearance using server widgets.

Web Browser integration

Any web browser integrated with Qtopia should respond to the WebAccess service. The web browser should invoke Qtopia services to fullfil external application needs, including:

  1. Messages::composeMessage(QMailMessage) - for "mailto:" URLs.
  2. Dialer::dial(QString,QString) - for "tel:" URLs.

The QSettings value "Trolltech/WebAccess/Locations/Home" is the user's globally set Home page.

See also QDeviceIndicators and QValueSpaceItem.


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3