Deployment of Scanner SDK for Linux

Overview

This chapter describes how to install the Zebra Scanner SDK and components on recommended 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 third party 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 OPOS, JPOS, and SNAPI drivers.

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.


SDK Components

The SDK installation package installs the following SDK components to the default locations

  • Zebra Scanner SDK core components and drivers.

    • Zebra core-scanner driver
    • Host communication libraries
    • Client libraries for supporting multiple applications
    • JNI Interface for JPOS
  • 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
    • JPOS Remote-management tool
  • GetAndSet Utility

System Requirements

Supported Linux Distributions

Please refer the supported distribution matrix.

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)

Or if you are using ARM packages, please use a Raspberry pi 3+ device.

Third Party Software Libraries

Table 1: Minimum Software Requirements for CoreScanner Installation

Library / Technology Version Limitation
C++ 98 and 11 standards compatibilities
Libudev 147 or above
GTK (for GUI applications) 2.24.10
Java 6 (JDK 1.6)

Scanner Communication Modes

Refer to the scanner's Product Reference Guide for supported communication modes, and specifically the appendix Functionality Supported via Communication (Cable) Interface for supported scanner functionality by communication protocol.


CoreScanner and SDK Installers

The CoreScanner Version 4.0 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.

Please refer the supported distribution matrix for more details.

Please refer the Step-by-Step Guide to Install and Uninstall Zebra Barcode Scanner SDK for Linux for more details.

Please refer the Install 32-bit CoreScanner and JAVAPOS Packages in a 64-bit Linux Environment to see the instructions to install Zebra 32bit applications on 64bit environment.

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

If you are using Raspberry pi, then you can use the provided Debian package with for ARM processor architecture. For others will have to check whether their system is x86_32bit system or x86_64bit system.

You can use various command methodologies to find your cpu architecture depending on your Linux distribution. As a generic command "lscpu" can be used in most of the Linux distributions.

Figure 1: Distribution Architecture

Linux C11 vs C98: GNU Compiler Collection (GCC) is an optimizing compiler produced by the GNU Project supporting various programming languages, hardware architectures and operating systems. GCC/g++ version 5.3.1 or later has C11 support. GCC prior to 5.3.1 use C98 versions. Command to show the GCC version are gcc --version or g++ --version.

Please refer https://gcc.gnu.org/projects/cxx-status.html to know more about C++ versions.

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 JPOS 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.
  • 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 the 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
    
    

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 an Ubuntu distribution:

    
    zebra-scanner-corescanner 2.0.0-0 amd64 Zebra Technologies Linux Corescanner Daemon
    zebra-scanner-devel 2.0.0-0 amd64 Development files for Zebra Technologies Linux Corescanner
    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 JPOS 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 dependency 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 Tarball

Software/Library requirements for code compilation.

Table 2: Scanner Device Communication Modes Vs. Capabilities

Software / Tool Chain / Library Requirement Minimum Version Required
GCC - GNU Compiler Collection 4.8
Libusb 1
Libusb-dev 1
Libgtk-dev 2.8
Libudev 1
Libudev-dev 1
Make tool N/A
Java standard edition / open-jdk 1.6
Ant java build tool N/A

  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 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 install
    
    
  8. Use make uninstall to remove an existing source tarball installation from the system.

    
    $> make uninstall
    
    

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 3: Zebra Scanner SDK Components

Component File Description Installation Path
CoreScanner cscore Scanner Driver Daemon Service /usr/bin/
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
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 Transport Component /usr/lib/zebra-scanner/corescanner
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 Component /usr/lib/zebra-scanner/javapos/jni
CoreScanner-JNI libcs-jniscanner.so JPOS-JNI Component /usr/lib/zebra-scanner/javapos/jni
CoreScanner-JNI libcs-jniscale.so.4.0.0 JPOS-JNI Component /usr/lib/zebra-scanner/javapos/jni
CoreScanner-JNI libcs-jniscale.so JPOS-JNI Component /usr/lib/zebra-scanner/javapos/jni
JPOS jpostest.sh Start Script for JPOS Test Application /usr/lib/zebra-scanner/javapos/jpos
JPOS dio.sh Start Script for JPOS Direct IO Test Application /usr/lib/zebra-scanner/javapos/jpos
JPOS xml-apis.jar Third party Java library used for JPOS /usr/lib/zebra-scanner/javapos/jpos
JPOS xercesImpl.jar Third party Java library used for JPOS /usr/lib/zebra-scanner/javapos/jpos
JPOS JposTest.jar JPOS sample application /usr/share/zebra-scanner/samples/ jpos-sample-app
JPOS JposTestDio.jar JPOS direct I/O sample application /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
JPOS Remote management JposRemoteManagementTool.jar Remote management application /usr/share/zebra-scanner/remote-management
JPOS Remote management remote-management.sh Remote management executing script /usr/share/zebra-scanner/remote-management
Console Application Makefile Local Make File for Console Application /usr/share/zebra-scanner/samples/ console-app
Console Application ConsoleApplication Execute File of Console Application /usr/share/zebra-scanner/samples/ console-app
Console Application ConsoleSampleEvent Listener.h Console Application Source File /usr/share/zebra-scanner/samples/ console-app
Console Application ConsoleMain.h Console Application Source File /usr/share/zebra-scanner/samples/ console-app
Console Application ConsoleSampleEvent Listener.cpp Console Application Source File /usr/share/zebra-scanner/samples/ console-app
Console Application ConsoleMain.cpp Console Application Source File /usr/share/zebra-scanner/samples/ console-app
Path Verifier Corescanner.conf Path Verifier for CoreScanner Shared Libraries /etc/ld.so.conf.d/
Init Script cscored Systemv Init Script /etc/init.d/
CoreScanner CsBarcodeTypes.h Header files required for application development on top of CoreScanner /usr/include/zebra-scanner
CoreScanner CsUserDefs.h Header files required for application development on top of CoreScanner /usr/include/zebra-scanner
CoreScanner CsIEventListenerXml.h Header files required for application development on top of CoreScanner /usr/include/zebra-scanner
CoreScanner Cslibcorescanner_xml.h Header files required for application development on top of CoreScanner /usr/include/zebra-scanner

Configuration

The corescanner-sdk.conf file located in the directory /etc/zebra-scanner can be used to configure logging, udev options and client library options of CoreScanner and the SDK. See sections Configure Logging, Configure Udev Options and Configure Client Library Options for more details on configuration.

Configure Logging


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

<enable> 1 - enable logging
0 - disable logging
<level> 1 - Desired level of logging ranges from 1 to 5. Default value is 5.
NOTE: All log entries will be in level 5 now.
<dir> The 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 a 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 is reached.

Configure Udev Options


<udev-options>
    <libudev_library_dir></libudev_library_dir>
</udev-options>                                                                        

<libudev_library_dir> Custom udev library path.

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.

Configure Hid Library Options


<hid-library-options>
    <hid_configuration>0</hid_configuration> 
</hid-library-options>                                                                       

<hid_configuration> 0 - Use Hidraw library based implementation to communicate with USB devices.
1 - Use libusb library based implementation to communicate with USB devices.

Configure Scan Avoidance Events


<notification-event>
    <scan_avoidance_as_notification_event>1</scan_avoidance_as_notification_event>   
</notification-event>                                                                        

<scan_avoidance_as_notification_event> 1 - Enable generating scanner notification event for scan avoidances.
0 - disable scan avoidance events.

Configure Command Time Out Values in CoreScanner


<delays>
    <bulk_transfer_timeout>8000</bulk_transfer_timeout>
    <command_response_timeout>20</command_response_timeout> 
</delays>

<bulk_transfer_timeout> Time-out in milliseconds for bulk data writing in SNAPI mode. Default value is 8000.
<command_response_timeout> Time-out in seconds. It is used to determine waiting time period for command responses. Default value is 20.

Configure HIDKB Simulation Settings


<hidkb_simulation>
    <enable>0</enable>  
    <inter_key_delay>10</inter_key_delay>  
</hidkb_simulation>                                                                        

<enable> 1 - Enable HIDKB simulation.
0 - Disable HIDKB simulation.
<inter_key_delay> Character transmission delay in milliseconds. Default value is 10.

Configure Driver Data Formatting (DDF) Settings

DDF enables the formatting of scanned Barcode data with prefix and suffix labels through the CoreScanner driver and has been available since CoreScanner version 3.07.0037. DDF is available when the scanner is in a mode such as USB SNAPI, USB IBM Hand-held and USB IBM Table-top. Unlike Advanced Data Formatting (ADF), DDF does not permit modifying the scanned Barcode data by scanner itself using any rule-based method.

The prefix/suffix labels are composed of one or more ASCII characters (1-255). There can be one or more prefix/suffix labels which are defined in the section governed by the <ddf-tag-def> in the corescanner-sdk.conf file. The <ddf> description is composed of a <ddf-meta> section and a <ddf-select> section. The <ddf-meta> section defines the prefix/suffix labels used in DDF and how they are combined in various ways to compose one or more DDF format definitions in the <ddfdef> tag format.

NOTE: For alt key press, use value 500.


<ddf>
<ddf-meta>
    <ddf-tag-def>suffix1.suffix2.prefix1.prefix3.suffix3</ddf-tag-def>
    <suffix1>13.14</suffix1>
    <suffix2>15.16</suffix2>
    <prefix1>12.11.5.56</prefix1>
    <prefix3>500</prefix3> <!--For alt key press, use value 500. see sample ddf_code 8 -->
    <ddfdef ddf_code='0' ddf_format='data'/>
    <ddfdef ddf_code='1' ddf_format='data.suffix1'/>
    <ddfdef ddf_code='2' ddf_format='data.suffix2'/>
    <ddfdef ddf_code='3' ddf_format='data.suffix1.suffix2'/>
    <ddfdef ddf_code='4' ddf_format='prefix1.data'/>
    <ddfdef ddf_code='5' ddf_format='prefix1.data.suffix1'/>
    <ddfdef ddf_code='6' ddf_format='prefix1.data.suffix2'/>
    <ddfdef ddf_code='7' ddf_format='prefix1.data.suffix1.suffix2'/>
    <ddfdef ddf_code='8' ddf_format='prefix3.data'/>     
</ddf-meta>
<ddf-select>0</ddf-select>
</ddf>

<ddf-tag-def> Prefix/Suffix labels are defined here.
<suffix1>, <prefix3>, ... prefix/suffix labels are defined with one or more ASCII characters (1-255). For alt key press, use value 500.
<ddfdef> Defines DDF format definitions (combinations of Barcode data and predefined suffixes and prefixes).
<ddf-select> Selected DDF format to apply.