The Bluetooth APIs provide developers a way to access the Palm OS® Bluetooth system and write Bluetooth-enabled applications.
This documentation covers how to use the Palm OS Bluetooth APIs but does not provide the basic understanding of Bluetooth concepts and protocols that you need to write Bluetooth code. For more information about Bluetooth, refer to the Specification of the Bluetooth System, available at the Bluetooth Special Interest Group website at www.bluetooth.com
. There are also several third-party books that you may wish to consult for helpful Bluetooth information.
NOTE: Palm OS supports version 1.2 of the Bluetooth specification; however, no Bluetooth 1.2 specific features have been exposed in the API at this time. However, two Bluetooth 1.2 compliant devices communicating with each other gain some performance advantages that are transparent to both the developer and to the user.
Capabilities of the Palm OS Bluetooth System
The Palm OS Bluetooth system enables a Palm Powered™ device to:
- access the Internet through LAN access points and cell phones
- exchange objects such as business cards and appointments over Bluetooth
- perform HotSync® operations over Bluetooth
- communicate with other handhelds for multi-user applications like games and various collaborative applications
- send SMS messages and manage your phone's internal phone book.
- act as a Bluetooth modem, thus providing a gateway to the Internet for other Bluetooth devices.
- use a Bluetooth headset.
- be controlled by a Bluetooth hands-free device.
The Palm OS Bluetooth system designers focused their efforts on the user, recognizing that on the Palm OS technical interoperability is simply not enough. The user cares about the overall experience. The user's "Bluetooth learning curve" should be short. And, as always, simplicity is key.
Bluetooth System Components
The Palm OS Bluetooth system contains the following components, which are built on top of the I/O Subsystem:
- Bluetooth Library
- Bluetooth Exchange Library
- Bluetooth Stack Library
- Bluetooth Devices
- Bluetooth HCI Transport Modules
- Hardware Device Drivers
This hierarchy is shown in Figure 10.1.
Figure 10.1 The hierarchy of the Palm OS Bluetooth system

Bluetooth Library
The Bluetooth Library is a shared library that provides an API for developers to develop Bluetooth applications. The API provides functions in the following areas:
- Managing remote devices, piconets, and ACL links
- Communicating using the L2CAP, RFCOMM, and BNEP protocols, as well as SCO links
- Advertising services and querying for remote services using SDP
- Maintaining a list of favorite devices, some or all of which may be paired with the local device
- Managing persistent service applications
The Bluetooth Library is actually split into two libraries. Applications, which run outside the I/O Process, link to BtLib, while BtLibLo executes within the I/O Process as part of the STREAMS framework.
Bluetooth Exchange Library
The Bluetooth Exchange Library allows applications to use the Palm OS Exchange Manager with Bluetooth as the link. The Bluetooth Exchange Library communicates with the rest of the Bluetooth system through the Bluetooth Library. RFCOMM is used as the sole transport mechanism for the Exchange Manager.
Bluetooth Stack Library
The Bluetooth Stack is a shared library that implements the various protocols of the Bluetooth specification. Palm OS developers don't need to access the Bluetooth Stack directly.
Bluetooth Devices
Bluetooth Devices are STREAMS drivers for the Management Entity, and for the L2CAP, RFCOMM, BNEP, and SDP protocols, as well as for SCO links.
Bluetooth HCI Transport Modules
Bluetooth HCI Transport Modules are STREAMS modules that provide an interface between the STREAMS architecture and the lower-level, hardware device driver for the radio.
Hardware Device Drivers
Hardware Device Drivers are shared libraries that act as device drivers for different radios. Palm OS developers cannot access the Bluetooth Device Drivers.
Profiles
Table 10.1 lists the profiles supported by the Palm OS Bluetooth system.
Table 10.1 Supported Bluetooth profiles
Note that although the Bluetooth system does not support the Bluetooth Synchronization profile, it implements HotSync operations over Bluetooth using the Serial Port profile. Also note that network HotSync operations use PPP.
The Bluetooth system can dial and control voice calls on a Bluetooth-enabled phone as if it were connected through a serial cable. It does this using AT modem commands and not the Cordless Telephony profile.
Usage Scenarios
Bluetooth-enabled devices are able to communicate with a variety of remote Bluetooth devices. The Bluetooth system uses the profiles defined by the Bluetooth specification in order to support the following usage scenarios:
- Palm OS device connects to the Internet via a cell phone to access email, browse the Web, or perform a remote HotSync operation.
- Palm OS device connects to the Internet via an access point or a desktop computer to access email, browse the Web, or perform a remote HotSync operation.
- Palm OS device connects to a desktop computer to perform a HotSync operation.
- Palm OS device connects to a cell phone to dial or to manage SMS messages.
- Palm OS device sends and receives addresses, appointments, or Palm OS applications to or from some other device.
- Another device connects to a Palm OS telephony device to access the Internet.
- Palm OS device uses a Bluetooth headset.
- Palm OS telephony device controlled by a hands-free device.
- Palm OS device hosts or joins an ad-hoc personal area network, for multi-user games or other collaborative operations.
Authentication and Encryption
The Bluetooth system handles the generation, utilization, and storage of authentication and encryption keys at the OS level.
The Bluetooth system doesn't support Authorization. Access concerns beyond authentication are left up to the individual application, as in a standard networking environment.
The Bluetooth system supports security modes 1 and 2: the "non-secure" and "service-level enforced security" modes. Security mode 3—"link-level enforced security"—isn't supported by the Bluetooth system.
Device Discovery
In a system of Bluetooth devices, ad-hoc networks are established between the devices. The "inquiry" procedure is used to discover Bluetooth devices within range. The specification defines two inquiry modes, "General" and "Limited." The General mode, which is supported by the Bluetooth system, is used by devices that need to discover devices that are made discoverable continuously or for no specific condition. Limited mode, on the other hand, is used to devices that need to discover devices that are made discoverable for only a limited period of time, during temporary conditions, or for a specific event. The Bluetooth system doesn't support the Limited inquiry mode.
Telephony and Bluetooth
The Dialup Networking Profile (DUNP), the Headset Profile (HSP), and the Hands-Free Profile (HFP) provide features that are relevant for smart phones. DUNP is integrated with the Palm OS Telephony Manager. Sample source code is provided for both HSP and HFP.
Dial-up Networking Profile
Palm OS supports both the gateway and data terminal roles for DUNP. As a data terminal, DUNP allows the Palm OS device to use a Bluetooth phone as a modem. As a gateway, DUNP lets a Palm OS smart phone be used as a modem by other devices, such as a laptop computer.
Support for the gateway role is new to Palm OS Cobalt, version 6.1. Any Palm OS device that supports the gateway role must also support telephony. When a data terminal connects to a Palm OS DUNP gateway, the Palm OS device will open a data connection to its local telephony service, then serve as a bridge between the data terminal and the network.
Headset Profile
PalmSource provides a sample application—including source code—for HSP that can be used both as a normal application and as a persistent Bluetooth service application. Users can launch it as a normal application, but because it registers itself as a Bluetooth service, it can automatically launch in a thread in the System Process when an inbound connection is detected from the headset.
The sample application provides the following features:
- Connections (the ACL link, RfComm connection, and SCO link) can be establishes either from the audio gateway or the headset.
- Connections can be released either by the audio gateway or the headset.
- Volume control can be performed remotely, by the audio gateway.
The sample HSP service application can be found in the samples/Bluetooth/BtHeadset
directory in the SDK.
Hands-Free Profile
PalmSource also provides a sample HFP application that can be used as either a normal application and as a service application. The HFP sample application simulates all the interaction between the audio gateway and the network. For example, there is user interface to let the user simulate an inbound connection from the network to the audio gateway.
The HFP sample application includes the following features (assuming the hands-free kit being used supports them):
- Service-level connection management; establishment and release of the ACL link and RfComm connection are possible from either the audio gateway or the hands-free unit. Each side of the connection informs the other of which features they support.
- Phone status information; changes in the registration status, call status, and call setup status that the audio gateway detects are reported to the hands-free kit.
- Audio connection handling; the SCO link can be established or released by either the audio gateway or the hands-free kit.
- Accept or reject an incoming voice call.
- Terminate a call.
- Audio connection transfer during an ongoing call; the SCO link can be established and released during an ongoing call without disturbing the call, from either the audio gateway or the hands-free kit.
- Place a call with a phone number supplied by the hands-free kit. Support for this feature is optional in the hands-free kit.
- Place a call using memory dialing. Support for this feature is optional in the hands-free kit.
- Place a call to the last number dialed. Support for this feature is optional in the hands-free kit.
- Call waiting notification. Support for this feature is optional in the hands-free kit.
- Calling line identification. Support for this feature is optional in the hands-free kit.
- Ability to transmit DTMF codes. Support for this feature is optional in the hands-free kit.
- Remote audio volume control. Support for this feature is optional in the hands-free kit.
The sample application does not support the following features, which are optional in both the audio gateway and in the hands-free kit:
- Three way calling.
- Echo canceling and noise reduction.
- Voice recognition activiation.
- Attaching a phone number to a voice tag.
The sample HFP service application can be found in the samples/Bluetooth/BtHandsfree
directory in the SDK.
Personal-Area Networking
PANP lets a Bluetooth piconet look like an ethernet, using that ethernet beneath TCP/IP. PANP uses the Basic Network Encapsulation Protocol (BNEP) below IP and above L2Cap to provide the illusion of ethernet.
PANP lets a distributed application, such as multi-player games or communication tools, work over Bluetooth without having to write any Bluetooth specific code. Any TCP/IP application can work over Bluetooth—the user simply needs to select "BluetoothPAN" as the connection type in the connection preferences.
NOTE: At this time, Palm OS only supports the PAN User (PANU) and Group Ad-Hoc Network Service (GN) roles for PANP. The Network Access Point (NAP) role is not supported at this time.
Radio Power Management
The extended battery life of Palm Powered devices is considered to be a key competitive advantage by many Palm Powered device manufacturers. The Bluetooth system helps preserve battery life by taking advantage of the Bluetooth power efficiency modes (hold, park, and sniff) and the internal power management functionality built into the Bluetooth radio chipset.
Applications don't explicitly put the radio into the sniff, park, or standby modes. Instead, power management is under the control of the Bluetooth system. When participating in a piconet, the Bluetooth system honors requests from the other members of the piconet to enter any of the defined power-saving modes.