PowaPOS OPOS-JPOS Support V1.0 20151015powaposdeveloper.net/.../PowaPOS-OPOS-JPOS-Support... · 10/15/2015 · 26/10/2015! ©!2015PowaTechnologies! Page1!of!21!! PowaPOSOPOS9JPOS!SupportV1.0!20151015.docx!

PowaPOS OPOS and JPOS Support Functional Specification Document Version 1.0

Document Date: 15 Oct 2015

26/10/2015 © 2015 Powa Technologies Page 1 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx

Confidentiality status: Contracted Customer or Partner only – Not for recirculation

Document Control

Version and Date

Revisions Document Owner

Version 1.0 15 Oct, 2015

First release based on uPOS 1.14.1 specification. Ben Scott, Jossuan Martell, Miguel Silva



Table of Contents

1 Introduction ........................................................................................................................................ 3

1.1 Terms and Concepts .................................................................................................................... 3

2 Architecture Overview ........................................................................................................................ 4

3 Powa Supported Devices .................................................................................................................... 5

3.1 Cash Drawer ................................................................................................................................. 5

3.2 POS Printer ................................................................................................................................... 5

3.3 Scanner (Bar Code Reader) ........................................................................................................ 11

4 Installation ........................................................................................................................................ 11

4.1 Hardware and Software Requirements ..................................................................................... 11

4.2 Installing the T-‐Series Windows USB Device Driver ................................................................... 11

4.3 Installing the T-‐Series OPOS and JPOS Package ......................................................................... 12

4.4 Configuring and Verifying the OPOS Service Objects ................................................................ 13

4.5 Configuring and Verifying the JPOS Service Classes .................................................................. 14

5 Creating an OPOS Sample Application .............................................................................................. 16

5.1 System Requirements ................................................................................................................ 16

5.2 C# Code Snippet – Cash Drawer ................................................................................................ 16

5.3 C# Code Snippet – Printer .......................................................................................................... 17

5.4 C# Code Snippet – Scanner ........................................................................................................ 18

6 Creating a JPOS Sample Application ................................................................................................. 19

6.1 Java Code Snippet – Cash Drawer .............................................................................................. 19

6.2 Java Code Snippet – Printer ....................................................................................................... 20

6.3 Java Code Snippet – Scanner ..................................................................................................... 21



1 Introduction This document describes PowaPOS support for OPOS (Pos for .net) and JPOS interfaces to the T-‐Series product line. The solution aims to be a bridge between the UPOS standard (version 1.14.1) and the supported capabilities of the T-‐Series devices. The intended audience for this document is system designers and application developers who wish to integrate the T-‐Series in their mobile commerce architecture.

1.1 Terms and Concepts

The following table describes the terms and acronyms found across the document.

Term Acronym Description Application Programming Interface

API A set of calling conventions that defines how a service is invoked through software. An API enables programs written by users or third parties to communicate with certain vendor-‐supplied software.

International Organisation for Standardisation

ISO An international body whose members are national standards bodies and which approves, develops and publishes international standards.

Point of Sale POS The terminal where the customer and card acceptor are located at the time a card is used for purchase or cash.

Java POS JPOS JPOS is a free and open source framework to support integration of multiple devices generally used in the POS retailing environment.

Ole for POS OPOS OPOS is a platform specific implementation of UnifiedPOS. It is intended for Microsoft operating systems.

Ole for POS (.net) OPOS for .net

Similar to OPOS but supported on the Microsoft .net framework.

UnifiedPOS UPOS UPOS is an open standard supported by multiple vendors in the ARTS consortium. It aims at providing a common standard API for the retailing peripherals.

Independent Software Vendor

ISV Is an organization specializing in making or selling software, designed for mass or niche markets.

Software Development Kit SDK Allows for easier integration of a software set of functionalities.



2 Architecture Overview The following diagram illustrates the main logical components and how they relate in the overall PowaPOS architecture.

ISV App (OPOS control) Represents the customer application that uses the OPOS interface directly. This application is a native windows application. ISV App (JPOS control) Represents the customer application that uses the JPOS interface directly. This application is a Java application. PowaPOS JPOS Service Classes Represents the required Java functionality provided by PowaPOS to support the JPOS interface and adaptation to the OPOS Service Objects. PowaPOS OPOS Service Objects Represents the required windows functionality provided by PowaPOS to support the OPOS interface and the adaptation to the native PowaPOS T-‐Series SDK. PowaPOS T-‐Series SDK Represents the native SDK that controls the existing functionality on the T-‐Series.



3 Powa Supported Devices The following sections describe the existing support for the T-‐Series peripherals. The description is made according to the UPOS specification and highlights which features are supported.

The notation uses the following abbreviations for the State column: O – Open E – Enabled C – Claimed

3.1 Cash Drawer

The Cash Drawer device interface wraps the T-‐Series Cash Drawer functionality.

The following table identifies the supported specific properties.

Property Type State Value

CapStatus boolean O True CapStatusMultiDrawerDetect boolean O False DrawerOpened boolean O, E (Variable)

The following table identifies the supported specific methods.

Method Type State Supported? openDrawer ( ) void O, E Yes

waitForDrawerClose ( beepTimeout: int32, beepFrequency: int32, beepDuration: int32, beepDelay: int32 )

void O, E No

3.2 POS Printer

The POS Printer device interface wraps the T-‐Series Printer functionality. This implementation is compatible with the Receipt station only.



CapCharacterSet int32 O PTR_CCS_UNICODE CapConcurrentJrnRec boolean O False

CapConcurrentJrnSlp boolean O False CapConcurrentPageMode boolean O False

CapConcurrentRecSlp boolean O False

CapCoverSensor boolean O True CapMapCharacterSet boolean O False



Property Type State Value CapTransaction boolean O True

CapJrnPresent boolean O False

CapJrn2Color boolean O False CapJrnBold boolean O False

CapJrnDhigh boolean O False

CapJrnDwide boolean O False CapJrnDwideDhigh boolean O False

CapJrnEmptySensor boolean O False

CapJrnItalic boolean O False CapJrnNearEndSensor boolean O False

CapJrnUnderline boolean O False

CapJrnCartridgeSensor int32 O 0 CapJrnColor int32 O 0 CapRecPresent boolean O True

CapRec2Color boolean O False CapRecBarCode boolean O True CapRecBitmap boolean O True CapRecBold boolean O False

CapRecDhigh boolean O False CapRecDwide boolean O False

CapRecDwideDhigh boolean O True CapRecEmptySensor boolean O True CapRecItalic boolean O False

CapRecLeft90 boolean O False CapRecNearEndSensor boolean O False

CapRecPapercut boolean O False

CapRecRight90 boolean O True CapRecRotate180 boolean O True

CapRecStamp boolean O False

CapRecUnderline boolean O True CapRecCartridgeSensor int32 O 0

CapRecColor int32 O 0

CapRecMarkFeed int32 O 0 CapRecPageMode boolean O False

CapRecRuledLine int32 O 0




CapSlpPresent boolean O False

CapSlpFullslip boolean O False CapSlp2Color boolean O False

CapSlpBarCode boolean O False

CapSlpBitmap boolean O False CapSlpBold boolean O False

CapSlpDhigh boolean O False

CapSlpDwide boolean O False CapSlpDwideDhigh boolean O False

CapSlpEmptySensor boolean O False

CapSlpItalic boolean O False CapSlpLeft90 boolean O False

CapSlpNearEndSensor boolean O False

CapSlpRight90 boolean O False CapSlpRotate180 boolean O False CapSlpUnderline boolean O False CapSlpBothSidesPrint boolean O False

CapSlpCartridgeSensor int32 O 0 CapSlpColor int32 O 0

CapSlpPageMode boolean O False CapSlpRuledLine int32 O 0 AsyncMode boolean O True

CartridgeNotify int32 O 0 CharacterSet int32 C, E PTR_CS_UNICODE

CharacterSetList string O 997

CoverOpen boolean C, E (Variable) ErrorLevel int32 O (Variable)

ErrorStation int32 O PTR_S_RECEIPT

ErrorString string O (Variable) FontTypefaceList string O ANK_8X16, ANK_12X24,

ANK_16X16, ANK_24X24, ANK_32X16, ANK_16X32, ANK_32X32, ANK_48X24, ANK_24X48, ANK_48X48

FlagWhenIdle boolean O False MapCharacterSet boolean O False

MapMode int32 O PTR_MM_DOTS



Property Type State Value PageModeArea string O 0

PageModeDescriptor int32 O 0

PageModeHorizontalPosition int32 O 0 PageModePrintArea string O (empty)

PageModePrintDirection int32 O 0

PageModeStation int32 O 0 PageModeVerticalPosition int32 O 0

RotateSpecial int32 O 0

JrnLineChars int32 C, E 0 JrnLineCharsList string O 0

JrnLineHeight int32 C, E 0

JrnLineSpacing int32 C, E 0 JrnLineWidth int32 C, E 0 JrnLetterQuality boolean C, E False

JrnEmpty boolean C, E False JrnNearEnd boolean C, E False JrnCartridgeState int32 C, E 0 JrnCurrentCartridge int32 C, E 0

RecLineChars int32 C, E (Variable) RecLineCharsList string O 48,32,24,16

RecLineHeight int32 C, E (Variable) RecLineSpacing int32 C, E (Variable) RecLineWidth int32 C, E 576

RecLetterQuality boolean C, E False RecEmpty boolean C, E (Variable)

RecNearEnd boolean C, E False

RecSidewaysMaxLines int32 C, E (Variable) RecSidewaysMaxChars int32 C, E (Variable)

RecLinesToPaperCut int32 C, E 0

RecBarCodeRotationList string O (empty) RecBitmapRotationList string O (empty)

RecCartridgeState int32 C, E 0

RecCurrentCartridge int32 C, E 0 SlpLineChars int32 C, E 0

SlpLineCharsList string O (empty)




SlpLineHeight int32 C, E 0

SlpLineSpacing int32 C, E 0 SlpLineWidth int32 C, E 0

SlpLetterQuality boolean C, E False

SlpEmpty boolean C, E False SlpNearEnd boolean C, E False

SlpSidewaysMaxLines int32 C, E 0

SlpSidewaysMaxChars int32 C, E 0 SlpMaxLines int32 C, E 0

SlpLinesNearEndToEnd int32 C, E 0

SlpBarCodeRotationList string O (empty) SlpBitmapRotationList string O (empty)

SlpPrintSide int32 C, E 0

SlpCartridgeState int32 C, E 0 SlpCurrentCartridge int32 C, E 0

The following table identifies the supported specific methods.

Method Type State Supported? beginInsertion ( timeout: int32 ) void O, C, E No

beginRemoval ( timeout: int32 ) void O, C, E No changePrintSide ( side: int32 ) void O, C, E No

clearPrintArea ( ) void O, C, E No

cutPaper ( percentage: int32 ) void O, C, E No drawRuledLine ( station: int32, positionList: string, lineDirection: int32, lineWidth: int32, lineStyle: int32, lineColor: int32 )

void O, C, E No

endInsertion ( ) void O, C, E No

endRemoval ( ) void O, C, E No

markFeed ( type: int32 ) void O, C, E No

pageModePrint ( control: int32 ) void O, C, E No printBarCode ( station: int32, data: string, symbology: int32, height: int32, width: int32, alignment: int32, textPosition: int32 )

void O, C, E Yes

printBitmap ( station: int32, fileName: string, width: int32, alignment: int32 )

void O, C, E Yes

printImmediate ( station: int32, data: string ) void O, C, E No printMemoryBitmap (station: int32, data: binary, type: int32, width: int32, alignment: int32)

void O, C, E Yes



printNormal ( station: int32, data: string ) void O, C, E Yes

printTwoNormal ( station: int32, data1: string, data2: string )

void O, C, E No

rotatePrint ( station: int32, rotation: int32 ) void O, C, E No setBitmap ( bitmapNumber: int32, station: int32, fileName: String, width: int32, alignment: int32 )

void O, C, E Yes

setLogo ( location: int32, data: string ) void O, C, E No

transactionPrint ( station: int32, control: int32 ) void O, C, E Yes validateData ( station: int32, data: string ) void O, C, E Yes

The following table describes the supported escape sequences:

Action Sequence Description Feed lines ESC |[#]lF

Feed the paper forward by lines. The placeholder ‘#’ is replaced by an ASCII decimal string telling the number of lines to be fed. If ‘#’ is omitted, then one line is fed.

Print stored bitmap ESC |#B

Prints the pre-‐stored bitmap. The placeholder ‘#’ is replaced by the bitmap number. See setBitmap method. If the given bitmap number has not been set successfully by the setBitmap method then the printing results may be unpredictable.

Font typeface selection ESC |#fT

Selects a new typeface for the following data. Values for the placeholder ‘#’ are: 0 = Default typeface. 1 = Select first typeface from the FontTypefaceList property. 2 = Select second typeface from the FontTypefaceList property. And so on.

Underline ESC |[!][#]uC

Prints with underline. The placeholder ‘#’ is not supported therefore the default thickness is used.

Reverse video ESC |[!]rvC Prints in a reverse video format. If ‘!’ is specified then reverse video is disabled.

Double high and wide ESC |1C Prints double-‐high/double-‐wide characters. Normal ESC |N Restores printer characteristics to normal

condition.

The following table describes the supported bar codes:

Bar Code Type Data Size PTR_BCS_UPCA Fixed(11 ≤ n ≤ 12) PTR_BCS_UPCE Fixed(11 ≤ n ≤ 12) PTR_BCS_EAN8 Fixed(7 ≤ n ≤ 8)



PTR_BCS_EAN13 Fixed(12 ≤ n ≤ 13) PTR_BCS_Code39 Variable PTR_BCS_ITF Variable PTR_BCS_Code128 Variable

3.3 Scanner (Bar Code Reader)

The Scanner device interface wraps the T-‐Series S10 Scanner functionality.



DecodeData boolean O (Variable)

ScanData binary O (Variable)

ScanDataLabel binary O (Variable)

ScanDataType Int32 O SCAN_SDT_UNKNOWN

Note: The ScanData property contains the raw data received from the scanner and ScanDataLabel contains the converted data.

4 Installation The following sections detail the installation procedures for the Powa OPOS and JPOS support.

4.1 Hardware and Software Requirements

Any PC, Laptop or Tablet running Microsoft Windows 7, 8.1 or 10 with version 4.5.1 (or above) of the Microsoft .NET Framework and Microsoft POS for .NET version 1.14 installed.

Important Note: the JPOS Service Classes rely on their OPOS equivalents and the Microsoft .NET Framework (see Section 2 Architecture Overview – above). It is therefore always necessary to install the T-‐Series OPOS Service Objects (and their dependencies) even if you wish to only use the JPOS Service Classes.

4.2 Installing the T-‐Series Windows USB Device Driver

The T-‐Series Windows USB Device Driver must be installed to enable communication between the Windows device and the T-‐Series.

To install the T-‐Series Windows USB Device Driver do the following:

1) Locate the “PowaPoS_T25.inf” and “PowaPOS_T25.cat” files in a directory on your machine



2) Right click on the “PowaPOS_T25.inf” file and select “Install” 3) If you receive a Security Warning, click “Open” and “Allow the programme to make changes

to this computer” 3) When prompted select “Install” to complete the installation of the device driver supplied by “Smart Business Technology, Inc”

4) You should receive a final pop up stating that “The operation completed successfully”. Click “OK”

5) Plug your PowaPOS T-‐Series device into any USB port on your Windows device and power on the T-‐Series

6) Run the “Device Manager” Windows utility and confirm that under “Universal Serial Bus Devices” you can see an entry for PowaPOS T25

4.3 Installing the T-‐Series OPOS and JPOS Package

Important Note: the JPOS Service Classes rely on their OPOS equivalents and the Microsoft .NET Framework (see Section 2 Architecture Overview – above). It is therefore always necessary to install the T-‐Series OPOS Service Objects (and their dependencies) even if you wish to only use the JPOS Service Classes.

To install the T-‐Series OPOS Service Objects and JPOS Service Classes do the following:

1) Ensure version 4.5.1 (or above) of the Microsoft .NET Framework is installed (available from www.microsoft.com)

2) Ensure version 1.14 of the Microsoft POS for .NET is installed (available from www.microsoft.com)

3) Ensure Windows Update has applied the fix reported in KB2959943 (otherwise the exception ‘POSControlException ErrorCode(Timeout) ExtendedErrorCode(0) occurred’ will be generated when you attempt to use the T-‐Series Service Objects concurrently

4) Locate and launch the “PowaPOS OPOS JPOS” installer

5) Select “Next”



6) Confirm the folder that the files will be installed. Select “Install”

7) After a few seconds the installation will be confirmed as complete. Click “Finish” to exit the

installation

4.4 Configuring and Verifying the OPOS Service Objects

Once the install has completed, three new Service Objects (contained with the PowaPOSServiceObjects.dll) are available to applications:

• PowaPOS T-‐Series CashDrawer • PowaPOS T-‐Series Printer • PowaPOS T-‐Series S10 Scanner



Each device should be assigned to be the “Default” and/or assigned a Logical Name. There are numerous ways to configure POS for .NET Service Objects but a common method is to use the Service Object Manager developed and maintained by Sean Liming (www.seanliming.com).

The Service Objects can be tested using a Microsoft POS Tester (TestApp.exe – which is available as part of the POS for .NET SDK).

Before running the POS Tester it is recommended that the T-‐Series is connected to the host device and powered on. If an S10 Scanner is being used it should have previously been paired to the host device.

Having configured and verified the Service Objects, advice on creating a sample application is provided in section 5 below.

4.5 Configuring and Verifying the JPOS Service Classes

Once the install has completed, three new Service Classes (representing the Cash Drawer, Printer and Scanner) and a shared Factory Class (contained with the PowaPOSServiceClassses.jar) are available to applications.

Important Note: Before continuing the Java Runtime Environment (version 1.6 or later) should be installed along with JavaPOS v1.14 (available from www.javapos.com).

To test the Service Classes it is recommended that the JavaPOS Device Tester application (POSTest) is used. This application can be downloaded from www.sourceforge.net. Care should be taken to ensure that the POSTest application is using jpos114.jar and not an earlier version (this can be verified by viewing/editing the ClassPath in the postest.bat file included in the distribution).

Before running the POSTest application it is necessary to add the PowaPOSServiceClasses.jar file to the ClassPath and update the jpos.xml file to contain the following entries (the Logical Names are customisable):



Upon running the POSTest application it is possible to review the Configured Devices by selecting the Configured Devices tab.

The individual devices (i.e. CashDrawer, POSPrinter and Scanner) can then be verified using the appropriate tabs and standard UPOS functions.

Before running POSTest it is recommended that the T-‐Series is connected to the host device and powered on. If an S10 Scanner is being used it should have previously been paired to the host device.

Having configured and verified the Service Classes, advice on creating a sample application is provided in section 6 below.



5 Creating an OPOS Sample Application The following sections contain sample code to illustrate the use of the OPOS support in .net.

5.1 System Requirements

Any PC or Laptop running Microsoft Windows 7, 8.1 or 10 with Microsoft Visual Studio 2013 (or above), the Microsoft .NET Framework version 4.5.1 (or above) and Microsoft POS for .NET version 1.14 installed. The namespace Microsoft.PointofService must be referenced in all examples.

5.2 C# Code Snippet – Cash Drawer

The following is an example of how to use the Cash Drawer.



5.3 C# Code Snippet – Printer

The following is an example on how to use the Printer.



5.4 C# Code Snippet – Scanner

The following is an example on how to use the S10 Scanner.



6 Creating a JPOS Sample Application The following sections illustrate how to use the supported peripherals in Java.

6.1 Java Code Snippet – Cash Drawer

The following is an example on how to use the Cash Drawer.



6.2 Java Code Snippet – Printer

The following is an example on how to use the Printer.



6.3 Java Code Snippet – Scanner

The following is an example on how to use the S10 Scanner.

Documents

PowaPOS OPOS-JPOS Support V1.0 20151015powaposdeveloper.net/.../PowaPOS-OPOS-JPOS-Support... · 10/15/2015 · 26/10/2015! ©!2015PowaTechnologies! Page1!of!21!! PowaPOSOPOS9JPOS!SupportV1.0!20151015.docx!