Mobile Barcode Solutions FAQ

The Manatee Works Barcode Scanner SDK has been fully integrated into the Cognex Mobile Barcode SDK (cmbSDK). Therefore, we are shifting our focus to the cmbSDK.

The good news is that the cmbSDK is backward compatible with the MW SDK. The cmbSDK simply adds a higher-level API to the scanning methods that utilize the camera of a smartphone or tablet. Or, you can continue to use the lower-level methods you have become familiar with in the Manatee Works SDK. Your account, login, license(s), and key(s) remain the same. If you do decide to program to the higher-level API, you will have the added benefit of your app(s) supporting the Cognex MX Series mobile barcode readers, and MX Series mobile terminals, with a single code base.

Scanning any barcode utilizing the Cognex Mobile Barcode SDK without previously entering a valid license key will produce a result partially masked with asterisks (*).

The solution is to:

• Utilize our Evaluation License generator to generate a free 45-day trial license. After 45 days, the decoder will revert to its unlicensed state, and again partially mask results. If you wish to continue evaluating the SDK after 45 days, you may request a renewal of the evaluation keys by clicking the Renew button under each barcode type and completing a short Survey;

• Obtain a commercial license by submitting a “Purchase Request” from our Purchase option within the Cognex Mobile Barcode Developer Network.

If you have trouble scanning a barcode with the Cognex Mobile Barcode SDK, try the following:

• Check if the barcode type you are attempting to scan is enabled and active within the SDK.

• For mobile devices, check that your camera meets our minimum requirements – 5 Megapixel (MP) with Autofocus (AF);

• Try different barcode images to confirm an image is not damaged, too small, or has poor resolution;

• Clean the camera lens;

• Try alternate devices to confirm a device is not physically damaged or defective;

• Decoder input is limited to 3000x3000 so image should be downscaled (by factor of 2 preferably) until it fits into that dimension;

• Default minimum length for Code 39 which is set to 5 - detailed explanation is in FAQ #5

There are several possible reasons that you might experience slow or incomplete decoding on mobile devices with cameras:

• Slow mobile devices - On older mobile devices with slower processors, scanning can be laggy and inefficient. Try using lower resolution camera buffer images and a lower scanning effort level (2 is recommended).

  readerDevice.getDataManSystem().sendCommand("DECODER.EFFORT 2"); - This example is for Android
          
  [readerDevice.dataManSystem sendCommand:@"DECODER.EFFORT 2"]; - This example is for iOS

• High-density barcodes - If you are trying to scan high density and complex barcodes it may be inefficient to use low resolution camera buffer images and lower scanning levels. Try increasing the resolution and scanning effort level to 3. Keep in mind that these settings could be CPU taxing for older, slower devices.

• Camera specifications - Check if your device has a camera with minimum requirements - Autofocus (AF) support and 5 megapixel (MP) capture is recommended minimum. Using cameras with lower specifications will decrease the likelihood of achieving a successful scan, especially on complex barcode types and images.

Codabar, Code 11, Code 25, Code 39, and MSI Plessey barcode symbologies have weak or non-existent error protection and checksum. This can lead to false detections whenever a code is encoded with four or less characters. In order to mitigate such cases, we have set a default minimum character length for those barcode types. The default values are currently set to 4 characters for Code 25, and MSI Plessey; and at 5 characters for Codabar, Code 11, and Code 39.

For specific use-cases that require scanning those barcode types below the default minimum threshold length, we have integrated a special configuration parameter within the Barcode Scanner SDK initialization block that can be used to change the barcode length for those symbologies.

Below are examples of the Barcode Scanner SDK initialization for setting minimum detection lengths.

iOS

[readerDevice.dataManSystem sendCommand:@"SET CODABAR.CODESIZE ON 5 20"];
            [readerDevice.dataManSystem sendCommand:@"SET C11.CODESIZE ON 5 20"];
            [readerDevice.dataManSystem sendCommand:@"SET C25.CODESIZE ON 5 20"];
            [readerDevice.dataManSystem sendCommand:@"SET C39.CODESIZE ON 5 20"];
            [readerDevice.dataManSystem sendCommand:@"SET C93.CODESIZE ON 5 20"];
            [readerDevice.dataManSystem sendCommand:@"SET MSI.CODESIZE ON 5 20"];

Android

readerDevice.getDataManSystem().sendCommand("SET CODABAR.CODESIZE ON 5 20");
        readerDevice.getDataManSystem().sendCommand("SET C11.CODESIZE ON 5 20");
        readerDevice.getDataManSystem().sendCommand("SET C25.CODESIZE ON 5 20");
        readerDevice.getDataManSystem().sendCommand("SET C39.CODESIZE ON 5 20");
        readerDevice.getDataManSystem().sendCommand("SET C93.CODESIZE ON 5 20");
        readerDevice.getDataManSystem().sendCommand("SET MSI.CODESIZE ON 5 20");

Yes! However you should first make sure that the front camera is of sufficient quality for successfully decoding your targeted barcodes. In order to proceed, follow these instructions:

iOS

kCDMCameraModeFrontCamera: This initializes the reader to use the front facing camera of the mobile device, if available (not all mobile devices have a front camera). This is an unusual, but possible configuration. Most front-facing cameras do not have auto focus and illumination, and provide significantly lower resolution images. This option should be used with care. In this mode, illumination is not available.

In the ScannerController of our sample iOS app, replace:

readerDevice = [CMBReaderDevice readerOfDeviceCameraWithCameraMode:kCDMCameraModeNoAimer previewOptions:0 previewView:self.ivPreview];

with the following code:

readerDevice = [CMBReaderDevice readerOfDeviceCameraWithCameraMode:kCDMCameraModeFrontCamera previewOptions:0 previewView:self.ivPreview];

iOS Swift

Replace the line in func createReaderDevice() ;

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

with the following code:

self.readerDevice = CMBReaderDevice.readerOfDeviceCamera(with: CDMCameraMode.frontCamera,
                                                                             previewOptions:CDMPreviewOption.init(rawValue: 0),
                                                                             previewView: self.ivPreview)

Android

Please place this code in initDevice() in the Activity before you init connection to Phone Camera:

FRONT_CAMERA: This initializes the reader to use the mobile front facing camera of the device, if available (not all mobile devices have a front camera). This is an unusual, but possible configuration. Most front facing cameras do not have auto focus and illumination, and provide significantly lower resolution images. This option should be used with care. In this mode, illumination is not available.

readerDevice = ReaderDevice.getPhoneCameraDevice(this,
                        CameraMode.FRONT_CAMERA, PreviewOption.DEFAULTS,
                        rlPreviewContainer);

Xamarin

How to use the front camera of the device in our Xamarin SDK:

Android:

 case DeviceType.PHONE_CAMERA:
                    readerDevice = GetPhoneCameraDevice(this, CameraMode.FrontCamera, PreviewOption.Defaults, rlPreviewContainer);
                    selectedDevice = "Mobile Camera";
                    break;

iOS:

readerDevice = CMBReaderDevice.ReaderOfDeviceCameraWithCameraMode(CDMCameraMode.FrontCamera, CDMPreviewOption.Defaults, ivPreview);

For maximum reliability, an Internet connection is highly recommended the first time a device opens the barcode scanner (i.e. the Initialize() method is executed). The SDK may subsequently attempt to periodically communicate with the Registration licensing service to register a device or update license information, but if an Internet connection is not available, the SDK will simply defer this operation and continue to function normally.

The SDK licensing component sends only information about the license key, SDK version and features, the name of the application using the SDK, number of scans, and some basic device information (make, model, and a pseudo random identifier Cognex uses to register the device with the license). The component never collects any personally identifiable information.

The app has crashed because it attempted to access privacy-sensitive data without a usage description. The app's Info.plist must contain an NSCameraUsageDescription key with a string value explaining to the user how the app uses this data.

<key>NSCameraUsageDescription</key>
<string>Camera usage description</string>

No. When purchasing your production license, a new license key is generated. You should consider this before deploying your application(s) with an evaluation key?

If you have purchased an MX Mobile Terminal (e.g., MX-1000 or MX-1502) no license is necessary; you can use the SDK to develop barcode scanning applications for your MX device. If you wish to scan barcodes using a mobile device's built-in camera, then a license is needed. Contact sdksales@cognex.com for additional details or sales assistance.

Please disconnect the iPhone from the MX-1000 and scan the code that is marked in the image that is added in the attachment. Then after the scan is completed you connect your iPhone again to the MX-1000 and the issue will be resolved.

MX-1000 Documentation

Since the MX-1000 and MX-1502 devices are MFi certified, we have to add your application to our MFi Project Plan (Apple's requirement, not ours!). Please follow the instructions in this knowledge base article on what information we need and how to provide it; we will get you set-up right away!

https://cmbdn.cognex.com/mfi/my

You need to have Cognex MX Connect application installed on your android device to connect with MX Device. Download and install the application from Play Store.

Also you can install DataMan Quick Setup application from Play Store. Use this application if you want to configure your MX Device, update MX Device firmware, etc.

The MX-1000 scanner operates in both USB Device Mode and USB AOA (Accessory) Mode. It switches back and forth between these modes when it needs to charge the mobile phone. When an MX-1000 originally boots up, it will be in Device Mode and after one minute, it will switch to AOA Mode. The very first time this happens, Android will display a security prompt, asking you to confirm that the MXConnect service can access the USB device. This will happen once for Device Mode and once for Accessory Mode. As long as you check the box on the screen and press OK, you will not receive this prompt again.

Use the attached "MX-1000_Quick_Setup_Sheet.pdf.zip" file to configure the MX-1000 for use as a keyboard, by scanning the "Android Keyboard Input - Enable" code. When in this mode, the MX-1000 will behave as a USB keyboard. The Android OS handles if the virtual keyboard will show, but the MX-1000 will "type" the scanned barcode regardless whether the virtual keyboard is displayed or not, as long as the application accepts keyboard input.

A couple of things to consider:

* You will need to determine precisely how to format the data returned from our scanner to best work with your application. By default, the MX-1000 will just send the contents of the scanned barcode, but you may want to append a CR, CRLF, or a TAB even to the end of the data so scanning the barcode causes the app to accept the input and/or advance to the next field on the screen. Most native applications work with the CRLF, while web based applications work better with a TAB character (and these days, it can be hard to tell if you're using a native app or just a webapp that has a native wrapper).

* You can setup the MX-1000's data formatting using the DataMan Quick Setup application. However, on Android there is a catch: when you put the MX-1000 in keyboard wedge mode, the DataMan Quick Setup application can no longer communicate with the MX-1000. This is a restriction of the USB keyboard wedge mode of Android. It means that when you need to use the DataMan Quick Setup app to change the MX-1000's settings you must take it out of keyboard wedge mode first, then the setup app will be able to connect to the MX-1000. There is a barcode in the MX-1000_Quick_Setup_Sheet.pdf.zip document to do this as well, just scan it, use DataMan Quick Setup to make any desired configuration changes, then scan the code to put the device back into wedge mode.

* Some Android devices may work better than others in keyboard wedge mode: Currently there is a bug with the J3 (that Samsung is addressing) where the connection may hang, so a reboot of either the J3 or our MX-1000 is required to get them to see each other again.

Android Kiosk/Pinning basically just locks the application to the screen and disables the buttons that would allow you to exit the application. The locking allows for a specified list of packages to be able to run. Pin MXConnect as a trusted app by adding com.cognex.mxconnect to the list of trusted packages. Activity name is MXConnectActivity.

There are two locations where you can access the latest firmware files:

1. This website's download section at https://cmbdn.cognex.com/download. Use this option if you plan to deploy firmware updates directly from your MDM or your own web server (for instances where your managed devices may not have internet access).

2. Access firmware files from our Amazon S3 storage. Use this method when your managed devices have internet access and can retrieve file from s3.amazon.com. This is the same file store the Cognex Quick Setup application uses for retrieving firmware files. The S3 bucket includes JSON catalogs of the firmware files--one catalog for MX-1000 Series devices (MX-1000, MX-1100) and one for MX-1500 Series devices (MX-1502ER, MX-1502XR, MX-1502LR, etc.). When accessing these catalogs via a web browser (to determine the path to the firmware file, consider using a browser extension for viewing JSON files for easier reading).
   1. The available firmware files for MX-1000 Series devices can be found here:
      https://s3.amazonaws.com/cognex-firmware/mx-1000/index.json
   2. The available firmware files for MX-1500 Series devices can be found here:
      https://s3.amazonaws.com/cognex-firmware/mx-1500/index.json
   3. The resulting JSON has an entry for each available firmware file and may look something like this:

4. The full path to the desired firmware file is the Cognex S3 bucket path (https://s3.amazonaws.com/cognex-firmware/) plus the file attribute in the catalog. For example, the full path for the 5.7.9 SR3 release of firmware for the MX-1000 is https://s3.amazonaws.com/cognex-firmware/files/MX-1000_v5.7.9_sr3.bin.gz

Create a configuration file with the Cognex Quick Setup app

The Cognex Quick Setup application can be used to change many of the common settings for your MX device, including enabled barcode symbologies and key features like data formatting, target decoding, and multi-code scanning. Once you have your MX device configured for your application, you can also use the Quick Setup app to retrieve a configuration file.

1. Make sure the MX device is powered on and ready.
2. Open the Quick Setup app
3. From the settings menu, select Share device config/backup
4. Select Share device configuration
5. Choose your preferred way of sharing content (e.g., via the Email or Gmail app).

Create a configuration file with the Cognex Setup Tool

The Cognex Setup Tool is a Windows desktop application that can be used to configure your MX device as well. The Cognex Setup Tool allows for much more advanced configuration of MX devices. Like the Cognex Quick Setup app, the Setup Tool can be used to save the MX device's configuration directly to your computer.

1. Make sure the MX device is powered on and ready.
2. Launch the Quick Setup app on the MX device's mobile phone.
3. Open Setup Tool
4. Connect to the MX device.
5. From System tab select Save Configuration

NOTE: be sure to click on the upper half of the icon (Save Configuration); this creates a .CFG file. The lower half is used to create a device backup.

The cmbSDK registers only the devices which initialize the barcode scanner component within your app.

Keeping that in mind, if you use the cmbSDK for Mobile, you should make sure that the initialization method is activated only when the device accesses the scanner and not on other app functions, like app start.

Another important thing is that uninstalls/reinstalls will not consume additional device licenses from your license pool. 

Decode counts are updated when the SDK's initialization function is called, but only periodically (about once a week), thus the count is not always precise if the SDK hasn't "phoned home". Your application should only be initializing the SDK when scanning functionality is needed (if you're doing it on app startup, then this will consume a device license, even if the decoding function is never called). The zero counts you might be seeing in your License Tracking page are either because the application always initializes the SDK, even when no scanning has been done, or in the case where no scanning has been done after the app was used for 6 days (as on the 7th day, the SDK would have updated the decode count).

The cmbWeb SDK on the other hand registers only the devices which use the scanner to successfully decode at least one code. Web apps are limited to a browser, so instead of devices we actually count unique browser clients. If an end-user opens the web app in two different browsers, say Chrome and Firefox, it will be registered as two counts.

On the other hand, some (different) devices with similar hardware might have the same ID, in which case those devices would be counted as one device. Due to the nature of tracking over the web, there is something to keep in consideration:
Identification relies on hardware and browsers, hardware changes and software changes that affect tracking might result in a different ID, meaning a different device. This hasn't been observed yet but it's something that's worked on in Firefox for example and should it happen we have no control over it.

The cmbWEB SDK will work on any browser that supports webassembly:

• Desktop: Chrome, Firefox (except ESR), Safari (macOS), Edge and Opera
• Android mobile: Chrome, Firefox, Samsung Internet and Opera
• iOS mobile: Safari, Chrome (no camera video streaming) and Firefox (no camera video streaming)

As the cmbWEB SDK relies on webassembly it really depends at which point / version browsers have adopted that technology. On the following pages you will find a summary of the support across most used browsers by version:
https://caniuse.com/#feat=wasm
https://developer.mozilla.org/en-US/docs/WebAssembly#Browser_compatibility

There are additional APIs that the cmbWEB SDK uses, but those have been adopted by browsers earlier than wasm, so you should use the wasm support as the guideline.

All you need for the web app using the SDK to work would be to have the minimum browser version that supports wasm.

Please do the following changes in your app's Build Settings

1. Under Architectures expand the "Excluded Architectures" row. It will show "Debug" and "Release" rows
2. Select "Debug" and press the + symbol to add new excluded architecture. Change the "Any SDK" to "Any iOS Simulator" and set the value to "arm64"
3. Repeat step 2 for "Release"

It should look like this:

With the latest update on cmbSDK v2.7.0, the sample is working fine on M1, you don't need to make any configuration for it.

If you are using cmbSDK with the MX Mobile Terminal, you also need to add Supported external accessory protocols or UISupportedExternalAccessoryProtocols to com.cognex.dmcc in your project's Info.plist. (You have to create an MFi Request in such case before publishing your app in Apple App Store. You can read further details in Getting your MX Mobile Terminal Enabled App into the App Store section.) 

If you are using only the camera API without MX Mobile Terminal, make sure that you removed Supported external accessory protocols or UISupportedExternalAccessoryProtocols from your project's Info.plist and submit your app again for review.

The cmbSDK will support all Android devices that run Android 5 or higher, SDK version 21, while for iOS the minimum supported version is 9.0.

For cmbWeb, JS 2017 and above is fully supported. For webpack variants, up until 1.2.0 you can use webpack 4, while from 1.3.0 webpack 5 is required.