Barcode Scanner SDK for iOS

Overview

This chapter provides detailed examples that demonstrate how to develop iOS applications using the Zebra Scanner Software Development Kit (SDK).


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.


@import "SbtSdkFactory.h"

// Get instance to the Zebra Scanner SDK API
id  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.

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

    
    // Registration of the callback interface with SDK 
    EventReceiver *eventListener = [[EventReceiver alloc] init];
    
    [apiInstance sbtSetDelegate:eventListener];
    
    
  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.
    
    // 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.


- (void)sbtEventScannerAppeared:(SbtScannerInfo*)availableScanner {
    // TODO: Handle event
}

Scanner Disappeared Event

This event occurs when a scanner is no longer present.


- (void) sbtEventScannerDisappeared:(int)scannerID {
    // TODO: Handle event
}

Communication Session Established Event

This event occurs when communication is established with a scanner.


- (void) sbtEventCommunicationSessionEstablished:(SbtScannerInfo*)activeScanner {
    // TODO: Handle event
}

Communication Session Terminated Event

This event occurs when communication with a scanner is terminated.


- (void) sbtEventCommunicationSessionTerminated:(int)scannerID {
    // TODO: Handle event
}

Barcode Data Received Event

This event occurs when barcode data is read and received.


- (void) sbtEventBarcodeData:(NSData *)barcodeData barcodeType:(int)barcodeType fromScanner:(int)scannerID {
    // TODO: Handle event
}

Image Data Received Event

This event occurs when image data is received.


- (void) sbtEventImage:(NSData*)imageData fromScanner:(int)scannerID {
    // TODO: Handle event
}

Video Data Received Event

This event occurs when video data is received.


- (void) sbtEventVideo:(NSData*)videoFrame fromScanner:(int)scannerID {
    // TODO: Handle event
}

Firmware Update Event

This event occurs when firmware update is in progress. You don't need to specifically subscribe to this event. You just have to implement this delegate method.


- (void) sbtEventFirmwareUpdate:(FirmwareUpdateEvent*)event {
    // TODO: Handle event
}


Connectivity Management

The SDK identifies scanners as "available" and "active". An "available" scanner is a scanner that is connected to the iOS device via Bluetooth, but has not yet established a communication session with the SDK. An "active" scanner is a scanner that is both connected to the iOS device via Bluetooth, and has established a communication session with the SDK.

The SDK supports simultaneous interaction with multiple scanners. To distinguish between various scanners, the SDK assigns a unique integer identifier for each scanner when it becomes available for the first time.

Set Operation Mode

Zebra Scanner SDK for iOS is designed to support interaction with scanners operating in BT MFi or BT LE mode. The SDK shall be configured to enable communication with a particular type of scanner by setting the operation mode.

Use the sbtSetOperationalMode function to set the required operational mode of the scanners to interface with.

Valid inputs include:

  • SBT_OPMODE_MFI
  • SBT_OPMODE_BTLE
  • SBT_OPMODE_ALL.

// Set operational mode to all so that SDK can interface with scanners operating in MFI or BTLE mode.
[apiInstance sbtSetOperationalMode:SBT_OPMODE_ALL];

Enable Scanner Detection

The SDK supports automatic detection of appearance and disappearance of available scanners. When the "Available scanners detection" option is enabled the SDK updates its internal list of available scanners and deliver a corresponding asynchronous notification once it detects connection or disconnection of a particular scanner to the iOS device via Bluetooth. If the option is disabled, the SDK updates its internal list of available scanners only when requested by the application via the sbtGetAvailableScannersList.

Use the sbtEnableAvailableScannersDetection method to actively detect appearance and disappearance of scanners.


// Actively detect appearance/disappearance of scanners [apiInstance sbtEnableAvailableScannersDetection:YES];

Get Available and Active Scanners

The SDK maintains an internal list of active and available scanners. The following example demonstrates how to receive a list of available and active scanners from the SDK.


// Allocate an array for storage of a list of available scanners 
NSMutableArray *availableScanners = [[NSMutableArray alloc] init];

// Allocate an array for storage of a list of active scanners 
NSMutableArray *activeScanners = [[NSMutableArray alloc] init];

// Retrieve a list of available scanners
[apiInstance sbtGetAvailableScanners:&availableScanners];

// Retrieve a list of active scanners
[apiInstance sbtGetActiveScanners:&activeScanners];

// Merge the available and active scanners into a single list 
NSMutableArray *allScanners = [[NSMutableArray alloc] init]; 
[allScanners addObjectsFromArray:availableScanners]; 
[allScanners addObjectsFromArray:activeScanners];

// Print information for each available and active scanner 
for (SbtScannerInfo *info in allScanners) {
    NSLog(@"Scanner is %@: ID = %d name = %@", (([info isActive] == YES) ? @"active" : @"available"), [info getScannerId], [info getScannerName]);
}

Connect to a Scanner

You can establish a connection with an available scanner by providing the scanner ID to the SDK's sbtEstablishCommunicationSession method.


// Attempt to establish a connection with the scanner device that has an ID = 3. 
SBT_RESULT result = [apiInstance sbtEstablishCommunicationSession:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful connection
    NSLog(@"Connection to scanner ID %d successful",scannerId);
}
else {
    // TODO: Process error (unsuccessful connection)
    NSLog(@"Failed to establish a connection with scanner ID %d",scannerId);
}

Disconnect from a Scanner

You can disconnect from an active scanner using the SDK's sbtTerminateCommunicationSession method.


// Attempt to disconnect from the scanner device that has an ID = 3. 
SBT_RESULT result = [apiInstance sbtTerminateCommunicationSession:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful disconnection
    NSLog(@"Disconnect from scanner ID %d successful",scannerId);
}
else {
    // TODO: Process error (unsuccessful connection) 
    NSLog(@"Failed to disconnect from scanner ID %d",scannerId);
}

Automatically Reconnect to a Scanner

The SDK supports "Automatic Session Reestablishment" option is used to automatically reconnect to a scanner that unexpectedly disappeared. If the "Automatic Session Reestablishment" option is enabled for a specific scanner, the SDK automatically attempts to reestablish a connection with the scanner when it becomes available again. The option has no effect if the application has intentionally terminated a communication session with the scanner via the sbtTerminateCommunicationSession function.

Use the sbtEnableAutomaticSessionReestablishment function to enable or disable automatic reconnection for a specific scanner.


// Set the automatic session reestablishment option for scanner ID 3 
SBT_RESULT result = [apiInstance sbtEnableAutomaticSessionReestablishment:YES forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Option successfully set
    NSLog(@"Automatic Session Reestablishment for scanner ID %d has been set successfully",scannerId);
}
else {
    // TODO: Error (option was not set)
    NSLog(@"Automatic Session Reestablishment for scanner ID %d could not be set",scannerId);
}


Performing Operations

The Zebra Scanner iOS SDK provides the capability to perform various scanner operations such as:

  • Adjusting beeper settings
  • Turning the LED on and off
  • Enabling and disabling scanning
  • Enabling and disabling supported symbologies
  • Pulling and releasing the trigger
  • Turning AIM on and off
  • Activate page motor.

Get Beeper Settings

The get attribute command (SBT_RSM_ATTR_GET) is used to retrieve the beeper volume and frequency attribute values. The attribute values are returned from the scanner as an XML formatted string.

Table 1 Beeper Setting Attributes

Attribute Description Attribute Name
Beeper Volume RMD_ATTR_BEEPER_VOLUME
Beeper Frequency RMD_ATTR_BEEPER_FREQUENCY

The following code example demonstrates how to retrieve the scanner's current beeper volume and frequency settings.


// Create XML string to request beeper volume and frequency settings for scanner ID 3
NSString *xmlInput = [NSString stringWithFormat:@"
<inArgs><scannerID>%d</scannerID><cmdArgs><arg-xml><attrib_list>%d,%d</attrib_lis t></arg-xml></cmdArgs></inArgs>",3, RMD_ATTR_BEEPER_VOLUME, RMD_ATTR_BEEPER_FREQUENCY];

NSMutableString *xmlResponse = [[NSMutableString] alloc] init];

// Retrieve beeper volume and frequency settings from Scanner ID 3 
SBT_RESULT result = [apiInstance sbtExecuteCommand:SBT_RSM_ATTR_GET aInXML:xmlInput aOutXML:&xmlResponse forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process xml string containing requested beeper settings 
    NSLog(@"Retrieved beeper settings from scanner ID %d:%@",scannerId,xmlResponse);
}
else {
    // TODO: Process error
    NSLog(@"Failed to retrieve beeper settings from scanner ID %d",scannerId);
}

Set Beeper Volume

The set attribute command (SBT_RSM_ATTR_SET) is used to set the value of the beeper volume attribute (RMD_ATTR_BEEPER_VOLUME).

Table 2 Beeper Volume Attribute Values

Beeper Volume Attribute Values
RMD_ATTR_VALUE_BEEPER_VOLUME_LOW
RMD_ATTR_VALUE_BEEPER_VOLUME_MEDIUM
RMD_ATTR_VALUE_BEEPER_VOLUME_HIGH

The following code example demonstrates how to set the scanner's beeper volume:


// Create XML string to set the beeper volume on scanner ID 3 to LOW. 
NSString *xmlInput = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID><cmdArgs><arg-xml><attrib_list><attribute><id>%d</id><datatype>B</datatype><value>%d</value></attribute></attrib_list></arg-xml></cmdArgs></inArgs>",3, RMD_ATTR_BEEPER_VOLUME, RMD_ATTR_VALUE_BEEPER_VOLUME_LOW];

// Command Scanner ID 3 to set beeper volume to LOW.
SBT_RESULT result = [apiInstance sbtExecuteCommand:SBT_RSM_ATTR_SET aInXML:xmlInput aOutXML:nil forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful operation
    NSLog(@"Successfully updated beeper settings for scanner ID %d:%@",scannerId,xmlResponse);
}
else {
    // TODO: Process error
    NSLog(@"Failed to update beeper settings from scanner ID %d",scannerId);
}

Set Beeper Frequency

The set attribute command (SBT_RSM_ATTR_SET) is used to set the value of the beeper frequency attribute (RMD_ATTR_BEEPER_FREQUENCY).

Table 3 Beeper Frequency Attribute Values

Beeper Frequency Attribute Values
RMD_ATTR_VALUE_BEEPER_FREQ_LOW
RMD_ATTR_VALUE_BEEPER_FREQ_MEDIUM
RMD_ATTR_VALUE_BEEPER_FREQ_HIGH

The following code example demonstrates how to set the scanner's beeper frequency.


// Create XML string to set the beeper frequency on scanner ID 3 to HIGH. 
NSString *xmlInput = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID><cmdArgs><arg-xml><attrib_list><attribute><id>%d</id><datatype>B</datatype><value>%d</value></attribute></attrib_list></arg-xml></cmdArgs></inArgs>",3, RMD_ATTR_BEEPER_FREQUENCY, RMD_ATTR_VALUE_BEEPER_FREQ_HIGH];

// Command Scanner ID 3 to set beeper frequency to HIGH.
SBT_RESULT result = [apiInstance sbtExecuteCommand:SBT_RSM_ATTR_SET aInXML:xmlInput aOutXML:nil forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful operation
    NSLog(@"Successfully updated beeper settings for scanner ID %d:%@",scannerId,xmlResponse);
}
else {
    // TODO: Process error
    NSLog(@"Failed to update beeper settings from scanner ID %d",scannerId);
}

Beep Control

Command the scanner's beeper to emit sound by using the sbtExecuteCommand API. Use command op code SBT_SET_ACTION and an attribute value shown in table below.

Table 4 Beeper Attribute Values

Description Attribute Values
One high short beep RMD_ATTR_VALUE_ACTION_HIGH_SHORT_BEEP_1
Two high short beeps RMD_ATTR_VALUE_ACTION_HIGH_SHORT_BEEP_2
Three high short beeps RMD_ATTR_VALUE_ACTION_HIGH_SHORT_BEEP_3
Four high short beeps RMD_ATTR_VALUE_ACTION_HIGH_SHORT_BEEP_4
Five high short beeps RMD_ATTR_VALUE_ACTION_HIGH_SHORT_BEEP_5
One low short beep RMD_ATTR_VALUE_ACTION_LOW_SHORT_BEEP_1
Two low short beeps RMD_ATTR_VALUE_ACTION_LOW_SHORT_BEEP_2
Three low short beeps RMD_ATTR_VALUE_ACTION_LOW_SHORT_BEEP_3
Four low short beeps RMD_ATTR_VALUE_ACTION_LOW_SHORT_BEEP_4
Five low short beeps RMD_ATTR_VALUE_ACTION_LOW_SHORT_BEEP_5
One high long beep RMD_ATTR_VALUE_ACTION_HIGH_LONG_BEEP_1
Two high long beeps RMD_ATTR_VALUE_ACTION_HIGH_LONG_BEEP_2
Three high long beeps RMD_ATTR_VALUE_ACTION_HIGH_LONG_BEEP_3
Four high long beeps RMD_ATTR_VALUE_ACTION_HIGH_LONG_BEEP_4
Five high long beeps RMD_ATTR_VALUE_ACTION_HIGH_LONG_BEEP_5
One low long beep RMD_ATTR_VALUE_ACTION_LOW_LONG_BEEP_1
Two low long beeps RMD_ATTR_VALUE_ACTION_LOW_LONG_BEEP_2
Three low long beeps RMD_ATTR_VALUE_ACTION_LOW_LONG_BEEP_3
Four low long beeps RMD_ATTR_VALUE_ACTION_LOW_LONG_BEEP_4
Five low long beeps RMD_ATTR_VALUE_ACTION_LOW_LONG_BEEP_5
Fast warble beep RMD_ATTR_VALUE_ACTION_FAST_WARBLE_BEEP
Slow warble beep RMD_ATTR_VALUE_ACTION_SLOW_WARBLE_BEEP
High-low beep RMD_ATTR_VALUE_ACTION_HIGH_LOW_BEEP
Low-high beep RMD_ATTR_VALUE_ACTION_LOW_HIGH_BEEP
High-low-high beep RMD_ATTR_VALUE_ACTION_HIGH_LOW_HIGH_BEEP
Low-high-low beep RMD_ATTR_VALUE_ACTION_LOW_HIGH_LOW_BEEP

The following code example demonstrates how to command the scanner's beeper to emit a high short beep sound.


@import "RMDAttributes.h"

// Specify the ID of the scanner to control int scannerID = 1;

// Specify the scanner ID and attribute value of the beeper command in the XML NSString *inXML = [NSString
stringWithFormat:@"<inArgs><scannerID>%d</scannerID><cmdArgs><arg-int>%d</arg-int
></cmdArgs></inArgs>", scannerID, RMD_ATTR_VALUE_ACTION_HIGH_SHORT_BEEP_1];

// Issue the beep command
[scannerSdkApi sbtExecuteCommand:SBT_SET_ACTION aInXML:inXML aOutXML:nil forScanner:scannerID];

LED Control

Control the scanner's LED by using the sbtExecuteCommand API. Use command opcode SBT_SET_ACTION and an attribute value shown in tha table below.

Table 5 LED Attribute Values

Description Attribute Values
Turn Green LED off RMD_ATTR_VALUE_ACTION_LED_GREEN_OFF
Turn Green LED on RMD_ATTR_VALUE_ACTION_LED_GREEN_ON
Turn Yellow LED on RMD_ATTR_VALUE_ACTION_LED_YELLOW_ON
Turn Yellow LED off RMD_ATTR_VALUE_ACTION_LED_YELLOW_OFF
Turn Red LED on RMD_ATTR_VALUE_ACTION_LED_RED_ON
Turn Red LED off RMD_ATTR_VALUE_ACTION_LED_RED_OFF

The following code example demonstrates how to command the scanner's LED to illuminate green.


#import "RMDAttributes.h"

// Specify the ID of the scanner to control int scannerID = 1;

// Specify the scanner ID and attribute value the LED command in the XML 
NSString *inXML = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID><cmdArgs><arg-int>%d</arg-int></cmdArgs></inArgs>", scannerID, RMD_ATTR_VALUE_ACTION_LED_GREEN_ON];

// Issue the LED command
[scannerSdkApi sbtExecuteCommand:SBT_SET_ACTION aInXML:inXML aOutXML:nil forScanner:scannerID];

Enable Scanning

The scan enable command (SBT_DEVICE_SCAN_ENABLE) is used to enable the device's scanning capability. The following code example demonstrates how to enable the scan capability.


// Create XML string to enable scanning on scanner ID 3 
NSString *xmlInput = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID></inArgs>",scannerId];

// Command scanner ID 3 to enable scanning
SBT_RESULT result = [apiInstance sbtExecuteCommand:SBT_DEVICE_SCAN_ENABLE aInXML:xmlInput aOutXML:nil forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful operation
    NSLog(@"Successfully enabled scanning on scanner ID %d",scannerId);
}
else {
    // TODO: Process error
    NSLog(@"Failed to enable scanning on scanner ID %d",scannerId);
}

Disable Scanning

The scan disable command (SBT_DEVICE_SCAN_DISABLE) is used to disable the device's scanning capability. The following code example demonstrates how to disable the scan capability.


// Create XML string to disable scanning on scanner ID 3 
NSString *xmlInput = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID></inArgs>",scannerId];

// Command scanner ID 3 to disable scanning
SBT_RESULT result = [apiInstance sbtExecuteCommand:SBT_DEVICE_SCAN_DISABLE aInXML:xmlInput aOutXML:nil forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful operation
    NSLog(@"Successfully disabled scanning on scanner ID %d",scannerId);
}
else {
    // TODO: Process error
    NSLog(@"Failed to disable scanning on scanner ID %d",scannerId);
}

Get Supported Symbology IDs

The get all symbologies command (SBT_RSM_ATTR_GETALL) is used to retrieve the scanner's support symbologies. The supported symbology attribute values are returned from the scanner as an XML formatted string. Following table includes valid symbology attribute values.

Table 6 Symbology Attribute Values

Description Attribute Values
UPC-A RMD_ATTR_SYM_UPC_A
UPC-E RMD_ATTR_SYM_UPC_E
UPC-E1 RMD_ATTR_SYM_UPC_E_1
EAN-8/JAN8 RMD_ATTR_SYM_EAN_8_JAN_8
EAN-13/JAN13 RMD_ATTR_SYM_EAN_13_JAN_13
Bookland EAN RMD_ATTR_SYM_BOOKLAND_EAN
Code 128 RMD_ATTR_SYM_CODE_128
UCC/EAN-128 RMD_ATTR_SYM_UCC_EAN_128
Code 39 RMD_ATTR_SYM_CODE_39
Code 93 RMD_ATTR_SYM_CODE_93
Code 11 RMD_ATTR_SYM_CODE_11
Interleaved 2 of 5 RMD_ATTR_SYM_INTERLEAVED_2_OF_5
Discrete 2 of 5 RMD_ATTR_SYM_DISCRETE_2_OF_5
Chinese 2 of 5 RMD_ATTR_SYM_CHINESE_2_OF_5
Codabar RMD_ATTR_SYM_CODABAR
MSI RMD_ATTR_SYM_MSI
Code 32 RMD_ATTR_SYM_CODE_32
Data Matrix RMD_ATTR_SYM_DATAMATRIXQR
PDF RMD_ATTR_SYM_PDF

The following code example demonstrates how to get all supported symbologies.


// Create XML string to request supported symbologies of scanner ID 3 
NSString *xmlInput = [NSStringstringWithFormat:@"<inArgs><scannerID>%d</scannerID></inArgs>",3]; 
NSMutableString *xmlResponse = [[NSMutableString] alloc] init];

// Retrieve supported symbologies of scanner device that has an ID = 3.
SBT_RESULT result = [apiInstance sbtExecuteCommand:SBT_RSM_ATTR_GETALL aInXML:xmlInput aOutXML:&xmlResponse forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process xml string containing supported symbologies
    NSLog(@"Supported symbologies from scanner ID %d:%@",scannerId,xmlResponse);
}
else {
    // TODO: Process error
    NSLog(@"Failed to retrieve supported symbologies from scanner ID%d",scannerId);
}

Get Symbology Values

The get attribute command (SBT_RSM_ATTR_GET) is used to retrieve the value of a symbology. The symbology value is returned from the scanner as an XML formatted string.

The following code example demonstrates how to retrieve the values of symbologies.


// Create XML string to request value of supported symbology ID's 1 and 8 for scanner ID 3
NSString *xmlInput = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID><cmdArgs><arg-xml><attrib_lis t>1,8</attrib_list></arg-xml></cmdArgs></inArgs>",3];

NSMutableString *xmlResponse = [[NSMutableString] alloc] init];

// Retrieved values of symbologies for scanner ID = 3.
SBT_RESULT result = [apiInstance sbtExecuteCommand:SBT_RSM_ATTR_GET aInXML:xmlInput aOutXML:&xmlResponse forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process xml string containing symbology values 
    NSLog(@"Supported symbology values from scanner ID %d:%@",scannerId,xmlResponse);
}
else {
    // TODO: Process error
    NSLog(@"Failed to retrieve symbology values from scanner ID %d",scannerId);
}

Set Symbology Values

The set attribute command (SBT_RSM_ATTR_SET) is used to set the value of a symbology. The symbology value is returned from the scanner as an XML formatted string.

The following code example demonstrates how to set the value of symbology.


int scannerId = 3;
int symbologyId = 8;

// Create XML string to set value of symbology ID 8 for scanner ID 3 to "True" 
NSString *xmlInput = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID><cmdArgs><arg-xml><attrib_list><attribute><id>%d</id><datatype>F</datatype><value>%@</value></attribute></attrib_list></arg-xml></cmdArgs></inArgs>",scannerId,symbologyId,"True"];

// Set value of symbology ID 8 for scanner ID = 3 to "True"
SBT_RESULT result = [apiInstance sbtExecuteCommand:SBT_RSM_ATTR_SET aInXML:xmlInput aOutXML:nil forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful operation
    NSLog(@"Successfully updated symbology value for scanner ID %d:%@",scannerId);
}
else {
    // TODO: Process error
    NSLog(@"Failed to set symbology value for scanner ID %d",scannerId);
}

Pull Trigger

The pull trigger command (SBT_DEVICE_PULL_TRIGGER) is used to pull the device's trigger. The following code example demonstrates how to command the scanner's trigger to be pulled.


// Create XML string to command scanner ID 3 to pull the trigger 
NSString *xmlInput = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID></inArgs>",scannerId];

// Command scanner ID 3 to pull the trigger
SBT_RESULT result = [apiInstance sbtExecuteCommand:SBT_DEVICE_PULL_TRIGGER aInXML:xmlInput aOutXML:nil forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful operation
    NSLog(@"Successfully pulled trigger on scanner ID %d: %@",scannerId);
}
else {
    // TODO: Process error
    NSLog(@"Failed to pull trigger on scanner ID %d",scannerId);
}

Release Trigger

The release trigger command (SBT_DEVICE_RELEASE_TRIGGER) is used to release the device's trigger. The following code example demonstrates how to command the scanner's trigger to be released.


// Create XML string to command scanner ID 3 to release the trigger 
NSString *xmlInput = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID></inArgs>",scannerId];

// Command scanner ID 3 to pull the trigger
SBT_RESULT result = [apiInstance sbtExecuteCommand:SBT_DEVICE_RELEASE_TRIGGER aInXML:xmlInput aOutXML:nil forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful operation
    NSLog(@"Successfully released trigger on scanner ID %d: %@",scannerId);
}
else {
    // TODO: Process error
    NSLog(@"Failed to release trigger on scanner ID %d",scannerId);
}

AIM On

The aim on command (SBT_DEVICE_AIM_ON) is used to AIM on. The following code example demonstrates how to command the scanner's AIM function should be ON.


// Create XML string to command scanner ID 3 to AIM on 
NSString *xmlInput = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID></inArgs>",scannerId];

// Command scanner ID 3 to pull the trigger
SBT_RESULT result = [apiInstance sbtExecuteCommand:SBT_DEVICE_AIM_ON aInXML:xmlInput aOutXML:nil forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful operation
    NSLog(@"Successfully Aim ON on scanner ID %d: %@",scannerId);
}
else {
    // TODO: Process error
    NSLog(@"Failed to Aim ON on scanner ID %d",scannerId);
}

AIM Off

The aim off command (SBT_DEVICE_AIM_OFF) is used to AIM on. The following code example demonstrates how to command the scanner's trigger to be released.


// Create XML string to command scanner ID 3 to AIM off 
NSString *xmlInput = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID></inArgs>",scannerId];

// Command scanner ID 3 to pull the trigger
SBT_RESULT result = [apiInstance sbtExecuteCommand:SBT_DEVICE_AIM_OFF aInXML:xmlInput aOutXML:nil forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful operation
    NSLog(@"Successfully AIM off on scanner ID %d: %@",scannerId);
}
else {
    // TODO: Process error
    NSLog(@"Failed to AIM off on scanner ID %d",scannerId);
}

Page Motor Function

The vibration feedback command (SBT_DEVICE_VIBRATION_FEEDBACK) is used to activate the page motor. The following code example demonstrates how to command the scanner's page motor to be activated.


// Create XML string to command scanner ID 3 to activate page motor. 
NSString *xmlInput = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID></inArgs>",scannerId];

// Command scanner ID 3 to pull the page motor SBT_RESULT result = [apiInstance
sbtExecuteCommand:SBT_DEVICE_VIBRATION_FEEDBACK aInXML:xmlInput aOutXML:nil forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful operation
    NSLog(@"Successfully activated page motor scanner ID %d: %@",scannerId);
}
else {
    // TODO: Process error
    NSLog(@"Failed to activate page motor on scanner ID %d",scannerId);
}

Update Firmware with DAT File

The firmware update command (SBT_UPDATE_FIRMWARE) is used to update firmware by DAT file. The following code example demonstrates how to command the scanner to update firmware by DAT file.


// Create XML string to command scanner ID 3 to update firmware
// selectedFWFilePath = absolute path of the DAT file 
NSString *in_xml = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID><cmdArgs><arg-string>%@</arg- string></cmdArgs></inArgs>", m_ScannerID, selectedFWFilePath];

// Command scanner ID 3 to update firmware
SBT_RESULT result = [apiInstance sbtExecuteCommand:SBT_UPDATE_FIRMWARE aInXML:xmlInput aOutXML:nil forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful operation
    NSLog(@"Successfully pulled updated firmware on scanner ID %d: %@",scannerId);
}
else {
    // TODO: Process error
    NSLog(@"Failed to update firmware on scanner ID %d",scannerId);
}

Update Firmware with Plug-in File

The firmware update command (SBT_UPDATE_FIRMWARE_FROM_PLUGIN) is used to update firmware by plug-in file. The following code example demonstrates how to command the scanner to update firmware by plug-in file.


// Create XML string to command scanner ID 3 to update firmware by plugin
// selectedFWFilePath = absolute path of the plugin file 
NSString *in_xml = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID><cmdArgs><arg-string>%@</arg- string></cmdArgs></inArgs>", m_ScannerID, selectedFWFilePath];

// Command scanner ID 3 to update firmware SBT_RESULT result = [apiInstance sbtExecuteCommand:
SBT_UPDATE_FIRMWARE_FROM_PLUGIN aInXML:xmlInput aOutXML:nil forScanner:3];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful operation
    NSLog(@"Successfully updated firmware on scanner ID %d: %@",scannerId);
}
else {
    // TODO: Process error
    NSLog(@"Failed to update firmware on scanner ID %d",scannerId);
}

Abort Firmware Update

The abort firmware update command (SBT_DEVICE_ABORT_UPDATE_FIRMWARE) is used to abort ongoing firmware update.


// Create XML string to command scanner ID 3 to update abort fw update
NSString *in_xml = [NSString stringWithFormat:@"<inArgs><scannerID>%d</scannerID></inArgs>", m_ScannerID];

SBT_RESULT res = [[zt_ScannerAppEngine sharedAppEngine] executeCommand:SBT_DEVICE_ABORT_UPDATE_FIRMWARE aInXML:in_xml aOutXML:nil forScanner:m_ScannerID];

if (result == SBT_RESULT_SUCCESS) {
    // TODO: Process successful operation
    NSLog(@"Successfully aborted firmware on scanner ID %d: %@",scannerId);
}
else {
    // TODO: Process error
    NSLog(@"Failed to abort firmware on scanner ID %d",scannerId);
}