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

Qtopia - Customizing Qtopia for a Device

• Introduction
• Custom Qtopia Launcher User Interface
  • Launcher
  • Other User-Interface Components
• Device Hardware Factors
  • Device-Specific Code
• Non-installed Components
• Unsupported Components
• Required Plugins
• Power Management
  • Technical Details
  • For PDA Edition
  • For Phone Edition
• Memory Management
• Storage Locations
  • Algorithm based on device names
  • Storage.conf
  • All-else-fails hack
  • Non-removable vs Removable storage
• I18N
• Access Permissions and Read-only Filesystems
  • Files and directories requiring write permissions
  • Using Read-only Filesystems
    • Single Executable
    • Using Symbolic Links
    • Using Multiple Qtopia Paths.
• MMS Client
  • WAP Stack Integration
  • AMR Encoder
• GSM Module Integration

Introduction

This document describes the implementation requirements for specific devices and makes recommendations for the optimal installation of Qtopia on a handheld device. How Qtopia is installed on a given device is determined by the functionality of that device.

See Also

• Qtopia - Customizing Qtopia for a Device: Keys and Buttons.
• Qtopia - System Integrators' Guidea for a Device.

Custom Qtopia Launcher User Interface

In some cases it is desirable to have a customized launcher interface better suited to the application on the target device. Qtopia supports custom launcher user-interfaces via the ServerInterface. This interface provides 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 file-system management.

Launcher

The default Qtopia launcher is implemented by the Launcher class. The first step when writing a user-interface is to implement a class derived from ServerInterface. This interface provides the functionality to display the 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.

The functions provided by the ServerInterface manage the addition and removal of applications and documents as necessary. The ServerInterface documentation describes the functions in detail.

Other User-Interface Components

In addition to the launcher it is 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 re-used in a custom interface. Most user-interfaces make use of some of these classes to ensure a usable system:

• InputMethods - loads and displays input methods.
• RunningAppBar - displays running application icons.
• SysTray - loads and displays applets.
• StartMenu - provides menus for launcher tabs and accessory plugins.

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

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

• message(QString) - display a status message.
• hideInputMethod() - hide any visible input method.
• showInputMethod() - show the currently selected input method.
• showInputMethod(QString) - show the specified input method.
• reloadInputMethods() - release and reload the input method plugins.
• reloadApplets() - release and reload the applets.

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 a number of factors that must be taken into consideration:

• If the device has a touch screen, Qtopia calibration must be enabled.
• If the device runs off batteries, Qtopia may be required to call APM functions for power saving. See the Power Management section below for more details.
• If the device has special hardware buttons, they may need to be mapped to applications and have associated images displayed in the user interface.
• If the device has a buzzer for alarms and other beeps, Qtopia will need to know how to use this hardware and enable it for the associated events.
• If the device has an LCD screen with a back or front light, Qtopia will need to know how to adjust its brightness.
• If the device has any special LEDs to indicate status to the user, Qtopia will need to know how to set the LEDs.
• If the device has or supports a camera, a Video4Linux (version 1) kernel driver has to be provided so that the Qtopia Camera application can use it.
• If the device has or supports phone hardware, a serial device that supports GSM AT-commands should be provided, so that Qtopia Phone can use it.
• If the device supports sound, the sound volume should be locked to the maximum intended volume.

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 -xplatform option is used to select which custom-<xplatform-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-<xplatform-spec>.cpp file will be compiled and linked to provide any custom functions that are required.

• QPE_USE_MALLOC_FOR_NEW - #define this to have memory allocated using malloc() instead of the default C++ new implementation (this is faster in some cases).
• QPE_NEED_CALIBRATION - #define this if there is a touch screen that requires calibration.
• QPE_OWNAPM - #define this if the device has existing APM settings that must be disabled first by Qtopia via ioctls to /dev/apm_bios.
• QPE_HAVE_MEMALERTER - #define this if the device needs Qtopia to alert the user of low memory conditions. A low memory situation will either be triggered/detected by initMemalerter() (if QPE_MEMALERTER_IMPL is defined) or Qtopia will use its own default implementation.
• QPE_MEMALERTER_IMPL - #define this as a macro that implements any functions required to implement the MEMALERTER functionality (including initMemalerter()).
• QPE_INITIAL_NUMLOCK_STATE - #define this as a macro that implements any device specific methods used to initialize the numlock state.
• QPE_ARCHITECTURE - #define this with a string that contains the manufacturer and model that uniquely identifies the device, for example "SHARP/SL5500".
• QPE_DEFAULT_TODAY_MODE - #define this as "Daily" or "Never" (including the quotes) to tell Qtopia if by default it should run the today program daily or never.
• QPE_FONT_HEIGHT_TO_ICONSIZE(x) - #define this as a macro to provide a mapping from a font height to an icon size in pixels.
• QPE_SYSTEM_SYSFILEMONITOR - #define this if your device's HotPlug system for Removable Storage Cards is Qtopia-aware.
• CUSTOM_SOUND_INIT - #define this to call a function to initialize any custom sound devices like buzzers.
• CUSTOM_SOUND_IMPL - #define this as a macro to define any custom functions required to be used by the other CUSTOM_SOUND macros.
• CUSTOM_SOUND_ALARM - #define this as a macro which implements the device specific code to sound an alarm (perhaps using a buzzer).
• CUSTOM_LEDS( led, status ) - #define this as a macro which can set an LED to a given status if applicable. The first argument specifies which LED, and the status is an integer with device specific meaning.
• CUSTOM_SOUND_TOUCH( press ) - #define this as a macro which implements a given sound to be associated with taps to the screen if applicable.
• CUSTOM_SOUND_KEYCLICK( k, p, r ) - #define this as a macro which implements a given sound to be associated with keyboard key presses if applicable.

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

• int qpe_sysBrightnessSteps(); - This function is called by Qtopia to query the number of graduations the device's LCD backlight/frontlight has.
• void qpe_setBrightness(int); - This function must be implemented with any device specific code used to set the backlight/frontlight brightness to the specified level.
• void PowerStatusManager::getStatus(); - This function must be implemented to query the power status. The PowerStatus class in qtopia/power.h defines the power status abstraction. See the custom-linux-generic-g++.cpp file for details of a default implementation.

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:

• Rotation Setting - This is provided to test and demonstrate Qtopia's ability to display in different orientations. This may be helpful during development if the device uses the transformation display driver.
• Shutdown Setting - This is provided as a development tool. It should not be necessary on a production device. It can be removed by deleting apps/Settings/quit.desktop, on most devices it is expected that there is a physical power button, therefore the user is not expected to ever manually run or shutdown Qtopia.
• screensize applet - allows changing the maximum window size for testing different screensizes quickly during development. This is a development tool only which is also not intended for end users.
• Terminal - This is provided as a development tool. It may be reasonable to provide this as a separate installable package for advanced users who are familiar with Linux however it is not expected that the majority of users will find this tool at all useful, only confusing. Therefore it is recommended this program is not included.
• File Manager - Provided as a development tool. Qtopia is functional without it using just Qtopia's document model. Adding the File Browser can make it possible for users to add and remove files from the device in a way which does not correspond to Qtopia's document model which can break the interface. We therefore do not recommend this program should be included on a device to ensure a consistent document model in addition to protecting critical user and system files and settings.

Unsupported Components

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

• VNC Viewer

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.

• Qtopia controls the power state (using pen and key input to restart timeouts), not the kernel.
• The system's "Power" key just sends a key to Qtopia, which then does the actual suspend.
• Qtopia supports multiple shutdown levels. By default these are On, Light Dim, LightOff, and Suspend. Additional levels can be added with a small amount of coding.
• Qtopia calls platform-specific functions to set lighting level for 'dimming' and turning off the light.
• 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).

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 behavior by extending from QWSScreenSaver. This screensaver (QPEScreenSaver) is implemented in qpeapplication.cpp and provides the following three screensaver levels:

• 0 - dims display light
• 1 - turns display light off
• 2 - depends on the Qtopia version

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

• void setScreenSaver ( QWSScreenSaver * )
• void setScreenSaverIntervals ( int * ms )
• void screenSaverActivate ( bool )

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" 

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.

Memory Management

Qtopia's memory management is divided into two segments. These parts can be controlled via QPE_HAVE_MEMALERTER and QPE_MEMALERTER_IMPL. QPE_HAVE_MEMALERTER enables Qtopia to alert the user if the device is running under low memory conditions. It relies on the macro QPE_MEMALERTER_IMPL which should be defined if a customized memory alerter implementation is available. Otherwise Qtopia will use it's own default implementation which is based on page faults. It is recommended to use initMemalerter() if the device has some kind of hardware support to detect the memory situation.

The memory alerter should return five different memory states. The following list describes these states and their consequences for the server.

• MemUnknown - This is the initial state and has no consequences for the server. This state can also be used to indicate that the system has no information available about the status of the memory usage.
• MemNormal - The memory consumption is within its normal parameters and does not require any attention from the server.
• MemLow - This state will initiate the shutdown of one lazy application (idle in the background). If QPE_LAZY_APPLICATION_SHUTDOWN is not defined this state will do nothing.
• MemVeryLow - This state initiates the shutdown of all lazy applications and will inform the user about the situation at hand.
• MemCritical - This state means that the system is overloaded. An indication for this state is page thrashing. The server will shutdown all lazy applications. If the lazy application shutdown is not enabled or did not shutdown any application gracefully the application that was started at last will be terminated in order to prevent that the kernel terminates the qpe server itself.

Storage Locations

Qtopia has 3 ways that it identifies storage locations.

• Algorithm based on device names
• Storage.conf
• All-else-fails hack

Algorithm based on device names

This is the original method and is generally not suitable to new devices. You can modify the algorithm but it it much easier to specify the locations you want with Storage.conf.

Storage.conf

If $QPEDIR/etc/default/Storage.conf exists, it is used when deciding what parts of the filesystem are available for Qtopia's use. It must define 1 non-removable and any number of removable locations.

Note: Due to the way the config system works, $HOME/Settings/Storage.conf will override $QPEDIR/etc/default/Storage.conf. This should not matter on released devices as the available devices will not change. On a development system you should ensure $HOME/Settings/Storage.conf is removed when $QPEDIR/etc/default/Storage.conf is changed.

Here is a simple example of a Storage.conf file.

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

This file specifies the device /dev/hda1 as the non-removable storage. It calls this location "Internal Storage". There is also a removable storage location called "CF card" that uses the device /dev/sda1.

It is possible to add translation to the names in Storage.conf. If you require this ability, please contact support-embedded@trolltech.com as a patch needs to be applied to your Qtopia tree.

The "device" in Storage.conf must correspond to the first column of /etc/mtab. Here are some examples of devices.

• IDE Hard Disk partition - /dev/hda1
• LVM partition - /dev/snow_vg1/home
• NFS/SMB mount - //server/path/to/mount

All-else-fails hack

If no storage locations are found a fallback is used. When this happens $HOME is used as the "Internal Storage" location. As $HOME is generally writable this tends to work but you will not have access to removable storage if this happens. Provide a Storage.conf file so that your devices are explicitely noted.

Non-removable vs Removable storage

Application data is stored in the non-removable location. Documents can be in any location. Removable locations are re-scanned on insertion and removal.

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

• mtabChanged() - Sent when /etc/mtab have changed.
• stabChanged() - Sent when /var/run/stab, /var/state/pcmcia/stab, or /var/lib/pcmcia/stab have changed.

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

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:

Files and directories requiring write permissions

Using Read-only Filesystems

Using read-only filesystems can have a number of benefits. Compressed read-only filesystems such as cramfs and squashfs often have better compression than read-write filesystems such as jffs2. Also read-only filesystems provide a measure of protection for important system files.

Single Executable

If the device does not require that users can install additional applications or plugins it is possible to compile Qtopia as a single, statically built executable. This uses less space than the dynamic build but does not allow other applications to link to Qtopia libraries.

If Qtopia is build as a single, statically built executable /opt/Qtopia does not require write permissions and can be mounted on a read-only filesystem.

See Qtopia Single Exec.

Using Symbolic Links

Symbolic links are the easiest way of mixing read-only and read-write filesystems. Set QPEDIR to be a location on the read-write filesystem and use symbolic links to link individual files to their respective locations on the read-only filesystem. For example /opt/Qtopia/apps/Applications/calculator.desktop would be a symbolic link to /opt/Qtopia-ROM/apps/Applications/calculator.desktop.

This has better flash usage than using just a read-write filesystem and allows installing additional applications and updating components of Qtopia.

Using Multiple Qtopia Paths.

Improved support for multiple Qtopia paths was added in Qtopia 2.1. Some components of Qtopia can reside in a number of directory locations. This reduces the need for symbolic links when mixing read-only and read-write file systems, reducing flash ram usage. The subdirectories of Qtopia that support multiple Qtopia paths include:

• $QPEDIR/bin
• $QPEDIR/help
• $QPEDIR/i18n
• $QPEDIR/lib
• $QPEDIR/pics
• $QPEDIR/plugins
• $QPEDIR/sounds

If the QTOPIA_PATHS environment variable is set to include an appropriate directory on the read-only filesystem, then for the above subdirectories symbolic linking of files to the read-only filesystem is not required. It is still necessary to use symbolic links for the apps subdirectory to allow installable applications.

The QTOPIA_PATH environment variable is set as a colon-separated list of directories. For example "/opt/Qtopia:/opt/Qtopia-ROM". It is also required that the PATH and LD_LIBRARY_PATH environment variables are set appropriately.

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

• modify the MmsClient::setAccount function in $QPEDIR/src/applications/qtmail/mmsclient.cpp to choose your MmsComms implementation
• modify MMSCOMMS_HEADERS and MSCOMMS_SOURCES in $QPEDIR/src/applications/qtmail/qtmail.pri to list the source/header files for your 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 plugin interface provides a convenient method of integrating the codec. See MediaRecorderEncoder class.

GSM Module Integration

We have found that the implementation of the GSM specification varies from GSM module to GSM module. It is therefore highly likely that modifications will be needed to $QPEDIR/src/libraries/qtopiaphone.

To simplify matters, most of the module-specific code can be placed in a vendor-specific plugin, located under $QPEDIR/src/plugins/phonevendors. The plugin should inherit the PhoneVendorAt class and override its methods to implement the vendor specifics.

Qtopia Phone will load every vendor plugin that is installed and queries each one to see which is capable of handling the GSM modem. A vendor plugin will typically issue vendor-specific AT commands to determine if the modem is supported.

The QTOPIA_PRELOAD_PHONE_PLUGIN macro in custom.h can be used to force Qtopia Phone to load that plugin and only that plugin, ignoring any others that may be present in the system.

GSM 07.10 multiplexing, implemented in muxdevice.*, is a common cause of problems. During initial testing, you can disable it by setting the QTOPIA_PHONE_MUX environment variable to "no". Qtopia Phone will still function, but you will be unable to make GPRS calls without multiplexing support.

The MAX_GSM0710_FRAME_SIZE, QTOPIA_EXTRA_CMUX_PARAMS, and QTOPIA_ADVANCED_CMUX macros in custom.h can be used to customize the behavior of the GSM 07.10 implementation a little. Otherwise it may be necessary to modify muxdevice.cpp.

The Qtopia source code also supports Wavecom-style multiplexing, as an example of how to implement a non-CMUX multiplexing system. This mode is enabled with the use of the QTOPIA_WAVECOM_MUX macro in custom.h.

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 write the vendor-specific plugin to issue these commands.
3. Run Qtopia.
4. Check the error/message log for commands that are reported as error.
5. Using the error log modify the plugin and/or the phone library 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 ...