---
title: "IceBT"
url: https://docs.zeroc.com/ice/3.8/plugins/icebt
language: java
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: Java. Other languages: [C++](https://docs.zeroc.com/ice/3.8/plugins/icebt/cpp.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/java.md) in every client and server that communicates over Bluetooth.

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

## Object Adapter Endpoints

To accept Bluetooth connections, configure an [object adapter](https://docs.zeroc.com/ice/3.8/runtime/dispatch/java.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/java.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
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.

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

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