Verifone E315 User Manual

e315 Barcode Application

Programmers Guide

VeriFone Part Number DOC087-070-EN-A, Revision A

e315 Barcode Application Programmers Guide

The information contained in this document is subject to change without notice . Although VeriFone has attempted to ensure the accuracy of the contents of this document, this document may include errors or omissions. The examples and sample programs are for illustration only and may not be suited for your purpose. You should verify the applicability of any example or sample p rogram before placing the software into productive use. This document, including without limitation the examples and software programs, is supplied “As-Is.”

VeriFone, the VeriFone logo, Omni, VeriCentre, Verix, and ZonTalk are registered trademarks of VeriFone. Other brand names or trademarks associated with VeriFone’s products and services are trademarks of VeriFone, Inc.

All other brand names and trademarks appearing in this manual are the property of their respective holders. Comments? Please e-mail all comments on this document to your local VeriFone Support Team.

VeriFone, Inc.

2099 Gateway Place, Suite 600

San Jose, CA, 95110 USA

www.verifone.com

VeriFone Part Number DOC087-070-EN-A, Revision A

PREFACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Organization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Assumptions About the Reader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Conventions and Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

CHAPTER 1

Verix Barcode

Application

CHAPTER 2

Barcode APIs Barcode Device Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Host Request Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Response Packet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Valid Host Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Barcode Device Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Barcode Start Scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Barcode Stop Scan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Barcode Passthru. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Barcode Application Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Barcode Trigger Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Beep Immediate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Auto Beep Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Get Auto Beep Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Barcode Button Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Barcode Firmware Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Barcode Restore Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Barcode Picklist Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Barcode Scan Timeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Barcode Timeout – Same Symbol Decodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Barcode Timeout – Different Symbol Decodes . . . . . . . . . . . . . . . . . . . . . . . . . 28

Barcode Continuous Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Barcode Unique Code Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Barcode Mobile Phone/Display Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Barcode Scan Data Prefix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Barcode Scan Data Suffix1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Barcode Scan Data Suffix2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Barcode Scan Data Transmit Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Barcode AIM Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Barcode Symbology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Barcode Disable All Symbologies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

APPENDIX A Beeper Tone Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

sound() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

APPENDIX B Default Parameter Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 3

TABLE OF CONTENTS

APPENDIX C Example Header File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

4 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

PREFACE

This programmer’s manual describes the following features of the Barcode application:

• Provides descriptions of the message packets

• Provides API descriptions and examples

This manual contains explicit information regarding use of these APIs with V/OS and a peripheral or internal scanner.

Organization

Audience

Assumptions About

the Reader

This manual is organized as follows:

CHAPTER 1 Presents an overview of the Barcode application, and host request and

response data packets.

Chapter 2 Presents application APIs. Appendix A Presents beep tone definitions. Appendix B Presents default parameter values. Appendix C Presents an example header file.

This document is of interest to application developers creating applications for use on V/OS-based terminals.

It is assumed that the reader:

• understands Linux programming concepts and terminology.

• has access to a PC running Windows XP or Windows 7.

• has installed the Mentor Sourcery CodeBench DTK and VeriFone SDK on this

machine.

• has access to a running, configured V/OS terminal with the Barcode

application installed.

Conventions and

Acronyms

Abbreviation Definition

bps bits per second Hz Hertz LSB least-significant bit MSB most-significant bit msec millisecond V/OS VeriFone Operating System VRK VeriShield Remote Key VSS VeriShield Security Scripts

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 5

PREFACE

Verix Barcode Application

HOST REQUEST PACKET IN BYTES

COMMAND PACKET BYTES

211

OPTIONAL PARAMETER PACKETS 1...n

1 1 VARIABLE

REQUEST

LENGTH

SEQUENCE

REQUEST

VERSION

PROTOCOL

COMMAND

LENGTH

COMMAND

NUMBER

PARAMETER

LENGTH

RESPONSE PACKET (BYTES)

4 4 4 VARIABLE

RESPONSE

LENGTH

SEQUENCE

RESPONSE

STATUS

OPTIONAL

RESPONSE

DATA

PARAMETER

VALUE

NOTE

The Host Control Interface defines the message packet format between the host application on the phone and the Verix Barcode application. These message packets reflect an encapsulated data field between the host application and the Verix Barcode application.

Figure 1 illustrates the host request and response packet length and sequence. The maximum size of the host request and response packets are 2048 bytes.

CHAPTER 1

Figure 1 Host Request and Response Packet Format

The sequence number is in the packet header before the payload, and is generated by the host device. It is used for proper handshaking and error handling.

Reference this manual with the header file Barcode_host.h.

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 7

VERIX BARCODE APPLICATION

Host Request Packet

Host Req uest

Packet

As shown in Figure 1, the Host Request packet is comprised of the following data packets:

• Request Length–The total size of the host request packet, including this

packet (maximum 2048 bytes).

• Request Sequence–Supplied by the host and unique per command, each

response packet sequence number is linked to the sequence number of the Request packet. However, asynchronous Response packets have random sequence numbers. Asynchronous responses are sent after the following events:

• A successful barcode scan

• A button change-status notification are sent in edge, level, and soft trigger

mode

• Command Packet–This structure comprises the command length, protocol

version, command number, and parameter packets.

• Parameter Packet–There are a variable number of Parameter packets in the

Command packet. The format of the Parameter packet is parameter length, parameter ID, and parameter value.

Response

Packet

Multiple parameter packets can be sent in the same Host Request packet, which is useful for sending more than one symbology configuration in a single Command packet.

The Response packet is comprised of the following data packets:

• Response Length–The total size of host response packet (maximum 2048

bytes).

• Response Sequence–This is usually the sequence number that the host

supplied in a Request packet. However, asynchronous responses have a random sequence number, which cannot be related to the request sequence number.

• Response Status–The process status of the previous request:

• 0x00000000 = Success

• 0x00000001 = Failure

• 0x80000000= Asynchronous scanned data

• 0x80000001= Asynchronous buttons change status

Sometimes when response data is available immediately, the data and status are sent in a single response packet.

• Response Data (optional)–Some responses have optional data with the status

update.

8 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

VERIX BARCODE APPLICATION

BARCODE SCAN DATA (BYTES)

444112 VARIABLE

LENGTH

SEQUENCE CODE ID

STATUS AIM ID

SYMBOL

NAME

LENGTH

SEQUENCE

STATUS

BUTTON

STATUS

SCAN DATA

BUTTON CHANGE STATUS (BYTES)

4441

Figure 2 illustrates the data format of asynchronous responses:

Valid Host Requ ests

Figure 2 Asynchronous Response Packet Format

Valid Host

Requests

The following lists valid host request calls:

• BAR_DEV_OPEN • BAR_DEV_CLOSE

• START_SCAN • STOP_SCAN

• PASS_THRU • GET_APP_VER

• SET_TRIG_MODE • BEEP_IMMEDIATE

• AUTO_ BEEP_CONFIG • GET_AUTO_BEEP_CONFIG

• BUTTON_STATUS • GET_FIRM_VER

• RESTORE_DEFAULTS • EN_PICKLIST_MODE

• SCAN_TIMEOUT • TIMEOUT_BW_SAME_SYM

• TIMEOUT_BW_DIFF_SYM • EN_CONTINUOUS_RD

• EN_UNIQUE_CODE_REPO • EN_MOBILE_PH_MODE

• EN_PREFIX • EN_SUFFIX1

• EN_SUFFIX2 • EN_XMIT_FMT

• EN_AIM_PATTERN • SYMBOLOGY

• DISABLE_ALL_SYMB •

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 9

VERIX BARCODE APPLICATION

Valid Host Requests

10 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

Barcode APIs

NOTE

Barcode Device Open

Powers barcode device and opens the communication port for communication.

This command must be sent before sending any other command.

Example

CHAPTER 2

Length (4 bytes)

0x0C – 0x04 0x01 BAR_DEV_OPEN

Sequence (4 bytes) Length (2 bytes) Protocol V ersion (1 byte)

Raw data in hex format (MSB to LSB): 0x0000000C000000010004011A

Command# (1 byte)

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 11

BARCODE APIS

Barcode Device Close

Powers down the barcode device and closes the communication port.

Example

Length (4 bytes)

0x0C – 0x04 0x01 BAR_DEV_CLOSE

Sequence (4 bytes) Length (2 bytes) Protocol V ersion (1 byte)

Command# (1 byte)

Raw data in hex format (MSB to LSB): 0x0000000C000000010004011B

12 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

Barcode Start Scan

NOTE

BARCODE APIS

Barcode Start Scan

Activates the scan by sending a START_SCAN command to the barcode reader. The host initially waits for an ACK/NAK response for this command. After receiving the ACK, the host waits for an asynchronous scan data response packet. Besides soft and passive trigger modes, edge and level trigger modes require START_SCAN to activate the barcode button(s).

The ACK response is null, but a 0x00 status value is in the response packet. The NAK response is null, but a 0x01 status value is in the response packet.

Example

Length (4 bytes)

0x0C – 0x04 0x01 START_SCAN

Sequence (4 bytes) Length (2 bytes) Protocol Ve rsion (1 byte)

Command# (1 byte)

Raw data in hex format (MSB to LSB): 0x0000000C0000000100040101

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 13

BARCODE APIS

Barcode Stop Scan

Deactivates scanner by sending a STOP_SCAN command to the barcode reader . The host receives an ACK/NAK response packet for this command.

Example

Length (4 bytes)

0x0C – 0x04 0x01 STOP_SCAN

Sequence (4 bytes) Length (2 bytes) Protocol Ve rsion (1 byte)

Command# (1 byte)

Raw data in hex format (MSB to LSB): 0x0000000C0000000100040102

14 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

Barcode Passthru

BARCODE APIS

Barcode Passthru

Reserved

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 15

BARCODE APIS

Barcode Application Version

Returns a null-terminated 6-byte ASCII version ID for the barcode reader.

Example

Length (4 bytes)

0x0C – 0x04 0x01 GET_APP_VER

Sequence (4 bytes) Length (2 bytes) Protocol V ersion (1 byte)

Command# (1 byte)

Raw data in hex format (MSB to LSB): 0x0000000C0000000100040104

16 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

Barcode Trigger Mode

NOTE

Sets the barcode trigger mode using the 1-byte (8-bit) parameter value. The terminal reverts to the default Level mode at every terminal power cycle and restart.

• The EDGE parameter enables Edge Trigger mode, where the scan session

• The LEVEL parameter enables Level Trigger mode, where the scan session

• The SOFT parameter enables Soft Trigger mode, where the host device

BARCODE APIS

Barcode Trigger Mode

starts when the barcode button(s) is pressed and released, and stays on until the timeout period expires or the barcode button(s) is pressed again and released.

starts when the barcode button(s) is pressed, and stays on until the button is released. The scan session turns off automatically when the specified timeout period is reached.

issues a command to start the scan session, and the barcode button(s) have no control during the scan session.

• The PASSIVE parameter enables Passive Trigger mode that behaves the

same as Soft Trigger mode, except th at a BUTT ON_STATUS command is not initiated. Button status is obtained by the host using the BUTT ON_STATUS command.

In Edge and Level Trigger modes, the START_SCAN command activates barcode buttons, and the STOP_SCAN command deactivates barcode buttons.

• By default, Continuous mode is enabled. If Continuous mode is disabled, a

single scan mode is enabled, where this mode scan session is turned off after one successful barcode scan or when the timeout period expires.

Prototype

enum {

EDGE = 0, LEVEL, SOFT, PASSIVE

};

Example

Length (4 bytes)

0x0F – 0x07 0x01 SET_TRIG_MODE

Length (1 byte) I D (1 byte) V alue (1 byte)

Sequence (4 bytes) Length (2 bytes) Protocol Ve rsion (1 byte)

0x03 PID_SET_TRIG_MODE 0x00-0x03

Command# (1 byte)

Raw data in hex format (MSB to LSB): 0x0000000F000000010007010503FE01

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 17

BARCODE APIS

BEEP FORMAT (BYTES)

1 SIZE OF BEEP DEFINITION

NUMBER OF

BEEP 1 ... BEEP 6

BEEPS

FREQUENCY

DURATION

PAUSE

BEEP DEFINITION (BYTES)

444

Beep Immediate

Beep

Immediate

Provides beep parameters for an immediate beep sequence. Specify the parameter value in the beep format shown below . This format requires the number of beeps (maximum of 6) followed by the values in the beep definition. Setting the beep frequency to zero disables beeping. See Appendix A for the supported range of beep frequencies.

Figure 3 Beep Command Packet

Example

Length (4 bytes)

? – ? 0x01 BEEP_IMMEDIATE

Length (1 byte) ID V alue (size of T_BEEP)

? PID_BEEP_IMMEDIATE V alue in BEEP FORMAT

Sequence (4 bytes) Length (2 bytes) Protocol Version (1 byte)

Command# (1 byte)

18 E315 BARCODE APPLICATION PROGRAMMERS GUIDE

Auto Beep Configuration

FREQUENCY

DURATION

BEEP (BYTES)

BEEP 1

PAUSE

BEEP 2

T_BEEP_DEF (BYTES) 848

(SIZE OF BEEP)

NOTE

Enables and disables auto beep. When enabled, the terminal beeps after a successful scan and when an error is detected. This API also allows scan beep and error beep parameter configuration.

This API requires up to three input parameters. The first parameter is in seque ntial order and must always be beep mode. The second parameter can be either a scan beep or an error beep, depending on how beep mode is set. The third parameter is an error beep when beep mode is set to 3.

Valid values for beep mode are 0, 1, 2, and 3:

• 0 = auto beep disabled

• 1 = auto beep enabled; configures scan beeps only

• 2 = auto beep enabled; configures error beeps only

• 3 = auto beep enabled; configures both scan and error beeps

BARCODE APIS

Auto Beep Configuration

Only one parameter is required in the Command packet to disable or enable auto beep. T wo p arameters are required t o configure either scan be eps or error beep s. Three parameters are required to configure both scan and error beeps.

Figure 4 Beep Packet Definitions

Default Values

Default auto beep configuration settings are enforced at terminal power cycle and restart.

Frequency 64 (2217 Hz) Frequency 58 (1568 Hz) Duration 50 msec Duration 100 msec Pause 5 0 msec Pause 75 msec Frequency 50 (988 Hz) Frequency 50 (988 Hz) Duration 50 msec Duration 100 msec

Scan Beep Error Beep

E315 BARCODE APPLICATION PROGRAMMERS GUIDE 19

+ 43 hidden pages

Verifone E315 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

TABLE OF CONTENTS

PREFACE

Organization

Audience

Related Documentation

Verix Barcode Application

Host Request Packet

Valid Host Requ ests

Barcode APIs

Barcode Device Open

Barcode Device Close

Barcode Start Scan

Barcode Stop Scan

Barcode Passthru

Barcode Application Version

Barcode Trigger Mode

Beep Immediate

Auto Beep Configuration