POSSUM

Description

POSSUM is a Spring Boot framework Java project designed to present the functionality of all USB-connected POS peripherals that follow the JavaPOS spec (scanners, printer, lane light, line display, cash drawer, check reader, scale, etc.) as web services.

Functionality provided by POSSUM will enable use outside of localhost for use by mobile applications, kiosks, and sharing between point of sale systems to create modern point of sale user experiences.

Team

POSSUM was created by Target Tech as an enterprise scale product to abstract point of sale peripheral hardware into discrete capabilities without regard to the differences between peripheral manufacturers and the implementation of their device drivers. This enables point of sale software developers to create point of sale software without hardware specific knowledge by calling simple web APIs for functions in a consistent manner.

POSSUM enables the following:

✅     Creates operational efficiencies

✅     Simplifies configuration management of retail peripherals

✅     Increases flexibility in the hardware lifecycle events

✅     Promotes competition through the commodification of peripheral devices

✅     Enables software developers to create modern point of sale experiences

Code Organization

Sequence Overview

Getting Started

To fix CORS error (To whitelist new CORS Origins in Developer box)

Add origins to environment CORS_ORIGINS variable separated by a comma (,)

`CORS_ORIGINS=http://localhost:8100,http://localhost:7777`

Running POSSUM Locally

• Click the “Code” dropdown
• Copy the link to the project
• Go to your terminal, then enter "git clone (project link)"
• Enter your credentials (if prompted)
• Once cloned, go to your development environment and click open, and navigate to the project in your finder/folder.
• Ensure the project is configured to build using Java 17
• Once opened, build the project using Gradle commands
• To run POSSUM on your local machine will require spring profile environment variable
• export SPRING_PROFILES_ACTIVE=local
• To run simulator use ./gradlew run -DuseSimulators=true

Running POSSUM on a POS Computer

Requirements:

• Java 17
• POS Hardware drivers (provided by the manufacturer)
• Note: ensure all dependencies for physical POS devices are installed (i.e. libusb for Honeywell scanners)

Verified Supported OS:

• CentOS 7

• Ubuntu

• NOTE: this is a Java application and can run many OS.

• Follow Running POSSUM Locally to ensure you are able to compile and run POSSUM (NOTE: this does not need to be done on a POS computer)

• Install the OS on the POS computer (refer to the Supported OS list above)

• Install Java 17 on POS computer

• Make the following directories:

  • sudo mkdir /opt/target
  • sudo mkdir /opt/target/possum
  • sudo mkdir /opt/target/possum/externalLib

• Compile POSSUM to create a jar file

• Copy jar file and following src/main/resource files from the development machine to the POS computer /opt/target/possum directory

  • devcon.xml
  • devicestarter.sh
  • ECIEncoding.csv
  • IHSParser.csv
  • LabelIdentifiers.csv
  • PossumDeviceManager-1.0.jar

• Install necessary libraries and JPOS drivers for your hardware (i.e. Honeywell scanners require libusb)

• For devices not already supported, update the devcon.xml file

• Launch POSSUM:

  • Navigate to /opt/target/possum
  • To run use sudo domenv=labs sh devicestarter.sh

API Specs

Scanner

URL	Description	Parameters	Response
🟢POST /v1/scanner/reconnect	Reconnects scanners	None	None
🔵GET /v1/scanner/healthstatus	Reports scanners status	None	DeviceHealthResponse
🔵GET /v1/scanner/health	Reports the health of both scanners	None	DeviceHealthResponse
🔵GET /v1/scanner/health/{scannerType}	Reports the health of one scanner	HANDHELD, FLATBED, BOTH	DeviceHealthResponse
🔵GET /v1/scan	Retrieve barcode data from connected scanner	None	Barcode
🔴DELETE /v1/scan	Cancel previously requested scan	None	None
🔵GET /v1/scan/{scannerType}	Retrieve barcode data from one connected scanner	HANDHELD, FLATBED, BOTH	Barcode

Scale

URL	Description	Parameters	Response
🟢POST /v1/scale/reconnect	Reconnects scale	None	None
🔵GET /v1/stableweight	Retrieves stable weight from scale. Use for selling weighted items.	None	FormattedWeight
🔵GET /v1/scale/healthstatus	Reports scale status	None	DeviceHealthResponse
🔵GET /v1/scale/health	Reports scale health	None	DeviceHealthResponse
🔵GET /v1/liveweight	Retrieves current weight from scale. For informational purposes only - DO NOT use for selling.	None	SseEmitter

Printer

URL	Description	Parameters	Response
🟢POST /v1/printer/reconnect	Reconnects printer	None	None
🟢POST /v1/print	Sends entities to attached printer	Receipt Entities*	None
🔵GET /v1/printer/healthstatus	Reports printer status	None	DeviceHealthResponse
🔵GET /v1/printer/health	Reports printer health	None	DeviceHealthResponse

*Includes any combination of BarcodeContent, ImageContent, and TextContent

Line Display

URL	Description	Parameters	Response
🟢POST /v1/linedisplay/reconnect	Reconnects line display	None	None
🟢POST /v1/linedisplay/display	Displays text on 2x20. To clear out a line, omit it from the request.	LineDisplayData	None
🔵GET /v1/linedisplay/healthstatus	Reports line display status	None	DeviceHealthResponse
🔵GET /v1/linedisplay/health	Reports line display health	None	DeviceHealthResponse

Device Availability

URL	Description	Parameters	Response
🔵GET /v1/peripherals	Reports list of attached peripherals	None	DeviceAvailabilityResponse
🔵GET /v1/health	Reports health for all devices	None	DeviceHealthResponse
🔵GET /v1/deviceerror	Reports errors for all devices	None	SseEmitter

Check

URL	Description	Parameters	Response
🔵GET /v1/check	Read data from a check or slip	None	MicrData
🟢POST /v1/check	Print data on a check or slip	CheckPrintData*	None
🔴DELETE /v1/check	Cancel get check data call and/or eject the check from the MICR	None	None
🟢POST /v1/check/reconnect	Reconnect MICR	None	None
🔵GET /v1/check/healthstatus	Reports MICR status	None	DeviceHealthResponse
🔵GET /v1/check/health	Reports MICR health	None	DeviceHealthResponse

*Includes any combination of BarcodeContent, ImageContent, and TextContent

Cash Drawer

URL	Description	Parameters	Response
🟢POST /v1/cashdrawer/reconnect	Reconnect cash drawer	None	None
🟢POST /v1/cashdrawer/open	Opens the cash drawer and waits until the cash drawer is closed before returning	None	None
🔵GET /v1/cashdrawer/healthstatus	Reports cash drawer status	None	DeviceHealthResponse
🔵GET /v1/cashdrawer/health	Reports cash drawer health	None	DeviceHealthResponse

Schemas

DeviceError

{
    code            string
    description     string
}

BarcodeContent

{
    type	    string (enum)
        [ TEXT, BARCODE, IMAGE ]
    data	    string
    barcodeType	    string (enum)
        [ UPCA, UPCE, JAN8, EAN8, JAN13, EAN13, TF, ITF, CODABAR, CODE_39, CODE_93, CODE_128, UPCA_S, UPCE_S, UPCD1, UPCD2, UPCD3, UPCD4, UPCD5, EAN8_S, EAN13_S, EAN128, OCRA, OCRB, CODE_128_PARSED, RSS14, RSS_EXPANDED, GS1DATABAR, GS1DATABAR_E, GS1DATABAR_S, GS1DATABAR_E_S, PDF417, MAXICODE, DATAMATRIX, QRCODE, UQRCODE, AZTEC, UPDF417, OTHER ]
    barcodeAlign    string (enum)
        [ LEFT, CENTER, RIGHT ]
    textLocation    string
        [ NONE, ABOVE, BELOW ]
    height	    integer ($int32)
    width	    integer ($int32)
}

ImageContent

{
    type            string (enum)
        [ TEXT, BARCODE, IMAGE ]
    data                string
    imageFormatType	string (enum)
        [ BMP, JPEG, GIF ]
}

PrinterContent

{
    type    string (enum)
        [ TEXT, BARCODE, IMAGE ]
    data    string
}

TextContent

{
    type    string (enum)
        [ TEXT, BARCODE, IMAGE ]
    data    string
}

PrinterError

{
    code	    string
    description	    string
}

LineDisplayData

{
    line1   string
    line2   string
}

CashDrawerError

{
    code            string
    description	    string
}

SseEmitter

{
    timeout integer ($int64)
}

ScaleError

{
    code            string
    description	    string
}

FormattedWeight

{
    weight  string
}

DeviceHealthResponse

{
    deviceName	    string
    healthStatus    string (enum)
        [ READY, NOTREADY ]
}

Barcode

{
    data    string
    type    string (enum)
        [ UPCA, UPCA_S, UPCE, UPCE_S, UPCD1, UPCD2, UPCD3, UPCD4, UPCD5, EAN8, JAN8, EAN8_S, EAN13, JAN13, EAN13_S, EAN128, TWO_OF_FIVE, INTERLEAVED_TWO_OF_FIVE, CODABAR, CODE39, CODE93, CODE128, OCRA, OCRB, RSS14, RSS_EXPANDED, GS1DATABAR, GS1DATABAR_E, CCA, CCB, CCC, PDF417, MAXICODE, DATAMATRIX, QRCODE, UQRCODE, AZTEC, UPDF417, OTHER, UNKNOWN ]
    source  string (enum)
        [ HANDHELD, FLATBED, BOTH ]
}

DeviceAvailabilityResponse

{
    possumversion    string
    confirmversion  string
    devicelist      DeviceConfigResponse
}

DeviceConfigResponse

{
    devicename	    string
    vidpid	    string
    usbport	    string
    manufacturer    string
    model	    string
    config	    string
    firmware	    string
    serialnumber    string
    isFunctional    boolean
    attached	    boolean
}

MicrError

{
    code            string
    description	    string
}

MicrData

{
    account_number      string
    bank_number         string
    transit_number      string
    raw_data            string
    sequence_number     string
}

Dependencies and External Links

POSSUM as a project leverages JavaPOS standards and service objects. To learn more about JavaPOS follow the links below.

https://www.omg.org/retail/unified-pos.htm

https://github.com/JavaPOSWorkingGroup

https://repo1.maven.org/maven2/org/javapos/javapos/1.14.1/

Supported Devices

Flatbed Scanner

• Datalogic 2300 Scanner
• Datalogic 3550 Scanner
• Datalogic 8200 Scanner
• Datalogic 8400 Scanner Scale
• Datalogic 8400 Scanner
• Datalogic 8405 Scale
• Datalogic 9400 Scanner
• Datalogic 9400 Scanner Scale
• Zebra MP7000 Scanner
• Zebra MP7001 Scanner Scale

Handheld Scanner

• Honeywell 1900/1950 Scanner

MICR

• NCR 7167 MICR

Line Display

• NCR 5975 Line Display Serial
• NCR 5976 Line Display Serial
• NCR 5976 Line Display USB
• NCR 5977 Line Display USB

Receipt Printer

• NCR POS Printer F309
• NCR POS Printer 7167
• NCR POS Printer EPIC 7199
• NCR POS Printer USB 7199

Cash Drawer

• Cash Drawer ELO Computer
• Cash Drawer NCR Computer
• Cash Drawer NCR via printer port