Capture Events¶

Add a @Subscribe annotated method that takes an Event as an argument to any Activity and Capture will automatically register your Activity to receive notifications for the subscribed Event.

Connection Events¶

Your app can only receive data from the scanner if your app and the scanner are both connected to the service and your app has ownership of the scanner. Your app has ownership of the scanner while it is in foreground. If your app is in background, even if the scanner is connected to the service and scans barcodes, the scanned data will not be sent to your app.

Note

Ownership of the reader will be given the last app to Start Capture.

The Socket Mobile reader may indicate that there is an active connection via an LED, but your app is responsible for displaying the status of its connection to both the service and the scanner to the user.

Service Status Event¶

Add an @Subscribe annotated method that takes a ConnectionStateEvent as an argument to any Activity to be notified of changes to the state of the connection to the service.

Sample code for Service Events¶

@Subscribe(threadMode = ThreadMode.MAIN, sticky = true)
public void onCaptureServiceConnectionStateChange(ConnectionStateEvent event) {
    ConnectionState state = event.getState();
    CaptureClient client = event.getClient();

    if (state.hasError()) {
        CaptureError error = state.getError();
        switch(error.getCode()) {
            // ...
        }
    }

    switch(state.intValue()) {
        case ConnectionState.CONNECTING:
            // ...
            break;
        case ConnectionState.CONNECTED:
            // ...
            break;
        case ConnectionState.READY:
            // ...
            break;
        case ConnectionState.DISCONNECTING:
            // ...
            break;
        case ConnectionState.DISCONNECTED:
            // ...
            break;
    }
}

Device Arrival Event¶

Device Arrival Event is sent everytime the service detects a new socket mobile device. To receive device availability events, add a @Subscribe annotated method that takes a DeviceStateEvent as an argument to any Activity and it will be called when a scanner becomes available or unavailable.

Sample code for Device Arrival Event¶

@Subscribe(threadMode = ThreadMode.MAIN, sticky = true)
    public void onCaptureDeviceStateChange(DeviceStateEvent event) {
        DeviceClient device = event.getDevice();
        DeviceState state = event.getState();

        if (DeviceType.retrieveInterfaceType(device.getDeviceType()) == DeviceType.InterfaceType.kNone) {
            Log.d(TAG, "Setting a socketcam device");
            mSocketCamDevice = device;
        }

        switch(state.intValue()) {
             case DeviceState.READY:
                 // Ready to use
                 break;
             default:
                  // Device not ready for use
                }
    }

Note

You should not need to store the current state of the device if you subscribe to the event with sticky = true. When an activity is destroyed and recreated, it will receive an event that contains the current state of the device.

Device Arrival for Combo devices¶

A Combo device supports barcode scanning as well as NFC &QR Reading and Writing. For a Combo device like S370, there will be two Device Arrival events. One for the NFC reader/writer and one for the Barcode scanner.

Sample code for Combo Device Arrival Event¶

 @Subscribe(threadMode = ThreadMode.MAIN, sticky = true)
    public void onCaptureDeviceStateChange(DeviceStateEvent event) {

        DeviceClient device = event.getDevice();

        if (DeviceType.isNfcScanner(device.getDeviceType())) {
            // Handle NFC function for Combo device
        } else if (DeviceType.isBarcodeScanner(device.getDeviceType())) {
            // Handle Barcode function for Combo device
        } else {
            // Unknown device type
        }
    }

Data Events¶

Subscribe to DataEvent to receive notifications when a barcode is scanned.

Sample code to Receive Data¶

@Subscribe(threadMode = ThreadMode.MAIN)
      public void onScan(DataEvent event) {
          Log.d(TAG, "onScan : event = [" + event + "]");
          DecodedData data = event.getData();
          if (data.result == DecodedData.RESULT_SUCCESS) {
              print(event.getData().getString());
          } else {
              Log.d(TAG, "Scan Cancelled");
          }
      }

Tip

Using ThreadMode.MAIN allows you to modify your UI in onData without switching threads - e.g. to display the decoded data. If you do not need to modify your UI in onData, consider using ThreadMode.ASYNC instead. For more info, see EventBus - Delivery Threads

Properties¶

Properties can be used to control the Scanner. There are two types of properties.

Properties that change the State of the scanner or the SDK. They have both get and set methods. An example of this is: Get/Set Friendly Name. You can use this property to get the current friendly name or update it to a new value.
Properties that take an Action. They have only set method. An example of this is : Set Trigger. This will programmatically trigger the scanner to start scanning for a barcode.

An implementation of the PropertyCallback listener is required to get the result for getProperty/setProperty. Result is sent in onComplete method of PropertyCallback.

PropertyCallback¶

void onComplete(CaptureError error, Property property)

In case of successful completion of getProperty/setProperty, CaptureError will be null.

Commonly used properties¶

Trigger Scanner¶

In certain scenarios it can be easier to trigger a scan using an on-screen button than using the trigger button the device. Call DeviceClient.trigger() on a connected device to trigger a scan.

Start Trigger
This will start the trigger the device to read barcode/tag. For combo devices like S370, this will start read and stops once a barcode/tag has been read
device.trigger(mSetPropertyCallback);
Stop Trigger
Stops the device to read a barcode/tag
device.triggerStop(mSetPropertyCallback);
Trigger Continuous
This can be used to do multiple scans with a single trigger for barcode/tag
device.triggerContinuous(mSetPropertyCallback);
Disable Trigger
This can be used to disable the Trigger button on the Scanner
device.triggerDisable(mSetPropertyCallback);
Enable Trigger
This can be used to enable the Trigger button on the Scanner
device.triggerEnable(mSetPropertyCallback);

Enable or Disable symbology¶

In CaptureSDK the barcode symbology is referred as Data Source. Enabling and disabling data sources allows your application to control which barcode types the scanner is able to read. This can be useful to enable a data source that isn’t enabled by default or to prevent the user from scanning an unwanted barcode.

Enable or disable the relevant data source when the device first becomes available.

// Example in Kotlin

@Subscribe(threadMode = ThreadMode.MAIN, sticky = true)
fun onCaptureDeviceStateChange(DeviceStateEvent event) : Unit {
    when(event.state.intValue()) {
        DeviceState.READY -> {
            event.device.enableDataSource(DataSource.ID_QR_CODE) {
                // OK or Error
            }
            event.device.disableDataSource(DataSource.ID_UPC_A) {
                // OK or Error
            }
        }
    }
}

Data Confirmation¶

Data Confirmation Mode indicates what is expected to the send the Data ACK back to the scanner.

Using the data confirmation APIs, your app can indicate to the user through the scanner user interface (Beep, LED and Vibrate) when decoded data is accepted or rejected. This can be used to simply validate the data in-app or to enforce a particular workflow.

Note

Until the data is acknowledged, the scanner’s trigger is locked and the user is unable to scan additional barcodes.

While it is possible to send feedback to the device without any additional configuration, the user may receive duplicate and potentially conflicting feedback unless you disable local acknowledgement first.

// Example in Kotlin

@Subscribe(threadMode = MAIN)
fun onDeviceReady(event: DeviceStateEvent) {
    when (event.state.intValue()) {
        DeviceState.READY -> {
            event.device.disableLocalAcknowledgment() {
                // OK or Error
            }
        }
    }
}

@Subscribe
fun onData(event: DataEvent) {
    scanCounter++
    when (scanCounter % 2) {
        0 -> event.device.acceptData()
        else -> event.device.rejectData()
    }
}

Theme Selection¶

The Themes Selection allows to choose LEDs sequences that are played on S550 or S370 devices.

There are 4 pre-programmed themes contained in the devices:

Health

Access

Value

Membership

Each theme has 4 sequences:

Ready: when the device is idle, waiting for reading a barcode or a NFC tag

Reading: when the device is reading a barcode or a NFC tag

Read success: when the device did read correctly a barcode or a NFC tag

Read failure: when the device did not read correctly a barcode or a NFC tag

// Example to set Health theme in java

byte theme = DeviceTheme.THEME_HEALTH;
device.setThemeSelection(theme, mSetPropertyCallback);

Note

You should not expect the current sequence to be affected. You will have to trigger a new read again to see the new sequence.

Note

Both devices of a combo device like S370 can have their own theme. For instance, Access theme for the NFC reader and Health theme for the Barcode scanner.