Home · All Classes · Annotated · Functions

Hardware Configuration

Introduction
Device-specific Code

Introduction

When planning to customize and install Qtopia on a specific device a number of 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.

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
`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_SYSTEM_SYSFILEMONITOR`	`#define` this if your device's HotPlug system for Removable Storage Cards is Qtopia-aware.
`QPE_SYNC_CLOCK_FROM_QD`	Datebook on Qtopia Desktop sends the current time to Qtopia after it has finished synchronizing. `#define` this to make Qtopia set it's clock from the time received so that the clock on the PDA is kept in sync with the desktop.
`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.
`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`.
`QTOPIA_USE_QSS_VOLUME`	`#define` this to set the system sound level through QSS rather than modifying `/dev/mixer` (for PDA Edition).

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.

Trademarks

Qtopia 4.1.7