Bluetooth Insights Setup

Overview

The Bluetooth Insights library is installed as any other Android library used by an app. The general setup process is as follows:

Download Bluetooth Insights library (.jar) and integrate with SDK
Register app using package name, signature and delegation service tag
Bind app with Bluetooth Insights core service
Configure BTI options for analysis and logging as required
Process incoming BTI events in app

Requirements

One or more Zebra devices running Android 11 (or later)
Devices also require the following platform-specific LifeGuard Updates:
- SDM660 platform: expected Jan., 2023
- 6490 platform: date TBD
- 6375 platform - date TBD

I. Register App

Use EMDK's Profile Manager to create settings for Access Manager.
In Access Manager, select Service Access Action.
To register, choose "Allow Caller to Call Service".
To unregister, select "Disallow Caller to Call Service".
In the Service Identifier field, enter delegation-zebra-bind-zebrabluetooth-insight-service
In the Caller Package Name field, enter the package name of the app to be registered.
In the Caller Signature field, navigate to the signature (.pem) file of the app.

The BTI core service starts automatically and is always available to apps for binding.

For help extracting a signature (.pem) file from an .apk, visit Zebra's Sig Tools page.

II. Bind to Service

1. Add the following permission to the app's AndroidManifest.xml file:

    
    zebra.permission.BLUETOOTH_ANALYSIS

2. Use the following Java code to bind to the BTI core service:


public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.main);
    IBtInsightService service;
    ServiceConnection serviceConnection = new ServiceConnection() {
        public void onServiceDisconnected(ComponentName name) {
            Log.e(TAG , "BTInsightService DisConnected!!!");
            service = null
        }
        public void onServiceConnected(ComponentName name, IBinder service) {
            service = IBtInsightService.Stub.asInterface(service);
            Log.e(TAG , "BTInsightService Connected!!!");
        }
    };
    if(service != null){
        Intent i = new Intent( "com.zebra.bluetooth.BT_INSIGHT_ANALYZER");
        i.setPackage("com.zebra.bluetooth");
        boolean isServiceBindSuccess = getApplicationContext().bindService(i, serviceConnection, Service.BIND_AUTO_CREATE);
    }
}

Once the connection with BTInsightService is established, the IBtInsightService object is returned to interact with the service.

3. An app also must register as a client to the BTI core service using the IBtInsightService object, and can then get IBtInsightManager:

  
private final IBtInsightCallback.Stub callbackListener = new IBtInsightCallback.Stub() {
  public void onClientRegistered(int status, int clientId) {
      if (status == BtInsightConstants.StatusCode.STATUS_SUCCESS) {
          clientIdentity = clientId;
          IBtInsightManager manager = service.getBtManager(clientId);
      }
  }

  public void onClientUnregistered() {
      IBtInsightManager manager = null;
  }
};

ParcelUuid CLIENT_UUID = new ParcelUuid(UUID.randomUUID());
int result = service.registerClient(CLIENT_UUID, callbackListener);

Zebra recommends using the same UUID for each registration to avoid leaks of previous client registrations. The maximum number of registered clients is five (5).

III. Configure Options

After an app is registered as a client, events must be registered with BtInsightManager to receive callback notifications with event data. Use BtEventFilter for registering more than one event.

Events are grouped under specific features and can be retrieved using the getFeaturesSupported() method. Apps must choose at least one event from the supported features.


private final IBtInsightCallback.Stub callbackListener = new IBtInsightCallback.Stub() {    
    public void onClientRegistered(int status, int clientId) {
        if (status == BtInsightConstants.StatusCode.STATUS_SUCCESS) {
            try {
                BtInsightManager manager = mBtInsightServiceIf.getBtManager(clientId);
                if (manager != null) {
                    BtEventFilter filter  = new BtEventFilter();
                    filter.addEvent(BtInsightConstants.EventType.EVENT_CONNECTION_TYPE);
                    filter.addEvent(BtInsightConstants.EventType.EVENT_BOND_TYPE);
                    manager.registerPeripheralStatusEvent(clientId, filter);
                }
            }
            catch (RemoteException e) {
                Log.e(TAG, Log.getStackTraceString(e));
            }
        }
    }
}

Known Behavior

An app must unbind with the BTI core service when it's main activity is destroyed for any reason.

Once started, the BTI core service continues to run until at least one client is registered.
An app must unbind with the BTI core service when its main activity is destroyed for any reason.
Serial numbers of Bluetooth peripherals are available only from RS5100 and RS6000 scanners in SSI mode.
The serial number is provided in the BtBondStateEvent and BtConnectionEvent objects.
The Bluetooth device type is provided only for devices of a known PeripheralType.
For better identification of peripheral types, Zebra recommends using the Bluetooth Settings app to clear bonding with a scanner when switching between scanner accessory modes (i.e. HID/SSI/SPP).
When a client app is unregistered, all data analyzed by the app is erased.
To ensure preservation of analyzed data, an app must perform its own caching.

Sample App

A sample app using the Bluetooth Insights library provides the following:

A mechanism for binding to the Bluetooth Insight core service
Support of GAP features and their relevant events (i.e. bond, connection, registration)
Display of peripheral device data and instant update in UI
Display of BTI stack version in UI