The TappyBLE connection and communication management section of the SDK are built around the concept of a TappyBleDeviceDefinition. These definitions encapsulate all of the information necessary for the API to communicate with a TappyBLE device including the hardware address, service UUID, characteristic UUIDs, and the Tappy's name. The underlying BLE details are not generally important, but it is a requirement to acquire the TappyBleDeviceDefinition in order to communicate with a Tappy using the SDK. To aid in this process, the tappyble-scanner module is provided.

Gradle Dependency

compile "com.taptrack.tcmptappy:tappyble-scanner:${latestVersion}"

Setup

This BLE scanner switches between the Lollipop (23+) BLE scanning APIs and the Jelly Bean (18+) depending on the version of Android the device is running. As such, in addition to the BLUETOOTH and BLUETOOTH_ADMIN permissions, scanning requires the ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION runtime permission when used on Android devices running Lollipop or later. You should also make sure that Bluetooth is available and turned on as the scanner will throw an IllegalStateException if you attempt to start a scan when Bluetooth is turned off.

Usage

public class SearchActivity extends Activity {
  Map<String,TappyBleDeviceDefinition> devices = new HashMap<>();

  private TappyBleFoundListener listener = new TappyBleFoundListener() {
    public void onTappyBleFound(TappyBleDeviceDefinition definition) {
      devices.put(definition.getAddress(),definition);
    }
  };

  private TappyBleScanner scanner;

  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    promptForPermissions();

    scanner = TappyBleScanner.get();
  }

  @Override
  public void onResume() {
    super.onResume();
    scanner.registerTappyBleFoundListener(listener);
    scanner.startScan();
  }

  @Override
  public void onPause() {
    super.onPause();
    scanner.unregisterTappyBleFoundListener(listener);
    scanner.stopScan();
  }
}

Note: Runtime permission and Bluetooth enabling code has been removed for brevity, but would be required in practise.

Scanning is a power-intensive process, so if you are using a TappyBLE with an Android device that is running on batteries, make sure to only scan when necessary.

Persisting Found Definitions

Once you find the device you wish to connect to, it is important to keep track of the device definition in a manner that will not be lost upon orientation changes. If you wish to store a device definition in a Bundle, you can use the ParcelableTappyBleDeviceDefinition

    public void writeDefinitionToBundle(TappyBleDeviceDefinition definition,
            Bundle bundle,
            String key) {
        bundle.putParcelable(key,
            new ParcelableTappyBleDeviceDefinition(definition));
    }

If you wish to persist the device definition to a database or to disk, you can safely store the name, address, and the three UUIDs from an existing device definition and reconstruct it using the 5 argument constructor of ParcelableTappyBleDeviceDefinition. Alternatively, can make your own class that implements TappyBleDeviceDefinition or extends AbstractTappyBleDeviceDefinition in order to persist the data if you wish to do so.