Getting Started - iOS

Including the SDK

The minimum iOS version is 9.1.

Add the BlueParrott SDK to your project by dragging the framework file into your project.

In your project's Target, enable Background Modes and tick 'Uses Bluetooth LE accessories' if you will be using the button while the app is in the background.

Permissions

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.

Use specific permissions

There are many different permissions depending on the function of the application program in question it is up to the programmer to ensure that all other permissions for your program are included (e.g. microphone).

Connect to the BlueParrott Button

Connect to the BlueParrott Button using methods from the BlueParrott SDK.

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.

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

    // ViewController.h

    #import <BPHeadset/BPHeadset.h>
    @interface ViewController : UIViewController <BPHeadsetListener>
    // ...
    @end
    // ViewController.m

    @implementation ViewController
    - (void)viewDidLoad {
        [super viewDidLoad];
        // To instantiate, just use `sharedInstance`:
        headset = [BPHeadset sharedInstance];
        [headset addListener:self];
    }

    // To connect, set a listener that conforms to the BPHeadsetListener protocol, then call connect:
    - (IBAction)connectButtonTouched:(id)sender {
        [headset connect];
    }
    @end

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.

    // ViewController.h

    #import <BPHeadset/BPHeadset.h>
    @interface ViewController : UIViewController <BPHeadsetListener>
    // ...
    @end
    // ViewController.m

    @implementation ViewController
    - (void)viewDidLoad {
        [super viewDidLoad];
        // To instantiate, just use `sharedInstance`:
        headset = [BPHeadset sharedInstance];
        [headset addListener:self];
    }

    // To connect, set a listener that conforms to the BPHeadsetListener protocol, then call connect:
    - (void) onConnect {
        NSLog(@"Connected");
        // place your code here
    }
    @end

The Blue BlueParrott listener allows your app to listen and manage activities 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, as connection may take time it is advisable to keep your user informed of progress.

Method from protocol: BPHeadsetListener
--------------------------------------------------------------------

public void onConnectProgress:(BPConnectProgress) status {
    logStatus(getStatusDescription(progressCode));
}

Note: Constants from BPConnectProgress are as per table
Status Value Meaning
BPConnectProgressStarted 0 Connection attempt has started
BPConnectProgressScanning 1 Scanning for BLE services
BPConnectProgressFound 2 The BlueParrott service has been found
BPConnectProgressReading 3 BLE connection established, reading settings from headset

Connection Failure

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

Method from protocol: BPHeadsetListener
--------------------------------------------------------------------

- (void) onConnectFailure:(BPConnectError) reasonCode {
    //handle the connection failure here
    //this may include instruction "Retry or turn headset off then on"
}

Note: Constants from BPConnectError are as per table
Reason Code Value Meaning
BPConnectErrorUnknown 0 Unknown error occurred
BPConnectErrorBluetoothDisabled 1 Bluetooth is not turned on
BPConnectErrorFirmwareTooOld 2 Firmware on the headset is not offering BlueParrott Button Service. Firmware may be too old
BPConnectErrorSDKTooOld 3 This SDK/App is too old to connect to the firmware version on headset

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.

    // ViewController.m
    // Enable SDK Mode
    if (!headset.sdkModeEnabled) {
        [headset enableSDKMode];
    }

    // Disable SDK Mode
    if (headset.sdkModeEnabled) {
        [headset disableSDKMode];
    }

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.

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 protocol: BPHeadsetListener
---------------------------------------------------------------------

    - (void) onModeUpdate {
        NSLog(@"Mode Updated");
    }

Listen for BlueParrott Button Mode Update Failure

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

Methods from protocol: BPHeadsetListener
---------------------------------------------------------------------

    - (void) onModeUpdateFailure:(BPModeUpdateError) reasonCode {
        NSLog(@"Mode Update Failed. Reason %@", [self getUpdateErrorDescription:reasonCode]);
        //handle error
    }
Reason Code Value Meaning
BPModeUpdateErrorUnknown 0 Writing to headset over BLE failed
BPModeUpdateErrorDisconnected 1 BLE connection not available

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.

Listening for BlueParrott Button Events

Once connected to the BlueParrott Button, with the button enabled to send events the BlueParrott Listener for the BlueParrottSDK may be used to monitor clicks of the BlueParrott Button.

When the user clicks on the headset BlueParrott Button your app will receive an event and can react to the users interactions.

The BlueParrott Listener provides methods to allow your code to interact with the users headset BlueParrott Button clicks:

  • Button Down - button has been pressed

  • Button Up - button has been released

  • Tap - single tap

  • Double Tap

  • Long Press

Methods from protocol: BPHeadsetListener
---------------------------------------------------------------------

- (void) onButtonDown:(BPButtonID) buttonID {
    NSLog(@"Button Down");
     //your code goes here
}

- (void) onButtonUp:(BPButtonID) buttonID {
    NSLog(@"Button Up");
     //your code goes here
}

- (void) onTap:(BPButtonID) buttonID {
    NSLog(@"Tap");
    //your code goes here
}

- (void) onDoubleTap:(BPButtonID) buttonID {
    NSLog(@"Double Tap");
    //your code goes here
}

- (void) onLongPress:(BPButtonID)buttonID {
    NSLog(@"Long Press");
     //your code goes here
}

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.

    // ViewController.m

    - (IBAction)disconnectButtonTouched:(id)sender {
        if (headset.connected) {
            [headset disconnect];
        }
    }
    @end

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.

    // ViewController.h

    #import <BPHeadset/BPHeadset.h>
    @interface ViewController : UIViewController <BPHeadsetListener>
    // ...
    @end
    // ViewController.m

    @implementation ViewController
    - (void)viewDidLoad {
        [super viewDidLoad];
        // To instantiate, just use `sharedInstance`:
        headset = [BPHeadset sharedInstance];
        [headset addListener:self];
    }

    // Called when the headset is disconnected (e.g. out of range)
    - (void) onDisconnect {
        // Notify the user
    }
    @end

Simple Sample Application

The iOS SDK Sample Application is a sample of a simple integration, allowing the developer to get up and running quickly while using the BlueParrott SDK.

The BPSDKSample 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
  • Enables BlueParrott SDK mode
  • Utilises BlueParrott listener recognising the BlueParrott Button clicks
  • Disables BlueParrott SDK mode
  • Disconnects from the headset BlueParrott Button

This is a sample screen from the application:

Screenshot BPSDKDemo