IceBT

5 min read

4 min read

4 min read

4 min read

4 min read

4 min read

IceBT is a transport plug-in that allows clients and servers to communicate over Bluetooth RFCOMM connections. Ice provides IceBT for C++ on Linux and for Java on Android. On Linux, Python, Ruby, PHP and MATLAB applications can also load the IceBT shared library.

Install the IceBT plug-in in every client and server that communicates over Bluetooth.

You should install IceBT in your communicator using the pluginFactories field of InitializationData:

C++
#include <IceBT/IceBT.h>
Ice::InitializationData initData;
initData.properties = Ice::createProperties(argc, argv);
initData.pluginFactories = {IceBT::btPluginFactory()};
Ice::CommunicatorPtr communicator = Ice::initialize(initData);

Alternatively, you can install the IceBT plug-in at runtime using configuration:

Properties
# Linux only
Ice.Plugin.IceBT=IceBT:createIceBT

You should install IceBT in your communicator using the pluginFactories field of InitializationData:

Java
// Android only
InitializationData initData = new InitializationData();
initData.properties = new com.zeroc.Ice.Properties(args);
initData.pluginFactories = java.util.List.of(
new com.zeroc.IceBT.PluginFactory());
try (Communicator communicator = new Communicator(initData)) {
// Use the communicator.
}

Alternatively, you can install the IceBT plug-in at runtime using configuration:

Properties
# Android only
Ice.Plugin.IceBT=com.zeroc.IceBT.PluginFactory

On Linux, install the IceBT shared library and load it with:

Properties
Ice.Plugin.IceBT=IceBT:createIceBT

To accept Bluetooth connections, configure an object adapter with a bt endpoint:

Properties
GreeterAdapter.Endpoints=bt -u 4f140cef-d75e-4c93-b4e4-20ac111d36d1 --name "Greeter Service"

IceBT registers this endpoint as a service with the Service Discovery Protocol (SDP) server of the local device: the service has the endpoint's UUID and name, and the RFCOMM channel on which the object adapter listens. Generate your own UUID for each service and use the same UUID in your clients' proxies. Bluetooth Endpoint Syntax describes all the options.

A Bluetooth endpoint in a proxy holds the UUID of the service and the Bluetooth address of the server's device:

greeter:bt -u 4f140cef-d75e-4c93-b4e4-20ac111d36d1 -a "01:23:45:67:89:AB"
Java
var greeter = GreeterPrx.createProxy(
communicator,
"greeter:bt -u 4f140cef-d75e-4c93-b4e4-20ac111d36d1 -a \"01:23:45:67:89:AB\"");

IceBT queries the SDP server of the device at the specified address for the UUID, and connects to the RFCOMM channel it returns. The address contains colons, so enclose it in double quotes: a colon outside double quotes separates two endpoints.

Applications find the Bluetooth address of the server's device with the platform's Bluetooth API. On Linux, the Bluetooth service must know the target device before IceBT can connect to it: discover or pair the device first.

On Linux, IceBT::Plugin provides startDiscovery, stopDiscovery, and getDevices. Obtain this interface from the communicator's plug-in manager:

C++
auto plugin = std::dynamic_pointer_cast<IceBT::Plugin>(
communicator->getPluginManager()->getPlugin("IceBT"));
std::string adapterAddress = "01:23:45:67:89:AB";
plugin->startDiscovery(
adapterAddress,
[](const std::string& address, const IceBT::PropertyMap& properties)
{
// Record or display the discovered device.
});

Replace adapterAddress with the address of a local Bluetooth adapter. Both startDiscovery and stopDiscovery require that address.

The callback receives the remote device's Bluetooth address and an IceBT::PropertyMap, a string-to-string map of metadata. The plug-in can report the same device more than once. Discovery continues until you stop it with plugin->stopDiscovery(adapterAddress) or the Bluetooth service stops it. Stopping discovery removes the callbacks registered for that adapter.

plugin->getDevices() returns a snapshot of all known remote devices as an IceBT::DeviceMap, keyed by Bluetooth address. The plug-in reads the initial devices from the Bluetooth service at startup and updates its map as devices are added or removed.

On Android, an app can use the APIs in android.bluetooth to initiate discovery and receive intent notifications about nearby devices. IceBT cancels Android device discovery before opening an outgoing connection.

The app must obtain the Bluetooth permissions required by its Android version and target SDK. See Android Bluetooth permissions.

The IceBT discovery API is available in C++ only. For a client, make the server's device known to the Linux Bluetooth service before the first connection: discover or pair the device with bluetoothctl, then use the device's address in the proxy endpoint. A server has nothing to discover; clients need the address of the server's Bluetooth adapter, which bluetoothctl show prints.

The IceBT properties set the sizes of a connection's send and receive buffers; the defaults suit most applications. Establishing a Bluetooth connection can take several seconds, so keep this in mind if you lower the connect timeout.

An application cannot open more than one Bluetooth connection to the same remote endpoint. Ice reuses an existing connection to an endpoint by default; an application that uses connection IDs to open several connections to the same endpoint cannot do so with Bluetooth.

The operating system manages Bluetooth pairing: applications pair devices through its facilities.

On Android, IceBT uses the secure RFCOMM APIs. Android can prompt the user to complete pairing while establishing a connection. See Android's Bluetooth connection guide.

For TLS over Bluetooth, use bts endpoints and the SSL configuration for your language mapping. IceBT installs both the bt and bts endpoint types.