Flutter™

To get a scanner up and running, the first thing to do, is to call the loadScanner() method. It expects a cmbDeviceType param. This method does not connect to the Reader Device. We need to call connect() in the callback to actually connect to the Reader Device

cmb.loadScanner(_deviceType).then((value) {
  cmb.connect().then((value) {
     ...
  }).catchError((error, stackTrace) {
     ...
  });
});

/*   @return
     - success callback if connection is completed
     - error callback if connection is rejected. The error object in this callback contains the error code and error message

*/

The result from the connect() method is returned as a success or error callback

cmb.connect().then((value) {
     ...
}).catchError((error, stackTrace) {
     ...
});

There is an Event Listener for the connection status of the ReaderDevice, namely the ConnectionStateChangedListener event which is explained in more detail below.

/*   @return
     - success callback if disconnection is completed
     - error callback if disconnection is not successfull. The error object in this callback contains the error code and error message

*/

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

cmb.disconnect().then((value) {
     ...
}).catchError((error, stackTrace) {
     ...
});

Similarly to connect(), disconnect() also triggers the ConnectionStateChangedListener event.

/*   @return
     - success callback if scanning state is changed
     - error callback if scanning state is not changed. The error object in this callback contains the error code and error message
*/

To start / stop the scanning process, we use these methods. They return a success callback if the command was successful (the scanning has started or stopped) or error callback (if there is no active ReaderDevice initialized or isn't connected). These methods trigger the ScanningStateChangedListener event where current scanning state is returned (true if scanning process is started and false if scanning process is stopped).

cmb.startScanning().then((value) {
     ...
}).catchError((error, stackTrace) {
     ...
});

After starting the scanner and scanning a barcode, the scan result triggers the ReadResultReceivedListener event.

Plays a beep on the reader device

cmb.beep()
.catchError((error, stackTrace){
   ...
});

/*   @return
     - success callback if symbology is enabled
     - error callback if symbology is NOT enabled. The error object in this callback contains the error code and error message
*/

Once there is a connection to the Reader, we can enable symbologies by calling setSymbologyEnabled(). It expects 2 params: a cmbSymbology which is the symbology to be enabled or disabled and a boolean for ON/OFF.

cmb.setSymbologyEnabled(cmbSymbology.DataMatrix, true)
.then((value) => print('DataMatrix enabled'))
.catchError((error, stackTrace) =>
   print('DataMatrix NOT enabled. ${error.message}'));

/*   @return
     - success callback with boolean value that show is symbology enabled or disabled
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

To check if we have a symbol enabled, we use isSymbologyEnabled(). It takes argument cmbSymbology.

cmb.isSymbologyEnabled(cmbSymbology.DataMatrix).then((value) {
      if (value)
        print('DataMatrix enabled');
      else
        print('DataMatrix NOT enabled');
}).catchError((error, stackTrace) =>
        print('${error.message}'));

/*   @return
     - success callback if light is turned on
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

If we want to enable the flash we can use setLightsOn(). It expects one argument boolean and returns a success or error callback.

cmb.setLightsOn(true)
   .catchError((error, stackTrace) => print('${error.message}'));

If we call this function before scanning is active, we are setting light initial state for every scanning session.

/*   @return
     - success callback with boolean value that represent current light status
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

We can check the lights status with isLightsOn(), which returns a callback with the current light status.

cmb.isLightsOn().then((value) {
      if (value)
        print('Light is ON');
      else
        print('Light is OFF');
}).catchError((error, stackTrace) => print('${error.message}'));

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

cmb.setCameraMode(cmbCameraMode.NoAimer);

Note: CameraMode should be set BEFORE we call loadScanner() for it to take effect.

This should be used only when using the device's built in camera for scanning (cmbDeviceType.Camera).

This function expects one integer argument that is a result of the OR-ed result of all the preview options that we want enabled.

cmb.setPreviewOptions(cmbPrevewiOption.NoZoomBtn | cmbPrevewiOption.NoIllumBtn);

Note: PreviewOptions should be set BEFORE we call loadScanner() for it to take effect.

This should be used only when using the device's built in camera for scanning (cmbDeviceType.Camera).

setPreviewContainerPositionAndSize takes four integer arguments, which are the X and Y values for the top left coordinate, and width and height values for the preview container size. All of the values are percentages of the device's screen.

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

Note: setPreviewContainerPositionAndSize should be set BEFORE we call loadScanner() for it to take effect.

/*   @return
     - success callback if full screen is set
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

This should be used only when using the device's built in camera for scanning (cmbDeviceType.Camera).

Sets the camera preview to start in full screen instead of partial view.

cmb.setPreviewContainerFullScreen()
.catchError((error, stackTrace) => print('${error.message}'));

Set the camera overlay mode.

Read more about overlay modes here and here

cmb.setPreviewOverlayMode(cmbOverlayMode.OMLegacy);

Note: OverlayMode should be set BEFORE we call loadScanner() for it to take effect.

/*   @return
     - success callback if image result is enabled
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

Used to enable / disable image result type. Expects one boolean argument.

cmb.enableImage(true)
.catchError((error, stackTrace) => print('${error.message}'));

/*   @return
     - success callback if svg result is enabled
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

Used to enable / disable svg result type. Expects one boolean argument.

cmb.enableImageGraphics(true)
.catchError((error, stackTrace) => print('${error.message}'));

/*   @return
     - success callback if parser is set
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

Enable or disable parsing for scanned barcodes. Expects one argument of type cmbResultParser.

cmb.setParser(cmbResultParser.Gs1)
.catchError((error, stackTrace) => print('${error.message}'));

/*   @return
     - success callback if encoding is set
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

Set encoding for the readString result type. Expects one argument of type cmbReadStringEncoding.

cmb.setReadStringEncoding(cmbReadStringEncoding.Utf8)
.catchError((error, stackTrace) => print('${error.message}'));

/*   @return
     - success callback with value that represent the battery level
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

Method to show the battery level of the connected device. Doesn't take any arguments.

cmb.getDeviceBatteryLevel().then((value) {
      print('Battery level is $value');
}).catchError((error, stackTrace) => print('${error.message}'));

/*   @return
     - success callback with int value that represent the current availability status
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

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

cmb.getAvailability().then((availability) {
  if (availability == cmbAvailability.Available.index)
    print('ReaderDevice is available');
  else
    print('ReaderDevice is NOT available');
}).catchError((error, stackTrace) => print('${error.message}'));

/*   @return
     - success callback with int value that represent the current connection state status
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

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

cmb.getConnectionState().then((currentState) {
  if (currentState == cmbConnectionState.Connected.index)
    print('ReaderDevice is connected');
}).catchError((error, stackTrace) => print('${error.message}'));

/*   @return
     - success callback that return result value from executed dmcc
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

All the methods can be replaced with sending DMCC strings to the READER device. For that we can use our API method sendCommand. It can be used to control the Reader completely with command strings. DMCC string is send as input parameter.

More on the command strings can be found here or here.

cmb.sendCommand('GET DEVICE.TYPE')
.then((value) => print('$value'))
.catchError((error, stackTrace) => print('${error.message}'));

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')
.catchError((error, stackTrace) => print('${error.message}'));

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)
.catchError((error, stackTrace) => print('${error.message}'));

/*   @return
     - success callback with json string value that represent the camera exposure compensation range:
     "lower" : min camera exposure value
     "upper" : max camera exposure value
      "step" : camera exposure step value

     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

cmb.getCameraExposureCompensationRange()
.then((value) => print('$value'))
.catchError((error, stackTrace) => print('${error.message}'));

Note: The camera needs to be started within cmbSDK at least once to get the camera exposure compensation range, otherwise it will return empty json string.

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

cmb.setCameraExposureCompensation(5)
.catchError((error, stackTrace) => print('${error.message}'));

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
     - success callback if param is set
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

cmb.setCameraParam(mask, param, value)
.catchError((error, stackTrace) => print('${error.message}'));

Load config from app data if exist.

/*   @return
     - success callback if config is loaded
     - error callback if something went wrong. The error object in this callback contains the error code and error message
*/

cmb.loadCameraConfig()
.catchError((error, stackTrace) => print('${error.message}'));

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:

cmb.setPairedBluetoothDevice(macAddress)

For iOS:

cmb.setPairedBluetoothDevice(btUuid)

Note: It should be called before we call loadScanner() for it to take effect.

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

cmb.getPairedBluetoothDevice().then((value) {
     ...
}).catchError((error, stackTrace) {
     ...
});

Note: Method is only supported for iOS

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

scanImageFromUri Declaration

cmb.scanImageFromUri(uri).then((result) {
   ...
})
.catchError((error, stackTrace){
   ...
});

scanImageFromBase64 Declaration

cmb.scanImageFromBase64(base64).then((result) {
   ...
})
.catchError((error, stackTrace){
   ...
});

Configure decoder flags for type specified by the code mask.

cmb.enableCameraFlag(mask, flag)
.catchError((error, stackTrace){
   ...
});

cmb.disableCameraFlag(mask, flag)
.catchError((error, stackTrace){
   ...
});

This listener is used only for MXReader when the availability changes (example: when the MX Mobile Terminal has connected or disconnected the cable, or has turned on or off). The result is an int containing the availability information.

cmb.setAvailabilityChangedListener((availability) {
  if (availability == cmbAvailability.Available.index)
    print('ReaderDevice is available');
});

This listener is triggered when the connection state of the ReaderDevice changes. The result is an int containing the connection information.

cmb.setConnectionStateChangedListener((state) {
  if (state == cmbConnectionState.Connected.index)
     print('ReaderDevice is connected');
});

This listener is triggered when the scanner state of the ReaderDevice changes. The result is a boolean that is true if the scanning started, or false if it stopped.

cmb.setScanningStateChangedListener((scanningState) {
   if (scanningState)
     print('Scanning is started');
});

This listener is triggered whenever a scan result is received.

cmb.setReadResultReceivedListener((resultJSON) {
  final Map<String, dynamic> resultMap = jsonDecode(resultJSON);
});

A resultJSON is a JSON object with the following structure:

- xml: string representation of complete result from reader device in xml format

- results: json array of all results. If you use multicode mode here you will find main result and all other partial results.

- subResults: json array of all partial results (if single code mode is used this array will be empty)

results and subResults array contains items with this structure:

- symbology: int representation of the barcode symbology detected

- symbologyString: string representation of the barcode symbology detected

- readString: string representation of barcode

- goodRead: bool that indicate if barcode is successful scanned

- isGS1: bool that indicate if barcode is GS1 or not

- parsedText: string that represent parsed text from the result

- parsedJSON: string that represent parsed text in json format from the result

- imageGraphics: string that represent svg image from last detected frame

- image: base64 string that contain image from last detected frame

- xml: string representation of partial result in xml format