Home · All Classes · Grouped Classes · Annotated · Functions

Bluetooth Support


Qtopia supports Bluetooth communications hardware and software profiles by relying on BlueZ, the official Linux Bluetooth stack. Qtopia provides implementations of Bluetooth profiles; settings applications for device and profile configuration; and advanced framework classes that enable implementation of custom profiles.


It is important to note that Qtopia make use of a PCM SCO connection since that connection type uses the least amount of power. This means that Qtopia does not process any audio data related to the Bluetooth connection.

Before using Qtopia's Bluetooth support it is highly recommended that the BlueZ tools be used to test the Bluetooth connection. As a minimum the follow should be run to check the device adaptor :

    dbus-send --system --dest=org.bluez --type=method_call \
        --print-reply '/org/bluez' org.bluez.Manager.DefaultAdapter'

The result should be something like: string "/org/bluez/hci0"

A Bluetooth connection requires a process called 'pairing' to be completed. This process typically involves

Hardware Requirements

Qtopia does not directly support any hardware, instead it relies on the BlueZ Bluetooth stack. Thus for any hardware to be supported by Qtopia, it must be supported by BlueZ. For more information, please visit the BlueZ website at http://www.bluez.org.

Software Requirements

Qtopia 4.3 requires BlueZ Bluetooth framework Version 3.19. This means both the bluez-libs-3.19 and bluez-utils-3.19 must be installed on your system. For more information about installing BlueZ, please refer to the BlueZ website at http://www.bluez.org.

Note that bluez-utils needs to be compiled with XML support as Qtopia uses its XML service record description feature. Versions 3.27 and earlier of bluez-utils require the expat or GLib libraries to enable this feature, and later versions use GLib only.

BlueZ uses the DBUS communications protocol to expose a rich and complex API. Qtopia uses this API to manage Bluetooth devices. Thus Qtopia requires DBUS to be configured and running in order to successfully communicate with hcid. Qtopia does not link to the BlueZ libraries, however correct version of the bluez-lib package must be installed as it is used by bluez-utils.

Qtopia requires:

Qtopia Configuration

Qtopia has several configure options which relate to Bluetoth support. These options are documented in the table below:

-bluetoothTurns Bluetooth Support on. This option also implies -dbus.
-dbusBluetooth support requires DBUS. This turns on DBUS support. By default, configure searches for DBUS installation hierarchy under /usr. Thus the libdbus-1.so will be found in /usr/lib/libdbus-1.so. If a useable version of the DBUS library is not found, the DBUS and Bluetooth support will be disabled. Use -dbuspath option to manually specify where DBUS library resides.
-dbuspathThis option is optional. If your DBUS installation is not in /usr, this specifies the DBUS installation path.


Qtopia Bluetooth currently supports GAP, SDAP and OPP, DUN, Headset and Handsfree profiles. The GAP and SDAP profiles are implemented largely by the BlueZ hcid and sdpd daemons.

The Headset and Handsfree profiles require that a QAudioStatePlugin be provide that suits the device.

The current BlueZ architecture uses the language-independent DBUS layer to communicate with its clients. Qtopia uses the Qt DBUS bindings to communicate with the BlueZ hcid daemon. Most notifications from the hcid daemon are exposed through the QBluetoothLocalDevice API.

Qtopia also communicates with the BlueZ sdpd daemon by using the sdptool utility. Qtopia compiles its own custom version of this tool.


Device Configuration

Each Bluetooth device or local Bluetooth host adapter has an associated Bluetooth address that is stored as a six byte array and is commonly represented as six hexadecimal bytes separated by colons. For example: FF:FF:FF:FF:FF:FF.

BlueZ and Qtopia support multiple local Bluetooth host adapters, however the most common case is to use a single adapter.

The local host adapter can be controlled through the QBluetoothLocalDevice class where the adapter can be switched on/off and device visibility can be controlled. Visibility is controlled by two variables:

  1. page scan - controls whether remote devices can connect to the local device.
  2. inquiry scan - controls whether remote devices can discover the local device.

This indicates that the discoverable state is controlled by setting the inquiry scan appropriately.


Qtopia fully supports Bluetooth GAP which handles the discovery and establishment of connections between Bluetooth devices. GAP defines how secure connections are established between two devices by a mechanism referred to as pairing and also defines the basic user interface paradigm that must be used by all Bluetooth devices.

Qtopia Bluetooth API allows its clients to discover remote devices and various relevant attributes, such as device name, device manufacturer, Bluetooth protocol version supported, etc. Additionally, establishment of trust relationships by pairing remote devices is also supported.

The functionality used to implement this profile is accessible through the QBluetoothLocalDevice class.


SDAP describes how an application should use the Service Discovery Protocol (SDP) to discover services on a remote device. Using the Qtopia Bluetooth API, clients can enable any application to discover services running on a remote device.

Two discovery modes are supported:

  1. searching - searching for a specific service or services
  2. browsing - searching for any services accessible from the public browse group.

Object Push Profile (OPP)

Qtopia fully supports the Bluetooth Object Push Profile in both client and server modes. This functionality can be found in the QObexPushClient and QObexPushService classes respectively. Qtopia depends on the 3rdparty OpenOBEX library for all OBEX services, including OPP.

The user can send and receive files over Bluetooth. If a file is received, the user can monitor the progress of the file transfer, and choose to accept or discard the file received. If a business card is received, the user has the option of saving it in his or her address book or discarding.

The user should also see the BluetoothPush service documentation.

Dial Up Networking Profile (DUN)

Qtopia supports the Dial-Up Networking profile. Using DUN users can use their Qtopia based Mobile phone to establish a ppp connection to the ISP supported by their provider. The connection is based on the industry standard PPP protocol. Qtopia provides both a service and client implementations of the DUN profile, so Qtopia Phone users can use other phones to establish a DUN connection over Bluetooth as well.

Headset Profile (HSAG)

Qtopia provides a reference implementation of the Headset Audio Gateway profile. This profile allows the use of Bluetooth devices that support the Headset (HS) profile by Qtopia based devices. Headset profile is used to provide wireless handsfree audio communication between a headset and a handset.

Qtopia provides only reference support for the Headset Audio Gateway profile, as frequently such support is hardware and device dependent.

Handsfree Profile (HFAG)

Qtopia provides a reference implementation of the Handsfree Audio Gateway profile (HFAG) This profile allows the user of Bluetooth devices that support the Handsfree (HF) profile by Qtopia based devices. Handsfree profile is frequently found in Bluetooth based car hands-free kits, and also in Bluetooth headsets. Handsfree profile is in principle very similar to the Headset profile, but provides many more capabilities, including direct dialing, last number redial, three-way calling, and other more advanced features.

Qtopia provides only a reference implementation for the Handsfree Audio Gateway profile. Handsfree profile requires the audio gateway to route all audio to the handsfree device. The profile also requires the audio stream to be able to be switched between several audio devices mid-stream. Such support is frequently device and hardware dependent.

For more details, please see the next section.

Note: Users of Qtopia Platform Edition must install the atinterface project (under src/tools/atinterface) in order to use the reference implementation of the Handsfree Audio Gateway profile. (The atinterface project is included by default in Qtopia Phone Edition.)

Linux btsco kernel module

The Handsfree and Headset profiles depend on the Linux btsco kernel module being installed. This module works by creating an ALSA sound card device. The device can then be used by ALSA aware applications. All audio data is then sent over a Bluetooth connection to the remote device.

For more information please see README document in src/3rdparty/patches/btsco

Service Management Framework

Qtopia provides a framework for creating and managing Bluetooth services. A Bluetooth service can be created and registered within this framework by subclassing the QBluetoothAbstractService class. The framework allows registered services to be controlled by external sources through IPC messages. For example, Qtopia's Bluetooth Settings application allows end users to enable or disable registered services, and also modify the security settings of registered services.

The service management framework stores various settings for each known service in the BluetoothServices.conf configuration file. This configuration file can be modified to provide default settings for registered services. As an example, a default configuration file is provided at etc/default/Trolltech/BluetoothServices.conf. This file sets the default security for the OBEX Object Push Service to 0, as Object Push services do not generally require authentication or encryption.

The service management framework is implemented through the service manager in src/server/bluetoothservicemanager.h.

For more information, see the Bluetooth Service Management Framework page.

Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3