powapos opos-jpos support v1.0 20151015powaposdeveloper.net/.../powapos-opos-jpos-support... ·...
TRANSCRIPT
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
26/10/2015 © 2015 Powa Technologies Page 2 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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
26/10/2015 © 2015 Powa Technologies Page 3 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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.
26/10/2015 © 2015 Powa Technologies Page 4 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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.
26/10/2015 © 2015 Powa Technologies Page 5 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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.
The following table identifies the supported specific properties.
Property Type State Value
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
26/10/2015 © 2015 Powa Technologies Page 6 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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
26/10/2015 © 2015 Powa Technologies Page 7 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
Property Type State Value
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
26/10/2015 © 2015 Powa Technologies Page 8 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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)
26/10/2015 © 2015 Powa Technologies Page 9 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
Property Type State Value
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
26/10/2015 © 2015 Powa Technologies Page 10 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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)
26/10/2015 © 2015 Powa Technologies Page 11 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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.
The following table identifies the supported specific properties.
Property Type State Value
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
26/10/2015 © 2015 Powa Technologies Page 12 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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”
26/10/2015 © 2015 Powa Technologies Page 13 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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
26/10/2015 © 2015 Powa Technologies Page 14 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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):
26/10/2015 © 2015 Powa Technologies Page 15 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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.
26/10/2015 © 2015 Powa Technologies Page 16 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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.
26/10/2015 © 2015 Powa Technologies Page 17 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
5.3 C# Code Snippet – Printer
The following is an example on how to use the Printer.
26/10/2015 © 2015 Powa Technologies Page 18 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
5.4 C# Code Snippet – Scanner
The following is an example on how to use the S10 Scanner.
26/10/2015 © 2015 Powa Technologies Page 19 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
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.
26/10/2015 © 2015 Powa Technologies Page 20 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
6.2 Java Code Snippet – Printer
The following is an example on how to use the Printer.
26/10/2015 © 2015 Powa Technologies Page 21 of 21 PowaPOS OPOS-‐JPOS Support V1.0 20151015.docx
Confidentiality status: Contracted Customer or Partner only – Not for recirculation
6.3 Java Code Snippet – Scanner
The following is an example on how to use the S10 Scanner.