Usage

The functionality provided by the server is grouped roughly into three categories, as briefly explained above. The documentation below provides a brief introduction to each of these, but for full details please refer to the Javadoc. The test application included in the repository also provides examples of how most services features could be used.

As a final note, please do be aware of threading when using the service. Most methods on the service interface can be called from any thread, but certain ones can only be called from the main (UI) thread. These methods are clearly marked in the Javadoc. Similarly, while most of the methods on the various callbacks and listeners provided by the service are called on the main (UI) thread for the sake of simplicity, others are not. Again, the Javadoc clearly indicates which threads these methods are called on.

Adapter / Subsystem Management

The features in this category focus on the BluetoothAdapter on the device, and in particular its status.

Primary features include:

• determining whether the system supports Bluetooth or not (i.e. has a Bluetooth adapter or not).
• determining whether the Bluetooth subsystem is enabled or not.
• requesting that Bluetooth be enabled (presents system UI to request the user do this).
• registering/unregistering listeners which are provided with notifications when the Bluetooth subsystem is enabled or disabled.

Device Pairing / Connectivity Management

The features in this category focus on BluetoothDevices.

Primary features include:

• obtaining the list of Bluetooth devices the adapter is paired with.
• determining the connectivity status (connected, connecting, etc.) of a Bluetooth device with the Bluetooth adapter.
• connecting to Bluetooth devices.
• disconnecting from Bluetooth devices.
• registering/unregistering listeners which are provided with notifications when Bluetooth devices are connected to and disconnected from.

Connecting to a Bluetooth device is a complex process, and although the service is designed to hide as much of this complexity away as possible it still bears further explanation.

Attempting a connection requires at least a BluetoothDevice and a ConnectionAttemptCallback be provided to the service. The service attempts to connect to the provided Bluetooth device, and reports results via the callback. One thing worth noting here is that the pairing process with the Bluetooth device, if required, is handled automatically during the connection attempt. Android will display a system UI which will provide instructions to the user and enable them to either pair or cancel. The requirement for pairing and the ultimate result are communicated via the callback as necessary.

If it also possible to provide a customised "configuration" for the connection attempt by providing a ConnectionConfiguration. This allows finer control of certain connection related settings such as the service UUID to connect to on the Bluetooth device, the number of times to retry the connection on failure, and so on.

Here is a very simple example of attempting a connection to the first paired BluetoothDevice available on the device, using a customised connection configuration. It assumes that the service has been initialized and that this implements ConnectionAttemptCallback.

final SimpleBluetoothService sbs = SimpleBluetoothService.getInstance();
final Set<BluetoothDevice> devices = sbs.getDeviceList();
if (!devices.isEmpty()) {
    final BluetoothDevice device = devices.iterator().next();
    final ConnectionConfiguration.Builder builder = new ConnectionConfiguration.Builder();
    final ConnectionConfiguration configuration = builder.setSecure(false)
            .setCanInterruptDiscoveryScan(false)
            .setRetryCount(2)
            .setInitialRetryDelay(3000)
            .setRetryDelayBackoffMultiplier(1.25f)
            .build();
    sbs.connect(device, configuration, this);
}

The progress and ultimate result of the connection attempt will be reported via the callback. Assuming the connection succeeds, a class implementing the Connection interface will be returned. This provides low level synchronous (blocking) read and write operations from and to the connected device. Be aware of threading when using this instance directly - in particular, it should never be used on the main (UI) thread as it may cause ANRs.

To simplify threading concerns a connection "client" which provides asynchronous read and write operations is available. It is a wrapper around a Connection that reports the results of operations via callback. To obtain an instance of a class implementing the ConnectionClient interface, use the ConnectionClients utility class.

For more details regarding connection management see the test application included in the repository.

Finally, regarding pairing, it is worth noting that:

• There is currently no support for pairing only (i.e. pairing without connecting). This functionality is supported from API 19, but is difficult to emulate cleanly on earlier API versions.
• There is currently no support for determining the pairing state of any given BluetoothDevice.
• The service does not currently provide a listener interface for pairing related events.

Discovery Scanning

The features in this category deal with the Bluetooth discovery capabilities of a BluetoothAdapter. In particular, it provides an extension around these which encapsulate features at the "service" level rather than at the "system" level, allowing interaction with discovery scans managed by the service without affecting those managed outside of it (i.e. by the system or other applications).

Primary features include:

• determining whether a discovery scan is running (started via the service or otherwise).
• starting a discovery scan.
• stopping a discovery scan (started via the service).
• registering/unregistering listeners which are provided with notifications when Bluetooth devices are connected to and disconnected from.