Apache Cordova™ Plugin

To get a scanner up and running, the first thing to do, is to call the loadScanner() method.

It expects a device type and a callback function as a second param. The callback function is wrapped within a Promise and it's returned as one.

​/*   @return 
{
    const (string)action : the taken action (will always return LOAD READER)
    (string)  result : the message from the server
    (bool)    status : if the reader was loaded it will return true
    (string)  err    : the string error if an error was thrown
    (int)     type   : the type of the device that we connected to [0,1]
    (string)  name   : the name of the type of device DEVICES[type]
}
*/  

The device type parameter can either be a string constant, with possible values:

DEVICES : ["DEVICE_TYPE_MX_1000","DEVICE_TYPE_MOBILE_DEVICE","DEVICE_TYPE_BLUETOOTH"]

Or we can just pass 0 for DEVICE_TYPE_MX 2 for DEVICE_TYPE_MOBILE_DEVICE or 3 for DEVICE_TYPE_BLUETOOTH

Examples

//example as a callback:
    cmbScanner.loadScanner("DEVICE_TYPE_MOBILE_DEVICE",function(result){
        cmbScanner.connect();
    });
//example as a Promise
    cmbScanner.loadScanner("DEVICE_TYPE_MOBILE_DEVICE").then(function(result){
        cmbScanner.connect();
    });
//example passing the device type as an integer
    cmbScanner.loadScanner(2).then(function(result){
        cmbScanner.connect();
    });

To connect to a READER after we've loaded it, we need to use Connect.

cmbScanner.connect([callback]);

/*   @return 
    (promise)  {
        status : boolean, if connection succeded true if not false
        err : string , if status false err will not be null
    }
*/ 

Examples

/** Using connect and returning the value as a promise */
cmbScanner.connect().then(function(connectionState){
    console.log(connectionState); 
// { "status" : false, "err" : "Did not return OK in success" }
});
/** Using connect and returning the value as a callback function */
cmbScanner.connect(function(connectionState){
  console.log(connectionState); 
});

Even though we return the result of the connect action, acting on the result from the connect callback for the purpose of updating DOM elements or calling API methods that only work after we have a connection set, is not advised.

There is a listener callback (setConnectionStateDidChangeOfReaderCallback) function that can be set, that will always trigger whenever there is a change in the connection state and we should really keep that code there.

/*   @return 
    (promise)  {
        status : boolean, if connection succeded true if not false
        err : string , if status false err will not be null
    }
*/ 

Just as there is connect(), there is a disconnect() method that does the opossite of connect() :

cmbScanner.disconnect([callback])

Similarly to connect(), disconnect() too returns the connectionState in the callback function (which is wrapped into a Promise), and we could act on the connectionState, for example change the label from "connected" to "disconnected":

cmbScanner.disconnect(function(connectionState){
  if(connectionState == cmbScanner.CONSTANTS.CONNECTION_STATE_DISCONNECTED){

    document.getElementById('some-label').innerHtml('DISCONNECTED');
  }
  else if (connectionState == cmbScanner.CONSTANTS.CONNECTION_STATE_CONNECTED){
    document.getElementById('some-label').innerHtml('DISCONNECTED');
  }
  })

But, just like connect(), we don't have to do this because of setConnectionStateDidChangeOfReaderCallback() that sets a listener to all connect / disconnect / connecting / disconnecting events.

To handle successful scan results, we need to setup the ResultCallback function. This is done via the setResultCallback.

It sets the callback function for all didReceiveReadResultFromReader events.

cmbScanner.setResultCallback(function(result){
     if(result && result.readResults && result.readResults.length > 0){

                 result.readResults.forEach(function (item, index){

                     if (item.goodRead == true) {
//Perform some action on barcode read
//example:
                         document.getElementById('content').insertAdjacentHTML('beforeend','<div class="result"><span class="symbol">'+item.symbologyString+'</span> : '+item.readString+'</div>');
//we could put all this DOM handling in the dom helper object, but since it's just one line of code let's leave it be
                     }
                     else{
//Perform some action when no barcode is read or just leave it empty
           // navigator.notification.alert("Stopped");
                     }
                 });
             }
});

ResultCallback will fire every time there is a barcode scan (or the scanner was stopped either manually or it timedout with No Result).

Result Object

The structure of the barcode result is as follows:

To monitor for availability of the MX device use:

Set a listener on availability changes. Will fire when the device becomes available or loses availability.

Usage

cmbScanner.setAvialabilityCallback(funciton(availability){
        /**
        * availability - int representation of the Device availability
        */
        if (availability == CONSTANTS.AVAILABILITY_UNKNOWN) {
            //Perform some action when device availability is not known
        }
        else if (availability == CONSTANTS.AVAILABILITY_AVAILABLE) {
            //Perform some action when device is available
        }
        else if (availability == CONSTANTS.AVAILABILITY_UNAVAILABLE) {
            //Perform some action when device is not available
        }  
});

All connect/disconnect events should be handled within the callback function set with this API method.

The callback is optional, because the plugin provides a default callback that handles connect/disconnect events, but the default callback is only a placeholder function and doesn't offer much functionality to the end app developer.

When the connetionStateDidChange is fired, it will return one of 4 possible integer values

These can be accessed directly as integers, or the developer can use them from the CONSTANTS enum available to them by accessing the CONSTANTS object within the cmbScanner.

Example of this in action would be:

cmbScanner.setConnectionStateDidChangeOfReaderCallback(function(connectionState){
      if(connectionState == cmbScanner.CONSTANTS.CONNECTION_STATE_CONNECTED){
//do stuff while connected, like set a symbology to enabled
          return cmbScanner.setSymbologyEnabled("SYMBOL.QR",true).then(function(rr){
//see setSymbologyEnabled for more info on the rr (returned result) object
//after the symbol has been set we can send a command. Let's set the flash ON
             cmbScanner.sendCommand("SET LIGHT.INTERNAL-ENABLE ON")
              .then(function(result){
//if the command is succesful we should have the LIGHT turn ON whenever we start the scanning process
//and to check if the flash is ON we can use the isLightsOn API method
                  cmbScanner.isLightsOn().then(function(lights_on){
//light should be on
                  });
              });              
          });
      }   
  });

Here we not only listen to the connect/disconnect event, but we also enable a few symbologies and set the flash light on, via a command and the API method isLightsOn.

If we want to monitor the state of the scanner (READER), we need to setup this callback function.

Declaration

Usage

cmbScanner.setActiveStartScanningCallback(function(scannerState){
  if(scannerState == true){
    console.log('scanner is working');
  }
  else{
    console.log('scanner is not working');
  }
  });

As previously mentioned, setting this function, completely removes the need to setup a callback on the startScanning() or stopScanning() methods.

Even though it may seem more appropriate to just have that action return in a promise or a callback immediately after startScanning()/stopScanning() is called, due to the nature of the stopScanning process, which occurs every time there's is a result, it's best to listen for both actions (starting and stopping) in the same place.

To check and request permission to use the camera for scanning barcodes with the mobile device.

checkCameraPermission Declaration

requestCameraPermission Declaration

Example of how you would use it:

cmbScanner.checkCameraPermission(function(result){
	// Camera permission is granted
}, function(result) {
	// Camera permission is denied
    // If result is 1, on android means permission rationale should be shown, 
    // while on ios means permission can be requested, otherwise the result is 0
});

cmbScanner.requestCameraPermission(function(result){
	// Camera permission is granted
}, function(result) {
	// Camera permission is denied
    // If result is 1, on android means permission rationale should be shown, 
    // while on ios means permission can be requested, otherwise the result is 0
});

To start/stop the scanning process, we use these two methods. They can either be called from a button via the app's UI, or we can call the programmatically.

startScanning Declaration

stopScanning Declaration

Usage

Because of the nature of the READERS we should always set the setActiveStartScanningCallback() function, if we want to control certain DOM elements based on the status of the scanner (Reader).

cmbScanner.startScanning(function(scannerState){
 if(scannerState)
  document.getElementById('scanner-active-label')[removed] = 'RUNNING';      
 else
  document.getElementById('scanner-active-label')[removed] = 'STOPPED';      
});

Examples

<a href="cmbScanner.startScanning();">Start Scanner</a> <!-- button to start the scanner -->
<a href="cmbScanner.stopScanning();">Stop Scanner</a> <!-- button to stop the scanner -->

<a href="cmbScanner.startScanning(function(scanner_state){
//this callback function will be used, only if we don't already have one set via
// setActiveStartScanningCallback. In all other cases it will be ignored.
console.log(scanner_state);
});">Start Scanner</a> <!-- button to start the scanner with a callback, avoid this and always use setActiveStartScanningCallback -->

To scan a barcode from an image, we can use either scanImageFromUri or scanImageFromBase64.

scanImageFromUri Declaration

scanImageFromBase64 Declaration

/*   @return 
    (promise)  {
        status : boolean, status of image scanning execution
        err : string , if status false err will not be null
    }
*/ 

To check if we have a symbol enabled, we use isSymbologyEnabled().

/**
@return A promise that contains the object
{
    action  : the DMCC command that was invoked
    status  : did it succeed or not, if an error happened it will be set to false
    result  : if the symbol is enabled then true, if not then false
    err     : the error message if the action didn't complete
}
*/

Example

cmbScanner.isSymbologyEnabled("SYMBOL.C93",function(rr){
  console.log(JSON.stringify(rr));
//will print {"action" : "GET SYMBOL.C93","status" : true, "err" : null,"result" : true} 
});

To set how the camera will behave when we use camera device as a barcode reader we use:

/**
Use camera with no aimer. Preview is on, illumination is available.
NO_AIMER = 0,

Use camera with a basic aimer (e.g., StingRay). Preview is off, illumination is not available.
PASSIVE_AIMER = 1,

Use mobile device front camera. Preview is on, illumination is not available.
FRONT_CAMERA = 3
*/

Configure decoder flags for type specified by the code mask.

/*   @return 
    (promise)  {
        status : boolean, status of execution
        err : string , if status false err will not be null
    }
*/ 

Example of how you would use it:

cmbscanner.enableCameraFlag(cmbscanner.CONSTANTS.MASKS.MWB_CODE_MASK_39, cmbscanner.CONSTANTS.FLAGS.MWB_CFG_CODE39_EXTENDED_MODE, function(result) {
   if(result.status == true)
      console.log('Decoder flag is enabled');
   else
      console.log('Decoder flag is NOT enabled. Error: ' + result.err);
});

This controls the preview/scanning options when using the Mobile device camera. Multiple options can be OR'd together.

/**
 * Use defaults (no overrides).
 */
"DEFAULTS" : 0,
/**
 * Disable zoom feature (removes zoom button from preview).
 */
"NO_ZOOM_BTN" : 1,
/**
 * Disable illumination (removes illumination button from preview).
 */
"NO_ILLUM_BTN" : 2,
/**
 * Enables the simulated hardware trigger (the volume down button).
 */
"HARDWARE_TRIGGER" : 4,
/**
 * When scanning starts, the preview is displayed but decoding is paused until a trigger (either the on screen button or the volume down button, if enabled) is pressed.
 */
"PREVIEW_PAUSED" : 8,
/**
 * Force the preview to be displayed, even if off by default (e.g., when using kCDMCameraModePassiveAimer or kCDMCameraModeActiveAimer).
 */
"PREVIEW_ALWAYS_SHOW" : 16,
/**
 * Use higher resolution if the device supports it. Default is 1280x720, with this param 1920x1080 will be used.
 */
"HIGH_RESOLUTION" : 32,
/**
 * Use higher framerate if the device supports it. Default is 30 FPS, with this param 60 FPS will be used.
 */
"HIGH_FRAME_RATE" : 64,
/**
 * Show close button in partial view.
 */
"SHOW_CLOSE_BUTTON" : 128,
/**
 * Keep the preview in paused state after read or timeout.
 */
"KEEP_PREVIEW_IN_PAUSED_STATE" : 256

To set the size and position of the preview container (only available to the user when they use the camera reader):

/*
  @params x,y,w,h
        x,y  : top left position
        w,h  : width and height of the rectangular in precentages of the full container
*/

cmbScanner.setPreviewContainerPositionAndSize(0,0,100,50);
//will set the preview to 0,0 and 100% width 50% height

Sets the camera preview to start in full screen instead of partial view. (only available to the user when they use the camera reader):

Available only on iOS, applies only for the camera reader.

Sets the camera preview partial view top axis to start below the status bar matching the Androids behavior. It expects one boolean argument. 

cmb.setPreviewContainerBelowStatusBar(true);
cmb.setPreviewContainerPositionAndSize([0,0,100,50]);
//will set the preview to 0,0 and 100% width 50% height. 
//On iOS the partial view will be shown below the status bar.

cmb.setPreviewContainerBelowStatusBar(false);
cmb.setPreviewContainerPositionAndSize([0,0,100,50]);
//will set the preview to 0,0 and 100% width 50% height. 
//On iOS the partial view will start from the top of the screen, and will overlap the status bar.

Set the camera overlay mode. You need to do it before loadScanner is called, otherwise it will not work properly.

ONLY AVAILABLE ON MX-Mobile.

Read more about overlay modes here

cmb.setPreviewOverlayMode(cmb.CONSTANTS.PREVIEW_OVERLAY_MODE.OM_CMB);

Set whether or not the scanning session should stop when the application UI changes orientation. It expects one boolean argument. 

cmb.setStopScannerOnRotate(true);

To show or hide a message on top of the camera preview while scanning with the mobile camera.

To enable the flash light programmatically, we can use:

/**
@return A promise that contains the JSON object
{
  (string)  action  : the DMCC command that was invoked
  (bool)    status  : did it succeed or not, if an error happened it will be set to false
  (string)  err     : the error message if the action didn't complete
  (bool)  result    : the result of the taken action, in this case TRUE if the light was enabled, false if not
}
*/

Example

cmbScanner.setLightsOn(true,function(response){
  //console.log(response);
});

cmbScanner.setLightsOn(true).then(function(response){
//or with a promise, the callback function is wrapped within a promise
//so if we don't set a callback function as a param, the default one will be used 
//and it will return a promise to continue the chain
});

To check if the flash light is ON, we can use:

/**
@return A promise that contains the JSON object
{
  (string)  action  : the DMCC command that was invoked
  (bool)    status  : did it succeed or not, if an error happened it will be set to false
  (string)  err     : the error message if the action didn't complete
  (bool)  result    : the result of the taken action, in this case TRUE if the light was enabled, false if not
}
*/

Example

cmbScanner.isLightsOn(true,function(response){
  //console.log(response);
});

cmbScanner.isLightsOn(true).then(function(response){
//or with a promise, the callback function is wrapped within a promise
//so if we don't set a callback function as a param, the default one will be used 
//and it will return a promise to continue the chain
});

If we want to return the last image seen by the decoder we use enableImage(). If we want image graphics stats on the returned image we use enableImageGraphics().

Declaration

Usage

cmbScanner.enableImage(true);
//it will enable the image in the result


cmbScanner.enableImageGraphics(true);
//will show where exactly the barcode was detected on the image

The structure of the bar code result object is:

interface BarcodeResult {
 readString : string,
 symbologyString: string,
 symbology : integer,
 goodRead : bool,
 xml: string,
 imageGraphics? : string,
 image? : string
};

Enable or disable parsing for scanned barcodes. Expects one argument of type cmb.CONSTANTS.PARSERS.

cmb.setParser(cmb.CONSTANTS.PARSERS.GS1);

Set encoding for the readString result type. Expects one argument of type cmb.CONSTANTS.READSTRING_ENCODING.

cmb.setReadStringEncoding(cmb.CONSTANTS.READSTRING_ENCODING.UTF_8);

Most of the API methods can be replaced with just sending the appropriate commands to the MX (or Camera) reader.

Send command receives a callback and wraps it into a promise, so the chain can be continued.

Usage

cmbScanner.sendCommand("SET SYMBOL.POSTNET OFF") 
          .then(function(result){
//and in the promise let's see what our command did
              console.log(JSON.stringify(result));
          });
//or like this                                  
cmbScanner.sendCommand("SET LIGHT.INTERNAL-ENABLE ON")
          .then(function(result){
//if the command is succesful we should have the LIGHT turn ON whenever we start the scanning process
              console.log(JSON.stringify(result));
          });

The first command will disable the SYMBOL POSTNET. The second will set the Flash ON.

Both actions can be performed with their appropriate API functions setSymbologyEnabled() and setLightsOn() and generally speaking a developer should always prefer the API functions to the sendCommand().

However, there are cases where the Cordova plugin doesn't cover certain use case scenarios, and we can always use the sendCommand for that.

Example

If we want to change the way our MX device "beeps" and "lights" we can use:

So for our example we would have:

cmbScanner.sendCommand("SET OUTPUT.USER-CONFIGURE 1 1 2 4 ON").then(function(response){
  //console.log(response); //print out the result of the action
});

This will configure user event #1 to two medium beeps with red LED and vibration. In order to activate this event, we use:

cmbScanner.sendCommand("OUTPUT.USER1").then(function(response){
     //this will call the stored settings item for USER1, so the MX device will basically beep twice with red LED and vibration
})

Plays a beep on the reader device

Available only on iOS.

A company owning and operating many Cognex Mobile Terminals may want to remotely collect up-to-date information about battery level, battery health, installed firmware, etc.

An iOS application using the cmbSDK framework can report status information of the attached Mobile Terminal to an MDM instance. This can be enabled with the setMDMReportingEnabled method that accepts one boolean argument.

More on the MDM Reporting can be found here

cmb.setMDMReportingEnabled(true);

Available only on iOS.

Used for creating authentication credentials used for MDM reporting. It takes four string arguments: username, password, clientID and clientSecret.

Should be called before setMDMReportingEnabled.

More on the MDM Reporting can be found here

cmb.createMDMAuthCredentials("username", "password", "clientID", "clientSecret"); 

If we need to reset the configuration settings stored for the MX/Camera reader we can use:

Declaration

Usage

cmbScanner.resetConfig(function(result){
      console.log(result);
})

Result Interface

/*
@return A promise that contains the JSON object
{
  (string) action  : the DMCC command that was invoked
  (bool)   status  : did it succeed or not, if an error happened it will be set to false
  (string) err     : the error message if the action didn't complete and there is an error. default is null
  (bool)  result   : the result of the sendCommand action 
}
*/

Another way to add your license key if you are using camera device. This one will overwrite your license key from manifest for Android or info.plist for iOS.

Example

cmbScanner.registerSDK("SDK_KEY");

To see what cmbSDK version you're currently using:

/**
@return A promise that contains the cmbSDK version string
{
  (string)  version  : cmbSDK version
}
*/

Get camera exposure compensation range.

Return successful callback with range as JSON object or error callback with the error message if something goes wrong. 

cmbScanner.getCameraExposureCompensationRange(function(range){
  // range is JSON object with these attributes
  // "lower" : min camera exposure value
  // "upper" : max camera exposure value
  // "step" : camera exposure step value
   console.log(JSON.stringify(range));
}, function(error){ console.log(error); });

Note: The camera needs to be started within cmbSDK at least once to get the camera exposure compensation range.

Sets the camera exposure compensation value. Send float value that will be set as exposure compensation.

cmbScanner.setCameraExposureCompensation(5, function(error){
    console.log(error); 
});

Note: This needs to be called after successful connection to reader device. If value that is send is greater than camera exposure max value, max value will be set, if value that is send is lower than camera exposure min value, min value will be set.

Configure decoder param id/value pair for type specified by the code mask.

/*   @return 
    (promise)  {
        status : boolean, status of execution
        err : string , if status false err will not be null
    }
*/ 

Example of how you would use it:

cmbscanner.setCameraParam(cmbscanner.CONSTANTS.MASKS.MWB_CODE_MASK_39, 1, 0, function(result) {
   if(result.status == true)
      console.log('Param is set');
   else
      console.log('Param is NOT set. Error: ' + result.err);
});

Load config from app data if exist.

Example of how you would use it:

cmbScanner.loadCameraConfig(function(result){
	// Camera config was loaded successfully
}, function(result) {
	// Camera config is NOT loaded successfully
});

Note: Use this API when reader device is used as camera only and it should be called when we have valid connection to reader. For handheld devices this API is not used and config is saved and automatically loaded from device memory.

To set paired BT device that will be used for scanning. Input param for Android platform represent the MAC address, while for iOS input param represent the UUID.

For Android:

For iOS:

To get paired BT device that is used for scanning. Returns current BT device UUID in successful callback.

To check if reader device is available use getAvailability().

Example

cmbScanner.getAvailability(function(availability){
  if (availability == cmbScanner.CONSTANTS.AVAILABILITY_AVAILABLE)
    console.log('ReaderDevice is available');
  else
    console.log('ReaderDevice is NOT available');
}

If you need to get the current connection state, getConnectionState() can be used

Example

cmbscanner.getConnectionState(function(connectionState){
if ((connectionState == cmbscanner.CONSTANTS.CONNECTION_STATE_CONNECTED)) {
    console.log('ReaderDevice is connected');
} else if (connectionState == cmbscanner.CONSTANTS.CONNECTION_STATE_DISCONNECTED) {
    console.log('ReaderDevice is disconnected');
} else if (connectionState == cmbscanner.CONSTANTS.CONNECTION_STATE_CONNECTING) {
    console.log('ReaderDevice is connecting');
} else if (connectionState == cmbscanner.CONSTANTS.CONNECTION_STATE_DISCONNECTING) {
    console.log('ReaderDevice is disconnecting');
});

Method to show the battery level of the connected device

Example

cmbscanner.getDeviceBatteryLevel(function(result) {
   if(result.status == true)
      console.log('Battery level is ' + result.charge);
   else
      console.log('Battery level is unknown. Error: ' + result.err);
});