Cognex Mobile Barcode SDK for Android

The differences in the capabilities of smartphones as barcode scanning devices result in a user experience different from purpose-built scanners, impacting the design of the mobile barcode scanning application. By following a few simple guidelines, you can develop applications with the cmbSDK that work the same way when using an MX Mobile Terminal or the built-in camera of a mobile device.

• To initiate barcode scanning without a dedicated hardware trigger, see Mobile Device Triggering.
• To aim for barcode scanning with a smartphone that does not have an aimer, see Mobile Device Aiming.
• To choose the most suitable orientation for barcode scanning, see Mobile Device Orientation.
• To reduce the CPU usage of the mobile device when it performs image analysis and barcode decoding, see Optimizing Mobile Device Performance.

CmbSDK employs a default set of options for barcode reading with the built-in camera of the mobile device. However, cmbSDK does not implement saved configurations for the camera reader. This means that every time an application starts that uses the camera reader, it starts with the default settings of the camera reader. For a list of the default settings, see the Appendix.

Without a hardware trigger, mobile devices must use alternative methods to initiate barcode scanning. The cmbSDK supports three methods to trigger barcode scanning:

• Application or workflow driven trigger: The application code or the business logic/workflow of the application invokes the scanning module. In simple programming terms, it is calling a function like startScanner().
• Virtual trigger: To start or stop the scanning process the application provides a button on the screen. Depending on the application design, you need to press and hold the virtual button to keep the scanner running, this invokes the scanning module.
• Simulated trigger: Press one of the volume-down buttons to start or stop the scanning process just like when you pull a trigger on a purpose-built scanner.

The built-in camera provides a live-stream preview on the display of the mobile device for barcode aiming. Reposition the mobile device until the barcode appears in the field of view of the built-in camera and the application decodes it. CmbSDK provides a built-in preview control that can be displayed in partial or full screen, and in either portrait or landscape orientation.

The cmbSDK also supports passive aimers: devices attached to the mobile device or its case that use the LED flash of the device as a light source to project an aiming or targeting pattern. The mobile device can project an aimer pattern similar to a purpose-built scanner so live-preview is not needed. However, by using the LED flash as an aimer, general scanning illumination is not available.

The cmbSDK supports portrait orientation, landscape orientation and auto-rotation for both the presentation of the barcode preview and the scan direction. Mobile devices can scan most barcodes regardless of the orientation of the application and/or the mobile device.

Mobile devices are an ideal platform for barcode decoding. The cmbSDK is optimized for mobile environment, but image analysis and barcode decoding is still a CPU intensive activity. Since these processes share the mobile device's CPU with the mobile operating system (OS), services, and other applications, these processes optimize your barcode scanning application and limit it to only using the features of the cmbSDK that they need.

To optimize your application:

• Enable decoding only for the barcode types the application needs to scan. The cmbSDK supports the decoding of almost 40 different barcode types and subtypes, enabling all results in low performance and unexpected errors.
• Do not enable certain symbologies and/or advanced features at the same time. 
• Optimize your camera resolution. By default, the cmbSDK uses HD images for barcode decoding.
• Use an appropriate decoder effort level. The cmbSDK has a configurable effort level that controls how aggressively it performs image analysis. The cmbSDK uses a default value (level 2) that is sufficient for most barcodes. Using a higher level can result in better decoding of poorer quality barcodes, resulting in slower performance.

No barcode symbologies are enabled by default, when the cmbSDK is initialized for use with the mobile device's built-in camera.

Installing the Android cmbSDK

1. Download the Cognex Mobile Barcode SDK for Android from the Cognex Mobile Barcode Scanner Solutions page.
2. Start Android Studio and add the SDK AAR file as a module to your project:
   1. Right click your app module, select New > Module > Import .JAR/.AAR Package, and click Next.

   2. Browse the cmbSDK .AAR file in the File name field, and click Finish.

      

3. After the new module is available, right click your app module, select the Open Module Settings, and choose the Dependencies tab.
4. Click the + sign at the top of the Declared Dependencies dialog box and select the 3 Module dependency.
5. Select cmbsdklib from the popup window and click OK, making the cmbsdklib module available under the Dependencies tab.

6. Install the MX Connect application from the Play Store to communicate with MX mobile terminals.

Installing the iOS cmbSDK:

1. Install the latest XCode for iOS Development.
2. Download the Cognex Mobile Barcode SDK for iOS.

To use cmbSDK for barcode scanning with a mobile device without an MX mobile terminal, you need to install a license key. If the license key is missing, asterisks will appear instead of scanned results.

Contact your Cognex Sales Representative for information on how to obtain a license key, including 30-day trial licenses.

Android: 

1. After obtaining your license key, add the following line in the AndroidManifest.xml file of your application under the application tag:

   <meta-data android:name="MX_MOBILE_LICENSE" android:value="YOUR_MX_MOBILE_LICENSE"/>

2. Replace YOUR_MX_MOBILE_LICENSE with your license key.

   <application
           android:allowBackup="true"
           android:icon="@mipmap/ic_launcher"
           android:label="@string/app_name"
           android:roundIcon="@mipmap/ic_launcher"
           android:supportsRtl="true"
           android:theme="@style/AppTheme">
           <activity android:name=".ScannerActivity" android:configChanges="orientation|screenSize">
               <intent-filter>
                   <action android:name="android.intent.action.MAIN" />
   
                   <category android:name="android.intent.category.LAUNCHER" />
               </intent-filter>
           </activity>
   
           <meta-data android:name="MX_MOBILE_LICENSE" 
              android:value="g/9ytJzcja+sxt4DTEDxR4hp6sZh9bmL97vUx+EE9uY=" />
   
   </application>

You can also add the license key by copying the text below when you create new instance from ReaderDevice.

case PhoneCamera:
          readerDevice = ReaderDevice.getPhoneCameraDevice(this, param_cameraMode,
             PreviewOption.DEFAULTS, null, "SDK_KEY");

iOS:

After obtaining your license key, add it as a String in your application's Info.plist file under the key MX_MOBILE_LICENSE.

1. Install the MX Connect application from the Play store. This app enables your mobile phone to seamlessly connect to Cognex MX readers.

2. Install cmbSDK to your project.

3. Use DataManSystem.createDataManSystemForMXDevice() factory method to create a DatamanSystem object.

4. Remove:
   • All DataManSystem.createDataManSystemOverUsb() methods from your project.
   • All DataManSystem.createDataManSystemOverUsbAccessory() methods from your project.
   • USB_ DEVICE-ATTACHED and USB_ACCESSORY_ATTACHED Intent filters and meta-data from the AndroidManifest.xml file.
   • USB and accessory descriptor xml files from the XML folder.

CmbSDK provides a high-level, abstract interface for supported scanning devices: the MX mobile terminals and the camera of the mobile phone.

The primary interface between your application and the barcode scanning device is the ReaderDevice class. The ReaderDevice class represents an abstraction layer to the device, handling all communication and necessary hardware management, such as scanning with a smartphone. 

Perform the following steps to use cmbSDK: 

1. Create an instance from the ReaderDevice class with the type of scanning device you want to use (MX reader or camera reader).

2. Connect to the ReaderDevice instance you created.

3. Configure the ReaderDevice instance, if necessary.

4. Start scanning. 

• MX mobile terminals need to be reconfigured if they become disconnected due to for example timing out or drained battery. To avoid this, you can save the configuration.
• Your application can use both an MX mobile terminal and camera scanning. In this case you have to establish a new connection to a different device after disconnecting from the current device. You can check our sample app for demonstration to see how it works.

Perform the following steps to set up and start using cmbSDK:

1. Import the following package members, or just the classes you use:

   import com.cognex.dataman.sdk.*
   import com.cognex.mobile.barcode.sdk.*

2. According to your needs:

   • If you want to show partial camera preview, you need the ViewGroup container, for example RelativeLayout, otherwise if you want to use full screen preview (default) you don't need any additional containers. For example if we want to use partial view in our sample application add this RelativeLayout inside activity_scanner.xml at the end of ConstraintLayout and use it in reader device constructor (ViewGroup parameter) when reader device is initialized.

     <RelativeLayout
        android:id="@+id/rlPreviewContainer"
        android:layout_width="match_parent"
        android:layout_height="200dp"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintStart_toEndOf="parent" />

   • If you want to display the last scanned image, you need the ImageView container for showing the last frame of a preview or scanning session.

   • If you want to display the scanned result as a text, you need a TextView.

3. Set up the following interfaces to monitor the connection state of the reader and receive information about the read code:

   public class ScannerActivity extends AppCompatActivity implements
           OnConnectionCompletedListener, ReaderDeviceListener,
           ActivityCompat.OnRequestPermissionsResultCallback {
   ....
   
   // The connect method has completed, here you can see whether there was an error with establishing the connection or not
       @Override
       public void onConnectionCompleted(ReaderDevice readerDevice, Throwable error) {
           // If we have valid connection error param will be null,
           // otherwise here is error that inform us about issue that we have while connecting to reader device
           if (error != null) {
   
               // ask for Camera Permission if necessary
               if (error instanceof CameraPermissionException)
                   ActivityCompat.requestPermissions(((ScannerActivity) this), new String[]{Manifest.permission.CAMERA}, REQUEST_PERMISSION_CODE);
   
               updateUIByConnectionState();
           }
       }
   
   // This is called when a connection with the self.readerDevice has been changed.
       // The readerDevice is usable only in the "ConnectionState.Connected" state
       @Override
       public void onConnectionStateChanged(ReaderDevice reader) {
           clearResult();
           if (reader.getConnectionState() == ConnectionState.Connected) {
               // We just connected, so now configure the device how we want it
               configureReaderDevice();
           }
   
           isScanning = false;
           updateUIByConnectionState();
       }
   
   // This is called after scanning has completed, either by detecting a barcode, canceling the scan by using the on-screen button or a hardware trigger button, or if the scanning timed-out
       @Override
       public void onReadResultReceived(ReaderDevice readerDevice, ReadResults results) {
           clearResult();
   
           if (results.getSubResults() != null && results.getSubResults().size() > 0) {
               for (ReadResult subResult : results.getSubResults()) {
                   createResultItem(subResult);
               }
           } else if (results.getCount() > 0) {
               createResultItem(results.getResultAt(0));
           }
   
           isScanning = false;
           btnScan.setText("START SCANNING");
           resultListAdapter.notifyDataSetChanged();
       }
   
   // This is called when a MX-1xxx device has became available (USB cable was plugged, or MX device was turned on),
       // or when a MX-1xxx that was previously available has become unavailable (USB cable was unplugged, turned off due to inactivity or battery drained)
       @Override
       public void onAvailabilityChanged(ReaderDevice reader) {
           if (reader.getAvailability() == Availability.AVAILABLE) {
               connectToReaderDevice();
           } else if (reader.getAvailability() == Availability.UNAVAILABLE) {
               AlertDialog.Builder alert = new AlertDialog.Builder(this);
               alert
                       .setTitle("Device became unavailable")
                       .setPositiveButton("OK", null)
                       .create()
                       .show();
           }
       }

4. Instantiate a ReaderDevice object.

Initialize a Reader Device object for MX readers using the following factory method: 

case MX:
      readerDevice = ReaderDevice.getMXDevice(this);

      //Listen when a MX device has became available/unavailable
      if (!availabilityListenerStarted) {
          readerDevice.startAvailabilityListening();
          availabilityListenerStarted = true;
      }

The availability of the MX mobile terminal can change when the device turns on or off, or if the USB cable gets connected or disconnected. You can handle those changes using the following ReaderDeviceListener interface method: 

public void onAvailabilityChanged(ReaderDevice reader);

You are recommended to use an MX mobile terminal to scan barcodes. However, cmbSDK also supports using the built-in camera of a mobile device. This includes the support of optional external aimers or illumination, and the customization of the live-stream preview's appearance.

To scan barcodes using the built-in camera of a mobile device, initialize the ReaderDevice object using the getPhoneCameraDevice static method. The camera reader has several options when initialized. The following parameters are required:

• Context
• CameraMode
• PreviewOption
• ViewGroup
• RegistrationKey
• CustomData

The Context parameter provides a reference to the activity you are currently in.

The CameraMode parameter is of type CameraMode defined in CameraMode.java and it accepts one of the values listed in the following table. 

These modes provide the following default settings for the reader:

• The zoom feature is available and a button to control it is visible on the live-stream preview (if displayed).
• The simulated hardware trigger (volume control buttons) is disabled.
• When startScanning() is called, the decoding process is started.

Based on the selected mode, additional illumination options and behaviors are set, also listed in the table.

The PreviewOption parameter is of type PreviewOption defined in PreviewOption.java, and is used to change the reader’s default values or override defaults derived from the selected CameraMode. You can specify the following options:

The ViewGroup (optional) parameter specifies the container for the live-stream preview. If the parameter is left null, a full screen preview is used.

The RegistrationKey (optional) parameter is used to license your SDK with license key that you have

The CustomData (optional) parameter is used for custom tracking

Example

Create a reader with no aimer, no zoom button, and using a soft trigger:

readerDevice = ReaderDevice.getPhoneCameraDevice(this, CameraMode.NO_AIMER, PreviewOption.NO_ZOOM_BUTTON | PreviewOption.PAUSED);

This starts a preview with the scanner paused and a soft trigger button to toggle scanning. After pressing the soft trigger button, the expected preview look is this:

The viewfinder in the image has an active scanning surface as a result of having set active symbologies. For more details, see Enabling Symbologies.

From Android 6.0 and above you need to request permission from the user to access the built-in camera of the mobile device.

If the camera cannot be opened due to permission issues, the onConnectionCompleted(readerDevice, error) callback contains a CameraPermissionException in the error parameter. You can check for this exception type with the instanceof operator and request permission within the Activity.

if (error instanceof CameraPermissionException)
      ActivityCompat.requestPermissions(((ScannerActivity) this), new String[]{Manifest.permission.CAMERA}, REQUEST_PERMISSION_CODE);

You need to implement the ActivityCompat.OnRequestPermissionResultCallback interface in your Activity to catch the user permission result.
To handle user response in onRequestPermissionResult(…), you can use the following code to retry connecting to the phone camera:

@Override
    public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
        // Check result from permission request. If it is allowed by the user, connect to readerDevice
        if (requestCode == REQUEST_PERMISSION_CODE) {
            if (grantResults.length > 0 && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                if (readerDevice != null && readerDevice.getConnectionState() != ConnectionState.Connected)
                    readerDevice.connect(ScannerActivity.this);
            } else {
                if (ActivityCompat.shouldShowRequestPermissionRationale(((ScannerActivity) this), Manifest.permission.CAMERA)) {
                    AlertDialog.Builder builder = new AlertDialog.Builder(this)
                            .setMessage("You need to allow access to the Camera")
                            .setPositiveButton("OK", new DialogInterface.OnClickListener() {
                                @Override
                                public void onClick(
                                        DialogInterface dialogInterface,
                                        int i) {
                                    ActivityCompat.requestPermissions(ScannerActivity.this, new String[]{Manifest.permission.CAMERA},
                                            REQUEST_PERMISSION_CODE);
                                }
                            })
                            .setNegativeButton("Cancel", null);
                    AlertDialog dialog = builder.create();
                    dialog.show();
                }
            }
        }
    }

Before connecting, set the ReaderDeviceListener object to receive events: 

readerDevice.setReaderDeviceListener(this);

For details, see step 3 in Setting up you application to-use the Cognex Mobile Barcode SDK for Android.

Additionally, you can enable sending the last triggered image and SVG from the reader: 

readerDevice.enableImage(true);
readerDevice.enableImageGraphics(true);

Invoke the connect method after initializing the ReaderDevice and setting a listener method to handle responses from the reader. The connect method takes OnConnectionCompletedListener as parameter: 

 //Make sure the device is turned ON and ready
readerDevice.connect(ScannerActivity.this);

The following listener methods are called with the new ReaderDevice status information:

public void onConnectionStateChanged(ReaderDevice reader);
public void onConnectionCompleted(ReaderDevice reader, Throwable err)

The onConnectionCompleted method passed as a parameter of connect is also invoked as the connection process completes. If there was a connection error, this method provides a Throwable object.

After connecting to the scanning device, you may need to change some of its settings. CmbSDK provides a set of high-level and device-independent APIs for setting and retrieving the current configuration of the device.

You can start scanning barcodes with a properly configured reader by calling the startScanning method from your ReaderDevice class:

readerDevice.startScanning();

• If using an MX mobile terminal, you can press a trigger button on the device to turn the scanner on and read a barcode.
• If using the camera reader, cmbSDK starts the camera, displays the configured live-stream preview, and begins analyzing the frames from the video stream, looking for a configured barcode symbology.

You can stop scanning with the following:

readerDevice.stopScanning();

Scanning stops under one of the following conditions:

• The reader found and decoded a barcode.
• You released the trigger or pressed the stop button on the live-stream preview screen.
• The camera reader timed out without finding a barcode.
• The application calls the stopScanning() method.

When a barcode is decoded successfully, you receive a ReadResults iterable result collection object in the ReaderDevice listener method. The onReadResultReceived listener method is invoked either because the reader decoded a barcode or the scanning process was complete. 

Example

// This is called after scanning has completed, either by detecting a barcode, canceling the scan by using the on-screen button or a hardware trigger button, or if the scanning timed-out
    @Override
    public void onReadResultReceived(ReaderDevice readerDevice, ReadResults results) {
        clearResult();

        if (results.getSubResults() != null && results.getSubResults().size() > 0) {
            for (ReadResult subResult : results.getSubResults()) {
                createResultItem(subResult);
            }
        } else if (results.getCount() > 0) {
            createResultItem(results.getResultAt(0));
        }

        isScanning = false;
        btnScan.setText("START SCANNING");
        resultListAdapter.notifyDataSetChanged();
    }

CmbSDK does not enable any symbologies by default for barcode reading with the built-in camera of the mobile device. You must enable all barcode symbologies your application needs to scan to achieve optimal scanning performance. For more details, see Optimizing Mobile Device Performance.

Individual symbologies can be enabled using the following method of the ReaderDevice class:

public void setSymbologyEnabled(final Symbology symbology, final boolean enable, final OnSymbologyListener listener)
readerDevice.setSymbologyEnabled(Symbology.DATAMATRIX, true, null);
readerDevice.setSymbologyEnabled(Symbology.UPC_EAN, true, null);

All symbologies used for the symbology parameter in this method can be found in ReaderDevice.java. 

Examples 

 /* Enable QR scanning */
readerDevice.setSymbologyEnabled(Symbology.QR, true, null);

You can also use the same method to disable symbologies: 

/ * Disable Code 25 scanning */ readerDevice.setSymbologyEnabled(Symbology.C25, false, null);

You can implement the method for OnSymbologiesListener to check the result of the symbology change:

@Override
public void onSymbologyEnabled(ReaderDevice reader, Symbology symbology, Boolean enabled, Throwable error) {
if (error != null) {
/* Unsuccessful
probably the symbology is unsupported by the current device, or there is a problem with the connection between the readerDevice and MX device */
} else {
// Success }
}

If your reader device is equipped with illumination lights, you can control them: when scanning starts, you can turn them on or off. Use the following method of your Reader Device object: 

readerDevice.setLightsOn(true, null);

You can implement the interface method for OnLightsListener, which is the second parameter of the method. 

public class ScannerActivity extends AppCompatActivity implements .... OnLightsListener .... { ....
@Override
public void onLightsOnCompleted(ReaderDevice reader, Boolean on, Throwable error) {
if (error != null) { // Unsuccessful
} else {
// Success }
} }

If the built-in camera of a mobile device is used as the reader device, you can configure zoom levels and how they are used. There are three zoom levels:

• normal: not zoomed (100%)
• level 1 zoom (150% on Android by default)
• level 2 zoom (300% on Android by default)

The SET CAMERA.ZOOM-PERCENT [100-MAX] [100-MAX] command is for configuring how far the two levels zoom in percentage. 100 is not zoomed and MAX (goes up to 1000) zooms as far as the device is capable of. The first argument is used for setting level 1 zoom, and the second for level 2 zoom.

You can check the current zoom setting with the GET CAMERA.ZOOM-PERCENT command, which returns two values: level 1 and level 2 zoom.

Example

readerDevice.getDataManSystem().sendCommand("SET CAMERA.ZOOM-PERCENT 250 500");

GET/SET CAMERA.ZOOM 0-2 is another command that sets the zoom level or returns the actual setting. Possible values for the SET command are:

• 0 - normal (not zoomed)
• 1 - level 1 zoom
• 2 - level 2 zoom

You can call this command before or even during scanning, and the zoom goes up to the configured level. If scanning is finished, the value is reset to normal behavior (0).

Example

readerDevice.getDataManSystem().sendCommand("SET CAMERA.ZOOM 2");

When using the mobile device's camera, cmbSDK allows you to see the camera preview inside a preview container or in full screen. This preview also contains a customizable overlay. The cmbSDK camera overlay features buttons for zooming, flashing and closing the scanner, and a progress bar indicating the scan timeout.

To use the legacy camera overlay originally used in cmbSDK v2.0.x and ManateeWorks SDK, use this property from MWOverlay before initializing the readerDevice:

MWOverlay.overlayMode = MWOverlay.OverlayMode.OM_LEGACY;

When using the cmbSDK overlay:

1. Copy the layout files from the Resources/layout directory into your project and modify them. Use cmb_scanner_partial_view.xml if scanning is started inside a container (partial view), and use cmb_scanner_view.xml if scanning is started in full screen.
2. Modify the layout according to your needs. For example, you can change the sizes, positions or color of the views, remove views and add your own views, like an overlay image.

Both the cmbSDK and the legacy overlay allow you to change the images used on the zoom and flash buttons if your images have the same name as the names cmbSDK uses. You can find the images and names used in cmbSDK in the Resources/drawable-mdpi and drawable-hdpi directories. While the other resolutions are optional, these two directories must contain your images with the correct names so that cmbSDK displays the proper images.

Both the cmbSDK and the legacy overlay allow you to change the color and width of the rectangle that is displayed when a barcode is detected.

Example:

MWOverlay.locationLineColor = Color.YELLOW;
MWOverlay.locationLineWidth = 6;

In scenario when you have a lot of barcodes on small surface, very close one to another there is new feature available from cmbSDK v.2.2.0 called Target (centered) decoding. There is 3 DMCC's that are used to configure this mode. Use them after valid connection to reader device:

• (GET|SET) DECODER.TARGET-DECODING [ON|OFF]
• (GET|SET) DECODER.CENTERING-WINDOW [0-100] [0-100] [1-100] [1-100]
• (GET|SET) DECODER.DISPLAY-TARGET [ON|OFF]

GET/SET DECODER.TARGET-DECODING command is used to enable or disable target decoding. By default OFF.

Example

readerDevice.getDataManSystem().sendCommand("SET DECODER.TARGET-DECODING ON");

DECODER.CENTERING-WINDOW command is used to set (or get) the size of the centering window. The numbers are in percent of the image. centerX and centerY defines where the middle of the centering window should be in the image. sizeX and sizeY define the size of the centering window.
If a barcode touches the centering window it is accepted. The barcode doesn’t have to be contained in the window, but just touch it. By default [50 50 10 10].

Example

readerDevice.getDataManSystem().sendCommand("SET DECODER.CENTERING-WINDOW 50 50 5 5");

DECODER.DISPLAY-TARGET command is used to set (or get) if the centering window should be shown on the SVG result. By default OFF

Example

readerDevice.getDataManSystem().sendCommand("SET DECODER.DISPLAY-TARGET ON");

Here is example of scanning preview when target decoding is enabled:

Centering window (rectangle) color and width can be changed with:

MWOverlay.targetRectLineColor = Color.RED;
MWOverlay.targetRectLineWidth = 2;

If you want to scan more barcodes at once and in one scanning session you can use Multi code mode. This mode is available from cbmSDK v.2.2.x. To configure this mode 4 DMCC's are used. Use them after valid connection to reader device:

• (GET|SET) MULTICODE.NUM-CODES [1-255]
• (GET|SET) MULTICODE.PARTIAL-RESULTS [ON|OFF]
• (GET|SET) DECODER.REREAD-NOT-LAST-N [0-100]
• (GET|SET) MULTICODE.MAX-NUM-CODES [1-5] [1-255]

GET/SET MULTICODE.NUM-CODES command is used to set number of codes reader must find for a successful read result. By default 1.

Example

readerDevice.getDataManSystem().sendCommand("SET MULTICODE.NUM-CODES 3");

GET/SET MULTICODE.PARTIAL-RESULTS command is used to set how the reader interprets the number of codes to find. ON = reader will return a successful read if 1 or more codes are found. OFF = reader will return a successful read only if number of codes found equals MULTICODE.NUM-CODES value. By default OFF.

Example

readerDevice.getDataManSystem().sendCommand("SET MULTICODE.PARTIAL-RESULTS ON");

GET/SET DECODER.REREAD-NOT-LAST-N command is used to define N, do not read code if this code was read within the last N reads. By default 0, no restriction.

Example

readerDevice.getDataManSystem().sendCommand("SET DECODER.REREAD-NOT-LAST-N 1");

GET/SET MULTICODE.MAX-NUM-CODES command is used to set expected maximum number of codes to find for each symbology grouping 1 - 5:

1. DataMatrix
2. QR Code/MaxiCode/AztecCode
3. Linear/ Postal/ Stacked
4. VeriCode
5. DotCode

No expected value for any single symbology can exceed parameter MULTICODE.NUM-CODES, the total number of codes to find. 1st param is symbology group, secont one is max num of codes. By default 1 for all.

Example

readerDevice.getDataManSystem().sendCommand("SET MULTICODE.MAX-NUM-CODES 1 3");

When multi code mode is enabled, in onReadResultReceived callback function you can get list of all results from getSubResults() method from ReadResults object. If multi code mode is disabled this method will return null.

Starting form v.2.2.x we add parsers plugin in cmbSDK. Parsers help us to extract decoded results into a structured format (JSON, Key-Value) for search, sort, and validation. There are six types of parsers:

1. AAMVA
2. GS1
3. HIBC
4. ISBT128
5. IUD
6. SCM

Also there is option to use AUTO parser type in our SDK and we will try to find which one should be used.

Use setParser() method from ReaderDevice object to set parser type that you want to use, or getParser() to get selected type. Set parser type after valid connection to reader device. None by default.

Example

readerDevice.setParser(ResultParser.AAMVA);

After you enable needed parser type in onReadResultReceived callback function from ReadResult object you can get structured format from received result:

//Returns parsed text in json format from the result
results.getResultAt(0).getParsedJSON();
//Returns parsed text from the result
results.getResultAt(0).getParsedText();

If you want to edit/resize region of interest for your scanning process while you are using phone camera as reader device you can use (GET|SET) DECODER.ROI-PERCENT [X W Y H] DMC command (available from cmbSDK v2.2.x), where X and Y represent the starting point of the RoI in each axis, and W H represent the RoI width and height starting from the starting point, with values in percentages. The range of 0-100 is checked, as well as minimum values of 5 for width and height, and the constraints implied between args, such as the total sum for a given axis to be no more than 100. Use this DMCC after valid connection to reader device.

Example

readerDevice.getDataManSystem().sendCommand("SET DECODER.ROI-PERCENT 10 80 10 80");

Cognex scanning devices implement DataMan Control Commands (DMCC) for configuring and controlling the device. Every feature of the device can be controlled using this text-based language. The API provides a method for sending DMCC commands to the device. Commands exist both for setting and querying configuration properties.

The Appendix includes the complete DMCC reference for the camera reader.

The following examples show different DMCC sent to the device for more advanced configuration.

Examples 

//Change the scan direction to omnidirectional 
readerDevice.getDataManSystem().sendCommand("SET DECODER.1D-SYMBOLORIENTATION 0", ScannerActivity.this);
//Change live-stream preview's scanning timeout to 10 seconds 
readerDevice.getDataManSystem().sendCommand("SET DECODER.MAX-SCAN-TIMEOUT 10", ScannerActivity.this);

You can also invoke DMCC query commands and receive their response in the OnResponseReceivedListener.onResponseReceived() method. 

//Get the type of device connected readerDevice.getDataManSystem().sendCommand("GET DEVICE.NAME", new OnResponseReceivedListener() {
@Override
public void onResponseReceived(DataManSystem dataManSystem, DmccResponse dmccResponse) {
if (dmccResponse.getError() != null) {
// Unsuccessful
Log.e("DMCC_ERR", “GET DEVICE.NAME failed”,dmccResponse.getError());
} else {
// Success - Use the following result fields:
//int mResponseId = dmccResponse.getResponseId(); //String mPayLoad = dmccResponse.getPayLoad(); //byte[] mBinaryData = dmccResponse.getBinaryData(); }
} );
}

CmbSDK includes a method for resetting the device to its default settings (not the factory defaults). In case of an MX mobile terminal, this is the saved configuration. In case of a built-in camera, these are the defaults identified in the Appendix, where no symbologies are enabled. This method of resetting the device is the following: 

readerDevice.resetConfig(null);

You can monitor the completion of this async method using the OnResetConfigListener interface, which is an optional parameter. 

public class ScannerActivity extends Activity implements .... OnResetConfigListener .... { ....
@Override
public void onResetConfigCompleted(ReaderDevice reader, Throwable error) {
if (error != null) { // Unsuccessful
} else {
// Success }
}

When a barcode is successfully read, the onReadResultReceived method creates and returns a ReadResult object. In case of having multiple barcodes successfully read on a single image or frame, multiple ReadResult objects are returned in the ReadResult object.

The ReadResult class has properties describing the result of a barcode read:

• is GoodRead() (boolean): tells whether the read was successful or not
• get ReadString() (String): the decoded barcode as a string
• get Image() (Bitmap): the image/frame that the decoder processed
• get ImageGraphics() (String): the boundary path of the barcode as SVG data
• get Xml() (String): the raw XML that the decoder returned
• get Symbology (Symbology): the symbology type of the barcode. This enum is defined in ReaderDevice.java.

When a scanning ends with no successful read, a ReadResult is returned with the goodRead property set to false.

To enable the image and imageGraphics properties being filled in the ReadResult object, set the corresponding enableImage() and/or enableImageGraphics() properties of the ReaderDevice object.

To access the raw bytes from the scanned barcode, you can use the XML property. The bytes are stored as a Base64 String under the "full_string" tag. The example shows how you can use an XML parser to extract the raw bytes from the XML property.

Example

try {
    XmlPullParserFactory factory = XmlPullParserFactory.newInstance();
    factory.setNamespaceAware(true);
    XmlPullParser xpp = factory.newPullParser();

    String tag = "";

    // the raw bytes will be stored in this variable
    byte[] bytes;

    xpp.setInput(new StringReader(result.getXml()));
    int eventType = xpp.getEventType();
    while (eventType != XmlPullParser.END_DOCUMENT) {
        if (eventType == XmlPullParser.START_TAG) {
            tag = xpp.getName();
        }
        else if (eventType == XmlPullParser.TEXT && tag.equals("full_string")) {
            String base64String = xpp.getText();
            // Get the bytes from the base64 string here
            bytes = Base64.decode(base64String, Base64.DEFAULT);
            break;
        }
        else if (eventType == XmlPullParser.END_TAG && tag.equals("full_string")) {
            tag = "";
            break;
        }
        eventType = xpp.next();
    }
} catch (Exception e) {
    e.printStackTrace();
}

The image and SVG results are disabled by default, which means that when scanning, the ReadResults do not contain any data in the corresponding properties.

To enable image results, invoke the enableImage() method from the ReaderDevice object:

readerDevice.enableImage(true);

To enable SVG results, invoke the enableImageGraphics() method on ReaderDevice object:

readerDevice. enableImageGraphics(true); 

If a device disconnects due to low battery condition or manual cable disconnection, it can be detected by the onConnectionStateChanged() method of the ReaderDeviceListener interface. 

The following table lists the various DMCC commands supported by the cmbSDK when using the built-in camera for barcode scanning. 

Observe these precautions when installing the Cognex product, to reduce the risk of injury or equipment damage:

• To reduce the risk of damage or malfunction due to over-voltage, line noise, electrostatic discharge (ESD), power surges, or other irregularities in the power supply, route all cables and wires away from high-voltage power sources.
• Changes or modifications not expressly approved by the party responsible for regulatory compliance could void the user’s authority to operate the equipment.
• Cable shielding can be degraded or cables can be damaged or wear out more quickly if a service loop or bend radius is tighter than 10X the cable diameter. The bend radius must begin at least six inches from the connector.
• This device should be used in accordance with the instructions in this manual.
• All specifications are for reference purpose only and may be changed without notice.