Grabba Driver for Android
Unified driver for Grabba devices on the Android operating system
API Overview


The APIs and associated types which form the interface to the driver may be grouped as follows:

  • Core functionality - connection, disconnection, versioning, etc; relevant for all Grabba devices
  • Technology-specific APIs - contain functions specific to a particular technology, e.g. the barcode API allows the user to start or stop barcode scans
  • Listener classes - listen for events from the driver and provide callbacks to user code when they occur
  • Data classes - encapsulate data in formats associated with the driver, and provide for querying and/or manipulation of that data

For new users, starting with the CoreAPI and ConnectionListener classes, particularly the and CoreAPI.close methods, is recommended.


The entire Android interface to the driver is contained within several packages each using the com.grabba.driver prefix:


The following conventions are followed throughout the driver APIs.

Non-blocking calls: Almost all API calls are non-blocking. Any operations which do take significant time to complete (e.g. barcode scanning) return their results via callbacks to listener objects, rather than blocking the calling thread for the duration. However, some operations involved with closing or releasing resources (most notably CoreAPI.close) do offer a blocking mode, which may be desirable when an application is suspending or shutting down.

Exceptions: Exceptions will not be thrown by these APIs except in response to erroneous input parameter values (e.g. supplying a value of 0 to a parameter with range 1-10). Any method (including constructors) which can throw an exception will be clearly documented as such. Exceptions may also be thrown by the Android runtime in rare scenarios (e.g. running out of memory); these will be passed through to the calling code, and should generally be considered to be fatal.

Error handling: Most error conditions (e.g. disconnection) are handled by way of error code objects (see ErrorCode for details) or sentinel values. Most methods which take error code parameters will proceed only if that error code object does not indicate any prior errors; consequently, it is possible to chain multiple operations together on the same error code object without having to check it after each call.

Thread-safety: Objects of the data classes are not thread-safe (except where immutable), and must consequently be restricted to a single thread or provided with protection. Aside from this, the remaining APIs - including all static functions and all listener classes - are fully thread-safe.

Callbacks: Callbacks may be triggered in response to driver-generated events. Callback support is managed by the listener classes, either via subclassing or delegation. No restrictions are placed upon the user functions which are called, other than that they must be thread-safe. The driver will not be adversely impacted if a callback function takes an extended period of time to complete execution.

Core Functionality

Core API functionality is provided by a single class, CoreAPI.

Of particular relevance are the and CoreAPI.close functions, which must be used by every application which interfaces to the driver, as these manage connections to Grabba devices.

Technology-Specific API Classes

Several classes provide functions for manipulating a particular hardware component or data source. They are:

  • BarcodeAPI - barcode reader support
  • ButtonAPI - button support, including press-to-scan functionality for barcode and proxcard readers
  • FingerprintAPI - fingerprint reader (and, in future, database) support
  • FirmwareAPI - Grabba device firmware versioning (and, in future, upgrade support)
  • KeyboardAPI - configuration and control of keyboard wedge application support
  • MagstripeAPI - magnetic stripe reader support
  • MRTD_API - machine-readable travel document (MRTD) support
  • MRZ_API - machine-readable zone (MRZ) support
  • ProxcardAPI - proximity card and radio-frequency identification (RFID) support
  • SmartcardAPI - contact smart card support

Each of these classes contain only static functions, do not require (or even support) object creation, and are fully thread-safe.

Listener Classes and Protocols

Several classes provide for user code to receive callbacks in response to driver-generated events:

  • BarcodeListener - receives barcode reader events (e.g. completion of barcode scan)
  • ButtonListener - receives button press and release events
  • ConnectionListener - receives device connection and disconnection events
  • FingerprintListener - receives fingerprint reader events (e.g. completion of fingerprint capture)
  • KeyboardListener - receives events for keystroke event generation in keyboard wedge applications
  • MagstripeListener - receives magnetic stripe reader events (e.g. completion of magstripe read)
  • MRTD_Listener - receives MRTD read events (e.g. read progress update)
  • MRZ_Listener - receives MRZ scan events (e.g. completion of scan)
  • ProxcardListener - receives proximity/RFID card events (e.g. completion of scan)
  • SmartcardListener - receives contact smart card events (e.g. insertion of card into reader slot)

Each of these inherit from generic base class Listener, which provides basic functionality common to all listener classes.

Objects of each listener class must be created in order to receive the associated callbacks; each such object is fully thread-safe.

The recommended approach for receiving callbacks is to subclass the relevant listener class, and create an object of that subclass. In cases where subclassing is infeasible (e.g. if callbacks must be received by a class with a different parent), each listener class also supports delegation - to use this, a listener object must be created and then its setDelegate method called.

Each listener class has an associated interface, which is implemented by the listener itself, and must also be implemented by any delegates:

Data Classes

The data classes encapsulate data used by the API and/or listener functions, or provide convenient capabilities for extracting and processing such data. They are:

  • BarcodeData - holds the contents and, if known, symbology ID for a scanned barcode
  • BER_TLV - encapsulates a Basic Encoding Rule: Type, Length, Value (BER-TLV) data structure as per the X.690 standard
  • CommandAPDU - holds a command Application Protocol Data Unit (APDU), for use with contact smart cards and selected proximity card functionality
  • ErrorCode - holds either a "no error" sentinel or an error code and associated description; used by many API functions to flag error conditions (e.g. loss of connection)
  • FingerprintImage - holds a captured fingerprint image plus associated metadata
  • FingerprintTemplate - holds a captured fingerprint template plus associated metadata
  • FingerprintUserMessage - holds a user message from the fingerprint reader, plus associated parameters (if any)
  • MagstripeData - holds the contents of a scanned magnetic stripe
  • MRTD_Image - extracts and holds embedded images from machine-readable travel documents (MRTDs)
  • MRZ_Data - holds raw contents of a scanned machine-readable zone (MRZ)
  • MRZ_Validated - holds fields parsed from a validated machine-readable zone (MRZ)
  • ProxcardData - holds the contents and card type ID for a scanned proximity/RFID card
  • ResponseAPDU - holds a response Application Protocol Data Unit (APDU), for use with contact smart cards and selected proximity card functionality

Objects of these classes are not thread-safe (unless immutable), however it is safe to concurrently access distinct objects and/or call static functions from different threads.