Getting Started - Android

How the SDK Works

Communication between the handset and headset is via Bluetooth and can be over Classic Bluetooth or Bluetooth Low Energy (BLE).

Different headsets support different Bluetooth protocols. This can be transparent to the developer, although in certain circumstances you may wish to force connection to the BlueParrott Button over Classic Bluetooth. On some Android versions this is more stable, and also requires less Permissions, making it easier to integrate into Enterprise Applications. Note that currently only the B550-XT headset supports connection to the BlueParrott Button over Bluetooth Classic. All headsets support connection over Bluetooth Low Energy.

Your may choose to force your application to connect to the BlueParrott Button via Classic or BLE Bluetooth or allow it to select the protocol using the Auto option.

The Auto option attempts to connect via Classic Bluetooth first and if that fails will attempt to connect over BLE.

Including the SDK

If using the gradle build tool the following will need to be included in the app build gradle


dependencies {
    compile(name: 'blueparrottsdk-release', ext: 'aar')

In addition the following will be required in the project build gradle


repositories {
        flatDir {
            dirs 'libs'
        }

Android

The minimum Android version is 19, although the current target android version is 27.

In order to include the BlueParrott SDK in your application copy the blueparrottsdk-release.aar SDK in to the Android library.

Depending on your build configuration appropriate changes will have to be made in order to include the compiled SDK in your project.

Permissions

Bluetooth

<!-- required for bluetooth -->

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

Connection between the handset and headset is via Bluetooth. The BlueParrott SDK allows three methods for bluetooth connection:

  • auto
  • classic
  • ble

For Android programming you must include specific permissions for Bluetooth connection, the Bluetooth connection is managed by the BlueParrott SDK but your program must include the uses-permission for Bluetooth.

Enable Bluetooth

The BlueParrott SDK manages the Bluetooth connection but you must manage the enabling of Bluetooth in your code. An approach to this is to alert the application user if Bluetooth is not available and ask the user to turn Bluetooth on in their handset settings, you must then provide another opportunity to connect.

Location

<!-- the following is only required if supporting BLE Versions of the BlueParrott Button -->
<!-- required on android 6.0 or greater to get at ble-->

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

If your Android program is targeting a BLE BlueParrott headset and the target android API is level 23 or greater then you must ask your user for permission to access location.

There are two options for access to location permission ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION. Either access permission will work for BLE access and the one you choose will be a consideration for you based on other functionality of your application.

Location permission prompt

If required you should prompt your user for permission to use location and handle their response appropriately. If access to location is denied you may need to advise of the limitations for use of your application if location use is not allowed for BLE. You can avoid the need for this permission by selecting CLASSIC as the connection method if you are just targeting the B550-XT headset.

     if (this.checkSelfPermission(Manifest.permission.ACCESS_COARSE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
     //place your code here

Connect to the BlueParrott Button

The first step is to get a handle to the BlueParrott Button on the BlueParrott Headset.

Now you have the ability to check the connection and connect or disconnect to the headset.

There are a number of methods to connect depending on the headset being used. Auto attempts to connect via classic Bluetooth first and if that fails will attempt to connect over BLE.

CONNECT_METHOD_ Value
AUTO 0
CLASSIC 1
BLE 2

The BlueParrott SDK method connect manages the BlueParrott Button connection and ensures that the relevant Bluetooth connection is available.

import com.blueparrott.blueparrottsdk.BPSdk;
import com.blueparrott.blueparrottsdk.BPHeadset;

BPHeadset headset;

    // Get a handle to the BlueParrott Button on the headset
    headset = BPSdk.getBPHeadset(this);

    if (!headset.connected()) {
               logStatus("Connecting");
               headset.connect(CONNECT_METHOD_AUTO);
                // perform your own code
    }

Listen for Connection Events

Through the BlueParrott SDK your app can get a handle to the BlueParrott Button on the headset, you can then add a Blue BlueParrott Headset Listener.

import com.blueparrott.blueparrottsdk.BPHeadsetListener;


public class BpSDKDemo extends AppCompatActivity implements BPHeadsetListener {

    BPHeadset headset;

    //get a handle to the BlueParrott Button on the headset
    headset = BPSdk.getBPHeadset(this)

    //add a BPHeadsetListener
    headset.addListener(this);

    @Override
    public void onConnect() {
        logStatus("Connected");
        //place your code here
    }

The BlueParrott listener allows your application to listen for the stages associated with establishing a connection to the BlueParrott Button:

  • Connected
  • Connection Progress
  • Connection Failure

Connected

When your app is successfully connected to the BlueParrott Button a connected event is triggered.

Connection Progress

You may retrieve the status of progress during the connection process, and optionally keep your user informed of progress.


Method from class : com.blueparrott.blueparrottsdk.BPHeadsetListener
--------------------------------------------------------------------

@Override
public void onConnectProgress(int progressCode) {
    logStatus(getStatusDescription(progressCode));
}

Note: Constants from class BPHeadsetListener are in the format PROGRESS_WAITING_TO_CONNECT as per table

PROGRESS_ Value Meaning
WAITING_TO_CONNECT 0 Connection attempt will commence shortly
STARTED 1 Connection attempt has started
FOUND_CLASSIC_HEADSET 2 A Bluetooth headset has been found
REUSING_CONNECTION 3 Another app is connected over BLE, attempting to re-use connection
BLE_SCANNING_ 4 Scanning for BLE services
FOUND_BP_SERVICE 5 The BlueParrott service has been found
CONNECTING_TO_BLE 6 Attempting to connect to the BlueParrott service over BLE
READING_HEADSET_VALUES 7 BLE connection established, reading settings from headset
USING_BT_CLASSIC 8 Checking to see if Classic is available

Connection Failure

Method from class : com.blueparrott.blueparrottsdk.BPHeadsetListener
--------------------------------------------------------------------

@Override
If the connection attempt fails the following error codes may be returned and should be handled in your code.

public void onConnectFailure(int errorCode) {
    //handle the connection failure here
    //this may include instruction "Retry or turn headset off then on"
}

Note: Constants from class BPHeadsetListener are in the format CONNECT_ERROR_UPDATE_ANDROID as per table
CONNECT_ERROR_ Value Meaning
UPDATE_ANDROID 1 Android OS 4.4 or greater required for Classic Connection
BLUETOOTH_NOT_AVAILABLE 2 Bluetooth is not turned on
ALREADY_CONNECTED 3 BlueParrott Button is already connected
ALREADY_CONNECTING 4 Another connection attempt is already under way
NO_HEADSET_CONNECTED 5 There is no Bluetooth headset connected
HEADSET_NOT_SUPPORTED 6 Headset may not support BlueParrott Button
UPDATE_YOUR_FIRMWARE 7 Firmware on the headset is not offering BlueParrott Button Service. Firmware may be too old
UPDATE_YOUR_SDK_APP 8 This SDK/App is too old to connect to the firmware version on headset
HEADSET_DISCONNECTED 9 Headset classic connection disconnected during BLE connection attempt
TIMEOUT 10 Unknown error, connection attempt has timed out
BLE_REQUIRES_LOLLIPOP 11 Android OS 5.0/Lollipop or greater required for BLE Connection

Setting the BlueParrott Button Mode

Once connected to the BlueParrott Button the next step is to enable the BlueParrott Button in order to send events from the BlueParrott Button on the headset to your application on the handset. It is possible to check to see if the BlueParrott Button has been enabled previously and if not you may proceed to enable it.

If required by your program you may also disable the BlueParrott Button SDK this would reset the BlueParrott Button to the factory setting of a mute button.

if (!headset.sdkModeEnabled()) {
    logStatus("Enabling SDK...");
    headset.enableSDKMode();
}

if (headset.sdkModeEnabled()) {
    headset.disableSDKMode();
    //do something...
}

Listen for BlueParrott Button Mode Update

You can monitor the success of enabling the SDK using the mode update methods from the BlueParrott Headset Listener.

Methods from class : com.blueparrott.blueparrottsdk.BPHeadsetListener
---------------------------------------------------------------------

@Override
public void onModeUpdate() {
    logStatus("Mode Updated");
}      

Listen for BlueParrott Button Mode Update Failure

Methods from class : com.blueparrott.blueparrottsdk.BPHeadsetListener
---------------------------------------------------------------------

@Override
public void onModeUpdateFailure (int reasonCode) {
    logStatus("Mode Update Failed. Reason" +getUpdateErrorDescription(reasonCode));
    //handle error
}

If mode update fails you may look for one of the following update errors to provide feedback to the user.

UPDATE_ERROR_ Value Meaning
NOT_CONNECTED 1 BLE connection not available
WRITE_FAILED 2 Writing to headset over BLE failed
TIMEOUT 3 Operation timed out

Once you enable the SDK on the BlueParrott Button data can be sent over bluetooth from the headset to your app for BlueParrott Button events.

You can then use BlueParrott Headset listener to monitor the traffic from the headset.


if (headset.sdkModeEnabled()) {
    logStatus("Disabling SDK...");
    headset.disableSDKMode();
}

Disconnecting from the BlueParrott Button

Generally at this point you will have established a handle to the BlueParrott Headset Button in order to connect to the BlueParrott Button.

Now you have the ability to check if the BlueParrott Button is connected and you can disconnect the BlueParrott Button in your code if required.

import com.blueparrott.blueparrottsdk.BPSdk;
import com.blueparrott.blueparrottsdk.BPHeadset;

BPHeadset headset;

//get a handle to the headset
    headset = BPSdk.getBPHeadset(this);

    if (headset.connected()) {
               logStatus("Disconnecting..");
               headset.disconnect();
           }

It is appropriate that at a point where the app is running in the foreground only and the UI is being shutdown that the app would disconnect from the BlueParrott Button.

    //in onDestroy
    if (headset != null) {
                headset.disconnect();
            }

Listen to Disconnect

Using the BlueParrott Headset Listener you may listen for a disconnect event in your program and carry out any appropriate actions and housekeeping at this point.

import com.blueparrott.blueparrottsdk.BPHeadsetListener;


public class BpSDKDemo extends AppCompatActivity implements BPHeadsetListener {

    //add a BPHeadsetListener
    headset.addListener(this);

        @Override
        public void onDisconnect() {
            logStatus("Disconnected");
             //do stuff here
        }

Simple Sample Application

There are two sample apps available for Android, this is a sample of a simple integration. Allowing the developer to get up and running quickly while using the BlueParrott SDK.

The blueParrottSDKdemo sample application runs in the foreground only. It allows you to connect to and disconnect from the BlueParrott Button. You may enable and disable the SDK on the BlueParrott Button. When the SDK is enabled it gives you feedback on the clicks of the BlueParrott Button.

This simple demo includes the following features:

  • Connects to headset BlueParrott Button
  • Includes a choice of connection via classic Bluetooth, BLE or Auto connection
    • including obtaining required Bluetooth permission
  • Enables BlueParrott SDK
  • Utilises BlueParrott listener recognising the BlueParrott Button clicks
  • Disables BlueParrott SDK
  • Disconnects from the headset BlueParrott Button

This is a sample screen from the application:

BluePArrott SDK Demoframe