No part of this publication may be reproduced or used in any form, or by any electrical or mechanical means,
without permission in writing from Zebra. This includes electronic or mechanical means, such as photocopying,
recording, or information storage and retrieval systems. The material in this manual is subject to change
without notice.
The software is provided strictly on an “as is” basis. All software, including firmware, furnished to the user is on
a licensed basis. Zebra grants to the user a non-transferable and non-exclusive license to use each software
or firmware program delivered hereunder (licensed program). Except as noted below, such license may not be
assigned, sublicensed, or otherwise transferred by the user without prior written consent of Zebra. No right to
copy a licensed program in whole or in part is granted, except as permitted under copyright law. The user shall
not modify, merge, or incorporate any form or portion of a licensed program with other program material, create
a derivative work from a licensed program, or use a licensed program in a network without written permission
from Zebra. The user agrees to maintain Zebra’s copyright notice on the licensed programs delivered
hereunder, and to include the same on any authorized copies it makes, in whole or in part. The user agrees not
to decompile, disassemble, decode, or reverse engineer any licensed program delivered to the user or any
portion thereof.
Zebra reserves the right to make changes to any software or product to improve reliability, function, or design.
Zebra does not assume any product liability arising out of, or in connection with, the application or use of any
product, circuit, or application described herein.
No license is granted, either expressly or by implication, estoppel, or otherwise under any Zebra Technologies
Corporation, intellectual property rights. An implied license only exists for equipment, circuits, and subsystems
contained in Zebra products.
Warranty
For the complete Zebra hardware product warranty statement, go to:
http://www.zebra.com/warranty
.
Revision History
Changes to the original manual are listed below:
-01 Rev A - 10/2015Initial Release
-02 Rev A - 12/2015- Removed all references to sbtEstablishCommunicationSession:aRawPipeMode and
iii
all uses of rawPipeMode;
- Removed all references to sbtEventRawData
- Removed Raw Data Received Event section
- Removed the following line
in ISbtSdkApiDelegate - - (void) sbtEventRawData:(NSData*)rawData
fromScanner:(int)scannerID;
- Removed sbtEventRawData section and all references to sbtReadRawData
- Removed the following line:
(SBT_RESULT) sbtReadRawData:(unsigned char*)buffer maxLength:(int)length
bytesRead:(int*)bytesRead forScanner:(int)scannerID;
- Removed the sbtReadRawData section
- Removed all references to sbtWriteRawData
- Remove the following line:
(SBT_RESULT) sbtWriteRawData:(unsigned char*)buffer maxLength:(int)length
bytesWritten:(int*)bytesWritten forScanner:(int)scannerID;
- Removed sbtWriteRawData section.
- Updated Beep Control section, table, and code sample
- Removed the Turn Off The LED section.
- Replaced the entire Turn On the LED section
- Added a deprecation statement to sbtBeepControl
- Added a deprecation statement to sbtLedControl
- Added code to SbtScannerInfo
-03 Rev A - 1/2017- Updated CS4070 mode to MFI SSI in Table 1-1
- Several updates changing "pulled trigger on scanner ID" to "pulled updated firmware
on scanner ID"
- Several updates changing "scanner ID 3 to pull the trigger" to "scanner ID 3 to update
firmware"
- Added BT scanners to Table 1-2
- Added Table 1-3
- Added page motor support and AIM on and AIM off to Performing Operations section
- Added sbtSetBTAddress and sbtGetPairingBarcode
- Added descriptions for sbtSetBTAddress and sbtGetPairingBarcode
- Added tables: Firmware Update Result Code; STC Bar Code Types; STC Communication Protocol; Set Default Status
- Added sbtEventFirmwareUpdate
-04 Rev A - 6/2019- Added DS8178
ivZebra Scanner SDK for iOS Developer Guide
ChangeDateDescription
-03 Rev A01/2017
-04 Rev A07/2019
•
Updated CS4070 mode to MFI SSI in Table 1-1
•
Several updates changing "pulled trigger on scanner ID" to "pulled updated
firmware on scanner ID"
•
Several updates changing "scanner ID 3 to pull the trigger" to "scanner ID 3 to
update firmware"
•
Added BT scanners to Table 1-2
•
Added Table 1-3
•
Added page motor support and AIM on and AIM off to Performing Operations
section
•
Added sbtSetBTAddress and sbtGetPairingBarcode
•
Added descriptions for sbtSetBTAddress and sbtGetPairingBarcode
•
Added tables: Firmware Update Result Code; STC Bar Code Types; STC
Communication Protocol; Set Default Status
•
Added sbtEventFirmwareUpdate
•
Added DS8178 support.
TABLE OF CONTENTS
Warranty ......................................................................................................................................... ii
Revision History .............................................................................................................................. iii
About This Guide
Introduction ..................................................................................................................................... ix
Chapter Descriptions ...................................................................................................................... ix
Related Documents ........................................................................................................................ ix
Notational Conventions................................................................................................................... x
Service Information ......................................................................................................................... x
Chapter 1: INTRODUCTION to the ZEBRA SCANNER SDK for iOS
The Zebra Scanner SDK for iOSDeveloper Guide provides installation and programming information for the
Software Developer Kit (SDK) that allows Software Decode based applications for iOS based devices.
Chapter Descriptions
This guide includes the following topics:
•
Chapter 1, INTRODUCTION to the ZEBRA SCANNER SDK for iOS provides an overview of the Zebra
Scanner SDK for iOS.
•
Chapter 2, ZEBRA SCANNER CONTROL APPLICATION INST ALLATION and CONFIGURATION describes
the process required to install and execute the scanner Zebra Scanner Control application.
•
Chapter 3, SAMPLE SOURCE CODE provides detailed examples that demonstrate how to develop iOS
applications using the Zebra Scanner Software Development Kit (SDK).
•
Chapter 4, ZEBRA SCANNER SDK for iOS API defines the API that can be used by external applications to
connect remote scanners to a specific iOS device and control connected scanners.
Related Documents
•
Zebra Scanner SDK for Android Developer Guide, p/n MN002223Axx.
•
RFD8500 RFID Developer Guide, p/n MN002222Axx.
•
RFD8500 Quick Start Guide, p/n MN002225Axx.
•
RFD8500 Regulatory Guide, p/n MN002062Axx.
•
CRDUNIV-RFD8500-1R Three Slot Universal Cradle Charge Only Regulatory Guide, p/n MN002224Axx.
•
RFD8500 User Guide, p/n MN002065Axx.
For the latest version of this guide and all guides, go to: www.zebra.com/support.
xZebra Scanner SDK for iOS Developer Guide
Notational Conventions
This document uses the followingconventions:
•
The prefix SBT is used to reference Zebra Scanner SDK for iOS APIs.
•
The abbreviation for Bluetooth is BT.
•
SDK refers to the Zebra Scanner SDK for iOS.
•
Italics are used to highlight chapters, screen names, fields, and sections in this and related documents
•
bullets (•) indicate:
• Action items
• Lists of alternatives
• Lists of required steps that are not necessarily sequential
•
Sequential lists (e.g., those that describe step-by-step procedures) appear as numbered lists.
NOTE This symbol indicates something of special interest or importance to the reader. Failure to read the note
does not result in physical harm to the reader, equipment or data.
CAUTION This symbol indicates that if this information is ignored, the possibility of data or material damage may
occur.
WARNING! This symbol indicates that if this information is ignored the possibility that serious personal
Service Information
If you have a problem using the equipment, contact your facility's technical or systems support. If there is a
problem with the equipment, they contact the Zebra Technologies Global Customer Support Center at:
http://www.zebra.com/support.
When contacting Zebra support, please have the following information available:
•
Product name
•
Version number
Zebra responds to calls by e-mail, telephone or fax within the time limits set forth in support agreements.
If your problem cannot be solved by Zebra support, you may need to return your equipment for servicing and
will be given specific directions. Zebra is not responsible for any damages incurred during shipment if the
approved shipping container is not used. Shipping the units improperly can possibly void the warranty.
injury may occur.
If you purchased your business product from a Zebra business partner, contact that business partner for
support.
Chapter 1INTRODUCTION to the ZEBRA
SCANNER SDK for iOS
Overview
The Zebra Scanner SDK for iOS is provided as a static library that can be linked to a custom iOS application.
The static library provides an Application Programming Interface (API) to provide the communication facilities
required to operate a supported Zebra scanner on the iOS platform. The SDK provides the capability to
manage connections, configure connected scanners, perform various operations with connected scanners,
and to obtain information about connected scanners.
Supported Scanners
The following MFi (Made for iPhone/iPod/iPad) Zebra scanners are currently supported by the iOS SDK.
Table 1-1
CS4070MFI SSI
RFD8500Bluetooth MFi Server mode, with primary mode set to MFI SSI
Table 1-2 lists the Bluetooth low energy Zebra scanners currently supported by the iOS SDK.
Table 1-2
DS3678SSI over Bluetooth low energy
LI3678SSI over Bluetooth low energy
DS8178SSI over Bluetooth low energy
Supported Zebra Scanners
Zebra ScannerConfiguration
Supported Zebra Scanners
Zebra ScannerConfiguration
NOTE To configure a device in the mode specified, refer to the appropriate Product Reference Guide, User
Guide, or Integration Guide.
1 - 2Zebra Scanner SDK for iOS Developer Guide
Table 1-3
LI3678NoYesYes
DS3678NoYesYes
CS4070NoNoYes
RFD8500NoNoYes
DS8178YesYesYes
Pairing Modes
Pairing Bar Code
Scanner Model
LegacySTCManual Pairing
System Requirements
The following system requirements are necessary in order to develop, test, and execute applications using the
Zebra Scanner SDK for iOS:
•
Xcode 6, or later
•
iOS SDK 8.0, or later
•
Zebra Scanner SDK for iOS
•
iPhone or iPod Touch running iOS 8.0 or later.
Chapter 2ZEBRA SCANNER CONTROL
APPLICATION INSTALLATION
and CONFIGURATION
Introduction
This chapter 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.
2 - 2Zebra Scanner SDK for iOS Developer Guide
Installing the Zebra Scanner Control Application
Using the Source Code
Prerequisites
•
OS X.
•
Xcode. Download Xcode from the Mac App Store.
•
iOS 8, or higher, installed.
•
An iOS Developer account with Apple.
•
A provisioned iOS device.
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 8, 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.
ZEBRA SCANNER CONTROL APPLICATION INSTALLATION and CONFIGURATION2 - 3
Launching the Zebra Scanner Control Application
1.Before launching the application, set the Zebra scanner to the appropriate configuration. See Supported
Scanners on page 1-1 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 2-1
Scanner Application - Initial Screen
2 - 4Zebra Scanner SDK for iOS Developer Guide
+
4.Select Scanners from the menu. The following screen displays:
Figure 2-2
5.Select the device from the left panel, and then tap the Connect button from the Available Scanner
menu.The following screen displays:
Figure 2 - Scanner Application - Scanners Screen
Figure 2-3
Scanner Application - Available Scanner Screen
ZEBRA SCANNER CONTROL APPLICATION INSTALLATION and CONFIGURATION2 - 5
6.Once connected, the Active Scanner menu displays. This menu is used to select various options including
Info, Barcode, and Settings.
a.Select the Info tab to view the Scanner ID, Type, Name, and Auto Reconnection state. This tab also
contains functionality to control the Beeper and LED. The following screen displays:
Figure 2-4
b. Select the Barcode tab to view scanned bar codes, and to pull/release the scanner trigger.The
Scanner Application - Active Scanner Screen
following screen displays:
Figure 2-5
Scanner Application - Barcode screen
2 - 6Zebra Scanner SDK for iOS Developer Guide
c.Select the Settings tab to select supported Symbologies, configure the beeper volume and frequency,
and to enable/disable scanning.The following screen displays:
Figure 2-6
i.To control which symbologies the scanner reads, select the Symbologies option. An on/off control
Scanner Application - Settings Screen
switch appears next to each bar code type displayed in the menu.
Figure 2-7
NOTE Custom symbology settings can be configured via 123Scan
Scanner Application - Symbologies Screen
2
. When setting the Inter Character Delay for
HID only, set the delay in milliseconds between emulated keystrokes. When pairing with an Android
device, set the Inter Character Delay to 70 ms to avoid data loss.
ZEBRA SCANNER CONTROL APPLICATION INSTALLATION and CONFIGURATION2 - 7
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 2-1
Communication Protocols
Communication ProtocolZebra Scanner
com.motorolasolutions.CS4070_ssiCS4070
com.zebra.scanner.SSI
RFD8500
com.motorolasolutions.scanner
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.
6.Select your Target, and then its Build Phases tab.
7.Expand the Link Binary With Libraries item.
8.Add the following frameworks by clicking the + button:
• libsymbolbt-sdk.a
• ExternalAccessory
• CoreBluetooth.
9.Select the Build Settings tab.
10. Navigate to the Search Paths section of the Build Settings.
11. Set User Header Search Paths to $(SRCROOT)/symbolbt-sdk/include/.
12. Your project is now configured to use the Zebra Scanner SDK for iOS.
2 - 8Zebra Scanner SDK for iOS Developer Guide
Chapter 3SAMPLE SOURCE CODE
Introduction
This chapter provides detailed examples that demonstrate how to develop iOS applications using the Zebra
Scanner Software Development Kit (SDK).
3 - 2Zebra Scanner SDK for iOS Developer Guide
Accessing the SDK
Create an instance of the Zebra Scanner SDK for iOS API inside of a class that conforms to the
ISbtSdkApiDelegate. All available API functions are defined by the ISbtSdkApi Objective-C protocol. A
single shared instance of an API object that implements the ISbtSdkApi can be obtained via
createSbtSdkApiInstance method of the SbtSdkFactory class.
Code Snippet - Obtain Instance of API
// ....
@import "SbtSdkFactory.h"
// ....
// Get instance to the Zebra Scanner SDK API
id <ISbtSdkApi> apiInstance = [SbtSdkFactory createSbtSdkApiInstance];
// Get the SDK version string
NSString *version = [apiInstance sbtGetVersion];
NSLog(@"Zebra SDK version: %@\n", version);
Event Handling
The SDK supports a set of asynchronous notifications to inform the application about scanner related events.
This includes connectivity related events (i.e., appearance of a scanner), and scanner action events (i.e.,
received bar code data). All supported callbacks are defined by the ISbtSdkApiDelegate Objective-C
protocol.
In order to receive asynchronous notifications from the SDK, the application performs the following steps:
1.Create an object that implements the ISbtSdkApiDelegate.
Code Snippet - Create A Class That Implements Isbtsdkapidelegate
// Definition of a class that implements the ISbtSdkApiDelegate protocol
@interface EventReceiver : NSObject <ISbtSdkApiDelegate> {
// TODO: variables
}
// TODO: methods definition
2.Register the created object as notification receiver via the sbtSetDelegate function.
Code Snippet - Set Delegate Of API Instance To Object That Implements ISbtSdkApiDelegate
// Registration of the callback interface with SDK
EventReceiver *eventListener = [[EventReceiver alloc] init];
[apiInstance sbtSetDelegate:eventListener];
SAMPLE SOURCE CODE3 - 3
3.Subscribe for specific asynchronous events using the sbtSubscribeForEvents method to specify
which events should be reported by the SDK.
Valid notification/event mask values include:
• SBT_EVENT_BARCODE
• SBT_EVENT_IMAGE
• SBT_EVENT_VIDEO
• SBT_EVENT_SCANNER_APPEARANCE
• SBT_EVENT_SCANNER_DISAPPEARANCE
• SBT_EVENT_SESSION_ESTABLISHMENT
• SBT_EVENT_SESSION_TERMINATION
• SBT_EVENT_RAW_DATA.
Code Snippet - Subscribe To Scanner Events
// Subscribe to scanner appearance/disappearance, session establishment/termination,
// barcode, and image & video event notifications.
[apiInstance sbtSubsribeForEvents:SBT_EVENT_SCANNER_APPEARANCE |
SBT_EVENT_SCANNER_DISAPPEARANCE | SBT_EVENT_SESSION_ESTABLISHMENT |
SBT_EVENT_SESSION_TERMINATION | SBT_EVENT_BARCODE | SBT_EVENT_IMAGE |
SBT_EVENT_VIDEO];
Events
If an object is registered as a notification receiver, the SDK calls the corresponding method of the registered
object when a particular event occurs and the application is subscribed for events of this type.
Scanner Appeared Event
This event occurs when the presence of a scanner appears.