Zebra Scanner SDK for Linux Scanner SDK for Linux Developer’s Guide (en)

Download

ZEBRA SCANNER SDK FOR LINUX

DEVELOPER’S GUIDE

ZEBRA SCANNER SDK FOR LINUX

DEVELOPER’S GUIDE

MN-003028-03

Revision A

May 2019

ii ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

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.

ZEBRA and the stylized Zebra head are trademarks of Zebra Technologies Corporation, registered in many jurisdictions worldwide. All other trademarks are the property of their respective owners.

Revision History

Changes to the original guide are listed below:

Change Date Description

-01 Rev A 4/2017 Initial release.

-02 Rev A 6/2017 Moved Sample Source Code chapter to Chapter 5

-03 Rev A 6/2019 Updates:

iii

Updated Third Party Software Tools and Libraries Updated Minimum Software Requirements Added Installing CoreScanner and SDK section Updated Table 2-3 with new filenames for CoreScanner version 4.0 Added Verification Methods and Utilities (Install Verifier Application (IVA)) Updated Table 5-1 with new filenames for CoreScanner version 4.0

- OPOS changed to UPOS on pg. 1-1 and in Many Applications Connected to Many Scanner section on pg. 1-6

- Table 1-1 on pg. 1-4

- Note on pg. 2-1

- Table 2-1 on pg. 2-2

- Table 2-2 on pg. 2-3

- new CoreScanner version 4.3 on pgs. 2-3 and 2-7

- Figure 2-1 on pg. 2-4

- section title Installing CoreScanner and SDK changed to Installing and Configuring CoreScanner and SDK on pg. 2-5

- steps 5 and 6 in Installing the Source Tar Ball on pg. 2-7

- Table 2-3 on pg. 2-8

- CommandResponseEvent and IO sections removed

- Table 3-11 (Table 3-10 in previous rev.) on pg. 3-17

- Table 3-14 (Table 3-13 in previous rev.) on pg. 3-36

- OPOS/IBM OPOS mode changed to IBM mode on pg 4-15

- Quick Startup and Zebra copyright statement of the last page.

Added:

- Configuration section in Chapter 2

- BinaryDataEvent on pg. 3-14.

iv ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Revision History.............................................................................................................................. iii

About This Guide

Introduction ..................................................................................................................................... ix

Chapter Descriptions ...................................................................................................................... ix

Notational Conventions................................................................................................................... x

Service Information......................................................................................................................... x

Chapter 1: INTRODUCTION TO THE SCANNER SDK

Overview ........................................................................................................................................ 1-1

FAQs .............................................................................................................................................. 1-2

Scanner SDK Architecture ............................................................................................................. 1-3

Host Communication Modes .................................................................................................... 1-3

Multiple Scanner Device Identification and Asset Tracking ........................................................... 1-4

Application Access to Multiple Scanners ....................................................................................... 1-5

Two Applications Connected To One Scanner ........................................................................ 1-5

Three Applications Connected To Two Scanners .................................................................... 1-6

Many Applications Connected To Many Scanners .................................................................. 1-6

One Application Connected to Two Scanners ......................................................................... 1-7

Chapter 2: INSTALLATION & CONFIGURATION

Overview ........................................................................................................................................ 2-1

SDK Components .......................................................................................................................... 2-2

System Requirements .................................................................................................................... 2-2

Supported Operating Systems ................................................................................................. 2-2

Hardware Requirements .......................................................................................................... 2-3

Third Party Software Libraries ................................................................................................. 2-3

Scanner Communication Modes .................................................................................................... 2-3

CoreScanner and SDK Installers ................................................................................................... 2-3

Choosing an Installer ............................................................................................................... 2-4

RPM and Debian Installer Packages ....................................................................................... 2-4

vi ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Installing and Configuring CoreScanner and SDK ......................................................................... 2-5

Installing RPM Packages ......................................................................................................... 2-5

Installing Debian Packages ...................................................................................................... 2-6

Installing the Source Tar ball ................................................................................................... 2-7

Verifying CoreScanner and SDK Installation ........................................................................... 2-7

Installed Components .................................................................................................................... 2-8

Configuration ................................................................................................................................. 2-10

Configure Logging .................................................................................................................... 2-10

Configure Udev Options ........................................................................................................... 2-11

Configure Client Library Options .............................................................................................. 2-11

Chapter 3: SCANNER SDK API

Overview ........................................................................................................................................ 3-1

Scanner ID ..................................................................................................................................... 3-2

API Commands .............................................................................................................................. 3-3

Open ........................................................................................................................................ 3-3

Syntax ................................................................................................................................ 3-3

Parameters ........................................................................................................................ 3-3

Return Values .................................................................................................................... 3-3

GetScanners ............................................................................................................................ 3-4

Syntax ................................................................................................................................ 3-4

Parameters ........................................................................................................................ 3-4

Return Values .................................................................................................................... 3-4

ExecCommand ........................................................................................................................ 3-4

Syntax ................................................................................................................................ 3-4

Parameters ........................................................................................................................ 3-4

Return Values .................................................................................................................... 3-4

ExecCommandAsync ............................................................................................................... 3-5

Syntax ................................................................................................................................ 3-5

Parameters ........................................................................................................................ 3-5

Return Values .................................................................................................................... 3-5

Close ........................................................................................................................................ 3-5

Syntax ................................................................................................................................ 3-5

Parameters ........................................................................................................................ 3-5

Return Values .................................................................................................................... 3-5

API Events ..................................................................................................................................... 3-6

ImageEvent .............................................................................................................................. 3-6

Syntax ................................................................................................................................ 3-6

Parameters ........................................................................................................................ 3-6

VideoEvent ............................................................................................................................... 3-7

Syntax ................................................................................................................................ 3-7

Parameters ........................................................................................................................ 3-7

BarcodeEvent .......................................................................................................................... 3-8

Syntax ................................................................................................................................ 3-8

Parameters ........................................................................................................................ 3-8

PNPEvent ................................................................................................................................ 3-12

Syntax ................................................................................................................................ 3-12

Parameters ........................................................................................................................ 3-12

Samples ............................................................................................................................. 3-12

ScanRMDEvent ....................................................................................................................... 3-13

Table of Contents vii

Syntax ................................................................................................................................ 3-13

Parameters ......................................................................................................................... 3-13

ScannerNotificationEvent ......................................................................................................... 3-14

Syntax ................................................................................................................................ 3-14

Parameters ......................................................................................................................... 3-14

BinaryDataEvent ...................................................................................................................... 3-14

Syntax ................................................................................................................................ 3-14

Parameters ......................................................................................................................... 3-14

Methods Invoked Through ExecCommand or ExecCommandAsync ............................................ 3-16

Method Examples .................................................................................................................... 3-20

REGISTER_FOR_EVENTS ............................................................................................... 3-20

UNREGISTER_FOR_EVENTS .......................................................................................... 3-21

CLAIM_DEVICE ................................................................................................................. 3-21

RELEASE_DEVICE ........................................................................................................... 3-21

ABORT_MACROPDF ........................................................................................................ 3-22

ABORT_UPDATE_FIRMWARE ......................................................................................... 3-22

AIM_OFF ............................................................................................................................ 3-22

AIM_ON ............................................................................................................................. 3-23

FLUSH_MACROPDF ......................................................................................................... 3-23

DEVICE_PULL_TRIGGER ................................................................................................ 3-23

DEVICE_RELEASE_TRIGGER ......................................................................................... 3-24

SCAN_DISABLE ................................................................................................................ 3-24

SCAN_ENABLE ................................................................................................................. 3-24

REBOOT_SCANNER ........................................................................................................ 3-25

DEVICE_CAPTURE_IMAGE ............................................................................................. 3-25

DEVICE_CAPTURE_BARCODE ....................................................................................... 3-25

DEVICE_CAPTURE_VIDEO ............................................................................................. 3-26

ATTR_GETALL .................................................................................................................. 3-27

ATTR_GET ........................................................................................................................ 3-29

ATTR_GETNEXT ............................................................................................................... 3-31

ATTR_SET ......................................................................................................................... 3-32

ATTR_STORE ................................................................................................................... 3-32

GET_DEVICE_TOPOLOGY .............................................................................................. 3-33

START_NEW_FIRMWARE ............................................................................................... 3-33

UPDATE_FIRMWARE ....................................................................................................... 3-34

UPDATE_FIRMWARE_FROM_PLUGIN ........................................................................... 3-34

SET_ACTION ...................................................................................................................

DEVICE_SWITCH_HOST_MODE ..................................................................................... 3-36

Error and Status Codes ........................................................................................................... 3-37

.. 3-35

Chapter 4: TEST UTILITIES & SOURCE CODE

Overview ........................................................................................................................................ 4-1

Install Verifier Application (IVA) Utility ............................................................................................ 4-1

IVA Outcome ............................................................................................................................ 4-2

Installing the IVA ...................................................................................................................... 4-2

Executing the IVA .................................................................................................................... 4-3

Test Utilities ................................................................................................................................... 4-4

Scanner SDK C++ GTK-based Sample Application ................................................................ 4-4

Verifying Scanner SDK Functionality ............................................................................................. 4-7

Scanner Discovery / Asset Tracking / Successful SDK Installation Validation ........................ 4-7

viii ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Barcode Scanning .................................................................................................................... 4-10

Example ............................................................................................................................. 4-10

Image and Video Capture ........................................................................................................ 4-11

Beep the Beeper ...................................................................................................................... 4-14

Flash the LED .......................................................................................................................... 4-15

Attribute and Parameter Query ................................................................................................ 4-16

Querying Specific Attributes ............................................................................................... 4-18

Parameter Setting (Device Configuration) ............................................................................... 4-20

Examples ........................................................................................................................... 4-21

Host Variant Switching ............................................................................................................. 4-25

Firmware Upgrade ................................................................................................................... 4-26

Firmware Upgrade Scenarios ............................................................................................ 4-26

Firmware Upgrade Procedure ............................................................................................ 4-27

Chapter 5: SAMPLE SOURCE CODE

Overview ........................................................................................................................................ 5-1

SDK Sample Utilities ...................................................................................................................... 5-1

Developing a Console Application Using zebra-scanner-devel and Libraries ......................... 5-1

Source Code for the Console Application ...................................................................................... 5-3

Class SampleEventListener (ConsoleSampleEventListener.h) ............................................... 5-3

Class SampleEventListener Definitions/Implementation (ConsoleSampleEventListener.cpp) 5-4

Main Method Implementation ................................................................................................... 5-13

Calling Open Command ........................................................................................................... 5-15

Calling Close Command .......................................................................................................... 5-15

Calling GetScanners Command .............................................................................................. 5-15

Calling ExecCommand Command and ExecCommandAsync Command ............................... 5-16

ABOUT THIS GUIDE

Introduction

This guide provides information about the Zebra Scanner Software Developer Kit (SDK) for Linux, an architectural framework providing a single programming interface across multiple programming languages and across multiple system environments for all scanner communication variants (such as SNAPI, IBMHID, HIDKB).

Chapter Descriptions

Topics covered in this guide are as follows:

•

Chapter 1, INTRODUCTION TO THE SCANNER SDK provides an overview of the Zebra Scanner Software

Developer Kit (SDK).

•

Chapter 2, INSTALLATION & CONFIGURATION describes how to install the Zebra Scanner SDK and

components on recommended platforms.

•

Chapter 3, SCANNER SDK API provides a set of APIs to interface with scanner devices.

•

Chapter 4, TEST UTILITIES & SOURCE CODE provides information about testing and evaluating Zebra

Scanner SDK software components using SDK test utilities.

•

Chapter 5, SAMPLE SOURCE CODE provides information about how a developer uses the Zebra Scanner

SDK.

x ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Notational Conventions

The following conventions are used in this document:

•

Courier New font is used for code segments.

•

Italics are used to highlight:

• Chapters and sections in this and related documents

• Dialog box, window and screen names

• Drop-down list and list box names

• Screen field names

• Check box and radio button names

• File names

• Directory names.

•

Bold text is used to highlight:

• Parameter and option names

• Icons on a screen

• Key names on a keypad

• Button names on a screen.

•

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.

•

Notes, caution and warning statements appear as follows:

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

injury may occur.

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 will contact the Zebra Technologies Global Customer Support Center at:

www.zebra.com/support

CHAPTER 1 INTRODUCTION TO THE

SCANNER SDK

Overview

CoreScanner is the driver which prepares the scanner to be used by the host. The CoreScanner driver creates

a connection between the host and scanner. The SDK uses CoreScanner to receive data from and send

commands to the scanner.

The Zebra Scanner Software Developer Kit (SDK) for Linux defines an architectural framework providing a

single programming interface across multiple programming languages (such as C++, Java) and across

multiple system environments (such as RPM based Linux distributions and Debian based Linux) for all scanner

communication variants (such as IBMHID, SNAPI, and HIDKB).

The Zebra Scanner SDK includes a suite of components that provides a unified software development

framework with a wide range of functions for interfacing Zebra scanners to user applications and solutions.

This SDK allows you to read barcodes, manage scanner configurations, capture images/videos, and select a

list of scanners on which to work. While one application in one programming language uses a scanner or a set

of scanners, you can use another application in a different language within the same system environment.

For a list of popular topics within this guide, see Quick Startup.

Figure 1-1

The SDK can build an application with complete control of scanner capabilities:

•

Software Developer Framework

Data, barcode

• uPOS/JPOS output

• SNAPI output

1 - 2 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

•

Command and control

• LED and beeper control

• Aim control

• Scan enable and disable

•

Imaging

• Capture and transfer of images

• Capture and transfer of video

NOTE For a list of a scanner's supported attribute (parameter) numbers and definitions, refer to the scanner

Product Reference Guide, available on the Zebra Support website http://www.zebra.com/support. Attributes include configuration parameters, monitored data, and asset tracking information.

FAQs

Q: Can you connect multiple scanners to the CoreScanner Driver?

A: Yes, you can connect multiple scanners simultaneously to one host running the CoreScanner driver.

Q: If two scanners are connected, can you track data by scanner ID?

A: Yes, if scanner X decodes a barcode 123, it returns to the application a data event containing the data label 123 and the serial number as the scanner ID.

Q: Can you connect multiple applications to the CoreScanner Driver?

A: Yes, you can connect multiple applications simultaneously on one host running the CoreScanner driver. An

application can register from an event type (such as barcode, image, video or management) and receives event information plus the originating scanner ID.

Scanner SDK Architecture

INTRODUCTION TO THE SCANNER SDK 1 - 3

Figure 1-2

SDK Architecture

Host Communication Modes

You can configure Zebra scanner devices to operate in different host communication modes such as USB

SNAPI, USB OPOS, USB HID Keyboard, and USB IBM Table-top. Device feature support varies by mode but

all modes support barcode scanning. Refer to the scanner Product Reference Guide to set the host

communication mode.

To use the Zebra Scanner SDK to switch between supported host communication modes, useful when

advanced functionality is required but not supported by the current communication mode, call the Host Variant

Switching command. This switches the scanner to a feature-rich mode to execute certain commands, and then

reverts the scanner to the previous mode.

For example, to disable the UPC-A symbology when the device is in USB HID Keyboard mode, switch the

scanner to USB SNAPI or USB OPOS (if supported by the scanner), disable UPC-A, and then revert the

scanner to USB HID Keyboard mode.

1 - 4 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Table 1-1 illustrates scanner capabilities supported in each communication mode. Refer to the scanner

specifications for support of each communication mode.

Table 1-1

Data Supported Supported Supported

Host Variant Switching Supported Supported Supported

Management Supported Not Available Supported

Image & Video Supported Not Available Not Available

Scanner Device Communication Modes Vs. Capabilities

Capabilities USB SNAPI

USB HID

Keyboard

Multiple Scanner Device Identification and Asset Tracking

The Zebra Scanner SDK supports connecting multiple scanners to any user application running on CoreScanner APIs. The application identifies each scanner by a unique scanner identification number. There cannot be multiple scanners with the same scanner ID.

Asset tracking information such as model number, serial number, firmware version, and date of manufacture is available if the scanner and its current host mode support the management feature. For example, asset tracking information does not appear for a scanner in USB HID Keyboard mode, but does appear if that scanner is in USB OPOS or USB SNAPI mode.

USB IBM Table-top

The format of device asset tracking information can vary between device models. For example, the length of a serial number for DS6707 and DS9808 scanners can be different.

Application Access to Multiple Scanners

The Zebra Scanner SDK supports multiple applications accessing multiple scanners connected to the host at

the same time.

The scanner ID uniquely identifies a connected scanner to all applications, and is consistent among all

applications for one SDK instance. Restarting the CoreScanner service or the host may assign a different

scanner ID to a scanner, but it is unique and referenced by all applications.

Two Applications Connected To One Scanner

App 1 & App 2 support bi-directional (two way) communication with the scanner.

INTRODUCTION TO THE SCANNER SDK 1 - 5

Figure 1-3

Two Applications Connected To One Scanner

1 - 6 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Three Applications Connected To Two Scanners

App 1 and App 2 support bi-directional (two way) communication with the DS6878.

Figure 1-4

Three Applications Connected To Two Scanners

Many Applications Connected To Many Scanners

App 1 performs image capture with the DS6878.

App 2 remotely manages both the DS6878 and LS4208.

App 3 receives JPOS data from both the DS6878 and LS4208.

Figure 1-5

Many Applications Connected To Many Scanners

INTRODUCTION TO THE SCANNER SDK 1 - 7

One Application Connected to Two Scanners

One application can manage multiple scanners in multiple communication interfaces. The application can

capture data, image, and video, send management commands, and receive responses from multiple scanners.

All scanner responses consist of details (ScannerID, serial number, model number, etc.) identifying the

scanner that sent the response.

Figure 1-6

One Application Connected to Two Scanners

The following example shows a barcode event for a scanned label. The label data contains a unique

ScannerID and the scanner's model number and serial number.

<?xml version="1.0" encoding="UTF-8"?>

<arg-xml>

</scandata>

</arg-xml>

</outArgs>

1 - 8 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

CHAPTER 2 INSTALLATION &

CONFIGURATION

Overview

This chapter describes how to install the Zebra Scanner SDK and components on recommended platforms.

NOTE See System Requirements on page 2-2 for supported platforms.

The SDK installation package includes:

•

Components that enable any Zebra scanner to communicate with applications or tools that execute on top of the Zebra Scanner SDK.

•

Supporting documents.

•

Test utilities.

•

Sample applications and source projects.

NOTE Uninstall any previous Zebra, Symbol, or drivers or SDKs which communicate with Zebra scanners before

installing the Zebra Scanner SDK. This includes but is not limited to Zebra and Symbol supplied JPOS driver.

For a list of popular topics within this guide, see Quick Startup.

NOTE For a list of a scanner's supported attribute (parameter) numbers and definitions, refer to the scanner

Product Reference Guide, available on the Zebra Support website http://www.zebra.com/support. Attributes include configuration parameters, monitored data, and asset tracking information.

2 - 2 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

SDK Components

The SDK installation package installs the following SDK components to the default locations in Table 2-3 on

page 2-8:

•

Zebra Scanner SDK core components and drivers (USB API (libudev and libusb), imaging drivers)

•

JPOS drivers (scanner and scale)

•

Link to the latest developer's guide

•

Test and sample utilities with source code packages:

• Scanner SDK GTK Sample Application (C++)

• Scanner SDK Console Application (C++)

• JPOS Test Utility for Scanner and Scale

System Requirements

Supported Operating Systems

Table 2-1

Distribution Version and Architecture

Ubuntu 12.04 (64bit and 32bit)

Debian

Suse Linux Enterprise Server 11 SP1 (64bit and 32bit)

RedHat

CentOS 6.3 (64bit and 32bit)

Supported Operating Systems

14.04 (64bit and 32bit)

16.04 (64bit and 32bit)

7 (64bit and 32bit) 8 (64bit and 32bit)

11 SP2 (64bit and 32bit) 11 SP3 (64bit and 32bit) 12 (64bit) 12 SP2 (64bit)

6.3 (64bit and 32bit)

7.4 (64bit)

7 (64bit)

OpenSuse 13.1 (32bit)

INSTALLATION & CONFIGURATION 2 - 3

Hardware Requirements

Minimum hardware requirements for the Zebra scanner driver and SDK depend on the minimum system

requirement for the Linux distribution installation. The following requirements are provided as a guideline.

•

Processor: Pentium* 4 1.6 GHz or higher (Pentium 4 2.4 GHz or higher or any AMD64 or Intel64 processor recommended)

•

Main memory: 1 GB physical RAM (2 GB recommended)

•

Hard disk: 10 GB available disk space for a minimal install, 25 GB available for a graphical desktop (more recommended)

Third Party Software Libraries

Table 2-2

Libudev 147 or above

GTK (for GUI applications) 2.24.10

Java 6 (JDK 1.6)

Minimum Software Requirements for CoreScanner Installation

Library Version Limitation

Scanner Communication Modes

Refer to the scanner's Product Reference Guide for supported communication modes, and specifically the

appendix Functionality Supported via Communication (Cable) Inte rface for supported scanner functionality by

communication protocol.

CoreScanner and SDK Installers

The CoreScanner Version 4.3 SDK and later offer three types of installers to accommodate many different

Linux distributions:

•

RPM package-based installers - Installable only on RPM-based Linux distributions

•

Debian package-based installers - Installable only on Debian-based Linux distributions

•

Source tarball based installers - Installable on any Linux distribution. You are prompted to install all required dependent packages when configuring the source tarball extraction for installation.

2 - 4 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Figure 2-1 lists supported distributions for the various installation options.

Figure 2-1

Supported Distributions

Choosing an Installer

There are many different Linux bases/trees available. Perform the appropriate research or contact Zebra support to determine the base tree of your distribution. Select the CoreScanner and SDK installer based on the following categories:

•

RPM-based packages (.rpm) for the following distributions:

• CentOS

• Suse (Open Suse, Suse Linux Enterprise Server, etc.)

• Opensus

• Red Hat

• Fedora

•

Debian-based packages (.dpkg) for the following distributions:

• Debian

• Ubuntu

•

Source tar ball based installer for other Linux distributions such as Gentoo.

NOTE RPM and Debian are package managers supported for the Linux distributions above. Each package

manager provides a shell command (rpm or dpkg) for installing/removing packages in a Linux distribution.

RPM and Debian Installer Packages

RPM and Debian installers provide three packages for installing different components:

•

zebra-scanner-corescanner - The core package of CoreScanner which includes the CoreScanner

daemon and libraries. This package places files into the standard file installation locations of Linux systems (in this case /usr/share/zebra-scanner/etc.) Install this package before installing the JavaPOS and Corescanner API development packages, as it is required for both.

•

zebra-scanner-javapos - Part of the CoreScanner-SDK, this includes all JPOS libraries, sample

applications, scripts, and C++ libraries for JNI. The zebra-scanner-corescanner package is required for JPOS package development and implementation.

INSTALLATION & CONFIGURATION 2 - 5

•

zebra-scanner-devel - This provides the application programming interface exposed from CoreScanner,

and contains header files required to develop C/C++ applications for CoreScanner and source files for simple console based sample applications. The zebra-scanner-corescanner package is required for this API development package.

Installing and Configuring CoreScanner and SDK

This section describes how to install each CoreScanner and SDK package after selecting the suitable installer

for the Linux distribution.

Installing RPM Packages

1. Check for existing CoreScanner and SDK installations using the rpm command -qa option:

rpm -qa | grep zebra

For example, list packages installed in a CentOS/Suse RPM based distribution:

[root@localhost]# rpm -qa | grep zebra

zebra-scanner-devel-3.0.0-0

zebra-scanner-javapos-3.0.0-0

zebra-scanner-corescanner-3.0.0-0

2. Remove existing CoreScanner and SDK packages using the rpm command -e option. Since the

zebra-scanner-corescanner package is required for JPOS and API development packages, remove this after uninstalling the other two packages.

For example:

# rpm -e zebra-scanner-javapos-2.0.0-0

# rpm -e zebra-scanner-devel-2.0.0-0

# rpm -e zebra-scanner-corescanner-2.0.0-0

3. Install new packages using the rpm command -i option. Install the CoreScanner packages first to avoid

possible package dependency issues.

For example:

# rpm -i zebra-scanner-corescanner-2.0.0-0-sles11_sp2-i586.rpm

# rpm -i zebra-scanner-devel-2.0.0-0-sles11_sp2-i586.rpm

# rpm -i zebra-scanner-javapos-2.0.0-0-sles11_sp2-i586.rpm

2 - 6 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Installing Debian Packages

1. Check for existing CoreScanner and SDK installations using the dpkg command -l option:

dpkg -l | grep zebra

For example, list packages installed in a Ubuntu distribution:

ii zebra-scanner-corescanner 2.0.0-0 amd64 Zebra Technologies Linux Corescanner Daemon

ii zebra-scanner-devel 2.0.0-0 amd64 Development files for Zebra Technologies Linux

Corescanner

ii zebra-scanner-javapos 2.0.0-0 amd64 Jpos 1.13 drivers for Zebra Technologies Linux

Corescanner Daemon

2. Remove existing CoreScanner and SDK packages using the dpkg command -r option. Since the

zebra-scanner-corescanner package is required for JavaPOS and API development packages, remove

this after uninstalling the other two packages.

For example:

# dpkg -r zebra-scanner-javapos

(Reading database ... 219367 files and directories currently installed.)

Removing zebra-scanner-javapos (2.0.0-0) ...

# dpkg -r zebra-scanner-devel

(Reading database ... 219343 files and directories currently installed.)

Removing zebra-scanner-devel (2.0.0-0) ...

# dpkg -r zebra-scanner-corescanner

(Reading database ... 219328 files and directories currently installed.)

Removing zebra-scanner-corescanner (2.0.0-0) ...

update-rc.d: /etc/init.d/cscored exists during rc.d purge (use -f to force)

Processing triggers for libc-bin (2.19-0ubuntu6.4) ...

3. Install new packages using the dpkg -i option. Install the CoreScanner package first to avoid possible

package dependancy issues.

For example:

# dpkg -i zebra-scanner-corescanner_2.0.0-0_ubuntu-14.04_amd64.deb

Sample output:

Selecting previously unselected package zebra-scanner-corescanner. (Reading database ... 219288 files and directories currently installed.) Preparing to unpack zebra-scanner-corescanner_2.0.0-0_ubuntu-14.04_amd64.deb ... Unpacking zebra-scanner-corescanner (2.0.0-0) ... Setting up zebra-scanner-corescanner (2.0.0-0) ... Adding system startup for /etc/init.d/cscored ... /etc/rc0.d/K20cscored -> ../init.d/cscored /etc/rc1.d/K20cscored -> ../init.d/cscored /etc/rc6.d/K20cscored -> ../init.d/cscored /etc/rc2.d/S20cscored -> ../init.d/cscored /etc/rc3.d/S20cscored -> ../init.d/cscored /etc/rc4.d/S20cscored -> ../init.d/cscored /etc/rc5.d/S20cscored -> ../init.d/cscored Processing triggers for ureadahead (0.100.0-16) ...

Processing triggers for libc-bin (2.19-0ubuntu6.4) ... # dpkg -i zebra-scanner-devel_2.0.0-0_ubuntu-14.04_amd64.deb

Sample output:

Selecting previously unselected package zebra-scanner-devel. (Reading database ... 219320 files and directories currently installed.) Preparing to unpack zebra-scanner-devel_2.0.0-0_ubuntu-14.04_amd64.deb ... Unpacking zebra-scanner-devel (2.0.0-0) ... Setting up zebra-scanner-devel (2.0.0-0) ... # dpkg -i zebra-scanner-javapos_2.0.0-0_ubuntu-14.04_amd64.deb

Sample output:

Selecting previously unselected package zebra-scanner-javapos. (Reading database ... 219335 files and directories currently installed.) Preparing to unpack zebra-scanner-javapos_2.0.0-0_ubuntu-14.04_amd64.deb ... Unpacking zebra-scanner-javapos (2.0.0-0) ... Setting up zebra-scanner-javapos (2.0.0-0) ...

Processing triggers for libc-bin (2.19-0ubuntu6.4) ....

Installing the Source Tar ball

INSTALLATION & CONFIGURATION 2 - 7

1. Download zebra-scanner-4.0.0.tar.gz to the home directory. This source tarball contains a script file to

install CoreScanner and SDK on the Linux system.

2. Extract the zebra-scanner-4.0.0.tar.gz file, which creates the zebra-scanner-4.0.0 directory.

$> tar -xvf zebra-scanner-4.0.0.tar.gz

3. Change directory to the zebra-scanner-4.0.0 folder.

4. Change the user to a super user using sudo/su commands. A super user password is required.

5. Configure CoreScanner for the Linux distribution, specifying the destination directory as the root directory

using the destdir option.

$> configure --destdir =/

6. Use the “make” build command to build the CoreScanner and SDK for the system. “make” searches for all

dependent third-party libraries, and displays errors and aborts the build if it can’t find a dependent package in the environment. Restart installation by installing these packages.

$> make

7. Use "make install" to install CoreScanner and SDK components.

$> make install

8. Use "make uninstall" to remove an existing source tarball installation from the system.

$> make uninstall

Verifying CoreScanner and SDK Installation

CoreScanner version 4.3 and later include the Install Verify Application, which verifies the status of the

CoreScanner installation and execution. See Install Verifier Application (IVA) Utility on page 4-1.

2 - 8 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Installed Components

CoreScanner daemon service (cscore) is installed with the zebra-scanner-corescanner package. This coordinates activity between the communication layer (SNAPI, IBMHH, IBMTT, etc.) and upper level drivers (JPOS, SDK API, etc.).

Table 2-3 lists the components installed.

Table 2-3

CoreScanner cscore Scanner Driver

CoreScanner libcs-iudev.so Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcs-iudev.so.4.0.0 Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcscl-hidkb.so Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcscl-hidkb.so.4.0.0 Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcscl-ibmhh.so Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcscl-ibmhh.so.4.0.0 Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcscl-ibmtt.so Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcscl-ibmtt.so.4.0.0 Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcscl-snapi.so Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcscl-snapi.so.4.0.0 Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcs-client.so Transport Component /usr/lib/zebra-scanner/corescanner

Zebra Scanner SDK Components

Component File Description Installation Path

/usr/bin/

Daemon Service

CoreScanner libcs-client.so.4.0.0 Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcs-common.so Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcs-common.so.4.0.0 Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcs-comm.so Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcs-comm.so.4.0.0 Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcs-clientscanner.so Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcs-clientscanner.so.

4.0.0

CoreScanner libcs-clientscale.so Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner libcs-clientscale.so.4.0.0 Transport Component /usr/lib/zebra-scanner/corescanner

CoreScanner-JNI libcs-jniscanner.so.4.0.0 JPOS-JNI

CoreScanner-JNI libcs-jniscanner.so JPOS-JNI

Transport Component /usr/lib/zebra-scanner/corescanner

/usr/lib/zebra-scanner/javapos/jni

Component

/usr/lib/zebra-scanner/javapos/jni

Component

INSTALLATION & CONFIGURATION 2 - 9

Table 2-3

CoreScanner-JNI libcs-jniscale.so.4.0.0 JPOS-JNI

CoreScanner-JNI libcs-jniscale.so JPOS-JNI

JPOS jpostest.sh Start Script for JPOS

JPOS dio.sh Start Script for JPOS

JPOS xml-apis.jar Third party Java

JPOS xercesImpl.jar Third party Java

JPOS JposTest.jar JPOS sample

JPOS JposTestDio.jar JPOS direct I/O

Zebra Scanner SDK Components (Continued)

Component File Description Installation Path

/usr/lib/zebra-scanner/javapos/jni

Component

/usr/lib/zebra-scanner/javapos/jni

Component

/usr/lib/zebra-scanner/javapos/jpos

Test Application

/usr/lib/zebra-scanner/javapos/jpos Direct IO Test Application

/usr/lib/zebra-scanner/javapos/jpos library used for JPOS

/usr/share/zebra-scanner/samples/ application

sample application

jpos-sample-app

/usr/share/zebra-scanner/samples/

jpos-directio-app

JPOS JposServiceScanner.jar JPOS Library /usr/lib/zebra-scanner/javapos

JPOS JposServiceScale.jar JPOS Library /usr/lib/zebra-scanner/javapos

JPOS JposServiceOnScanner.jar JPOS Library /usr/lib/zebra-scanner/javapos

JPOS JposServiceOnScale.jar JPOS Library /usr/lib/zebra-scanner/javapos

JPOS JposServiceJniScanner.jar JPOS Library /usr/lib/zebra-scanner/javapos

JPOS JposServiceJniScale.jar JPOS Library /usr/lib/zebra-scanner/javapos

JPOS jpos113.jar JPOS Library /usr/lib/zebra-scanner/javapos

Console Application

Makefile Local Make File for

Console Application

ConsoleApplication Execute File of

Console Application

ConsoleSampleEvent Listener.h

ConsoleMain.h Console Application

ConsoleSampleEvent Listener.cpp

Console Application Source File

Source File

Console Application Source File

/usr/share/zebra-scanner/samples/

console-app

/usr/share/zebra-scanner/samples/

console-app

/usr/share/zebra-scanner/samples/

console-app

/usr/share/zebra-scanner/samples/

console-app

/usr/share/zebra-scanner/samples/

console-app

Console Application

ConsoleMain.cpp Console Application

Source File

/usr/share/zebra-scanner/samples/

console-app

2 - 10 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Table 2-3

Configuration corescanner-sdk.conf Configurations for

Init Script cscored Systemv Init Script /etc/init.d/

CoreScanner CsBarcodeTypes.h Header files required

CoreScanner CsUserDefs.h Header files required

CoreScanner CsIEventListenerXml.h Header files required

CoreScanner Cslibcorescanner_xml.h Header files required

Zebra Scanner SDK Components (Continued)

Component File Description Installation Path

/etc/zebra-scanner CoreScanner and client libraries

/usr/include/zebra-scanner for application development on top of CoreScanner

Configuration

To configure logging, udev options and client library options for CoreScanner and SDK, use the

corescanner-sdk.conf file located in the directory /etc/zebra-scanner. See Configure Logging, Configure Udev

Options and Configure Client Library Options for configuration.

Configure Logging

<enable>1</enable> <level>5</level> <dir>/var/log/zebra-scanner/corescannerd/</dir> <max_lines_for_a_file>20000</max_lines_for_a_file> <max_number_of_files>200</max_number_of_files>

</logging>

•

• 1 - Enable logging

• 0 - Disable logging

•

<level>

• Desiderd level of logging ranges from 1 to 5. Default value is 5. NOTE: All log entries will be in level 5 now.

•

< dir >

• Pre-existing location for log creation. The default location is /var/log/zebra-scanner/corescannerd.

•

<max_lines_for_a_file>

• Maximum number of log entries for single log file. Any positive value is valid for this entry.

•

<max_number_of_files>

• Maximum number of log files ranges from 1 to 999. Oldest file will be replaced by a new file once the limit reaches.

Configure Udev Options

<udev-options>

<libudev_library_dir></libudev_library_dir>

</udev-options>

•

<libudev_library_dir>

• Custom udev library path

INSTALLATION & CONFIGURATION 2 - 11

Configure Client Library Options

<client-library>

<binary_data_event>1</binary_data_event>

</client-library>

•

<binary_data_event>

• 1 - Enable Binary Data Event; IDC data to be received in ISO1543 format

• 0 - Disable Binary Data Event; IDC data to be received in separate image and barcode events

2 - 12 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

CHAPTER 3 SCANNER SDK API

Overview

The Zebra Scanner SDK provides an easy to use and powerful set of API commands to interface with scanners. Commands include:

•

Open

•

GetScanners

•

ExecCommand

•

ExecCommandAsync

•

Close.

Once you invoke the Open and GetScanners commands and retrieve the list of connected scanners, all other methods execute using the ExecCommand and ExecCommandAsync commands. This user friendly approach

facilitates coding.

As SDK capabilities grow, the number of methods increases rather than the number of API commands. Once the system is up and running, a new method is just an additional operation to the existing code.

The Zebra Scanner SDK supports seven types of events:

•

ImageEvent

•

VideoEvent

•

BarcodeEvent

•

PNPEvent

•

ScanRMDEvent

•

CommandResponseEvent

•

IOEvent

See Chapter 5, SAMPLE SOURCE CODE for an example of an application illustrating the Zebra Scanner SDK

API.

NOTE For a list of a scanner's supported attribute (parameter) numbers and definitions, refer to the scanner

Product Reference Guide, available on the Zebra Support website: http://www.zebra.com/support. Attributes include configuration parameters, monitored data, and asset tracking information.

3 - 2 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Scanner ID

The scanner ID uniquely identifies a scanner connected to the CoreScanner driver, and is required to

communicate with the device. Developers call the GetScanners method to retrieve the scanner IDs of

connected devices. For example, to switch on a scanner’s red LED, obtain the scanner ID of that scanner and

provide this value in the <scannerID> element of inXML in the ExecCommand method call.

Each CoreScanner driver instance assigns scanner IDs sequentially to each connected device. Restarting the CoreScanner service re-initializes the array of connected scanners, and previous scanner IDs may no longer

be valid. In this case, execute the GetScanners method to obtain the new scanner IDs.

During a single CoreScanner driver instance, a Remote Scanner Management (RSM)-supported scanner that is disconnected and reconnected retains its unique scanner ID, while non-RSM device is assigned a different scanner ID each time it is reconnected.

API Commands

Open

Opens an application instance from the user application or user library. This must be the first API command called before invoking any other API command from the user level application.

Syntax

unsigned short Open(

/* [in] */ IEventListenerXml* pEventListener, /* [in] */ unsigned int scannerTypeFlags, /* [out]*/ StatusID *status);

Parameters

•

pEventListener - Input argument of IEventListener class type object reference.

•

scannerTypeFlags - The types of scanners requested for use with the API. Use "|" to specify multiple

types.

SCANNER SDK API 3 - 3

Table 3-1

SCANNER_TYPES_ALL 0 All Scanners

SCANNER_TYPES_SNAPI 1 SNAPI Scanners

SCANNER_TYPES_IBMHID 2 IBM Hand-held Scanners

SCANNER_TYPES_IBMTT 4 IBM Table-top Scanners

SCANNER_TYPES_HIDKB 8 USB HID Keyboard scanners

Values for scannerTypeFlags

Code Value Scanner Category

Return Values

0 - Success.

Any other value. See Error and Status Codes on page 3-37.

3 - 4 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

GetScanners

Gets a list of connected scanners of the requested types. Invoke this command after the Open command.

Syntax

unsigned short GetScanners(

/* [out] */ unsigned short *numberOfScanners, /* [out][in] */ std::vector<unsigned int> *scannerIDList, /* [out] */ std::string& outXML, /* [out] */ StatusID *status);

Parameters

•

numberOfScanners - Number of connected scanners of requested type(s).

•

sfScannerIDList - Vector/Array of scannerIDs of the requested type(s). The size of the array is 255

(MAX_NUM_DEVICES).

•

outXML - XML string scanner meta information. See Chapter 4, TEST UTILITIES & SOURCE CODE for

examples.

•

status - Return value for the command.

Return Values

0 - Success.

Any other value. See Error and Status Codes on page 3-37.

ExecCommand

Provides synchronous execution of a method via an opcode.

Syntax

unsigned short ExecCommand( /* [in] */ unsigned int opcode, /* [in] */const std::string inXML, /* [out] */ std::string& outXML, /* [out] */ StatusID *status);

Parameters

•

opcode - Method to execute. See Table 3-11 on page 3-16 for opcodes.

•

inXML - Relevant argument list for the opcode, structured into an XML string.

•

outXML - XML string, scanner meta information.

•

status - Return value for the command.

Return Values

0 - Success.

Any other value. See Error and Status Codes on page 3-37.

SCANNER SDK API 3 - 5

ExecCommandAsync

Provides asynchronous execution of a method via an opcode. Any response data is retrieved as a

ScannerNotificationEvent.

Syntax

unsigned short ExecCommandAsync(

/* [in] */ unsigned int opcode, /* [in] */ const std::string inXML, /* [out] */ StatusID *status);

Parameters

•

opcode - Method to execute. See Table 3-11 on page 3-16 for opcodes.

•

inXML - Relevant argument list for the opcode, structured into an XML string.

•

status - Return value for the command.

Return Values

0 - Success.

Any other value. See Error and Status Codes on page 3-37.

Close

Closes the application instance through the CoreScanner service.

Syntax

unsigned short Close(

/* [in] */ unsigned int appHandle, /* [out] */ StatusID *status);

Parameters

•

appHandle - Reserved argument. Set to 0.

•

status - Return value for the command.

Return Values

0 - Success.

Any other value. See Error and Status Codes on page 3-37.

3 - 6 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

API Events

The user application must register for each event category separately to receive events for that category. Use

the methods REGISTER_FOR_EVENTS and UNREGISTER_FOR_EVENTS. See Table 3-11 on page 3-16.

ImageEvent

Triggered when an imaging scanner captures images in image mode. To receive ImageEvents, an application

must execute the REGISTER_FOR_EVENTS method with the SUBSCRIBE_IMAGE event type.

Syntax

void OnImageEvent( short eventType,

int size, short imageFormat, char* sfimageData, int dataLength, std::string& pScannerData )

Parameters

•

eventType - Type of image event received. See Table 3-2.

Table 3-2

Image Event Types

Event Type Value Description

IMAGE_COMPLETE 1 A complete image is captured

IMAGE_TRAN_STATUS 2 Image error or status

•

size - Size of image data buffer.

•

dataLength - Length of image data buffer.

•

imageFormat - Format of image. See Table 3-3.

Table 3-3

Image Formats

Image Type Value

BMP_FILE_SELECTION 3

TIFF_FILE_SELECTION 4

JPEG_FILE_SELECTION 1

•

sfimageData - Image data buffer.

•

pScannerData - Information in XML format about the scanner (ID, Model Number, Serial Number, and

GUID) that triggered the image event.

<?xml version="1.0" encoding="UTF-8"?> <outArgs>

</arg-xml>

</outArgs>

SCANNER SDK API 3 - 7

VideoEvent

Triggered when an imaging scanner captures video in video mode. To receive VideoEvents, an application

must execute the REGISTER_FOR_EVENTS method with the SUBSCRIBE_VIDEO event type.

Syntax

void OnVideoEvent( short eventType,

int size, char* sfvideoData, int dataLength, std::string& pScannerData )

Parameters

•

eventType - Type of video event received. See Table 3-4.

Table 3-4

VIDEO_FRAME_COMPLETE 1

•

Video Event Types

Event Type Value Description

A complete video frame is captured.

size - Size of video data buffer. sfvideoData - Video data buffer. dataLength - Length of video data buffer. pScannerData - Reserved parameter. Always returns an empty string.

3 - 8 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

BarcodeEvent

Triggered when a scanner captures barcodes. To receive BarcodeEvents, an application must execute the

REGISTER_FOR_EVENTS method with the SUBSCRIBE_BARCODE event type.

Syntax

void OnBarcodeEvent(short int eventType,

std::string & pscanData);

Parameters

•

eventType - Type of barcode event received. See Table 3-5.

Table 3-5

Barcode Event Types

Event Type Value Description

SCANNER_DECODE_GOOD

•

pscanData - Barcode string that contains information about the scanner that triggered the barcode event

A decode is successful.

including data type, data label, and raw data of the scanned barcode.

<?xml version="1.0" encoding="UTF-8"?> <outArgs>

</scandata>

</arg-xml>

</outArgs>

<datatype> indicates the barcode type of the scanned barcode.

Table 3-6 lists the values received in SNAPI and IBM Hand-held USB communication protocols for each

supported barcode type.

Table 3-6

Barcode Data Types

Communication Protocol

Barcode Data Type

SNAPI IBM Hand-held

Code 39 1 1

Codabar 2 2

Code 128 3 3

Discrete (Standard) 2 of 5 4 4

IATA 5N/A

N/A indicates that the communication protocol does not support that barcode data type. The SDK typically returns a value of 0 for these data types, but in some cases may identify these as a related data type. For example, Nixdorf Mode B does not support UPC-A + 2 Supplemental but the SDK identifies it as UPC-A.

SCANNER SDK API 3 - 9

Table 3-6

Interleaved 2 of 5 6 6

Code 93 7 7

UPC-A 88

UPC-E0 99

EAN-8 10 10

EAN-13 11 11

Code 11 12 N/A

Code 49 13 13

MSI 14 N/A

EAN-128 15 15

UPC-E1 16 N/A

PDF-417 17 17

Barcode Data Types (Continued)

Barcode Data Type

Communication Protocol

SNAPI IBM Hand-held

Code 16K 18 N/A

Code 39 Full ASCII 19 N/A

UPC-D 20 N/A

Code 39 Trioptic 21 N/A

Bookland 22 N/A

Coupon Code 23 N/A

NW-7 24 N/A

ISBT-128 25 N/A

Micro PDF 26 N/A

DataMatrix 27 27

QR Code 28 28

Micro PDF CCA 29 N/A

PostNet US 30 N/A

Planet Code 31 N/A

Code 32 32 N/A

ISBT-128 Con 33 N/A

3 - 10 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Table 3-6

Japan Postal 34 N/A

Australian Postal 35 N/A

Dutch Postal 36 N/A

MaxiCode 37 37

Canadian Postal 38 N/A

UK Postal 39 N/A

Macro PDF 40 N/A

Micro QR code 44 44

Aztec 45 45

GS1 Databar (RSS-14) 48 48

RSS Limited 49 49

GS1 Databar Expanded (RSS Expanded) 50 50

Barcode Data Types (Continued)

Barcode Data Type

Communication Protocol

SNAPI IBM Hand-held

Scanlet 55 N/A

UPC-A + 2 Supplemental 72 72

UPC-E0 + 2 Supplemental 73 73

EAN-8 + 2 Supplemental 74 74

EAN-13 + 2 Supplemental 75 75

UPC-E1 + 2 Supplemental 80 N/A

CCA EAN-128 81 N/A

CCA EAN-13 82 N/A

CCA EAN-8 83 N/A

CCA RSS Expanded 84 N/A

CCA RSS Limited 85 N/A

CCA RSS-14 86 N/A

CCA UPC-A 87 N/A

CCA UPC-E 88 N/A

CCC EAN-128 89 N/A

TLC-39 90 N/A

SCANNER SDK API 3 - 11

Table 3-6

CCB EAN-128 97 N/A

CCB EAN-13 98 N/A

CCB EAN-8 99 N/A

CCB RSS Expanded 100 N/A

CCB RSS Limited 101 N/A

CCB RSS-14 102 N/A

CCB UPC-A 103 N/A

CCB UPC-E 104 N/A

Signature Capture 105 N/A

Matrix 2 of 5 113 N/A

Chinese 2 of 5 114 N/A

UPC-A + 5 Supplemental 136 136

Barcode Data Types (Continued)

Barcode Data Type

Communication Protocol

SNAPI IBM Hand-held

UPC-E0 + 5 Supplemental 137 137

EAN-8 + 5 Supplemental 138 138

EAN-13 + 5 Supplemental 139 139

UPC-E1 + 5 Supplemental 144 N/A

Macro Micro PDF 154 N/A

3 - 12 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

PNPEvent

Triggered when a scanner of a requested type attaches to or detaches from the system. Pairing a Bluetooth scanner to a cradle does not trigger a PnP event. To receive information about a newly paired device, call the

GetScanners command again.

To receive PnPEvents, an application must execute the REGISTER_FOR_EVENTS method with the

SUBSCRIBE_PNP event type.

Syntax

void OnPNPEvent( short eventType, std::string ppnpData )

Parameters

•

eventType - Type of PnP event received. See Table 3-7.

Table 3-7

PnP Event Types

Event Type Value Description

SCANNER_ATTACHED

SCANNER_DETACHED

•

ppnpData - PnP information string containing the asset tracking information of the attached or detached

A Zebra scanner is attached.

A Zebra scanner is detached.

device.

Samples

Sample ppnpData XML for attachment of a direct scanner:

<?xml version="1.0" encoding="UTF-8"?> <outArgs>

<arg-xml> <scanners> <scanner type="SNAPI"> <scannerID>1</scannerID> <modelnumber>DS9808-SR00007C1WR</modelnumber> <serialnumber>1026300507698 </serialnumber> <GUID>77E48FC31C75444B90BE318FECFAE867</GUID> </scanner> </scanners> <status>1</status> </arg-xml>

</outArgs>

SCANNER SDK API 3 - 13

<?xml version="1.0" encoding="UTF-8"?> <outArgs>

<arg-xml> <scanners> <scanner type="USBIBMHID"> <scannerID>1</scannerID> <modelnumber>CR0078-SC10007WR </modelnumber> <serialnumber>1020800512980 </serialnumber> <GUID>3665579766A9514DAAF523D35E051674</GUID> <pnp>0</pnp> <scanner type="USBIBMHID"> <scannerID>2</scannerID> <modelnumber>DS6878-SR20007WR </modelnumber> <serialnumber>M1M87R38Y </serialnumber> <GUID></

GUID> <pnp>1</pnp> </scanner> </scanner> </scanners> <status>1</status> </arg-xml>

</outArgs>

Information about Bluetooth Cradle

Information about Bluetooth Scanner

Sample ppnpData XML for attachment of a cascaded scanner. This XML can be received as a PnP event after

a GetScanners command if there are devices newly paired to a Bluetooth cradle.

ScanRMDEvent

Receives RMD events when updating scanner firmware. To receive RMD events, an application must execute

the REGISTER_FOR_EVENTS method with the SUBSCRIBE_RMD event type.

Syntax

void OnScanRMDEvent ( short eventType, std::string & pscanData)

Parameters

•

eventType - Type of RMD event received. See Table 3-8.

Table 3-8

SCANNER_UF_SESS_START 11 Flash download session started.

SCANNER_UF_DL_START 12 Component download started.

SCANNER_UF_DL_PROGRESS 13 Block(s) of flash completed.

SCANNER_UF_DL_END 14 Component download ended.

SCANNER_UF_SESS_END 15 Flash download session ended.

SCANNER_UF_STATUS 16 Updated error or status.

•

RMD Event Types

Event Type Value Description

prmdData - ScanRMD information string containing the event data. See Firmware Upgrade Scenarios on

page 4-26 for more information.

3 - 14 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

ScannerNotificationEvent

Received when a SNAPI scanner changes operational mode. To receive ScannerNotificationEvents, an

application must execute the REGISTER_FOR_EVENTS method with the SUBSCRIBE_OTHER event type.

Syntax

void OnScannerNotification ( short notificationType,

std::string & pScannerData);

Parameters

•

notificationType - Type of the notification event received. See Table 3-9.

Table 3-9

DECODE_MODE 1 Triggered when a scanner changes its operation mode to

SNAPSHOT_MODE 2 Triggered when a scanner changes its operation mode to

VIDEO_MODE 3 Triggered when a scanner changes its operation mode to

•

Notification Event Types

Notification Type Value Description

decode.

image mode.

video mode.

pScannerData - Information about the scanner (ID, Model Number, Serial Number and GUID) that

triggered the notification event.

BinaryDataEvent

Triggered when an IDC-supported imaging scanner captures an image in Intelligent Document Capture (IDC).

To receive a BinaryDataEvent, an application must execute the REGISTER_FOR_EVENTS method with the SUBSCRIBE_IMAGE event type. See Configure Client Library Options on page 2-11 for more information.

Syntax

void OnBinaryDataEvent( short eventType, int size, short dataFormat, unsigned char* sfBinaryData, std::string& pScannerData);

Parameters

•

eventType - Reserved

•

size - Size of binary data buffer

•

dataFormat - The format of the BinaryDataEvent

Table 3-10

0xB5 IDC format

•

Binary data Formats

Data format

sfBinaryData - Binary data buffer. pScannerData - Information in XML format about the scanner (ID, Model Number, Serial Number, and

GUID) that triggered the Binary data event.

Data format

<?xml version="1.0" encoding="UTF-8"?> <outArgs>

</arg-xml>

</outArgs>

SCANNER SDK API 3 - 15

3 - 16 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Methods Invoked Through ExecCommand or ExecCommandAsync

Table 3-11

Scanner SDK Commands GET_VERSION 1000

Scanner Access Control Commands CLAIM_DEVICE 1500

Scanner Common Commands ABORT_MACROPDF 2000

List of Methods

Description Method Value Page

REGISTER_FOR_EVENTS 1001

UNREGISTER_FOR_EVENTS 1002

RELEASE_DEVICE 1501

ABORT_UPDATE_FIRMWARE 2001

AIM_OFF 2002

AIM_ON 2003

FLUSH_MACROPDF 2005

DEVICE_PULL_TRIGGER 2011

DEVICE_RELEASE_TRIGGER 2012

SCAN_DISABLE 2013

3-20 3-21 3-21 3-21 3-22 3-22 3-22 3-23 3-23 3-23 3-24 3-24

SCAN_ENABLE 2014

REBOOT_SCANNER 2019

Scanner Operation Mode Commands DEVICE_CAPTURE_IMAGE 3000

DEVICE_CAPTURE_BARCODE 3500

DEVICE_CAPTURE_VIDEO 4000

Scanner Management Commands ATTR_GETALL 5000

ATTR_GET 5001

ATTR_GETNEXT 5002

ATTR_SET 5004

ATTR_STORE 5005

GET_DEVICE_TOPOLOGY 5006

START_NEW_FIRMWARE 5014

UPDATE_FIRMWARE 5016

UPDATE_FIRMWARE_FROM_PLUGIN 5017

* Values for the SET_ACTION method are available in

Table 3-12

3-24 3-25 3-25 3-25 3-26 3-27 3-29 3-31 3-32 3-32 3-33 3-33 3-34 3-34

SCANNER SDK API 3 - 17

Table 3-11

Scanner Action Commands * SET_ACTION 6000

Other Commands DEVICE_SWITCH_HOST_MODE 6200

* Values for the SET_ACTION method are available in

List of Methods (Continued)

Description Method Value Page

Table 3-12

3-35 3-36

3 - 18 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Table 3-12

Attribute

Number

(Opcode)

6000 Beeper/LED Triggers the

Action Attributes and Values

Attribute Name Description

beeper/LED via command

Data Ty pe

'X' 0 - 1 high short beep

1 - 2 high short beeps 2 - 3 high short beeps 3 - 4 high short beeps 4 - 5 high short beeps 5 - 1 low short beep 6 - 2 low short beeps 7 - 3 low short beeps 8 - 4 low short beeps 9 - 5 low short beeps 10 - 1 high long beep 11 - 2 high long beeps 12 - 3 high long beeps 13 - 4 high long beeps 14 - 5 high long beeps 15 - 1 low long beep 16 - 2 low long beeps 17 - 3 low long beeps 18 - 4 low long beeps 19 - 5 low long beeps 20 - Fast warble beep 21 - Slow warble beep 22 - High-low beep 23 - Low-high beep 24 - High-low-high beep 25 - Low-high-low beep 26 - High-high-low-low beep 42 - Green LED off 43 - Green LED on 45 - Yellow LED 46 - Yellow LED off 47 - Red LED on 48 - Red LED off

Values

6001 ParameterDefaults Initiates a

parameter defaults command

6003 BeepOnNextBootup Controls whether

to suppress boot up / power up beep on the next power up

6004 Reboot Remote reboot

command

'X' 0 - Restore defaults

1 - Restore factory defaults 2 - Write custom defaults

'X' 0 - Disable beep on next bootup

1 - Enable beep on next bootup

'X'

SCANNER SDK API 3 - 19

Table 3-12

Attribute

Number

(Opcode)

6005 HostTriggerSession Triggers the

6011 StatsReset Reset/default a

6013 StatsResetAll Reset/default all

6017 ScaleReadWeight Read weight from

Action Attributes and Values (Continued)

Attribute Name Description

scanner to start scanning via command

specific statistic

statistics

scale

Data Ty pe

'X' 0 - Start host trigger session

1 - Stop host trigger session

'X' The specific statistic attribute to reset.

Range: 15002-19999

'X' '

'A' Byte[0] status:

0 - scaleNotEnabled 1 - scaleNotReady 2 - stableWeightOverLimit 3 - stableWeightUnderZero 4 - nonStableWeight 5 - stableZeroWeight 6 - stableNonZeroWeight Byte[1] units: 0=kgs 1=lbs Bytes[2-5] weight in thousandths of units

Values

6018 ScaleZero Zeros the scale 'X'

6019 ScaleReset Resets the scale 'X'

6022 ChangeAllCodeTypes Enables/Disables

all code types

'X' 0 = Disable all code types

1 = Enable all code types

3 - 20 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Number of events

Event ID(s)

Method Examples

The following inXML segments are examples only. Program inXML strings for customization based on application requirements.

REGISTER_FOR_EVENTS

Value 1001

Description: Register for API events described in API Events beginning on

page 3-6

Asynchronous supported: No

Supported scanner communication protocols: N/A

inXml:

Table 3-13 lists the Event IDs for the inXML code above.

Table 3-13

Event IDs

Event Name Event ID

SUBSCRIBE_BARCODE

SUBSCRIBE_IMAGE

SUBSCRIBE_VIDEO

SUBSCRIBE_RMD

SUBSCRIBE_PNP

SUBSCRIBE_OTHER

outXml:null

SCANNER SDK API 3 - 21

Number of Events

Event ID(s)

Specified Scanner ID

Specified Scanner ID

UNREGISTER_FOR_EVENTS

Value 1002

Description: Unregister from API events described in API Events

beginning on page 3-6

Asynchronous supported: No

Supported scanner communication protocols: N/A

inXml:

outXml:null

CLAIM_DEVICE

Value 1500

Description: Claim a specified device

Asynchronous supported: No

Supported scanner communication protocols: N/A

inXml:

outXml:null

RELEASE_DEVICE

Value 1501

Description: Release a specified device

Asynchronous supported: No

Supported scanner communication protocols: N/A

inXml:

outXml:null

3 - 22 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Specified Scanner ID

Specified Scanner ID

Specified Scanner ID

ABORT_MACROPDF

Value 2000

Description: Abort MacroPDF of a specified scanner

Asynchronous supported: No

Supported scanner communication protocols: SNAPI

inXml:

outXml:null

ABORT_UPDATE_FIRMWARE

Value 2001

Description: Abort firmware update process of a specified scanner

Asynchronous supported: No

Supported scanner communication protocols: IBM Hand-held, IBM Table-top, SNAPI

inXml:

outXml:null

AIM_OFF

Value 2002

Description: Turn off the aiming of a specified scanner

Asynchronous supported: No

Supported scanner communication protocols: SNAPI

inXml:

outXml:null

SCANNER SDK API 3 - 23

Specified Scanner ID

Specified Scanner ID

Specified Scanner ID

AIM_ON

Value 2003

Description: Turn on the aiming of a specified scanner

Asynchronous supported: No

Supported scanner communication protocols: SNAPI

inXml:

outXml:null

FLUSH_MACROPDF

Value 2005

Description: Flush MacroPDF of a specified scanner

Asynchronous supported: No

Supported scanner communication protocols: SNAPI

inXml:

outXml:null

DEVICE_PULL_TRIGGER

Value 2011

Description: Pull the trigger of a specified scanner

Asynchronous supported: N/A

Supported scanner communication protocols: SNAPI, IBM Hand-held*, IBM Table-top

* Supported auxiliary scanners if the firmware supports.

inXml:

outXml:null

3 - 24 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Specified Scanner ID

Specified Scanner ID

Specified Scanner ID

DEVICE_RELEASE_TRIGGER

Value 2012

Description: Release the pulled trigger of a specified scanner

Asynchronous supported: N/A

Supported scanner communication protocols: SNAPI, IBM Hand-held*, IBM Table-top*

* Supported auxiliary scanners if the firmware supports.

inXml:

outXml:null

SCAN_DISABLE

Value 2013

Description: Disable scanning on a specified scanner

Asynchronous supported: N/A

Supported scanner communication protocols: SNAPI, IBM Hand-held, IBM Table-top

inXml:

outXml:null

SCAN_ENABLE

Value 2014

Description: Enable scanning on a specified scanner

Asynchronous supported: N/A

Supported scanner communication protocols: SNAPI, IBM Hand-held, IBM Table-top

inXml:

outXml:null

SCANNER SDK API 3 - 25

Specified Scanner ID

Specified Scanner ID

Specified Scanner ID

REBOOT_SCANNER

Value 2019

Description: Reboot a scanner. To reboot a Bluetooth scanner, send this

command to the scanner’s associated cradle.

Asynchronous supported: N/A

Supported scanner communication protocols: IBM Hand-held, IBM Table-top, SNAPI

inXml:

outXml:null

DEVICE_CAPTURE_IMAGE

Value 3000

Description: Invoke snapshot mode on an imaging scanner. The scanner

blinks the green LED at one second intervals to indicate it is not in standard operating (decode) mode, and reverts to standard operating mode after a trigger pull or the snapshot time out occurs. After a trigger pull, the CoreScanner driver triggers an ImageEvent containing the captured image. See

ImageEvent on page 3-6.

Asynchronous supported: N/A

Supported scanner communication protocols: SNAPI

inXml:

outXml:null

DEVICE_CAPTURE_BARCODE

Value 3500

Description: Change a scanner to decode mode.

Asynchronous supported: N/A

Supported scanner communication protocols: SNAPI

inXml:

outXml:null

3 - 26 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Specified Scanner ID

DEVICE_CAPTURE_VIDEO

Value 4000

Description: Invoke video mode on an imaging scanner. The scanner

behaves as a video camera as long as the trigger is pulled. Releasing the trigger returns the scanner to decode mode. As long as the trigger is pulled, the CoreScanner driver triggers VideoEvents that contain the video data. See

VideoEvent on page 3-7.

Asynchronous supported: N/A

Supported scanner communication protocols: SNAPI

inXml:

outXml:null

SCANNER SDK API 3 - 27

<inArgs> <scannerID>1</scannerID> </inArgs> outXml: <?xml version="1.0" encoding="UTF-8" ?> <outArgs> <scannerID>1</scannerID> <arg-xml> <modelnumber>DS670-SR20001ZZR</modelnumber> <serialnumber>7116000501003</serialnumber> <GUID>A2E647DED2163545B18BCEBD0A2A133D</GUID> <response> <opcode>5000</opcode> <attrib_list> <attribute name="">0</attribute> <attribute name="">1</attribute> <attribute name="">2</attribute> <attribute name="">3</attribute> <attribute name="">4</attribute> <attribute name="">5</attribute> <attribute name="">6</attribute> <attribute name="">7</attribute> <attribute name="">8</attribute> <attribute name="">9</attribute> <attribute name="">10</attribute> <attribute name="">11</attribute> <attribute name="">12</attribute> <attribute name="">13</attribute> <attribute name="">14</attribute> <attribute name="">15</attribute> <attribute name="">16</attribute>

Specified Scanner ID

Scanner ID of Data Receiving

Method Response Received

Asset Tracking Information of the Scanner

Attribute Numbers

ATTR_GETALL

Value 5000

Description: Get all attributes of a scanner. A synchronous call of this

method returns an outXML as in the following example. An

asynchronous call triggers a CommandResponseEvent. See

page 3-14.

Asynchronous supported: Yes

Supported scanner communication protocols: IBM Hand-held, IBM Table-top, SNAPI

inXml:

3 - 28 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Attribute Numbers

inXml (continued):

SCANNER SDK API 3 - 29

><inArgs> <scannerID>1</scannerID> <cmdArgs> <arg-xml> <attrib_list>535,20004,1,140,392</attrib_list> </arg-xml> </cmdArgs> </inArgs>

Specified Scanner ID

Required Attribute Numbers

NOTE For a list of supported attribute (parameter) numbers and definitions, refer to the scanner Product

Reference Guide, available on the Zebra Support website: http://www.zebra.com/support. Attributes include configuration parameters, monitored data, and asset tracking information.

ATTR_GET

Value 5001

Description: Get the attribute values of a scanner. A synchronous call of

this method returns outXML as in the following example. An asynchronous call triggers a CommandResponseEvent. See

ScannerNotificationEvent on page 3-14.

Asynchronous supported: Yes

Supported scanner communication protocols: IBM Hand-held, IBM Table-top, SNAPI

inXml:

3 - 30 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Scanner ID of Data Receiving

Method Response Received

Asset Tracking Information of the Scanner

Attribute Number

Attribute Data Typer Permissions of the Attribute

Attribute Value

outXML:

SCANNER SDK API 3 - 31

Attribute Numbers

Specified Scanner ID

Scanner ID of Data Receiving

Method Response Received

Asset Tracking Information of the Scanner

Attribute Numbers

Attribute Value

Permissions of the Attribute

ATTR_GETNEXT

Value 5002

Description: Get the value of the next attribute to a given attribute of a

scanner. A synchronous call of this method returns an outXML as in the following example. An asynchronous call triggers a CommandResponseEvent. See

ScannerNotificationEvent on page 3-14.

Asynchronous supported: Yes

Supported scanner communication protocols: IBM Hand-held, IBM Table-top, SNAPI

inXml:

outXML:

NOTE If the next available attribute is not readable (for example, an Action attribute), this command returns the

next available readable attribute value.

3 - 32 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

<inArgs> <scannerID>1</scannerID> <cmdArgs> <arg-xml> <attrib_list> <attribute> <id>1</id> <datatype>F</datatype> <value>False</value> </attribute> </attrib_list> </arg-xml> </cmdArgs> </inArgs>

Attribute Numbers Attribute Data Type

Attribute Value

Specified Scanner ID

<inArgs> <scannerID>1</scannerID> <cmdArgs> <arg-xml> <attrib_list> <attribute> <id>1</id> <datatype>F</datatype> <value>False</value> </attribute> </attrib_list> </arg-xml> </cmdArgs>

Attribute Number Attribute Data Type Attribute Value

Specified Scanner ID

ATTR_SET

Value 5004

Description: Set the attribute values of a scanner. These values are

discarded on power down.

Asynchronous supported: N/A

Supported scanner communication protocols: IBM Hand-held, IBM Table-top, SNAPI

inXml:

outXml:null

ATTR_STORE

Value 5005

Description: Store the attribute values of a scanner. These values persist

Asynchronous supported: N/A

Supported scanner communication protocols: IBM Hand-held, IBM Table-top, SNAPI

inXml:

outXml: null

over power down and power up cycles.

SCANNER SDK API 3 - 33

<?xml version="1.0" encoding="UTF-8"?> <outArgs> <arg-xml> <scanners> <scanner type="SNAPI"> <scannerID>1</scannerID> <modelnumber>DS670-SR20001ZZR</modelnumber> <serialnumber>7116000501003</serialnumber> <GUID>A2E647DED2163545B18BCEBD0A2A133D</GUID> <VID>1504</VID> <PID>6400</PID> <DoM>24MAR10</DoM> <firmware>NBRPUAAM</firmware> </scanner> <scanner type="USBIBMHID"> <scannerID>2</scannerID> <modelnumber>CR0078-SC10007WR</modelnumber> <serialnumber>MXA4WD88</serialnumber> <GUID>993DF345C3B00E408E8160116AE9A319</GUID> <VID>1504</VID> <PID>2080</PID> <DoM>24MAR10</DoM> <firmware>NBCACAK7</firmware> <scanner type="USBIBMHID"> <scannerID>3</scannerID> <serialnumber>M1M87R39H</serialnumber> <modelnumber>DS6878-SR20007WR</modelnumber> <DoM>08OCT10</DoM> <firmware>PAAAJS00-002-N25</firmware> </scanner> </scanner> </scanners>

Scanner Type

Asset Tracking Information of the Scanner

Cascaded Scanner

Specified Scanner ID

GET_DEVICE_TOPOLOGY

Value 5006

Description: Get the topology of devices connected to the calling system.

Asynchronous supported: No

Supported scanner communication protocols: IBM Hand-held, IBM Table-top, SNAPI

inXml:

outXML:

START_NEW_FIRMWARE

Value 5014

Description: Start the updated firmware. This reboots the scanner.

Asynchronous supported: N/A

Supported scanner communication protocols: IBM Hand-held, IBM Table-top, SNAPI

inXml:

outXml:null

3 - 34 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

<scannerID>1</scannerID> <cmdArgs> <arg-string>D:\ScannerFW\DS6707\NBRPUCAM.DAT</arg-string> <arg-int>2</arg-int> </cmdArgs>

Specified Scanner ID

Bulk Update Option

Path to the DAT File

<scannerID>1</scannerID> <cmdArgs> <arg-string>D:\ScannerFW\DS9808\DS9808-COMMON SR MODELS-S-018.SCNPLG</arg-string> <arg-int>2</arg-int> </cmdArgs>

Specified Scanner ID

Bulk Update Option

Path to the Plug-in File

UPDATE_FIRMWARE

Value 5016

Description: Update the firmware of a scanner. Specify the bulk firmware

update option for faster firmware download in SNAPI mode. If an application registered for ScanRMDEvents, it receives

ScanRMDEvents as described on page 3-13.

Asynchronous supported: N/A

Supported scanner communication protocols: IBM Hand-held, IBM Table-top, SNAPI

inXml:

outXml:null

UPDATE_FIRMWARE_FROM_PLUGIN

Value 5017

Description: Update the firmware of a scanner using a plug-in. Specify the

bulk firmware update option for faster firmware download in SNAPI mode. If an application registered for ScanRMDEvents, it receives ScanRMDEvents as described

on page 3-13.

Asynchronous supported: N/A

Supported scanner communication protocols: IBM Hand-held, IBM Table-top, SNAPI

inXml:

outXml:null

NOTE This command does not verify supported scanner models of the plug-in. It attempts the firmware update

with the DAT file extracted from the specified plug-in file regardless of model.

SCANNER SDK API 3 - 35

</cmdArgs>

</inArgs>

Specified Scanner ID Scanner Action

Commands

SET_ACTION

Value 6000

NOTE Values for the SET_ACTION method are available in Table 3-12 on page 3-18.

Description: Perform an action involving the scanner’s beeper or LEDs.

Asynchronous supported: N/A

Supported scanner communication protocols: IBM Hand-held, IBM Table-top, SNAPI

inXml:

outXml:null

3 - 36 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

<inArgs> <scannerID>1</scannerID> <cmdArgs> <arg-string>XUA-45001-1</arg-string> <arg-bool>TRUE</arg-bool> <arg-bool>FALSE</arg-bool> </cmdArgs> </inArgs>

String Code for Target Host Variant Silent Switch Option

Permanent Change Option

Specified Scanner ID

DEVICE_SWITCH_HOST_MODE

Value 6200

Description: Switch the USB host mode of a scanner. This reboots the

scanner. If the scanner is in HID Keyboard mode, the only supported host variants are IBM Hand-held, IBM Table-top, and SNAPI. To configure this as a silent switch (suppressing reboot beeps) and persist the targeted host mode as permanent, set the parameters in the inXML string.

For a Bluetooth scanner, send this command to the scanner’s associated cradle.

Asynchronous supported: N/A

Supported scanner communication protocols: IBM Hand-held, IBM Table-top, SNAPI, HID Keyboard.

inXml:

Table 3-14 lists the string codes for USB host variants.

Table 3-14

USB Host Variants

Host Variant String Code

USB-IBMHID XUA-45001-1

USB-IBMTT XUA-45001-2

USB-HIDKB XUA-45001-3

USB-SNAPI with Imaging XUA-45001-9

USB-SNAPI without Imaging XUA-45001-10

outXml:null

Error and Status Codes

SCANNER SDK API 3 - 37

Table 3-15

SUCCESS 0 Generic success

STATUS_LOCKED 10 Device is locked by another application

ERROR_INVALID_APPHANDLE 100 Invalid application handle. Reserved

ERROR_COMMLIB_UNAVAILABLE 101 Required Comm Lib is unavailable to

ERROR_NULL_BUFFER_POINTER 102 Null buffer pointer

ERROR_INVALID_BUFFER_POINTER 103 Invalid buffer pointer

ERROR_INCORRECT_BUFFER_SIZE 104 Incorrect buffer size

ERROR_DUPLICATE_TYPES 105 Requested Type IDs are duplicated

ERROR_INCORRECT_NUMBER_OF_TYPES 106 Incorrect value for number of Types

ERROR_INVALID_ARG 107 Invalid argument

ERROR_INVALID_SCANNERID 108 Invalid scanner ID

ERROR_INCORRECT_NUMBER_OF_EVENTS 109 Incorrect value for number of Event IDs

Error and Status Codes

Error/ Status Code Value Description

parameter. Value is zero.

support the requested Type

ERROR_DUPLICATE_EVENTID 110 Event IDs are duplicated

ERROR_INVALID_EVENTID 111 Invalid value for Event ID

ERROR_DEVICE_UNAVAILABLE 112 Required device is unavailable

ERROR_INVALID_OPCODE 113 Opcode is invalid

ERROR_INVALID_TYPE 114 Invalid value for Type

ERROR_ASYNC_NOT_SUPPORTED 115 Opcode does not support asynchronous

method

ERROR_OPCODE_NOT_SUPPORTED 116 Device does not support the Opcode

ERROR_OPERATION_FAILED 117 Operation failed in device

ERROR_REQUEST_FAILED 118 Request failed in CoreScanner

ERROR_OPERATION_NOT_SUPPORTED_FOR_ AUXILIARY_SCANNERS

ERROR_DEVICE_BUSY 120 Device busy, retry the command

ERROR_ALREADY_OPENED 200 CoreScanner is already opened

ERROR_ALREADY_CLOSED 201 CoreScanner is already closed

ERROR_CLOSED 202 CoreScanner is closed

119 Operation not supported for auxiliary

scanners

ERROR_INVALID_INXML 300 Malformed inXML

3 - 38 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Table 3-15

ERROR_XMLREADER_NOT_CREATED 301 Could not instantiate XML Reader

ERROR_XMLREADER_INPUT_NOT_SET 302 Could not set input for XML Reader

ERROR_XMLREADER_PROPERTY_NOT_SET 303 Could not set XML Reader property

ERROR_XMLWRITER_NOT_CREATED 304 Could not instantiate XML Writer

ERROR_XMLWRITER_OUTPUT_NOT_SET 305 Could not set output for XML Writer

ERROR_XMLWRITER_PROPERTY_NOT_SET 306 Could not set XML Writer property

ERROR_XML_ELEMENT_CANT_READ 307 Cannot read element from XML input

ERROR_XML_INVALID_ARG 308 Arguments in inXML are not valid

ERROR_XML_WRITE_FAIL 309 Write to XML output string failed

ERROR_XML_INXML_EXCEED_LENGTH 310 InXML length exceeded

ERROR_XML_EXCEED_BUFFER_LENGTH 311 Buffer length for type exceeded

ERROR_NULL_POINTER 400 Null pointer

ERROR_DUPLICATE_CLIENT 401 Cannot add a duplicate client

Error and Status Codes (Continued)

Error/ Status Code Value Description

ERROR_FW_INVALID_DATFILE 500 Invalid firmware file

ERROR_FW_UPDATE_FAILED_IN_SCN 501 Firmware update failed in scanner

ERROR_FW_READ_FAILED_DATFILE 502 Failed to read DAT file

ERROR_FW_UPDATE_INPROGRESS 503 Firmware update in progress (cannot

proceed another firmware update or another command)

ERROR_FW_UPDATE_ALREADY_ABORTED 504 Firmware update is already aborted

ERROR_FW_UPDATE_ABORTED 505 Firmware update aborted

ERROR_FW_SCN_DETTACHED 506 Scanner is disconnected during firmware

update

STATUS_FW_SWCOMP_RESIDENT 600 Software component is already resident in

the scanner

CHAPTER 4 TEST UTILITIES & SOURCE

CODE

Overview

This chapter provides information for evaluating Zebra Scanner SDK software components using the SDK test utilities.

For a list of popular topics within this guide, see Quick Startup in the back of the guide.

NOTE For supported scanner attributes (parameters), refer to the scanner Product Reference Guide. This guide

may also contain an appendix listing non-parameter attributes that most Zebra scanners support.

Install Verifier Application (IVA) Utility

The Zebra Scanner SDK versions 4.0 and later provide the Install Verifier Application (IVA) utility, a self-installable source tarball package that verifies the CoreScanner and SDK utilities are installed and working properly.

After installing the CoreScanner and SDK packages on a Linux distribution, the IVA application performs the following checks:

•

CoreScanner and SDK package installation status using the standard package manager program or Linux commands.

•

File-by-file check on installed files.

•

Verify generic actions/behaviors of CoreScanner. Check cscore daemon to ensure systemd or systemv daemon is working properly, and ensure that operations (service controlling commands such like start, stop, restart, and status) on cscore daemon are working properly.

•

Ability to test basic CoreScanner commands and events.

•

Installation and environment setup for CoreScanner and JPOS test tools.

IVA execution generates a summary report containing the status of these verification tests.

4 - 2 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

IVA Outcome

The utility executes in a predefined order and generates a text report indicating the status of the test. This report verifies that driver installation is successful and working as expected.

Following is a section of a sample output report:

=============================================

Zebra Technologies Corescanner Driver Install Verifier App

===========================================================

Install verifier app started: [08122016_03:32:56]

- - - - - - - - - - - - - - - - - - - -

You are running root..................................................................[ SUCCESS ]

- - - - - - - - - - - - - - - - - - - - - - -

Found RPM based package manager in your system.

Found Debain based package manager in your system.

zebra-scanner-corescanner package......................................[ FOUND ]

zebra-scanner-devel package.................................................[ FOUND ]

zebra-scanner-javapos package..............................................[ FOUND ]

- - - - - - - - - - - - - - - - - - - - - - -

Installing the IVA

To install the IVA utility:

1. Place install-verifier-app.tar.gz into the selected directory using the cp command or the system GUI.

2. Extract install-verifier-app.tar.gz using the tar command or the system GUI.

$> tar -xvf install-verifier-app.tar.gz

3. Open a terminal window. Change the directory to install-verifier-app and build the source.

The zebra-install-verifier executable file is now available in the directory.

$> make

g++ -c main.cpp -o main.o -I/usr/share/include/zebra-scanner

g++ -c pugixml.cpp -o pugixml.o -I/usr

g++ -c xml_formatter.cpp -o xml_formatter.o -I/usr/include/zebra-scanner

g++ -o zebra-install-verifier main.o pugixml.o xml_formatter.o -L/usr/share/zebra-scanner/corescanner/

-lcs-client

Execute the zebra-install-verifier using the command line interface.

/include/zebra-scanner

TEST UTILITIES & SOURCE CODE 4 - 3

Executing the IVA

The auto_run.sh script is available in the same directory as zebra-install-verifier. Ensure you have root permission to execute the script.

$> sh auto_run.sh

The tool runs initial commands in the background and displays the status on the console/terminal window. Use the self-help menu to choose the test case and the execution steps.

Sample menu from the app:

==============================================================

==1.: Continue to next test after the PNP event.

==2.: Skip to next test.

==0.: Exit.

==============================================================

Continue to test and verify CoreScanner installation using this menu. Applications refresh at the end of each verification entry.

IVA verifies the following:

•

Status of CoreScanner and SDK installation (RPM/Debian package and source tarball installation)

•

CoreScanner daemon is working properly

•

CoreScanner command GetScanner

•

PNP events

•

Barcode scanning events

•

CoreScanner Command: RSM Get All Attributes

•

CoreScanner Command: RSM Get Attribute

•

CoreScanner Command: Execute an action attribute (beep, LED ON/OFF)

•

SNAPI Imaging with pull trigger and release trigger

•

SNAPI direct commands: AIM ON/OFF

4 - 4 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Test Utilities

The Zebra Scanner SDK includes the following test utilities that demonstrate SDK functionality to help you gain an understanding of the Zebra Scanner SDK.

•

Zebra Scanner SDK C++ GUI Demonstration Application, GTK

•

Zebra Scanner SDK C++ Console Sample Application, Commandline (see Chapter 5, SAMPLE

SOURCE CODE)

NOTE You may need to install all dependent packages before installing the CoreScanner.

The Zebra Scanner SDK test utilities support the following functionality:

•

Discovery of asset tracking information

•

Barcode scanning

•

Image and video capture

•

Attribute query and setting

•

Host variant switching

•

Firmware upgrade.

Scanner SDK C++ GTK-based Sample Application

The Scanner SDK C++ Sample Application demonstrates SDK functionality by simulating an application that communicates with the Scanner SDK. It includes C++ source code and solution and project files for further reference.

Figure 4-1

C++ Sample Application

TEST UTILITIES & SOURCE CODE 4 - 5

Table 4-1

Discover Scanners Invoke Open and GetScanners methods and register for all events

Select Scanner Select the scanner to invoke the command

Connected Scanners List all connected scanners regardless of mode

Pull Trigger Soft Pull Trigger the scanner for barcode, image, and video actions

Release Trigger Soft Release Trigger the scanner for barcode, image, and video actions

Barcode Tab

Flush Macro PDF Flush Macro PDF barcode buffer

Abort Macro PDF Abort Macro PDF read

Clear Clear the barcode data area

Decoded Barcode Display the label value of the scanned barcode

Symbology Display the symbology of the scanned barcode

Image/Video Tab

Image Invoke image capture mode

Test Utility Buttons and Fields by Tab

Button or Field Description

Video Invoke video capture mode

Abort Transfer Abort image transfer on serial scanners

Image Type Select JPG, TIFF, or BMP image type

Enable Video View Finder Enable the view finder in image mode

Save Image Save the captured image

Scanner Actions Tab

Enable/Disable Scanner Enable/Disable the scanner for data/image/video capture initiation

Aim Switch on and off Aim control of the scanner

Beeper Beep the beeper of the scanner

Reboot Scanner Reboot the scanner

LED Light the LED(s) on the scanner

Switch Host Variant Switch the scanner host type; you can select a silent feature and persist the

variant change

RSM Tab

Get All IDs Get all supported attribute IDs from the selected scanner

Get Value Select one or more attribute IDs and get their values

Next Value Get the next attribute value given the current attribute number

Store Value Store value(s) for selected attribute(s)

4 - 6 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Table 4-1

Set Value Set value(s) for selected attribute(s)

Select All Select all attribute IDs at the RSM data viewer

Clear All Clear all attribute data at the RSM data viewer

Clear All Values Clear all attribute values at the RSM data viewer (C# only)

Clear Value Clear a selected attribute value at the RSM data viewer (C# only)

Advance Tab

Firmware Update Operations Update firmware and launch the new firmware on the scanner

Browse Browse the firmware file (*.DAT) or plug-in file (*.SCNPLG)

Update Initiate firmware update

Abort Abort firmware update

Launch Once firmware update finishes launch the new firmware in the scanner

Claim Scanner Exclusively claim and declaim the scanner for this application

Logs Tab

Test Utility Buttons and Fields by Tab (Continued)

Button or Field Description

Event Log Command and event log; logs initiated commands

XML log Displays output of each function if available

Clear Event Log Clear command and event log area

Clear XML Log Clear XML log area

TEST UTILITIES & SOURCE CODE 4 - 7

Verifying Scanner SDK Functionality

This section provides test cases to demonstrate Zebra Scanner SDK functionality. See Installing and

Configuring CoreScanner and SDK on page 2-5 for more information.

Scanner Discovery / Asset Tracking / Successful SDK Installation Validation

1. Connect a Zebra USB scanner(s) to the host computer.

2. Scan one of the following barcodes to place the scanner in USB Hand-held or USB SNAPI mode.

USB (IBM Hand-held)

USB SNAPI

3. Launch the Zebra Scanner SDK Sample Utility on the host computer.

Figure 4-2

4. Use the change directory (cd) command to change to the /usr/share/zebra-scanner/samples/gui-app

directory and run the corescanner-gui-app executable file.

Start Scanner SDK Sample Application (C++)

4 - 8 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

5. Click Discover Scanners to display all connected scanners. This executes an Open for all types of

scanners and an ExecCommand with the REGISTER_FOR_EVENTS method using the following XML and a GetScanners API call:

NOTE The first <inArgs> tag in the XML contains the number of events to register, in this example, 6.

The second <arg-int> tag contains the event IDs to register separated by commas (","). See T a ble 4-2.

Table 4-2

Supported Event IDs

Event Name Event ID

SUBSCRIBE_BARCODE 1

SUBSCRIBE_IMAGE 2

SUBSCRIBE_VIDEO 4

SUBSCRIBE_RMD 8

SUBSCRIBE_PNP 16

SUBSCRIBE_OTHER 32

See Chapter 5, SAMPLE SOURCE CODE for more information about Open, ExecCommand, and

GetScanners APIs.

The GetScanners API call produces the following XML code:

<?xml version="1.0" encoding="UTF-8" ?> <scanners> <scanner type="SNAPI"> <scannerID>1</scannerID> <serialnumber>7116000501003</serialnumber> <GUID>A2E647DED2163545B18BCEBD0A2A133D</GUID> <VID>1504</VID> <PID>6400</PID> <modelnumber>DS670-SR20001ZZR</modelnumber> <DoM>27APR07</DoM> <firmware>NBRPUAAC</firmware> </scanner> </scanners>

TEST UTILITIES & SOURCE CODE 4 - 9

Table 4-3

Scanner Information Value Description

Scanner ID 1 A unique ID that the SDK assigns to a

Serial Number 7116000501003 Device serial number printed on the

Model Number DS670-SR20001ZZR Device model number.

Date of Manufacture 27APR07 Device date of manufacture.

Firmware Version NBRPUAAC Current firmware version.

H/W GUID A2E647DED2163545B18BCEBD0A2A133D Hardware unique ID.

The XML consists of the scanner type, scanner ID, serial number, GUID, VID, PID, model number, date of manufacture, and firmware version of the connected scanners.

The Connected Scanners list displays all discovered scanners by processing the XML from the GetScanners

command along with asset tracking information returned by querying device parameters. This information indicates the SDK was installed successfully.

GetScanners Output For This Example

scanner. Any scanner specific method executed via must point to this.

label.

ExecCommand

Figure 4-3

Connected Scanners

4 - 10 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

1 2 3 4 5 6 7 8 9 1

Barcode Scanning

Connect and discover a scanner. See Scanner Discovery / Asset Tracking / Successful SDK Installation

Validation on page 4-7.

Scanning a barcode returns decoded data as XML on the Barcode tab. To illustrate the implementation, the

sample application displays only the barcode data below the XML data.

Figure 4-4

Decoded Barcode Data

Example

Scan the following barcode after discovering the scanner in the sample application.

Sample Barcode

This returns the following XML:

<?xml version="1.0" encoding="UTF-8" ?> <outArgs> <scannerID>2</scannerID> <arg-xml> <scandata> <modelnumber>DS670-SR20001ZZR</modelnumber> <serialnumber>7116000501003</serialnumber> <GUID>A2E647DED2163545B18BCEBD0A2A133D</GUID> <datatype>8</datatype> <datalabel>0x30 0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 0x39 0x31 0x32< /datalabel> <rawdata>0x30 0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 0x39 0x31 0x32</rawdata> </scandata> </arg-xml> </outArgs>

The sample application processes this XML and displays the decoded barcode in the Decoded Barcode text box, and the symbology in the Symbology text box.

TEST UTILITIES & SOURCE CODE 4 - 11

Image and Video Capture

1. Connect and discover an imaging scanner. See Scanner Discovery / Asset Tracking / Successful SDK

Installation Validation on page 4-7.

2. Select a SNAPI mode scanner ID from the Select Scanner drop-down list. The selection appears in the

Connected Scanners list.

NOTE If no SNAPI scanner appears in the Connected Scanners list, connect an imaging scanner that supports

image/video transfer. For a list if scanner models and their supported communication modes, refer to the Scanner SDK for Windows website: www.zebra.com/scannersdkforwindows.

Alternatively, select the SNAPI mode scanner in the Connected Scanners area. The selected scanner's ID appears in the Select Scanner drop-down list.

Figure 4-5

3. Select the Image & Video tab.

4. Select an image type of JPG, TIFF, or BMP. This executes an ExecCommand API call using the

Scanner Selection

ATTR_SET method and following XML code:

NOTE The <scannerID> tag in the XML contains the scanner ID selected in the Connected Scanners list. The

<id> tag contains the image file type parameter of the selected scanner, in this example, 304. The value 4

indicates the image type the user gets from the scanner. See Table 4-4.

4 - 12 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Table 4-4

Image Types

Image Type Value

BMP_FILE_SELECTION 3

TIFF_FILE_SELECTION 4

JPEG_FILE_SELECTION 1

NOTE These values may vary by scanner model. Refer to the scanner Product Reference Guide for information

on scanner parameters. For more information about parameter settings, see Parameter Setting (Device

Configuration) on page 4-20.

5. Check Enable Video View Finder. This executes an ExecCommand API call with the ATTR_SET method

and the following XML code:

NOTE The <scannerID> tag in the XML contains the ID of the scanner selected in the Connected Scanners list.

The <id> tag contains the video view finder parameter number of the scanner and value 1 indicates that the view finder is enabled. A value 0 indicates the view finder is disabled.

Click either Image to put the scanner into image capture mode or Video to put the scanner into video

capture mode. This executes an ExecCommand API call using the DEVICE_CAPTURE_IMAGE method for Image, or DEVICE_CAPTURE_VIDEO method for Video, with the following XML code:

Click Pull Trigger on the bottom left side of the utility. The scanner captures an image if in image capture

mode, or begins video capture if in video capture mode. Click Release Trigger to stop video capture.

Clicking Pull Trigger or Release Trigger executes an ExecCommand API call using the corresponding

DEVICE_PULL_TRIGGER or DEVICE_RELEASE_TRIGGER method with the following XML code:

NOTE You can use the trigger on the scanner to start and stop image or video capture instead of the soft trigger

buttons provided in the sample utility.

TEST UTILITIES & SOURCE CODE 4 - 13

Figure 4-6

If you registered with ImageEvent you receive an image event for the pull trigger when in image mode. If you registered with VideoEvent you receive a video event for the pull trigger when in video mode. See

REGISTER_FOR_EVENTS on page 3-20.

Captured Image Displayed on the Image & Video Tab

4 - 14 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Beep the Beeper

Zebra scanners sound the beeper when the host system invokes the Beeper method.

1. Connect and discover a scanner. See Scanner Discovery / Asset Tracking / Successful SDK Installation

Validation on page 4-7.

2. Select a SNAPI or IBM mode scanner ID from the Select Scanner drop-down list. The selection appears in

the Connected Scanners list. See Figure 4-5 on page 4-11.

3. On the Actions tab, select the beep sequence.

Figure 4-7

4. Click Beep to execute an ExecCommand API call with the SET_ACTION method and following XML code:

To sound a beep listed in Table 3-12 on page 3-18, change the value of the <arg-int> tag in the XML code.

Beep Values

NOTE The <scannerID> tag in the XML contains the scanner ID selected in the Connected Scanners list. The

<arg-int> tag in the XML contains the beep value selected in the Beeper drop-down list in Figure 4-7.

A successful command returns the status parameter 0.

TEST UTILITIES & SOURCE CODE 4 - 15

Flash the LED

Zebra scanners flash an LED when the host system initiates the flash LED method.

1. Connect and discover a scanner. See Scanner Discovery / Asset Tracking / Successful SDK Installation

Validation on page 4-7.

2. Select a SNAPI or IBM mode scanner ID from the Select Scanner drop-down list. The selection appears in

the Connected Scanners list. See Figure 4-5 on page 4-11.

3. On the Actions tab, select the desired LED.

Figure 4-8

4. Click On to execute an ExecCommand API call with the SET_ACTION method and the following XML

LED Selection

code:

NOTE The <scannerID> tag in the XML contains the scanner ID selected in the Connected Scanners list. The

<arg-int> tag in the XML contains the corresponding action value to turn on or off the LED selected from

the drop-down list in Figure 4-8.

To control the LED, change the action value in the <arg-int> tag. Table 3-12 on page 3-18 lists the action

values.

Click Off to execute an ExecCommand API call using the DEVICE_LED_OFF method with the same XML

code that turned it on.

NOTE The Beep the Beeper and Flash the LED XML code examples are the same except for the method name.

All XML used in an ExecCommand API call has a common format. The </inArgs> tag always contains the

<scannerID> tag and optionally contains <cmdArgs> tags and <arg-xml> tags inside the </inArgs> tag. <cmdArgs> can contain <arg-string>, <arg-bool>, and <arg-int> tags. Execute different commands for the

same XML by changing the method parameter in ExecCommand.

4 - 16 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Attribute and Parameter Query

To query parameters from a specific device, such as the Date of Manufacture and Firmware Version:

1. Connect and discover a scanner. See Scanner Discovery / Asset Tracking / Successful SDK Installation

Validation on page 4-7.

2. Select the scanner to query from the list of Connected Scanners.

3. On the RSM tab, click Get All IDs to retrieve a list of all attribute IDs supported by the scanner. This

executes an ExecCommand API call with the ATTR_GETALL method and the following XML:

NOTE The <scannerID> tag in the XML contains the ID of the scanner selected in the Connected Scanners list.

The sample application receives the following XML output and displays the corresponding attribute IDs.

See Figure 4-9 on page 4-18.

</outArgs>

NOTE To find the corresponding attribute names, refer to the scanner Product Reference Guide, available on the

Zebra Support website. Attributes include configuration parameters, monitored data, and asset tracking information.

TEST UTILITIES & SOURCE CODE 4 - 17

4 - 18 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Figure 4-9

Get RSM IDs

Querying Specific Attributes

To query attributes, select attribute IDs and click Get Value. This executes an ExecCommand API call with the

ATTR_GET method and the following XML.

NOTE The <scannerID> tag in the XML contains the ID of the scanner selected in the Connected Scanners list

and the <attrib_list> tag with the attribute IDs selected on the RSM tab.

For example, to retrieve the values of the Date of Manufacture, Firmware Version, UPC -A status, Beeper

Volume, and ADF Rule parameters, select these attribute IDs and click Get Value. This executes an

ExecCommand API call with the ATTR_GET method and the XML shown above. See Table 4-5 for the

corresponding IDs.

Table 4-5

Device Parameters to Query

Parameter Attribute #

Date of Manufacture 535

Firmware Version 20004

UPC A status 1

Beeper Volume 140

ADF Rule 392

TEST UTILITIES & SOURCE CODE 4 - 19

After a successful command, the output XML appears in the Logs tab as follows:

<?xml version="1.0" encoding="UTF-8" ?> <outArgs> <scannerID>1</scannerID> <arg-xml> <modelnumber>DS670-SR20001ZZR</modelnumber> <serialnumber>7116000501003</serialnumber> <GUID>A2E647DED2163545B18BCEBD0A2A133D</GUID> <response> <opcode>5001</opcode> <attrib_list> <attribute> <id>535</id> <name></name> <datatype>S</datatype> <permission>R</permission> <value>27APR07</value> </attribute> <attribute> <id>20004</id> <name></name> <datatype>S</datatype> <permission>R</permission> <value>DS6707X4</value> </attribute> <attribute> <id>1</id> <name></name> <datatype>F</datatype> <permission>RWP</permission> <value>True</value> </attribute> <attribute> <id>140</id> <name></name> <datatype>B</datatype> <permission>RWP</permission> <value>0</value> </attribute> <attribute> <id>392</id> <name></name> <datatype>A</datatype> <permission>RWP</permission> <value>0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00</value> </attribute> </attrib_list> </response> </arg-xml>

</outArgs>

4 - 20 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

The sample application processes this XML and displays the output on the RSM tab.

Figure 4-10

Get Attribute Values

Parameter Setting (Device Configuration)

To set parameters of a specific device, such as UPC-A status or beeper volume:

1. Query the parameter. See Attribute and Parameter Query on page 4-16.

2. To set an attribute, select and edit the attribute value in the RSM window.

3. Select the row of the updated attribute and click Set Value or Store Value. This executes an

ExecCommand API call using the ATTR_SET or ATTR_STORE method and the following XML code:

<inArgs> <scannerID>1</scannerID> <cmdArgs> <arg-xml> <attrib_list> <attribute> <id>1</id> <datatype>F</datatype> <value>False</value> </attribute> </attrib_list> </arg-xml> </cmdArgs> </inArgs>

NOTE The <scannerID> tag in the XML contains the ID of the scanner selected in the Connected Scanners list

and the <attrib_list> tag contains the <attribute> tags selected on the RSM tab.

TEST UTILITIES & SOURCE CODE 4 - 21

1 2 3 4 5 6 7 8 9 1

Examples

The following examples demonstrate how to enable or disable a symbology, program an ADF rule, control beeper volume, and control LEDs.

Before starting an example, scan the Set All Defaults barcode to return all parameters to default values (replacing the scanner's current settings). Refer to the scanner Product Reference Guide for default values.

Set All Defaults

Enable / Disable a Symbology

To disable a symbology, refer to the scanner Product Reference Guide to determine the attribute ID. The attribute ID of the UPC-A parameter is 1. To change and validate the setting:

1. Put the scanner into USB OPOS (Hand-held) or USB SNAPI mode by scanning one of the barcodes in

Scanner Discovery / Asset Tracking / Successful SDK Installation Validation on page 4-7, or using the

procedure in Host Variant Switching on page 4-25.

2. Get the value of attribute ID 1, which is TRUE if you scanned the Set All Defaults barcode.

3. To disable UPC-A, change the value of attribute ID 1 to FALSE on the RSM tab, and click Set Value or

Store Value. This executes an ExecCommand API call with the ATTR_SET or ATTR_STORE method and

the XML shown in Parameter Setting (Device Configuration) on page 4-20.

If the command was successful, the scanner cannot scan the following UPC-A barcode.

Sample UPC-A Barcode

4 - 22 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Program an ADF Rule

To create an ADF rule to add the prefix "A" to any barcode and an Enter key after, modify the scanner ADF buffer. The attribute ID of the ADF rule is 392.

To change and validate the setting:

USB Host Type = HID Keyboard Wedge

1. Scan the following barcode, or see Host Variant Switching on page 4-25, to switch the scanner to HID

keyboard mode. This enables the scanner to send data to any text editor.

USB Host Type - HID Keyboard Wedge

2. Open a text editor such as Windows Notepad.

3. Scan the Sample UPC-A Barcode on page 4-21 with the text editor as the active window to insert the

barcode data "012345678912" in the window.

4. Put the scanner into USB OPOS (Hand-held) or USB SNAPI mode by scanning one of the barcodes in

Scanner Discovery / Asset Tracking / Successful SDK Installation Validation on page 4-7, or using the

procedure in Host Variant Switching on page 4-25.

5. In the sample application, change the value of the selected scanner's attribute 392 to:

0x01 0x0C 0x11 0xF4 0x14 0x10 0x47 0x0D.

6. Click Store Value. The sample application executes an ExecCommand API call using the ATTR_STORE

method and the following XML code:

After successfully executing the command, repeat steps 1 - 3.

The text entered in Notepad is "A012345678912<Enter key>".

TEST UTILITIES & SOURCE CODE 4 - 23

Beeper Volume Control

The beeper volume attribute ID is 140, and the scanner beeper has three volume levels:

•

2 = low

•

1 = Medium

•

0 = High

To change and validate this setting:

1. Put the scanner into USB OPOS (Hand-held) or USB SNAPI mode by scanning one of the barcodes in

Scanner Discovery / Asset Tracking / Successful SDK Installation Validation on page 4-7, or using the

procedure in Host Variant Switching on page 4-25.

2. Scan the Sample UPC-A Barcode on page 4-21 and listen to the beeper.

3. Select attribute ID 140 from the RSM attribute grid. Its value is 0 if you scanned the Set All Defaults

barcode at the beginning of the example.

4. Change the value to 2 and click Set Value or Store Value. The sample application executes an

ExecCommand API call with the ATTR_SET or ATTR_STORE method and the following XML code:

Scan the Sample UPC-A Barcode again. The beeper volume is lower if the command was successful.

NOTE Changes made using the Store Value commands are permanent, persisting over power down and power

up cycles. Changes made using the Set Value command are temporary and are discarded after the next

power down.

4 - 24 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Beeper and LED Control

Table 3-12 on page 3-18 indicates that the attribute ID for beeper and LED control is 6000. To change and

validate this setting:

1. Put the scanner into USB OPOS (Hand-held) or USB SNAPI mode by scanning one of the barcodes in

Scanner Discovery / Asset Tracking / Successful SDK Installation Validation on page 4-7, or using the

procedure in Host Variant Switching on page 4-25.

2. To turn on the scanner LED, execute an ExecCommand API call with the ATTR_SET or ATTR_STORE

method and the following XML code:

NOTE You can execute several actions by changing the <value> tag in this XML. For example, to turn off the

LED, change the value to 42; to beep the beeper, change the value to an integer between 0 and 25.

TEST UTILITIES & SOURCE CODE 4 - 25

Host Variant Switching

1. Connect and discover a scanner. See Scanner Discovery / Asset Tracking / Successful SDK Installation

Validation on page 4-7.

2. On the Actions tab, select a target mode from the Switch Host Variant drop-down list.

3. If desired, select Permanent Change or Silent Reboot options (hidden by the Switch Host Variant

drop-down list).

Figure 4-11

4. Click Switch Host Mode to reboot the scanner and set the target mode. This executes an ExecCommand

Changing Host Mode

API call with the DEVICE_SWITCH_HOST_MODE method and the following XML code:

<inArgs> <scannerID>1</scannerID> <cmdArgs> <arg-string>XUA-45001-1</arg-string> <arg-bool>TRUE</arg-bool> <arg-bool>FALSE</arg-bool> </cmdArgs> </inArgs>

NOTE The <scannerID> tag in the XML code contains the ID of the scanner selected in the Connected Scanners

list. The <arg-string> tag contains the string code of the selected target host variant. See Table 3-14 on

page 3-36 for these codes.

The first <arg-bool> tag contains the boolean value for the silent reboot option. A value of TRUE silently reboots the scanner (without reboot beeps). The second <arg-bool> tag contains the boolean value for the permanent change option. A value of TRUE persists the target host variant over power down and power up cycles. Otherwise the host variant change is temporary until the next reboot.

HID Keyboard mode only supports the IBM Hand-held USB and SNAPI host variants. See Table 3-14 on page

3-36 for USB host variant codes.

4 - 26 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

Firmware Upgrade

Firmware Upgrade Scenarios

There are three firmware upgrade scenarios.

Loading a compatible, different version of firmware to the scanner

Firmware upgrade downloads the firmware file to the scanner and activates the firmware. Activation takes approximately 50 seconds, during which the LED blinks red and the scanner does not respond to network queries.

When activation (programming) completes, the scanner reboots. The LED turns off, the scanner emits a power up beep, and powers up with the new firmware.

A firmware download can take up to 20 minutes depending on the connection speed between the POS terminal and the scanner, the operating mode of the scanner, and the size of the firmware file.

Loading the same version of firmware that is on the scanner

A firmware file can include multiple components. When loading the same version of firmware, some components in the firmware file may be the same as those on the scanner, while other components are different.

Before loading firmware, the scanner driver reads the header information of each firmware component to validate the model number and version, and only loads components that are different on the scanner. For example, if the first component downloading from the firmware file is the same version as one already on the scanner, the component does not load.

Loading an incompatible version of firmware on the scanner

This occurs when attempting to load firmware designed for one scanner model, for example a DS6707, onto another incompatible scanner model, for example the DS6708.

A firmware file can include multiple components. Before downloading firmware to the scanner, the scanner driver reads the header information of each firmware component to validate the model number and version. If the firmware component model number does not match the scanner, the component does not load. This process continues, verifying each remaining component in the firmware file.

TEST UTILITIES & SOURCE CODE 4 - 27

Firmware Upgrade Procedure

1. Connect and discover a scanner. SeeScanner Discovery / Asset Tracking / Successful SDK Installation

Validation on page 4-7.

2. Use 123Scan

a. Download and launch 123Scan

b. Using 123Scan

to obtain the latest scanner plug-in which contains the firmware .DAT file.

from www.zebra.com/123scan2.

, confirm you have the latest scanner plug-in, which contains a number of files

including the firmware file and release notes.

• To download the latest scanner plug-ins from within 123Scan

, on the help menu, select Check for

updates.

• For a list of scanner models, plug-ins, and firmware files supported in 123Scan

on the help menu,

select Supported scanners and plug-ins.

• The plug-ins are located in one of the following 123Scan

sub folders:

For Windows XP systems:

[WINDOWSDRIVE]\ Documents and Settings\ [USERNAME]\Application Data\123Scan2\Plug-ins For later versions of Windows: [WINDOWSDRIVE]\Users\ Application Data\123Scan2\Plug-ins

3. Extract the firmware .DAT file from 123Scan

a. Rename the file extension of the plug-in from .SCNPLG to .ZIP.

b. Use a standard archive tool, such as WinZip, to extract the firmware update file which contains the file

plug-in:

extension .DAT.

For example, the DS9808 plug-in is named DS9808-COMMON SR MODELS-S-017.SCNPLG. Change .SCNPLG to .ZIP and access the firmware file CAAABS00-006-R02D0.DAT using WinZip.

4. In the sample application, select the Advanced tab and browse to and select the firmware .DAT file.

5. Check the Bulk Update option if desired.

NOTE There are two communication interfaces (channels), USB HID or the faster USB Bulk, to perform a

firmware update. Most SNAPI devices support USB Bulk firmware update but some do not. To determine if your scanner supports USB Bulk mode, refer to the Scanner SDK for Windows website:

www.zebra.com/scannersdkforwindows.

6. Click Update to transfer the firmware file to the scanner. This executes an ExecCommand API call with the

UPDATE_FIRMWARE method and the following XML code:

<inArgs> <scannerID>1</scannerID> <cmdArgs> <arg-string>D:\scanner\ScannerFW\DS6707\DS6707X4.DAT</arg-string> <arg-int>2</arg-int> </cmdArgs> </inArgs>

NOTE The <scannerID> tag in the XML contains the ID of the scanner selected in the Connected Scanners list.

The <arg-string> tag contains the path to the firmware file. The <arg-int> tag contains 2 if the bulk update option is selected, or 1 if not.

4 - 28 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

7. If you have registered with ScanRMDEvent (see REGISTER_FOR_EVENTS on page 3-20), you receive

six types of events per firmware update cycle, shown in Table 4-6.

Table 4-6

Value

Firmware Update Event Types

Event

Event Type Description

11 SCANNER_UF_SESS_START Triggered when flash download session starts

12 SCANNER_UF_DL_START Triggered when component download starts

13 SCANNER_UF_DL_PROGRESS Triggered when block(s) of flash completed

14 SCANNER_UF_DL_END Triggered when component download ends

15 SCANNER_UF_SESS_END Triggered when flash download session ends

16 SCANNER_UF_STATUS Triggered when update error or status

The OnScanRMDEvent function has two parameters:

• The first short type parameter contains the event type described above.

• The second parameter contains an XML for the event types in Table 4-6. Processing the XML

provides further information. The receiving XML formats for each event types are as follows, and include information about the scanner it updates.

NOTE A firmware file can include multiple components. Before downloading firmware to the scanner, the

scanner driver reads the header information of each firmware component to validate the model number and version. If the component model number does not match the scanner’s, the component does not load. This process verifies each component in the firmware file.

a. SCANNER_UF_SESS_START

<?xml version="1.0" encoding="UTF-8"?> <outArgs> <scannerID>1</scannerID> <arg-xml> <sess_start> <modelnumber>DS670-SR20001ZZR</modelnumber> <serialnumber>S/N:7108E15933CA1B4BB776F7BDB4B3F826</serialnumber> <GUID>7108E15933CA1B4BB776F7BDB4B3F826</GUID> <maxcount>3075</maxcount> <status>0</status> </sess_start> </arg-xml> </outArgs>

NOTE The <maxcount> tag contains the number of records in the firmware file.

SCANNER_UF_DL_START

<?xml version="1.0" encoding="UTF-8"?> <outArgs> <scannerID>1</scannerID> <arg-xml> <dl_start> <modelnumber>DS670-SR20001ZZR</modelnumber> <serialnumber>S/N:7108E15933CA1B4BB776F7BDB4B3F826</serialnumber> <GUID>7108E15933CA1B4BB776F7BDB4B3F826</GUID> <software_component>0</software_component> <status>0</status>

TEST UTILITIES & SOURCE CODE 4 - 29

</dl_start> </arg-xml> </outArgs>

NOTE The <software_component> tag contains the component number that starts downloading.

c. SCANNER_UF_DL_PROGRESS

<?xml version="1.0" encoding="UTF-8"?> <outArgs> <scannerID>1</scannerID> <arg-xml> <dl_progress> <modelnumber> DS670-SR20001ZZR </modelnumber> <serialnumber>S/N:7108E15933CA1B4BB776F7BDB4B3F826</serialnumber> <GUID>7108E15933CA1B4BB776F7BDB4B3F826</GUID> <software_component>1</software_component> <progress>7</progress> <status>600</status> </dl_progress> </arg-xml> </outArgs>

NOTE The <progress> tag contains the record number that is currently downloading. The <status> tag contains

the record of the download progress. 600 indicates the resident firmware. For status and error codes see

Table 3-15 on page 3-37.

SCANNER_UF_DL_END

<?xml version="1.0" encoding="UTF-8"?> <outArgs> <scannerID>1</scannerID> <arg-xml> <dl_end> <modelnumber> DS670-SR20001ZZR </modelnumber> <serialnumber>S/N:7108E15933CA1B4BB776F7BDB4B3F826</serialnumber> <GUID>7108E15933CA1B4BB776F7BDB4B3F826</GUID> <software_component>2</software_component> <size>0</size> <status>0</status> </dl_end> </arg-xml> </outArgs>

SCANNER_UF_SESS_END

<?xml version="1.0" encoding="UTF-8"?> <outArgs> <scannerID>1</scannerID> <arg-xml> <sess_end> <modelnumber> DS670-SR20001ZZR </modelnumber> <serialnumber>S/N:7108E15933CA1B4BB776F7BDB4B3F826</serialnumber> <GUID>7108E15933CA1B4BB776F7BDB4B3F826</GUID> <status>0</status> </sess_end> </arg-xml> </outArgs>

4 - 30 ZEBRA SCANNER SDK FOR LINUX DEVELOPER’S GUIDE

f. SCANNER_UF_STATUS

<?xml version="1.0" encoding="UTF-8"?> <outArgs> <scannerID>1</scannerID> <arg-xml> <sess_info> <modelnumber> DS670-SR20001ZZR </modelnumber> <serialnumber>S/N:7108E15933CA1B4BB776F7BDB4B3F826</serialnumber> <GUID>7108E15933CA1B4BB776F7BDB4B3F826</GUID> <status>506</status> </sess_info> </arg-xml> </outArgs>

After file transfer completes, click Launch to activate (program into the scanner) the new firmware.

Activation takes approximately one minute, during which the scanner blinks the red LED, cannot scan barcodes, and does not respond to network queries. When activation completes, the scanner reboots and turns off the LED, and then emits a power up beep and restarts with the new firmware.

Figure 4-12

Firmware Upgrade Through Bulk (Faster Download Mode) Channel

Zebra Scanner SDK for Linux Scanner SDK for Linux Developer’s Guide (en)

Specifications and Main Features

Frequently Asked Questions

User Manual

Revision History

TABLE OF CONTENTS

ABOUT THIS GUIDE

Introduction

Chapter Descriptions

Notational Conventions

Service Information

Overview

FAQs

Scanner SDK Architecture

Host Communication Modes

Multiple Scanner Device Identification and Asset Tracking

Application Access to Multiple Scanners

Two Applications Connected To One Scanner

Three Applications Connected To Two Scanners

Many Applications Connected To Many Scanners

One Application Connected to Two Scanners

Overview

SDK Components

System Requirements

Supported Operating Systems

Hardware Requirements

Third Party Software Libraries

Scanner Communication Modes

CoreScanner and SDK Installers

Choosing an Installer

RPM and Debian Installer Packages

Installing and Configuring CoreScanner and SDK

Installing RPM Packages

Installing Debian Packages

Installing the Source Tar ball

Verifying CoreScanner and SDK Installation

Installed Components

Configuration

Configure Logging

Configure Udev Options

Configure Client Library Options

Overview

Scanner ID

API Commands

Open

Syntax

Parameters

Return Values

GetScanners

Syntax

Parameters

Return Values

ExecCommand

Syntax

Parameters

Return Values

ExecCommandAsync

Syntax

Parameters

Return Values

Close

Syntax

Parameters

Return Values

API Events

ImageEvent

Syntax

Parameters

VideoEvent

Syntax

Parameters

BarcodeEvent

Syntax

Parameters

PNPEvent

Syntax

Parameters

Samples

ScanRMDEvent

Syntax