---
title: "IceBT"
url: https://docs.zeroc.com/ice/3.8/plugins/icebt
language: cpp
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# IceBT

Programming language: C++. Other languages: [Java](https://docs.zeroc.com/ice/3.8/plugins/icebt/java.md), [MATLAB](https://docs.zeroc.com/ice/3.8/plugins/icebt/matlab.md), [PHP](https://docs.zeroc.com/ice/3.8/plugins/icebt/php.md), [Python](https://docs.zeroc.com/ice/3.8/plugins/icebt/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/plugins/icebt/ruby.md).

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.

## Installing IceBT

Install the IceBT [plug-in](https://docs.zeroc.com/ice/3.8/plugins/plug-in-facility/cpp.md) in every client and server that communicates over Bluetooth.

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

```cpp
#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:

```config
# Linux only
Ice.Plugin.IceBT=IceBT:createIceBT
```

## Object Adapter Endpoints

To accept Bluetooth connections, configure an [object adapter](https://docs.zeroc.com/ice/3.8/runtime/dispatch/cpp.md) with a `bt` endpoint:

```config
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](https://docs.zeroc.com/ice/3.8/runtime/endpoint-syntax/cpp.md#bluetooth-endpoint-syntax) describes all the options.

## Proxy Endpoints

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

```text
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.

### Discovering Devices

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:

```cpp
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.

## Configuring IceBT

The [IceBT properties](https://docs.zeroc.com/ice/3.8/property-reference/icebt-properties.md) 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](https://docs.zeroc.com/ice/3.8/property-reference/ice-connection-properties/cpp.md#ice.connection.name.connecttimeout).

An application cannot open more than one Bluetooth connection to the same remote endpoint. Ice [reuses an existing connection](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-establishment/cpp.md) to an endpoint by default; an application that uses [connection IDs](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-establishment/cpp.md#connection-ids) to open several connections to the same endpoint cannot do so with Bluetooth.

## Security Notes for IceBT

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](https://developer.android.com/develop/connectivity/bluetooth/connect-bluetooth-devices).

For TLS over Bluetooth, use `bts` endpoints and the [SSL configuration](https://docs.zeroc.com/ice/3.8/runtime/ssl-transport/cpp.md) for your language mapping. IceBT installs both the `bt` and `bts` endpoint types.

## See Also

- [IceBT.\*](https://docs.zeroc.com/ice/3.8/property-reference/icebt-properties.md)
- [Plug-in Facility](https://docs.zeroc.com/ice/3.8/plugins/plug-in-facility/cpp.md)
- [Proxy and Endpoint Syntax](https://docs.zeroc.com/ice/3.8/runtime/endpoint-syntax/cpp.md)
