IceBT is a transport plug-in that enables clients and servers to communicate via Bluetooth RFCOMM connections on Android and Linux platforms.
On this page:
IceBT is an Ice plug-in that must be installed in all of the clients and servers in your application that need to communicate over Bluetooth. This section reviews some concepts that will help you as you learn more about IceBT.
The Bluetooth specification defines a standard mechanism for discovering services called the Service Discovery Protocol (SDP). It's a flexible but complex specification that accommodates a wide range of Bluetooth device functionality and requirements. Fortunately, Ice users only need a passing familiarity with SDP.
The operating system's Bluetooth stack implements an SDP service that provides two basic functions: query and registration. IceBT considers each object adapter endpoint in an Ice server to be a service and adds a corresponding entry for it in the local SDP registry. This entry associates a UUID with a human-friendly name and an RFCOMM channel. For example, an entry might contain:
Name: My Bluetooth Service UUID: 1c6a142a-aae6-4d58-bef8-33196f531da7 RFCOMM: Channel #8 |
The SDP entry automatically expires when its service terminates.
An Ice client requires two values to connect to a server:
01:23:45:67:89:AB
)To establish a connection, the client first queries the SDP service on the server device for an entry matching the target UUID. If a match is found, the SDP service returns the server's current RFCOMM channel, and the client open a connection to that channel.
IceBT takes care of all of this for you during server initialization and connection establishment.
When developing a client application, you'll normally hard-code the UUIDs of the remote services that your client requires because those UUIDs must match the ones advertised by your servers. However, in addition to a UUID, a client also needs to know the device address on which a service is running. Typically the client will use the system's Bluetooth API to initiate device discovery and present the results to the user. We discuss this further in the "Using IceBT" section below.
The IceBT plug-in must be installed in every client and server that needs to communicate via Bluetooth.
You can use the Ice.Plugin
property to load and install the plug-in at run time; the property value depends on the language mapping you're using:
|
If using C++, instead of dynamically loading the plug-in at run time your application can explicitly link with and register the plug-in. To register the plug-in, you must call the Ice::registerIceBT(bool loadOnInitialize = true)
function before the communicator initialization. The loadOnInitialize
parameter specifies if the plug-in is installed when the communicator is initialized. If set to false
, you will need to enable the plug-in by setting the Ice.Plugin.IceBT
property to 1
.
|
Refer to the next section for information on configuring the plug-in.
The IceBT plug-in supports some new configuration properties, including settings to modify the size of the send and receive buffers for a connection. The default settings should be sufficient for most applications.
Developers should also be aware of some core Ice properties that can affect Bluetooth connections:
Ice.Default.Host
.This section describes how to incorporate IceBT into your Ice applications.
A Bluetooth "service" corresponds to an Ice endpoint, and each endpoint requires its own UUID.
On Linux, you can use the |
For example, using the syntax for Bluetooth endpoints, you can configure an object adapter named HelloService
as follows:
HelloService.Endpoints=bt -u 4f140cef-d75e-4c93-b4e4-20ac111d36d1 --name "Hello Service" |
We're associating the UUID 4f140cef-d75e-4c93-b4e4-20ac111d36d1
with our service. At run time, this service will be advertised in the Service Discovery Protocol (SDP) registry along with the descriptive name Hello Service
. We omitted a device address, so the plug-in will listen on the host's default Bluetooth adapter. We also did not specify a particular RFCOMM channel (using the -c
option) and therefore the plug-in will automatically select an available channel.
If you omit the -u UUID
option from the object adapter's endpoint, the plug-in will automatically generate a random UUID for use in the SDP registry. Note however that your clients will still need some way of discovering this UUID. Generally speaking, you should generate and use your own well-known UUIDs instead.
On Linux, use the
The first command displays the active services of the local host, and the second command shows the active services of a remote device. |
A Bluetooth endpoint in a proxy must include a UUID and a device address:
|
The UUID specified with the -u
option must match the one you assigned to your object adapter endpoint.
Notice that the device address given by the -a
option is enclosed in quotes; this is necessary because colon (:
) characters are used as separators in stringified proxies.
You can omit a device address if you define |
Refer to Proxy and Endpoint Syntax for complete details on the format of a Bluetooth endpoint.
Applications are responsible for determining the Bluetooth address of the device hosting the target service, as described in the next section.
Device discovery is a platform-specific activity that applications are responsible for implementing. On Android, an app can use the APIs in android.bluetooth
to initiate discovery and receive intent notifications about nearby devices. The Android sample program talk
(see below) shows how to implement discovery.
On Linux, the IceBT plug-in provides a C++ API for device discovery:
|
An application must implement a callback function or object and pass it to startDiscovery
:
|
For each nearby device discovered by the Bluetooth stack, the plug-in will invoke the callback. The arguments to the callback are the Bluetooth address of the nearby device and a string map of properties containing metadata about that device. As shown in the example above, the application can pass an empty string to startDiscovery
and the plug-in will use the default Bluetooth adapter, otherwise the application can pass the device address of the desired adapter.
Discovery will continue until stopDiscovery
is called or a Bluetooth connection is initiated.
Be aware of the following limitations when using IceBT:
The ice-demos repository includes a C++ command-line program for Linux (in cpp/IceBT/talk
) and an app for Android (in java/Android/talk
). These programs allow two devices to talk to one another via Bluetooth.
The Bluetooth stack performs its own encryption of transmitted data using keys generated during the pairing process. Two devices must already be paired before Ice applications on those devices can communicate with one another. IceBT does not implement or provide an API for pairing; rather, this is something that is normally done at the user level. However, it's possible that an Ice connection attempt will initiate a pairing process that the user must then complete.
Android provides two APIs for establishing a connection: a secure version and an insecure version. The difference between the two lies in the pairing behavior, where the secure version causes the system to prompt the user (if necessary) and the insecure version does not. IceBT always uses the secure API.
For added security, you can use SSL over Bluetooth by installing the IceSSL plug-in. During its initialization, the IceBT plug-in checks for the presence of IceSSL and, if it's found, IceBT adds a second transport protocol named bts
. No additional changes are necessary to your endpoints, and you can use the IceSSL configuration properties as usual to define your security settings.