Installation and Configuration

Overview

This page describes the process required to install and execute the Zebra Scanner Control application that is provided with the Zebra Scanner SDK for iOS.

NOTE: The purpose of the scanner Zebra Scanner Control application is to demonstrate the various capabilities of the SDK library. It is not intended for production use purposes.

Installing the Zebra Scanner Control Application

Using the Source Code

Prerequisites

  • OS X
  • Xcode. Download Xcode from the Mac App Store.
  • An iOS Developer account with Apple.
  • A provisioned iOS device with iOS 15, or higher installed.

Launching the Zebra Scanner Control Application

To launch the application on the device:

  1. Connect a provisioned iOS device to your Mac.
  2. Open the ScannerSDKApp.xcodeproj project file.

  3. In the project navigator, choose your device from the Scheme toolbar menu.

    NOTE: If your iOS device is listed as an ineligible device, fix the issue before continuing. The version of iOS that is installed on the device must match the deployment target set in the project.

  4. Click the Run button. Xcode installs the application on the device.
  5. If a warning message appears that states No matching provisioning profile found, click the Fix Issue button. Xcode needs to add the device to the team provisioning profile before it can launch the application on the device.
  6. If a prompt appears that asks whether or not codesign may sign the application using a key in your keychain, click Always Allow.
  7. The application launches on your device.

From the Apple App Store

Prerequisites

  • An iOS device with iOS 15, or higher, installed.

Launching the Zebra Scanner Control Application

To launch the scanner application on the device from the Apple App Store:

  1. Launch the App Store application on your iOS device.
  2. Search for the Zebra Scanner application, or Zebra Scanner Control application by Zebra Technologies.
  3. Tap the Get button next to the application, then tap the Install button.

Launching the Zebra Scanner Control Application

  1. Before launching the application, set the Zebra scanner to the appropriate configuration. See Supported Scanners to determine the required configuration needed for your Zebra scanner.
  2. Enable Bluetooth on your iOS device and pair it with the Bluetooth Zebra scanner, if it is not paired already. Refer to the relevant Product Reference Guide, User Guide, or Integration Guide for instructions on how to pair the device.
  3. Launch the application by selecting the Zebra Scanner Control application from your device's home screen. The following screen displays:
    Figure 1: Pair New Scanner
  4. Connect to a scanner.

    Prior to connecting a scanner if any settings are required to be updated, those can be updated by navigating to the 'More → App Settings' tab. Ex: Communication Mode, Set Factory Defaults. The screen is as follows.

    Figure 2: App Settings

    1. Connect a BLE scanner: Scan the STC (Scan To Connect) pairing barcode on the 'BT LE' tab to connect a BLE scanner (See the Figure 1).
    2. Connect a MFi supported scanner: Navigate to 'More → Connection Help → Pairing Help' for the pairing information and pair a MFi supported scanner. Navigate to 'MFi' tab and select the paired MFi scanner on the list to connect.
    Figure 3: Connect MFi Scanners

  5. When a scanner is connected to the application a set of scanner settings are displayed in the 'Settings' tab. At the bottom of the screen, three more tabs: 'Data View', 'Advanced', and 'More , each offering other additional features are displayed.
    1. Select the Settings' tab to access basic scanner settings including 'Beeper', 'LED Control', 'Symbologies' and etc.
      Figure 4: Scanner Settings

    2. To control which symbologies the scanner reads, select the Symbologies option. An on/off control switch appears next to each barcode type displayed in the menu.
      Figure 5: Symbologies

      NOTE: Custom symbology settings can be configured via 123Scan.

    3. Select the 'Data View' tab to view scanned barcodes. This screen also includes an option to view sample barcodes for scanning.
      Figure 6: Data View

    4. Select the 'Advanced' tab to access Asset Information, Update Firmware and etc.
      Figure 7: Advanced Settings

Features Supported in Scanner Control App

  1. Display barcode data within a tablet/phone application.
  2. Apps using the SDK can command and control the scanner.
    1. LED and Beeper Control.
    2. Aim Control.
    3. Enable/disable Symbologies.
    4. Scanner control,
      1. Remote scanner trigger (i.e. Host app-initiated triggering).
      2. Enable/disable scanning.
    5. Automatic reconnection to last connected scanner (i.e. scanner goes out range and then returns).
    6. Enable/Disable the pager vibrating motor.
  3. Device Configuration (Get, Set and Store Scanner attributes).
  4. Asset tracking,
    1. Model number
    2. Serial number
    3. Date of manufacture
    4. Firmware version
  5. Simplified pairing using Scan-To-Connect technology.
  6. Enables image and video capture.
  7. Update scanner firmware.
  8. Auto connection to the last connected scanner on app relaunch with Bluetooth Low Energy mode.

Configuring the Xcode Project

The Zebra Scanner SDK for iOS consists of a static library that can be linked with an external iOS application and a set of necessary header files.

To add the SDK:

  1. Create a new Xcode project and save it to a new project folder.
  2. Copy the symbolbt-sdk folder provided by Zebra Technologies into the new project folder. This folder contains the libsymbolbt-sdk.a file and an include folder containing SDK header files.
  3. Open the new project in Xcode, and select your project in the file navigator sidebar.

  4. Configure the Xcode project to support one or more external accessory communication protocols through the UISupportedExternalAccessoryProtocols key in your application Info.plist file or via the Info tab of your project settings.

    Table 1: Communication Protocols

    Communication Protocols Zebra Scanner
    com.motorolasolutions.CS4070_ssi CS4070
    com.zebra.scanner.SSI CS6080
    DS8178
    RFD8500

    Figure 8: Supported External Accessory Protocols

  5. In order to configure your application to communicate with Bluetooth scanners in a background mode, configure your Xcode project to specify the background modes that your application supports using the UIBackgroundModes key in your application Info.plist file or via the Info tab of your project settings.

    Figure 9: Required Background Modes

  6. Set Property List Key NSBluetoothAlwaysUsageDescription to use the device's Bluetooth interface. Description value should be a string.

    Example: "Zebra Scanner Control App uses Bluetooth to find, connect and communicate with nearby zebra devices. Please grant access".

    Figure 10: Privacy - Bluetooth Always Usage Description

  7. Select your Target, and then its Build Phases tab. Expand the Link Binary With Libraries item. Add the following frameworks by clicking the + button:
    • libsymbolbt-sdk.a
    • ExternalAccessory
    • CoreBluetooth
    Figure 11: Link Binary with Libraries

  8. Select the Build Settings tab. Navigate to the Search Paths section of the Build Settings. Set User Header Search Paths to $(SRCROOT)/symbolbt-sdk/include/.

    Figure 12: User Header Search Paths

  9. If linker issue occurs when building the project, Follow below steps.
    • Go to the project Build Settings tab.
    • Search for Other Linker Flags.
    • Add -lz as a linker flag (see screenshot).
    • In the Product menu, select Clean Build Folder option before building again.
    Figure 13: Other Linker Flags

    NOTE: With the above steps your Objective-C project will be configured to use the Zebra Scanner SDK for iOS. Further steps as given below are required to configure a Swift Project for accessing the Zebra Scanner SDK.

  10. Create a Bridging Header by adding a new header file to your Xcode project.
    • Select File > New > File.
    • Then select iOS and under Source, click Header File.
    • Name your file "YourProjectName-Bridging-Header.h". Example: "Scanner", the file is named "Scanner-Bridging-Header.h".
    • Create the header file.
  11. Setting the Objective-C Bridging Header path.
    • Select your Target and then navigate to the Build Settings tab.
    • Navigate to Swift Compiler - General section in Build Settings tab.
    • Set Objective-C Bridging Header path.
    • Next to Objective-C Bridging Header, you will need to add the path of your header file as follows. $(SWIFT_MODULE_NAME)/ YourBridgingHeaderFileName.h
    Figure 14: Objective-C Bridging Header

  12. Adding Objective-C header files to the bridging header file.
    • Open your newly created bridging header file.
    • Import all the header files in the "include" folder which is in the "symbolbt-sdk" folder.
      
#ifndef SwiftSample_Bridging_Header_h
#define SwiftSample_Bridging_Header_h

#import "ISbtSdkApi.h"
#import "FirmwareUpdateEvent.h"
#import "SbtSdkFactory.h"
#import "ISbtSdkApiDelegate.h"
#import "RMDAttributes.h"
#import "SbtScannerInfo.h"
#import "SbtSdkDefs.h"
#import "SbtSdkFactory.h"

#endif /* SwiftSample_Bridging_Header_h */
  13. Any headers listed in the bridging header file will be accessible from your Swift classes without importing those files.
  14. Your Swift project is now configured to use the Zebra Scanner SDK for iOS.

NOTE: When bridging an Objective-C interface to Swift, int type in Objective-C is bridged as Int32 in Swift. Therefore, it requires to be casted manually when accessing SDK APIs in Swift.