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 an XCFramework that can be linked with an external iOS application and a set of necessary header files.

Migrating to the XCFramework (ZebraScannerSDK.xcframework) from the static library(libsymbolbt-sdk.a)

  1. Delete the existing static library(libsymbolbt-sdk.a) from the project.

    Figure 8: Delete the static library from a Xcode project

  2. Delete existing Library and User Header Search Paths from the Build Settings.

    Figure 9: Delete Library and User Header Search Paths

  3. Add ZebraScannerSDK.xcframework to the project.

    Copy the ZebraScannerSDK.xcframework provided by Zebra Technologies into the project folder. Select the Project Target, click on Build Phases → Link Binary With Libraries → + Mark → Add Files.

    Figure 10: Add ZebraScannerSDK.xcframework to a Xcode project

  4. Embed and Sign the ZebraScannerSDK.xcframework in General → Frameworks, Libraries, and Embedded Content

    Figure 11: Embed and Sign

  5. Make sure Runpath Search Paths in the Build Settings is as follows.

    Figure 12: Runpath Search Paths

  6. Import Framework headers where it is necessary.

    If the existing Xcode project is an Objective C one, replace the new framework headers with Framework module name like below.

    Figure 13: Import Framework headers to an Objective C project

    If the existing Xcode project is a Swift one, replace the new framework headers with Framework module name in the bridging header file as below.

    Figure 14: Import Framework headers to a Swift project

Add Zebra Scanner SDK to a new Xcode project

  1. Create a new Xcode project and save it to a new project folder.
  2. Open the new project in Xcode and select your project in the file navigator sidebar.

  3. 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 15: Supported external accessory protocols

  4. 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 16: Required background modes

  5. 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 17: Privacy - Bluetooth Always Usage Description

  6. Add Zebra Scanner SDK (XCFramework bundle)

    1. Copy the ZebraScannerSDK.xcframework provided by Zebra Technologies into the new Xcode project folder.

      Select your Target, and then navigate to it's "Build Phases" tab. Expand the "Link Binary With Libraries" item. Add the following frameworks by clicking the + button:

      • ZebraScannerSDK.xcframework
      • ExternalAccessory
      • CoreBluetooth
      Figure 18: Link Binary with Libraries

    2. Embed and Sign the ZebraScannerSDK.xcframework in General → Frameworks, Libraries, and Embedded Content.

      Figure 19: Embed and Sign

  7. Add Zebra Scanner SDK (Swift Package)

    Zebra iOS Scanner SDK is available to download as a Swift Package on v1.4.43 onwards.

    1. Navigate to the Project → Package Dependencies → Add(+)

      Figure 20: Open SPM Window

    2. Enter the repository URL: https://github.com/ZebraDevs/Zebra-Scanner-SDK-iOS-SPM in the SPM window and add the package.

      Figure 21: Add the Package

    3. Add other required frameworks.

      Select your Target, and then its Build Phases tab. Expand the Link Binary With Libraries item. Add the following frameworks by clicking the add(+) button:

      • ExternalAccessory
      • CoreBluetooth
      Figure 22: Add other required frameworks

  8. Make sure Runpath Search Paths in the Build Settings as follows.

    Figure 23: Runpath Search Paths

  9. Import Framework headers where it is necessary.

    If the Xcode project is an Objective C one, import the framework headers with the Framework module name like below.

    Figure 24: Import Framework headers to an Objective C project

    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 225: Objective-C Bridging Header

  12. Adding Framework header files to the bridging header file.

    • Open your newly created bridging header file.
    • Import all the Framework header files as below.
    Figure 26: Framework headers in Bridging header

  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.