How to Use Barcode Xpress Mobile for Android

This SDK provides the Barcode Xpress native recognition library and Java source code examples that demonstrate how to access it.

The source code is divided into two layers.

BXAPI, the most basic layer provides an interface to the native recognition library.
Two other examples are the sample applications that show how to use BXAPI.

BXCameraSample manages the user interface and camera hardware by sending images to BXAPI for recognition. It may be used as an example or serve as the basis of your own application by customizing the hooks it provides for key operations.
BXFileSample is a simple example of how to decode an image using BXAPI and use the results.

The Java sources are located in src/main/java/com/accusoft/BarcodeXpress. The native recognition library is delivered as a shared library, located at BXAPI/BXAPI/src/main/jniLibs/armeabi/libAccusoft.BarcodeXpress.so.

BarcodeXpress Mobile supports recognition of the full set of the types supported by the full version of Barcode Xpress. These are listed in supported barcode types.

Deployment of Barcode Xpress Mobile is licensed on a per situation basis and requires a licensing agreement with Accusoft. The Barcode Xpress Mobile SDK requires a license key to be compiled into the source code of your application. Complete a licensing agreement with an Accusoft Sales Representative and receive the license key. Our licenses are designed to work for only one application. So, we require the package name or applicationId of your application to make an appropriate license.

If you are using Gradle, your application's package name should be the same as your applicationId. You can find the applicationId in the "defaultConfig" section of your build.gradle file for the main module of your app.
If you are not using Gradle, you can find your package name in the manifest tag inside the AndroidManifest.xml file of your project.

For example, com.accusoft.BarcodeXpress.BXCameraSample is the applicationId and package name of our BXCameraSample demonstration application. This can be found in the "defaultConfig" section of BXCameraSample/BXCameraSample/build.gradle.

Note: This string is case sensitive.

When you have the package name, contact sales@accusoft.com to obtain a license or for more information.

BXAPI - package com.accusoft.BarcodeXpress.BXAPI

SDK users with an existing application will be interested primarily with BXAPI. It provides methods that accept images in several formats and it makes calls into the native recognition library for barcode decoding. It also provides utility methods for obtaining the library version, specifying the required license key, and setting the types of barcodes that will be recognized. The native recognition library has the optional ability to detect and reject blurred images.
Important methods are:

recognizeImage(Bitmap image, long barcodeTypes) - Recognize and decode barcode from a Bitmap image, which may be in RGB_565 (16 bits per pixel), ARGB_8888 (32 bits per pixel), or grayscale (8 bits per pixel) format.
recognizeImage(byte[] rawPixels, int width, int height, int stride, int bpp, long barcodeTypes) - Recognize and decode barcode from an array of uncompressed pixel data, which can be in RGB_565, ARGB_8888, or 8-bit gray format. Suitable for processing an image from the video camera.
recognizeImageFromJPEGPixels(byte[] jpegPixels, long barcodeTypes) - Recognize and decode barcode from a byte array of JPEG-compressed pixel data. Suitable for processing an image from the picture camera.
setBlurDetection(boolean) - Enable (default) or disable rejection of blurred images before recognition is attempted.
getWorkerLibraryVersion() - Get version information from the decoding library.
YUVtoRGB565(byte[] pixels, int width, int height) - Convert a YUV image (supplied from video camera) to RGB565 format suitable for creating an Android Bitmap.

The BXLicense class holds information from the Accusoft license, primarily the license key. Until a valid license key is provided, the license key contained in the sources of BXCameraSample or BXFileSample may be used and will result in the final character of every decoded value being replaced with an asterisk (*). The constructor for BXAPI requires a BXLicense and image recognition by the native library will not be performed if the license is invalid.
Sample BXLicense constructor:


BXLicense(String OEMKey, Application application, long solutionKey1, long solutionKey2, long solutionKey3, long solutionKey4)

Note: The OEMKey string is provided by Accusoft upon completion of a licensing agreement, and that the solutionKey1, solutionKey2, solutionKey3, and solutionKey4 parameters are currently un-used.

The BXTypeConstants class defines the constants from which you build the set of barcode types you want the library to decode. This value would then be used as a parameter to one of the recognition methods of BXAPI.

The BXResult class contains the result of recognition by the native library. It contains points that describe a rectangle locating the barcode inside the image. It also contains decoding status, confidence, decoded data, and the barcode type. The class has methods to return information about what was learned by decoding the image:

getBarcodeType() - Returns the barcode type. You may use BXTypeConstants.toString() to obtain a String representation of its name.
getConfidence() - Returns an integer in the range 0..100 which describes how certain the result is.
getDataString() - Returns the decoded string from the barcode.
getResultPoints() - Returns a 4-element array of BXResultIdentLocation[] that contains the location of the barcode in the bitmap.
getResultStatus() - Returns a status code that describes the overall decoding operation.
getDataBytes() - returns a byte array which contains the raw decoded data.
getDataLength() - returns the length in bytes of the decoded data.

BXCameraSample - package com.accusoft.BarcodeXpress.BXCameraSample

The BXCameraSample is right for you if you are looking for a simple Android application to scan barcodes with the camera and display decoded results. Android applications interact with the hardware using an event-driven interface called an Activity. The Activity model means that certain actions are done in callbacks. BXCameraSample provides callbacks that happen at key points in the application, such as when an image frame has been obtained from the camera or when decoding results are available. These callbacks allow for insertion of customized code to be run at key points during application execution.

Specifically, the following callbacks are provided by BXCameraSampleActivity.java:

onStartBarcodeXpress() - Called upon initialization of the activity, when application is being started.
onResumeRecognition(SurfaceHolder holder) - Called when the activity gains focus, both at application startup and after having previously lost focus (user switched to another application).
onPictureImage(byte[]) - Called after capturing a JPEG-encoded picture image from the camera, but before passing it to the recognition library.
onPreviewImage(byte[] yuvData, int width, int height) - Called after capturing a preview image from the camera, but before passing it to the recognition library.
onBarcodeRecognition(Bundle msgBundle) - Called when a barcode is recognized by Barcode Xpress.

When onBarcodeRecognition(Bundle msgBundle) is called, the msgBundle parameter may be used as follows:

msgBundle.getParcelable("Bitmap") - Returns the Bitmap that was decoded.
msgBundle.getParcelable("Result") - Returns a BXResult which contains the results of decoding the image.

In addition, the method setBarcodeTypes(long barcodeTypes) is provided to allow you to enable or disable the recognition of any of the supported barcode types.

The BXAPI.BXLicense class holds information from the Accusoft license. The constructor for BXAPI requires a BXLicense; image recognition by the native library will not be performed if the license key is invalid. It would be appropriate to set the license in BXCameraSample.onStartBarcodeXpress(). The BXCameraSample class will then handle setting the license in a manner that will allow the recognition library to proceed successfully.

BXFileSample - package com.accusoft.BarcodeXpress.BXFileSample

The BXFileSample is right for you if you want to see the mechanism for integrating Barcode Xpress, without all the complexity of camera management. It shows the basic operations necessary to decode an image and use the results. The image file that it decodes is located in res/drawable-nodpi/barcode.bmp.

Customizing the Samples

Things you will want to customize for your own build of either demo application are as follows:

Application Icon - The SDK ships with high, medium and low resolution demo icons. If you rename these icons, you will want to change the android:icon element in AndroidManifest.xml.
The icons are located at:
```
                    res/drawable-hdpi/icon_demo.png
                    res/drawable-mdpi/icon_demo.png
                    res/drawable-ldpi/icon_demo.png
                    
```
Keystore - For your convenience, a .keystore file is provided; you will want to replace this with a .keystore file you have built for your application.
Local.properties - Defines where the Android SDK is installed.
AndroidManifest.xml - A number of things are specified in the manifest that are particular to your organization; the included manifest is an example.
Build.gradle - Each module in your app should have its own build.gradle file. This file tells Gradle how your application should be built, what SDK to use, which dependencies it needs, and where to get them. If you are using Gradle, settings in the build.gradle file will override those found in AndroidManifest.xml. Settings like compiledSdkVersion, targetSdkVersion, minimumSdkVersion will be taken from build.gradle. The applicationId will also override the package name specified in AndroidManifest.xml.

If you already have your own application and are integrating Barcode Xpress, you will want to include BXAPI as a dependency.

Permissions

This BXCameraSample requires the following permission setting, found in AndroidManifest.xml:

          android.permission.CAMERA

To write data to the SD card, you need to add the following below the existing uses-permission elements:

          <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

To read data from the SD card, you need to add the following below the existing uses-permission elements:

          <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

Build and Run the Barcode Mobile Sample Applications

Use the following instructions as a guideline to load, run and deploy the sample applications.

NOTE: These instructions should be used with Android Studio.

Open the IDE.
Click File > Open and select the sample to run. Click OK. Wait for Gradle to finish syncing.
Run the application.