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.

Requirements

Software Requirements | 2. Communications

Software Requirements | 3. Platform / OS

Related Jira Issues

https://unity3d.atlassian.net/browse/FNSDKEXT-109

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.

Operating System

This Communications Interface implementation will be provided as an Android Library written in Java and compiled into an Android Archive (AAR), enabling VictoR device application development for hardware targets running Android 10 and above. The library will be designed according to the guide provided in the official Android SDK documentation.

Ease of Use

Interacting with a BLE device is a complicated multi-step process for almost every interaction. The Communications Interface should abstract this process away from the end-user so that they don’t need to know all of the OS-specific implementation details for communicating with a VictoR device over BLE. All they have to do is use the simple set of functions provided by the interface.

Detailed Design

Architecture

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

Open

Figure 1: Android BLE Communications API Class Diagram

Implementation

The following outline describes the function calls to the Android SDK that will be used, as well as a general outline of the algorithm for the function using them, for all of the functions provided by the Android BLE Communications API.

Device

• 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

Unity Project Integration

• Unity natively supports integration of AAR plug-ins.

• The Android BLE Communications API will be wrapped in C# scripts using the AndroidJavaObject and AndroidJavaClass classes.

• Any Java Future<T> objects will be translated to C# Task<T> objects

• Any Java Callback Interfaces will be translated to C# Action<T> function calls.

Glossary