Introduction

The VictoR SDK will provide end-users with an Android Communications library that enables them to communicate with a VictoR device over various communication protocols within their Android-based applications.. One of the supported protocols of this library will be the Bluetooth Low-Energy (BLE) protocol. The following design explains how support for the BLE protocol will be implemented for Android.

...

Constraints

Performance

Calls to a VictoR device are time intensive I/O operations. The Communications Interface should not block and force the end-user to wait for those operations to complete. It should instead return the results asynchronously through callbacks.

...

The Android BLE Communications API will be composed primarily of two classes: VictorBleDevice and VictorBleDeviceManager. These classes are implementations of the abstract VictorDevice and VictorDeviceManager interfaces provided by the VictoR Core library. The VictorBleDevice class represents the connection interface to an individual VictoR device over a physical BLE radio. This class handles all interactions with that device over the BLE communications protocol, including connecting/disconnecting, reading/writing data, and subscribing/unsubscribing from events for that device like attribute (characteristic) changes and connection state changes. These interactions are implemented using the BLE API provided by the Android SDK. The details of the specific function calls required are outlined below in the Implementation section. The VictorBleDeviceManager manages all VictoR device connection interfaces through VictorBleDevice objects that it creates, maintains, and destroys as needed. This class acts as the primary interface for end-users to discover devices and manage connections to them. It also utilizes the Android SDK’s BLE API to accomplish this. In addition, the VictorBleDeviceManager provides a wrapper around the functions that the VictorBleDevice class offers, requiring only that the end-user provide the ID address for the specific device they are interested in interacting with, so that they don’t need to have any knowledge of the underlying organization of the devices within the manager. The class diagram in Figure 1 below illustrates the architecture of the Android BLE Communications API.

...

Anchor
Implementation Implementation

Implementation

...

• Connect

  • Request connection to a device using BluetoothDevice.connectGatt

    • Save the BluetoothGatt object returned by the call

    • Get connection results asynchronously via BluetoothGattCallback.onConnectionStateChange callback

  • Discover BluetoothGattServices before retrieving them using BluetoothGattCallback.discoverServices

    • Get discovery results asynchronously via BluetoothGattCallback.onServicesDiscovered callback

  • Retrieve a list of offered BluetoothGattServices (after discovery has completed) using BluetoothGatt.getServices

  • For each BluetoothGattService , retrieve a list of offered BluetoothGattCharacteristics using BluetoothGattService.getCharacteristics

    • Save each retrieved BluetoothGattCharacteristic into a map keyed on UUID

• Disconnect

  • Request disconnection from a device using BluetoothGatt.disconnect

    • Get connection results asynchronously via BluetoothGattCallback.onConnectionStateChange callback

• Reconnect

  • Request reconnection to a device using BluetoothGatt.connect

  • Get connection results asynchronously via BluetoothGattCallback.onConnectionStateChange callback

• Read

  • Request a read using BluetoothGatt.readCharacteristic

  • Get read results asynchronously via BluetoothGattCallback.onCharacteristicRead callback

• Write

  • Request a write using BluetoothGatt.writeCharacteristic

  • Get write results asynchronously via BluetoothGattCallback.onCharacteristicWrite callback

• Subscribe

  • Enable notifications using BluetoothGatt.setCharacteristicNotification

  • Get notifications asynchronously via BluetoothGattCallback.onCharacteristicChanged callback

• Unsubscribe

  • Disable notifications using BluetoothGatt.setCharacteristicNotification

Device Manager

...

• Scan for devices

  • Get the BluetoothManager from the application Context using Context.getSystemService

  • Get the BluetoothAdapter from BluetoothManager using BluetoothManager.getAdapter

  • Get the BluetoothLeScanner from the BluetoothAdapter using BluetoothAdapter.getBluetoothLeScanner

  • Start a scan using BluetoothLeScanner.startScan

    • Get scan results asynchronously via ScanCallback.onScanResult callback

    • Get the BluetoothDevice from a scan result using ScanResult.getDevice

  • Stop a scan using BluetoothLeScanner.stopScan

• Get scanned devices

  • Maintain a map of BluetoothDevices returned by ScanResult.getDevice as part of ScanCallback.onScanResult callback

    • Key the map using BluetoothDevice.getAddress

• Get connected devices

  • Maintain a map of BluetoothDevices that have connected successfully

    • Key the map using BluetoothDevice.getAddress

...