Home · All Classes · Grouped Classes · Annotated · Functions

Hardware Configuration

Introduction
Device-specific Code
Removable Media and Devices

Introduction

When planning to customize and install Qtopia on a specific device there are 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 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.
If the device supports removable media or PCMCIA cards, notifications must be sent to Qtopia when these are inserted or removed.

All 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-<platform-spec>.h file will be used when compiling Qtopia.

The following macros can be defined or undefined in a custom.h file to customize Qtopia for the specific hardware. The associated custom-<platform-spec>.cpp file will be compiled and linked to provide any custom functions that are required.

Macro Name	description
`NO_WIRELESS_LAN`	`#define` this to disable wireless LAN. This reduces Qtopia's foot print by a considerable amount.
`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_ARCHITECTURE`	#define this with a string that contains the manufacturer and model that uniquely identifies the device, for example SHARP/SL5500.
`QTOPIA_ENABLE_EXPORTED_BACKGROUNDS`	`#define` this to have the phone homescreen background used as the background for the launcher.
`QTOPIA_ENABLE_GLOBAL_BACKGROUNDS`	`#define` this to have the phone homescreen background used as the background for all applications. Requires `QTOPIA_ENABLE_EXPORTED_BACKGROUNDS`.
`QGLOBAL_PIXMAP_CACHE_LIMIT=5242880`	`#define` this if the default 1M pixmap cache size is not big enough, screen size of 640x480 or bigger.
`QTOPIA_PHONE_DEVICE`	`#define` this to select the modem device, e.g. `/dev/ttyS0` (for details see Tutorial: Writing a Multiplexer Plug-in)
`QTOPIA_PHONE_MUX`	`enables/disables` multiplexing in Qtopia (for details see GSM Modem Integration)
`QTOPIA_PHONE_VENDOR`	`#define` this to select the default multiplexer (for details see GSM Modem Integration)
`QTOPIA_ZONEINFO_PATH`	`#define` this to select the path to zoneinfo information (for details see Time on an Embedded Device)
`QTOPIA_COMPATIBLE_DEVICES`	`#define` this with a comma delimited string to specify the devices whose packages are known to be compatible with this device. By convention the first device listed is this device.

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

Function Name	Description
`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 assistance.

Removable Media and Devices

Qtopia supports both removable media, such as SD cards, and removable hotplug devices, such as PCMCIA network cards. However, as there is no standard way in Linux for Qtopia to detect when these devices or media are inserted or removed, it is the system integrators responsibility to detect whenever the attached PCMCIA devices or mounted filesystems change notify Qtopia appropriately.

Integrators notify Qtopia by sending QCop messages. QCop messages may be sent from C++ code using the QtopiaIpcEnvelope class, or from system shell scripts using the qcop command line tool.

The following table describes the events and the QCop messages that should be sent:

Event Message

Removable media added or removed

Event	Message
Removable media added or removed	A `mtabChanged()` message must be sent to the `QPE/Card` channel after the media has been mounted or unmounted. To do this from the command line or a script, the following QCop command would suffice: qcop send QPE/Card "mtabChanged()"
Removable PCMCIA device added or removed	A `stabChanged()` message must be sent to the `QPE/Card` channel. The StabMonitor server task provides a default implementation by monitoring certain files on the file system. To do this from the command line or a script, the following QCop command would suffice: qcop send QPE/Card "stabChanged()"

A mtabChanged() message must be sent to the QPE/Card channel after the media has been mounted or unmounted.

To do this from the command line or a script, the following QCop command would suffice:

    qcop send QPE/Card "mtabChanged()"

Removable PCMCIA device added or removed

A stabChanged() message must be sent to the QPE/Card channel. The StabMonitor server task provides a default implementation by monitoring certain files on the file system.

To do this from the command line or a script, the following QCop command would suffice:

    qcop send QPE/Card "stabChanged()"

Trademarks

Qtopia 4.2.5