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

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

# IceBT

This page is written for C++, Java, MATLAB, PHP, Python, and Ruby.

Parts of this page are for some programming languages only, and name them. For one language's text alone, see [C++](https://docs.zeroc.com/ice/3.8/plugins/icebt/cpp.md), [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), and [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.md) in every client and server that communicates over Bluetooth.

> **C++**
>
> 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
> ```

> **Java**
>
> 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:
>
> ```config
> # Android only
> Ice.Plugin.IceBT=com.zeroc.IceBT.PluginFactory
> ```

> **MATLAB, PHP, Python, and Ruby**
>
> On Linux, install the IceBT shared library and load it with:
>
> ```config
> 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.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.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"
```

> **Java**
>
> ```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.

### 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.

> **C++**
>
> 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.

> **Java**
>
> 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](https://developer.android.com/develop/connectivity/bluetooth/bt-permissions).

> **MATLAB, PHP, Python, and Ruby**
>
> 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.

## 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.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.md) to an endpoint by default; an application that uses [connection IDs](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-establishment.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.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.md)
- [Proxy and Endpoint Syntax](https://docs.zeroc.com/ice/3.8/runtime/endpoint-syntax.md)
