Cognex Mobile Barcode SDK for iOS

The differences in the barcode scanning capabilities of smartphones and purpose-built scanners result in different user experience, 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. Here are some links to start from:

• 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.

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 by calling  the startScanner() function.
• Virtual trigger: To start or stop the scanning process, the application provides a virtual button on the screen. Depending on the application design, you need to press and hold the virtual button to keep the scanner running invoking the scanning module.
• Simulated trigger: Press one of the volume control 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 that can be in partial or full screen, in portrait or landscape orientation, 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.

The cmbSDK 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.

In addition the CmbSDK supports an active aimer that has its own built-in LEDs for illumination and aiming: the MX-100 Barcode Reader. The MX-100 is a mobile device accessory for iOS smartphones attached to the mobile device with a mobile device case. The built-in LED of the MX-100 projects a green dot to help in reading the barcode.

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 the mobile device.

For better read performance read QR, Data Matrix, and  Maxicode in portrait orientation, and long codes like PDF417 in landscape orientation.

The cmbSDK is optimized for mobile environment, but image analysis and barcode decoding are still CPU intensive activities. Since these processes share the CPU of the mobile device with the mobile operating system (OS), services, and other applications, the following 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.

• Do not enable certain symbologies and/or advanced features at the same time. PDF417, DataMatrix and Dotcode are the most CPU demanding codes, enabled with advanced features they can slow down decoding 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.

Set up your application to use the iOS cmbSDK:

1. Open XCode and start a new project.

2. Add the following lib and frameworks to your project:

   * SystemConfiguration.framework 
   * AVFoundation.framework
   * CoreGraphics.framework
   * CoreMedia.framework
   * CoreVideo.framework
   * MediaPlayer.framework 
   * Security.framework
   * AudioToolbox.framework 
   * cmbSDK.framework

3. Go to your project's Info.plist file and add the Privacy - Camera Usage Description or NSCameraUsageDescription to display a message about how your application uses the camera of the user's mobile device.

The cmbSDK has been designed to provide a high-level, abstract interface for supported scanning devices. This includes not only the MX series of mobile terminals, but also for applications that intend to use the mobile device camera as the imaging device. The intricacies of communicating with and managing these devices is encapsulated within the SDK itself: leaving the application to just connect to the device of choice, then using it.

The primary interface between your application and a supported barcode scanning device is the CMBReaderDevice class. This class represents the abstraction layer to the device itself, handling all communication as well as any necessary hardware management (e.g., for smartphone scanning).

Perform the following steps to use the cmbSDK: 

1. Initialize a Reader Device for the type of device you want to use: MX reader or camera reader.

2. Connect the Reader Device.

3. Configure the reader (if necessary).

4. Start scanning. 

Initialization, connection, and configuration generally need to be performed only once in your application, except for the following cases:

• An MX reader can become disconnected (times out from disuse, dead battery, etc.). A method has been provided to handle this case, and is discussed in a later section.
• Your application has been designed to allow the user to change devices.The cmbSDK is explicitly designed to support this: your application simply disconnects from the current device and establishes a new connection to a different device. The sample application has been written to explicitly demonstrate this capability, which you get when downloading the CmbSDK.

Initializing the CMBReaderDevice for use with an MX mobile terminal like the MX-1000, MX-1100, or MX-1502 is easy: simply create the reader device using the MX device method (it requires no parameters), and set the appropriate delegate (normally self): 

let readerDevice:CMBReaderDevice = CMBReaderDevice.readerOfMX()
readerDevice.delegate = self

CMBReaderDevice *readerDevice = [CMBReaderDevice readerOfMXDevice];
readerDevice.delegate = self;

The availability of the MX mobile terminal can change when the device turns ON or OFF, or if the lightning cable gets connected or disconnected. You can handle those changes using the following CMBReaderDeviceDelegate method.

func availabilityDidChange(ofReader reader: CMBReaderDevice)

- (void)availabilityDidChangeOfReader:(CMBReaderDevice *)reader

Using other Cognex network device

If you want to connect to a Cognex device on the network (e.g handheld or fixed mount) you have to use another framework named as NetworkDiscovery. This framework can be found in the cmbSDK bundle.

Barcode scanning with the built-in camera of the mobile device can be more complex than with an MX mobile terminal. Therefore the cmbSDK supports several configurations to provide the maximum flexibility, including support of optional external aimers and illumination, as well as the ability to customize the appearance of the live-stream preview. MX-100 is such an external device for your iPhone that we call active aimer.

To scan barcodes using MX-100 or the built-in camera of the mobile device, initialize the CMBReaderDevice object using the readerOfDeviceCameraWithCameraMode static method. The camera reader has several options when initialized. The following parameters are required:

* CDMCameraMode
* CDMPreviewOption
* UIView

The CameraMode parameter is of the type CDMCameraMode (defined in CDMDataManSystem.h), and it accepts one of the following values:

• kCDMCameraModeNoAimer: If no aiming accessory is available, this mode initializes the live-stream preview on the screen to help positioning the barcode in the field of view for detection and decoding. 
• kCDMCameraModePassiveAimer: Initializes passive aimer use, which is an external accessory that uses the device's built-in LED flash for illumination to project an aiming pattern. In this mode no live-stream preview is presented on the screen.
• kCDMCameraModeActiveAimer: Initializes active aimer use, such as the MX-100. Such an attachment has built-in LEDs for projecting an aiming pattern and illumination powered by a built-in battery. In this mode no live-stream preview is presented on the screen.
• kCDMCameraModeFrontCamera: Initializes use of the front facing camera. In this mode, illumination is not available.

The above modes provide the following default settings for the mobile device as a code reader:

• The simulated hardware trigger is disabled.
• When startScanning() is called, the decoding process is started. (Seek CDMPreviewOptionPaused for more details).

Based on the selected mode, the following additional options and behaviors are set:

• kCDMCameraModeNoAimer (NoAimer)
  • The live-stream preview is displayed when the startScanning() method is called.
  • Illumination and control button are available and visible on the live-stream preview.
  •  Aimer control commands are ignored.

• kCDMCameraModePassiveAimer (PassiveAimer)
  • The live-stream preview will not be displayed when the startScanning() method is called by default.
  • Illumination is not available
  • Illumination control commands are ignored.

• kCDMCameraModeActiveAimer (MX-100)
  • The live-stream preview will not be displayed when the startScanning() method is called by default.
  • Illumination is available, if a preview option for camera preview is enabled, the illumination control button is available too.
  • Illumination or aimer control commands are accepted.

• kCDMCameraModeFrontCamera (FrontCamera)
  • The live-stream preview is displayed when the startScanning() method is called.
  • The front camera is used.
  • Illumination and the control button are not available. 
  • Illumination or aimer control commands are ignored.

The previewOptions parameter (of type CDMPreviewOption, defined in CDMDataManSystem.h) is used to change the reader’s default values or override defaults derived from the selected CameraMode. Multiple options can be specified by OR-ing them when passing the parameter. The available options are the following:

• kCDMPreviewOptionDefaults: Accept all defaults set by the CameraMode.
• kCDMPreviewOptionNoZoomBtn: Hide the zoom button on the live-stream preview.
• kCDMPreviewOptionNoIllumBtn: Hide the illumination button on the live-stream preview.
• kCDMPreviewOptionHwTrigger: Enable simulated hardware trigger (volume controls) for starting scanning. When pressed, scanning starts.
• kCDMPreviewOptionPaused: Display the live-preview when the startScanning() method is called without starting the decoding (i.e. looking for barcodes). Pressing the on-screen scanning button starts the decoding.
• kCDMPreviewOptionAlwaysShow: Force display of live-preview when active or passive aiming mode has been selected (e.g. CameraMode == kCDMCameraModePassiveAimer )
• kCDMPreviewOptionPessimisticCaching: Use only when CameraMode == kCDMCameraModeActiveAimer, this will read the settings from the ActiveAimer when the app resumes from background, in case the aimer settings were changed from another app.

• kCDMPreviewOptionHighResolution: Use the device camera in higher resolution to help with scanning small barcodes, but slow decode time. The option sets resolution to 1920x1080 on devices that support it, and the default one on devices that do not.The default resolution is 1280x720.  

• kCDMPreviewOptionHighFrameRate: Sets the camera to 60 FPS instead of the default 30 FPS to provide a smoother camera preview.

Examples:

Create a reader with no aimer and a full screen live-stream preview:

let readerDevice:CMBReaderDevice = CMBReaderDevice.readerOfDeviceCamera(with: CDMCameraMode.noAimer, previewOptions:CDMPreviewOption.init(rawValue: 0), previewView:nil)
readerDevice.delegate = self

CMBReaderDevice *readerDevice = [CMBReaderDevice readerOfDeviceCameraWithCameraMode:kCDMCameraModeNoAimer previewOptions:kCDMPreviewOptionDefaults previewView:nil];
readerDevice.delegate = self;

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

let readerDevice:CMBReaderDevice = CMBReaderDevice.readerOfDeviceCamera(with: CDMCameraMode.noAimer, previewOptions:[CDMPreviewOption.noZoomBtn, CDMPreviewOption.hwTrigger], previewView:nil)
readerDevice.delegate = self

CMBReaderDevice *readerDevice = [CMBReaderDevice readerOfDeviceCameraWithCameraMode:kCDMCameraModeNoAimer previewOptions:(kCDMPreviewOptionNoZoomBtn | kCDMPreviewOptionHwTrigger) previewView:nil];
readerDevice.delegate = self;

Initialize the CMBReaderDevice and set a delegate to handle responses from the reader.

Then connect using connectWithCompletion: 

// Make sure the device is turned ON and ready
if self.readerDevice.availability == CMBReaderAvailibilityAvailable {
    // create the connection between the readerDevice object and device
    self.readerDevice.connect(completion: { (error:Error?) in
        if error != nil {
            // handle connection error
        }
    })
}

// Make sure the device is turned ON and ready
if (readerDevice.availability == CMBReaderAvailibilityAvailable) {
    // create the connection between the readerDevice object and device
    [readerDevice connectWithCompletion:^(NSError *error) {
        if (error) {
            // handle connection error
        }
    }];
}

When connected connectionStateDidChangeOfReader in the delegate is called, where you can check the connection status in your Reader Device's connectionState parameter. It should be CMBConnectionStateConnected, which means that you have successfully made the connection to the CMBReaderDevice, and can begin using the Cognex Mobile Barcode SDK. 

To change some settings after connecting to the device the cmbSDK provides a set of high-level, device independent APIs for setting and retrieving the current configuration of the device.

The differences between using an MX reader and the camera reader for scanning are detailed in the following sections. 

The MX family of mobile terminals provides sophisticated device configuration and management including saved configurations on the device. MX devices come Cognex preconfigured with most symbologies and features ready to use.

If you would like a custom configuration, reconfigure through DataMan Setup Tool, or the Cognex Quick Setup. Both tools distribute saved configurations easily to multiple devices for simple configuration management.

The mobile application is able to configure the MX device giving you the option to: 

• have multiple scanning applications, each of which requiring a different set of device settings
• create your own options in a “known” state, even though the device has been pre-configured correctly

The cmbSDK employs a default set of options for barcode reading with the built-in camera of the mobile device. However, there are two important differences to keep in mind:

• The cmbSDK does not implement saved configurations for the built-in camera reader. Every time an application using the camera reader starts defaults ar used automatically.
• The cmbSDK does not enable symbologies by default. The application programmer enables all barcode symbologies to scan in your application. The requisite for enabling only the needed symbologies explicitly, the application achieves most optimal scanning performance on the mobile device. 

MX-100 is a device-case attachment for iPhones only that provides additional functionalities to the built-in camera such as aiming capabilities and better illumination control. Being a hybrid of an MX device and a built in scanner, the MX-100 has settings for aimer intensity, illumination intensity, and aimer modulation stored on the device, while the rest of the settings, like symbologies settings, are stored in the cmbSDK. See the MX-100 User Guide for more information.

Here are a few things to keep in mind when using an MX-100 device:

• The MX-100 does not require a license to use the device camera, optionally a free licence can be generated for tracking purposes.
• MX-100 comes pre-configured and the cmbSDK has the following symbologies enabled by default:
  • Code 39
  • Code 128
  • Databar
  • PDF417
  • QR
  • UPC/EAN
• The cmbSDK is extended with a cache mechanism to strengthen optical communication with MX-100. The cache stores all MX-100 settings and it is transparent and available in cmbSDK. Initializing and updating of the cache is the responsibility of cmbSDK. There are different caches for different settings:
  • Persistent cache: Settings/values that rarely change (if at all) and SDK can cache on the iPhone for an extended period of time. These items are the MX-100 Serial number, model number, and firmware version. The persistent cache is updated in every 7 days.
  • Session cache: Settings/values that may change while an application is using an MX-100 (not likely), but should be read from the MX-100 on SDK load/initial connection to the MX-100. These items are: Aimer intensity, Aimer modulation, Aimer timeout, Illumination intensity, and Illumination state. 
    By default, the session cache will be maintained optimistically for the best performance. The SDK assumes that another application is not changing the settings of the aimer, the SDK only needs to read the aimer's settings one time, when the initial connection is established.

Individual symbologies can be enabled using the following method of the CMBReaderDevice object: 

-(void) setSymbology:(CMBSymbology)symbology 
enabled:(bool)enabled
completion:(void (^)(NSError *error))completionBlock;

All symbologies used for the symbology parameter in this method can be found in CMBReaderDevice.h.

Examples 

self.readerDevice.setSymbology(CMBSymbologyQR, enabled: true, completion: {(_ error: Error?) -> Void in
    if error != nil {
        // Failed to enable that symbology, Possible causes are: reader disconnected, out of battery or cable unplugged, or symbology not supported by the current readerDevice
    }
})

[readerDevice setSymbology:CMBSymbologyQR enabled:YES completion:^(NSError *error){
    if (error) {
        // Failed to enable that symbology, Possible causes are: reader disconnected, out of battery or cable unplugged, or symbology not supported by the current readerDevice
    }
}];

The same method can also be used to turn symbologies off: 

self.readerDevice.setSymbology(CMBSymbologyUpcEan, enabled: false, completion: {(_ error: Error?) -> Void in
    if error != nil {
        // Failed to enable that symbology, Possible causes are: reader disconnected, out of battery or cable unplugged, or symbology not supported by the current readerDevice
    }
})

[readerDevice setSymbology:CMBSymbologyUpcEan enabled:NO completion:^(NSError *error){
    if (error) {
        // Failed to enable that symbology, Possible causes are: reader disconnected, out of battery or cable unplugged, or symbology not supported by the current readerDevice
    }
}];

If your reader device is equipped with illumination (e.g. LEDs), you can control whether they are ON or OFF when scanning starts using the following method of your CMBReaderDevice object: 

self.readerDevice.setLightsON(true) { (error:Error?) in
    if error != nil {
        // Failed to enable illumination, Possible causes are: reader disconnected, out of battery or cable unplugged, or device doesn't come with illumination lights
    }
}

[readerDevice setLightsON:YES completion:^(NSError *error) {
    if (error) {
        // Failed to enable illumination, Possible causes are: reader disconnected, out of battery or cable unplugged, or device doesn't come with illumination lights
    }
}];

Keep in mind that not all devices and device modes supported by the cmbSDK allow illumination control. For example, if using the built-in camera in passive aimer mode, illumination is not available since the LED is being used for aiming. 

If built-in camera is used as reader device you have the possibility to configure zoom levels and define the way these zoom levels are used.

There are 3 zoom levels for the phone camera, which are:

• normal: not zoomed (100%)
• level 1 zoom (default 200%)
• level 2 zoom (default 400%)

You can define these zoom levels with "SET CAMERA.ZOOM-PERCENT [100-MAX] [100-MAX]" command. It configures how far the two levels will zoom in percentage. 100 is without zoom, and MAX (goes up to 1000) will zoom as far as the device is capable of. First argument is used for setting level 1 zoom, and the second for level 2 zoom.

When you want to check current setting, you can do this with the "GET CAMERA.ZOOM-PERCENT" that returns two values: level 1 and level 2 zoom.

Example

readerDevice.dataManSystem()?.sendCommand("SET CAMERA.ZOOM-PERCENT 250 500")

[readerDevice.dataManSystem sendCommand:@"SET CAMERA.ZOOM-PERCENT 250 500"];

here is another command that sets which zoom level you want to use or returns the actual setting: "GET/SET CAMERA.ZOOM 0-2".

Possible values for the SET command are:

• 0 - normal (un-zoomed)
• 1 - zoom at level 1
• 2 - zoom at level 2

You can call this command before scanning or even during scanning, the zoom goes up to the level that was configured.

When the scanning is finished, the values are reset to normal(0).

Example

readerDevice.dataManSystem()?.sendCommand("SET CAMERA.ZOOM 2")

[readerDevice.dataManSystem sendCommand:@"SET CAMERA.ZOOM 2"];

When using the built-in camrea of the mobile device, the cmbSDK allows you to see the Camera Preview inside a preview container or in full screen. This preview also contains an overlay, which can be customized. The cmbSDK camera overlay is built from buttons for zoom, flash, closing the scanner (in full screen), a progress bar indicating the scan timeout, and lines on the corners of the camera preview. There are two available overlays: legacy and CMB overlay.

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

MWOverlay.setOverlayMode(Int32(OM_LEGACY.rawValue))

[MWOverlay setOverlayMode:OM_LEGACY];

If using the CMB overlay, you can find the  layout files in the Resources/layout directory:

CMBScannerPartialView.xib used when the scanner is started inside a container (partial view) 

CMBScannerView.xib when the scanner is started in full screen

Copy the layout file that you need, or both layouts, then modify them as you like. Change the size, position or color of the views, remove views, and add your own views, like an overlay image. The views that are used by the cmbSDK (zoom, flash, close buttons, the view used for drawing lines on the corners, and the progress bar) are accessed by the sdk using the Tag attribute, make sure the Tag attribute remains unchanged, so that the cmbSDK is able to recognize the views and continue to function correctly.

Both the CMB and the legacy overlay allow you to change the images used on the zoom and flash buttons. To do that, first copy the assets folder MWBScannerImages.xcassets from the Resources dir into your project. In XCode you can look at the images contained in this assets folder, and replace them with your own while keeping the image names unchanged.

Both the CMB and the LEGACY overlay allow you to change the color and width of the rectangle that is displayed when a barcode is detected. Here's an example on how to do that:

MWOverlay.setLocationLineUIColor(UIColor.yellow)
MWOverlay.setLocationLineWidth(5)

[MWOverlay setLocationLineUIColor:UIColor.yellowColor];
[MWOverlay setLocationLineWidth:5];

Every Cognex scanning device implements DataMan Control Commands (DMCC), a method for configuring and controlling the device. Virtually 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.

Appendix A includes the complete DMCC reference for use with the camera reader. DMCC commands for other supported devices (e.g. the MX-1000) are included with the documentation of that particular device.
Appendix B provides the default values for the camera reader’s configuration settings as related to the corresponding DMCC setting.
The following examples show different DMCC commands being sent to the device for more advanced configuration.

Example:

Change the scan direction to omnidirectional: 

self.readerDevice.dataManSystem()?.sendCommand("SET DECODER.1D-SYMBOLORIENTATION 0", withCallback: { (response:CDMResponse?) in
    if response?.status == DMCC_STATUS_NO_ERROR {
        // Command was executed successfully
    } else {
        // Command failed, handle errors here
    }
})

[readerDevice.dataManSystem sendCommand:@"SET DECODER.1D-SYMBOLORIENTATION 0" withCallback:^(CDMResponse *response){
    if (response.status == DMCC_STATUS_NO_ERROR) {
        // Command was executed successfully
    } else {
        // Command failed, handle errors here
    }
}];

Change the scanning timeout of the live-stream preview to 10 seconds: 

self.readerDevice.dataManSystem()?.sendCommand("SET DECODER.MAX-SCAN-TIMEOUT 10", withCallback: { (response:CDMResponse?) in
    if response?.status == DMCC_STATUS_NO_ERROR {
        // Command was executed successfully
    } else {
        // Command failed, handle errors here
    }
})

[readerDevice.dataManSystem sendCommand:@"SET DECODER.MAX-SCAN-TIMEOUT 10" withCallback:^(CDMResponse *response){
    if (response.status == DMCC_STATUS_NO_ERROR) {
        // Command was executed successfully
    } else {
        // Command failed, handle errors here
    }
}];

Get the type of the connected device: 

self.readerDevice.dataManSystem()?.sendCommand("GET DEVICE.TYPE", withCallback: { (response:CDMResponse?) in
    if response?.status == DMCC_STATUS_NO_ERROR {
        // Command was executed successfully
        let deviceType:String = response?.payload
    } else {
        // Command failed, handle errors here
    }
})

[readerDevice.dataManSystem sendCommand:@"GET DEVICE.TYPE" withCallback:^(CDMResponse *response){
    if (response.status == DMCC_STATUS_NO_ERROR) {
        // Command was executed successfully
        NSString *deviceType = response.payload;
    } else {
        // Command failed, handle errors here
    }
}];

The cmbSDK includes a method for resetting the device to its default settings. In the case of an MX mobile terminal, this is the configuration saved by default, while in the case of the built-in camera, these are the defaults identified in Appendix B, where no symbologies will be enabled. This method is the following: 

self.readerDevice.resetConfig { (error:Error?) in
    if error != nil {
        // Failed to reset configuration, Possible causes are: reader disconnected, out of battery or cable unplugged
    }
}

[readerDevice resetConfigWithCompletion:^(NSError *error) {
    if (error) {
        // Failed to reset configuration, Possible causes are: reader disconnected, out of battery or cable unplugged
    }
}];

With a properly configured reader, you are ready to scan barcodes. This is simply accomplished by calling the startScanning() method from your CMBReaderDevice object. What happens next is based on the type of CMBReaderDevice and how it has been configured. Generally: 

• If using an MX terminal, press a trigger button on the device to turn the scanner on and read a barcode.
• If using the camera reader, the 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. 

Scanning stops under one of the following conditions: 

• The reader found and decoded a barcode.
• The user 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 program calls the stopScanning() method. 

When a barcode is decoded successfully, you will receive a CMBReadResults array in your CMBReaderDevice's delegate using the following CMBReaderDeviceDelegate method: 

func didReceiveReadResult(fromReader reader: CMBReaderDevice, results readResults: CMBReadResults!)

- (void)didReceiveReadResultFromReader:(CMBReaderDevice *)reader results:(CMBReadResults *)readResults;

 To simply display a ReadResult after scanning a barcode: 

func didReceiveReadResult(fromReader reader: CMBReaderDevice, results readResults: CMBReadResults!) {
    if readResults.readResults.count > 0 {
        let readResult:CMBReadResult = readResults.readResults?.first as! CMBReadResult
        if readResult.image != nil {
            self.ivPreview.image = readResult.image
        }
        if readResult.readString != nil {
            self.lblCode.text = readResult.readString
        }
    }
}

- (void)didReceiveReadResultFromReader:(CMBReaderDevice *)reader results:(CMBReadResults *)readResults {
    if (readResults.readResults.count > 0) {
        CMBReadResult *readResult = readResults.readResults.firstObject;
        if (readResult.image) {
            self.ivPreview.image = readResult.image;
        }
        if (readResult.readString) {
            self.lblCode.text = readResult.readString;
        }
    }
}

In the example above, ivPreview is an UIImageView used to display an image of the barcode that was scanned, and lblCode is a UILabel used to show the result from the barcode. You can also use the BOOL from readResult.goodRead to check whether the scan was successful or not. 

When a barcode is successfully read, a CMBReadResult object is created and returned by the didReceiveReadResultFromReader:results: method. In case of having multiple barcodes successfully read on a single image/frame, multiple CMBReadResult objects are returned. This is why the CMBReadResults class has an array of CMBReadResult objects containing all results.

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

• goodRead (BOOL): tells whether the read was successful or not
• readString (NSString): the decoded barcode as a string
• image (UIImage): the image/frame that the decoder has processed
• imageGraphics (NSData): the boundary path of the barcodeas SVG data
• XML (NSData): the raw XML that the decoder returned
• symbology (CMBSymbology): the symbology type of the barcode. This enum is defined in CMBReaderDevice.h.

When a scanning ends with no successful read, a CMBReadResult is returned with the goodRead property set to false. This usually happens when scanning is canceled or timed out.

To enable the image and imageGraphics properties being filled in the CMBReadResult object, you have to set the corresponding imageResultEnabled and/or SVGResultEnabled properties of the CMBReaderDevice object.

To see an example on how the image and SVG graphics are used and displayed in parallel, refer to the sample applications provided in the SDK package.

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. Here's an example how you can use the iOS XML parser to extract the raw bytes from the XML property.

Example:

Parsing the XML and extracting the Base64 String is done using the XMLParserDelegate delegate. Add this delegate and the following methods from it in your ViewController:

// XMLParserDelegate
var currentElement = ""
var base64String = ""
func parser(_ parser: XMLParser, didStartElement elementName: String, namespaceURI: String?, qualifiedName qName: String?, attributes attributeDict: [String : String] = [:]) {
    currentElement = elementName
}

func parser(_ parser: XMLParser, foundCharacters string: String) {
    if currentElement == "full_string" {
        base64String = string
    }
}

#pragma NSXMLParserDelegate
NSString *currentElement;
NSString *base64String;
- (void)parser:(NSXMLParser *)parser didStartElement:(NSString *)elementName namespaceURI:(NSString *)namespaceURI qualifiedName:(NSString *)qName attributes:(NSDictionary<NSString *,NSString *> *)attributeDict {
    currentElement = elementName;
}

- (void)parser:(NSXMLParser *)parser foundCharacters:(NSString *)string {
    if ([currentElement isEqualToString:@"full_string"]) {
        base64String = string;
    }
}

After you have set the XMLParserDelegate to extract the base64 string from the XML result, you need to create a XMLParser object and parse the result.xml using this delegate. This can be done when receiving the scan result in the CMBReaderDeviceDelegate, or when accessing a CMBReadResult object. Here's how you can get the raw bytes using the delegate that you created earlier:

let xmlParser:XMLParser = XMLParser.init(data: result.xml)
xmlParser.delegate = self
if xmlParser.parse() {
    // Access the raw bytes via this variable
    let bytes:Data? = Data.init(base64Encoded: base64String)
}

NSXMLParser *xmlParser = [NSXMLParser.alloc initWithData:result.XML];
xmlParser.delegate = self;
if ([xmlParser parse]) {
    // Access the raw bytes via this variable
    NSData *bytes = [NSData.alloc initWithBase64EncodedString:base64String options:0];
}

By default, the image and SVG results are disabled, which means that when scanning, the CMBReadResults will not contain any data in the corresponding properties.

To enable image results, set the imageResultEnabled property from the CMBReaderDevice class by using the following method: 

self.readerDevice.imageResultEnabled = true

[readerDevice setImageResultEnabled:YES];

To enable SVG results, set the imageResultEnabled property from the CMBReaderDevice class by using the following method: 

self.readerDevice.svgResultEnabled = true

[readerDevice setSVGResultEnabled:YES];

There may be cases when a device disconnects due to low battery condition or manual cable disconnection. These cases can be detected by the connectionStateDidChangeOfReader callback of the CMBReaderDeviceDelegate.

After returning to your application from inactive state, the reader device remains initialized but not connected. There is no need for reinitializing the SDK but you need to re-connect.

Some iOS versions will send an "Availability" notification when resuming the application that the external accessory is available. You can use this in the CMBReaderDeviceDelegate method: (void)availabilityDidChangeOfReader:(CMBReaderDevice *)reader so when the reader becomes available, you can connect.

For example:

func availabilityDidChange(ofReader reader: CMBReaderDevice) {
    if (reader.availability == CMBReaderAvailibilityAvailable) {
        readerDevice.connect(completion: { error in
            if error != nil {
                // handle connection error
            }
        })
    }
}

- (void)availabilityDidChangeOfReader:(CMBReaderDevice *)reader {
    if (readerDevice.availability == CMBReaderAvailibilityAvailable) {
        [readerDevice connectWithCompletion:^(NSError *error) {
            if (error) {
               // handle connection error
            }
        }];
    }
}

Some iOS versions do not report availability change on resume, so you need to handle this manually. Add an observer for UIApplicationDidBecomeActiveNotification and connect.

Example:

override func viewDidLoad() {
    super.viewDidLoad()
    // Reconnect when app resumes
    NotificationCenter.default.addObserver(self, selector: #selector(self.appBecameActive), name:NSNotification.Name.UIApplicationDidBecomeActive, object: nil)
}

// handle app resume
func appBecameActive() {
    if readerDevice != nil
        && readerDevice.availability == CMBReaderAvailibilityAvailable
        && readerDevice.connectionState != CMBConnectionStateConnecting && readerDevice.connectionState != CMBConnectionStateConnected {
        readerDevice.connect(completion: { error in
            if error != nil {
                // handle connection error
            }
        })
    }
}

- (void)viewDidLoad {
     // Reconnect when app resumes
     [[NSNotificationCenter defaultCenter] addObserver:self
                                                 selector:@selector(appBecameActive)
                                                     name:UIApplicationDidBecomeActiveNotification object:nil];
}

// handle app resume
-(void) appBecameActive {
    if (readerDevice != nil
        && readerDevice.availability == CMBReaderAvailibilityAvailable
        && readerDevice.connectionState != CMBConnectionStateConnecting && readerDevice.connectionState != CMBConnectionStateConnected) {
        [readerDevice connectWithCompletion:^(NSError *error) {
            if (error) {
                // handle connection error
            }
        }];
    }
}

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