Menu

Manage peripherals

As described in the Peripherals overview and How it works, your app can use an abstracted set of APIs in the Knox SDK to manage different vendor peripherals and models, without needing to call APIs in the vendor-proprietary peripheral SDKs.

This tutorial describes how an app on a mobile device uses the Knox SDK to connect to a USB-integrated barcode reader, get information about the reader, configure the reader's settings, and start reader operation. The tutorial introduces key concepts, data models, and methods. For more comprehensive detail, see the following:

Tip: This tutorial uses Java naming conventions. Constants are in all caps (KEY_USB_DEVICES_FOR_DEFAULT_ACCESS), classes have initial capitalization (ContentValues), and methods are in camel case (getConstantResolver). To see if an API is from the Android or Samsung Knox SDK, hover over the linked text to see if it goes to an Android or Samsung web domain.

Knox 3.7.1 introduced the use of Android content providers to manage features. For more information, browse Use content providers.

Select a peripheral

To select a peripheral and grant it permission to use the USB port on a mobile device, use KEY_USB_DEVICES_FOR_DEFAULT_ACCESS, which defines constants to grant packages USB permission.

First, define a class to identify the peripheral you want to manage, using the vendor ID, plugin app package name, and product ID defined in KEY_USB_DEVICES_FOR_DEFAULT_ACCESS. Ideally, a backend web server provides the data values to your app, after an OT admin selects a peripheral through a web console. However, a standalone sample app can either accept the data through UI fields, or hardcode the data as follows:

static class UsbPermission {
    final static  Uri KNOX_CONFIG_URI
       = Uri.parse("content://com.samsung.android.knox.sdk/config/application");
    final static String SELECTION = "usb-devices-for-default-access";
    final static String DEFAULT_PACKAGE = "com.samsung.android.peripheral.koamtacplugin";
    final static String DEFAULT_VID = "7232";
    final static String DEFAULT_PID = "1081";
}

Next, allow the identified peripheral to use the Samsung device's USB port. Use a ContentValues object to build the key-value pairs.

public void setUsbPermission(boolean enable) {
    if (enable) {
        ContentValues contentValues = new ContentValues();
        contentValues.put("vendor-id", UsbPermission.DEFAULT_VID);
        contentValues.put("package-name", UsbPermission.DEFAULT_PACKAGE);
        contentValues.put("product-id", UsbPermission.DEFAULT_PID);
        String selection = "key=?";
        String[] selectionArgs = new String[] {UsbPermission.SELECTION};
        mContext.getContentResolver().update(UsbPermission.KNOX_CONFIG_URI,
            contentValues, selection, selectionArgs);
    } ...

Get peripheral configuration

Define a method to get information about a peripheral's current configuration, using constants defined in PeripheralConstants.

    public void getConfiguration(Context context, String peripheralId) {
        ArrayList<String> list = new ArrayList<>();
        list.add(KEY_PERIPHERAL_BARCODE_DATA_PROCESS_MODE_STR);
        list.add(KEY_PERIPHERAL_PREFIX_STR);
        list.add(KEY_PERIPHERAL_SUFFIX_STR);
        list.add(KEY_PERIPHERAL_BARCODE_ENABLE_TIMESTAMP_BOOL);
        list.add(KEY_PERIPHERAL_ENABLE_BEEP_SOUND_BOOL);
        list.add(KEY_PERIPHERAL_BARCODE_ENABLED_SYMBOLOGY_LIST);
        list.add(KEY_PERIPHERAL_BARCODE_SUPPORTED_SYMBOLOGY_LIST);
        list.add(KEY_PERIPHERAL_BATTERY_LEVEL_STR);
        list.add(KEY_PERIPHERAL_CONNECTIVITY_TYPE_STR);
        list.add(KEY_PERIPHERAL_FIRMWARE_STR);
        list.add(KEY_PERIPHERAL_MANUFACTURER_STR);
        list.add(KEY_PERIPHERAL_NAME_STR);
        list.add(KEY_PERIPHERAL_SERIAL_NUMBER_STR);
        list.add(KEY_PLUGIN_VENDOR_STR);
        list.add(KEY_PLUGIN_VERSION_STR);

Create an instance of a PeripheralManager and get the configuration from the peripheral:

    PeripheralManager peripheralManager = PeripheralManager.getInstance(context);

    peripheralManager.getConfiguration(peripheralId, list,
        new PeripheralResultListener(){
            @Override
            public void onSuccess(Bundle bundle) {
                onGetConfiguration(bundle);
            }
        });

Once you get the configuration, parse the received information into variables:

private void onGetConfiguration(Bundle bundle) {
    ArrayList peripheralList = bundle.getParcelableArrayList(KEY_PERIPHERAL_BUNDLE_LIST);
    for (Bundle peripheral : peripheralList) {
        // barcodeDataProcessMode is matched PeripheralConstants.BarcodeDataProcessMode
        String barcodeDataProcessMode = peripheral.getString(KEY_PERIPHERAL_BARCODE_DATA_PROCESS_MODE_STR);
        boolean enableTimestamp = peripheral.getBoolean(KEY_PERIPHERAL_BARCODE_ENABLE_TIMESTAMP_BOOL);
        String batteryLevel = peripheral.getString(KEY_PERIPHERAL_BATTERY_LEVEL_STR);
        // connectivityType is matched with PeripheralConstants.ConnectivityType
        String connectivityType = peripheral.getString(KEY_PERIPHERAL_CONNECTIVITY_TYPE_STR);
        boolean enableBeepSound = peripheral.getBoolean(KEY_PERIPHERAL_ENABLE_BEEP_SOUND_BOOL);
        String firmware = peripheral.getString(KEY_PERIPHERAL_FIRMWARE_STR);
        String manufacturer = peripheral.getString(KEY_PERIPHERAL_MANUFACTURER_STR);
        String peripheralName = peripheral.getString(KEY_PERIPHERAL_NAME_STR);
        String prefix = peripheral.getString(KEY_PERIPHERAL_PREFIX_STR);
        String suffix = peripheral.getString(KEY_PERIPHERAL_SUFFIX_STR);
        String serialNumber = peripheral.getString(KEY_PERIPHERAL_SERIAL_NUMBER_STR);
        String vendor = peripheral.getString(KEY_PLUGIN_VENDOR_STR);
        String version = peripheral.getString(KEY_PLUGIN_VERSION_STR);
        // symbology is matched with PeripheralBarcodeConstants.Symbology 
        ArrayList enabledSymbologyList =
            peripheral.getStringArrayList(KEY_PERIPHERAL_BARCODE_ENABLED_SYMBOLOGY_LIST);
        ArrayList supportedSymbologyList =
            peripheral.getStringArrayList(KEY_PERIPHERAL_BARCODE_SUPPORTED_SYMBOLOGY_LIST);

Display the variable values:

        Log.d(TAG, "barcodeDataProcessMode [" + barcodeDataProcessMode + "]");
        Log.d(TAG, "enableTimestamp [" + enableTimestamp + "]");
        Log.d(TAG, "batteryLevel [" + batteryLevel + "]");
        Log.d(TAG, "connectivityType [" + connectivityType + "]");
        Log.d(TAG, "enableBeepSound [" + enableBeepSound + "]");

Configure peripheral settings

Configure the barcode reader's supported symbologies, barcode prefixes and suffixes, timestamps, and beep sound.

public void setConfiguration(Context context, String peripheralId) {
    Bundle bundle = new Bundle();
    bundle.putString(KEY_PERIPHERAL_BARCODE_DATA_PROCESS_MODE_STR,
        PeripheralConstants.BarcodeDataProcessMode.WEDGE);
    bundle.putString(KEY_PERIPHERAL_PREFIX_STR, "test_prefix");
    bundle.putString(KEY_PERIPHERAL_SUFFIX_STR, "test_suffix");
    bundle.putBoolean(KEY_PERIPHERAL_BARCODE_ENABLE_TIMESTAMP_BOOL, true);
    bundle.putBoolean(KEY_PERIPHERAL_ENABLE_BEEP_SOUND_BOOL, true);
    // symbology list
    ArrayList symbolList = new ArrayList<>();
    symbolList.add(PeripheralBarcodeConstants.Symbology.CODABAR);
    symbolList.add(PeripheralBarcodeConstants.Symbology.CODE11);
    symbolList.add(PeripheralBarcodeConstants.Symbology.CODE32);
    symbolList.add(PeripheralBarcodeConstants.Symbology.EAN13);
    bundle.putStringArrayList(KEY_PERIPHERAL_BARCODE_ENABLED_SYMBOLOGY_LIST, symbolList);
    PeripheralManager peripheralManager = PeripheralManager.getInstance(context);
    PeripheralManager.getInstance(context).setConfiguration(peripheralId, bundle,
        new PeripheralResultListener(){
            public void onSuccess(Bundle bundle) {
                // confirm success
            }
        });
}

Start and stop peripheral operation

Start the barcode reader and verify that the service returns a success indicator.

PeripheralManager.getInstance(context).start(profile,
    new PeripheralResultListener() {
        public void onSuccess(Bundle data) {
            // invoked when 'start' function succeeds
        }
}); 

Stop the barcode reader and verify that the service returns a success indicator.

PeripheralManager.getInstance(context).stop(
    new PeripheralResultListener() {
        public void onSuccess(Bundle data) {
             // invoked when 'stop' function succeeds
        }
});
Share it: