Android SSP API

Innovative Technology LTD

Android SSP library

A library API for using ITL SSP protocol to connected devices

Version 0.0.3
Android SSP API

Contents

Version History........................................................................................................................................ 3
Introduction ............................................................................................................................................ 4
Description .............................................................................................................................................. 5
Serial Communications ........................................................................................................................... 6
Use ...................................................................................................................................................... 7
API functions ........................................................................................................................................... 8
SetAddress .......................................................................................................................................... 8
DisableDevice ...................................................................................................................................... 8
EnableDevice ....................................................................................................................................... 8
EscrowMode ....................................................................................................................................... 9
SetBillEscrowAction ............................................................................................................................ 9
SetESSPMode .................................................................................................................................... 10
SetBarcodeConfig.............................................................................................................................. 10
SetPayoutRoute ................................................................................................................................ 11
PayoutAmount .................................................................................................................................. 11
FloatAmount ..................................................................................................................................... 12
EmptyPayout ..................................................................................................................................... 12
GetDownloadState ............................................................................................................................ 13
GetComsConfig ................................................................................................................................. 14
SetComsBufferWritten...................................................................................................................... 15
GetNewData...................................................................................................................................... 15
ProcessResponse............................................................................................................................... 15
SetDownload ..................................................................................................................................... 16
GetBillPositions ................................................................................................................................. 17
BillPayoutAction ................................................................................................................................ 17

Version 0.0.3
Android SSP API

Version History

Version date comment id

0.0.1 26th Jan 2017 First draft TB
0.0.2 6th April 2017 add NF/SPO TB
0.0.3 18th April 2017 Typo corrections. TB
New functions:
GetBillPositions
BillPayoutAction

Version 0.0.3
Android SSP API

Introduction

This document describes the ITL sspcom.jar library for use with android applications.

Version 0.0.3
Android SSP API

Description

The library is supplied as a sspcoms.jar file and the SDK includes an Android Studio™
example application to demonstrate its use.

The library provides an API of functions and parameters to allow the system programmer to
connect, control and read events from a ITL SSP devices.

Current devices supported:

• ITL Bill Validators

• ITL Bill Payouts (Note Float, SMART Payout)

The user creates an object of the SSPSystem class, sets some initial parameters and event
listeners and provides a method to pass the communications buffers to and from the object.

Version 0.0.3
Android SSP API

Serial Communications

To abstract the serial communications hardware and handers away from the API, the
SSPSystem use a polling and flag method to allow the serial information to be transmitted
from and received to the object for processing.
The final implementation of this is up to the developer but it is suggested that a thread
handler loop is employed to handle this
See the example Android Studio implementations for full details of how to use the library.

Version 0.0.3
Android SSP API

Use

ITLDeviceCom Runable Thread

ssp object

ssp parameters

ssp set listeners

ssp buffer loop

UI Commands

Run

Stop
Device Events Enable
New Setup Disable
Disconnection
Escrow
Device Events Escrow Accept
Payout Events Escrow Reject
File Update Events Payout

Float

Empty

Route

Barcode Config

Set Download

UI Activity

Version 0.0.3
Android SSP API

API functions

SetAddress
Function void SetAddress(int address)

Description Sets the SSP address for the device to connect to

Parameters address: the address of the device (0x00 – 0x7E)

Default the address is set to 0x00

Example use ssp.SetAddress(0); // set the address to 0x00

Return none

DisableDevice
Function void DisableDevice()

Description A command to disable the device for Bill entry after start-up

Parameters none

Default The device will enable on start-up by default

Example use ssp.DisableDevice(); // disable device for bill entry

Return none

EnableDevice
Function void EnableDevice()

Description A command to re-enable the device for Bill entry after a DisableDevice()
command has been sent;
Parameters none

Default The device will enable on startup by default

Example use ssp.EnableDevice(); // enable device for bill entry

Return none

Version 0.0.3
Android SSP API

EscrowMode
Function void EscrowMode(boolean mode)

Description Enables or disables escrow mode for bill acceptance

Parameters mode: true to enable escrow mode, false to disable

Default The object will be set to escrow disabled at start-up

Example use ssp.EscrowMode(true); // enable for escrow mode

Return none

SetBillEscrowAction
Function void SetBillEscrowAction(BillAction action)

Description Accepts or rejects a bill held in escrow of the device

Parameters BillAction action: BillAction.Accept – accept the bill, BillAction.Reject –

reject the bill.

public enum BillAction{

Accept,
Reject;
};

Default none

Example use ssp.SetBillEscrowAction(BillAction.Accept); // Accept the bill from

escrow
Return none

Version 0.0.3
Android SSP API

SetESSPMode
Function void SetESSPMode

Description sets the object eSSP mode state

Parameters Boolean mode: true – enable eSSP, false disable eSSP

long key: the eSSP fixed key for the device e.g 0x0123456701234567

Default eSSP disabled

Example use // enable essp

ssp.SetESSPMode(true,0x0123456701234567);
// disable essp
ssp.SetESSPMode(false,0);

Return none

SetBarcodeConfig
Function void SetBarCodeConfig

Description sets the device barcode configuration

Parameters BarcodeReader object ref

public BarCodeStatus hardWareConfig;

public BarCodeStatus enabledConfig;
public byte numberOfCharacters;
public BarCodeFormat format;
public boolean billReadEnabled;
public boolean barcodeReadEnabled;
public String lastBarCodeValue;

Default Barcode disabled

Example use BarCodeReader cfg = new BarCodeReader();

cfg.barcodeReadEnabled = true;
cfg.billReadEnabled = true;
cfg.numberOfCharacters = 18;
cfg.format = SSPDevice.BarCodeFormat.Interleaved2of5;
cfg.enabledConfig = SSPDevice.BarCodeStatus.Both;
ssp.SetBarCodeConfig(cfg);

Return none

Version 0.0.3
Android SSP API

SetPayoutRoute
Function void SetPayoutRoute

Description Sets the payout route of a denominatiomn

Parameters ItlCurrency object ref:

PayoutRoute enum ref:

Default none

Example use //set GBP 5.00 to payout store

ItlCurrency cur = new IitlCurrency();
cur.country = “GBP”;
cur.value = 500;
PayoutRoute rt = PayoutRoute.PayooutStore;
ssp.SetPayoutRoute(cur,rt);

Return none

PayoutAmount
Function void PayoutAmount

Description Sets the payout level request

Parameters ItlCurrency object ref:

Default none

Example use //payout GBP 30.00

ItlCurrency cur = new IitlCurrency();
cur.country = “GBP”;
cur.value = 3000;
ssp.PayoutAmount(cur);

Return none

Comment Payout errors or wrong values are handled in payout events

Version 0.0.3
Android SSP API

FloatAmount
Function void FloatAmount

Description Sets the float request

Parameters ItlCurrency object ref: amount to float to

ItlCurrency object ref: minimum amount to leave in payout

Default none

Example use //float to GBP 30.00 leaving a min payment of GBP 5.00
ItlCurrency cur = new IitlCurrency();
cur.country = “GBP”;
cur.value = 3000;
ItlCurrency curmin = new IitlCurrency();
curmin.country = “GBP”;
curmin.value = 500;

ssp.FloatAmount(cur,curmin);

Return none

Comment Float errors or wrong values are handled in payout events

EmptyPayout
Function void EmptyPayout

Description Empties the payout store to the cashbox

Parameters none

Default none

Example use ssp.EmptyPayout

Return none

Version 0.0.3
Android SSP API

GetDownloadState
Function DownloadSetupState GetDownloadState()

Description returns the current state of a download setup process

Parameters none

Default DownloadSetupState.idle

Example use DownloadSetupState st = ssp.GetDownloadState();

Return DownloadSetupState: enum containing the state

public enum DownloadSetupState{

idle,setup,inprogress,active;
};

Version 0.0.3
Android SSP API

GetComsConfig
Function SSPComsConfig GetComsConfig()

Description returns the coms config object to allow changes to be made to baud
rates etc.
Parameters none

Default The coms is set to 9600 bd with np parity, two stop bits with flow
control none at start-up by default
Example use SSPComsConfig cfg = ssp.GetComsConfig();

Return SSPComsConfig object

public class SSPComsConfig {

public enum ComsConfigChangeState{

ccIdle,
ccNewConfig,
ccUpdating,
ccUpdated;
};

public int baud;

public byte dataBits;
public byte stopBits;
public byte parity;
public byte flowControl;
public ComsConfigChangeState configUpdate;

public SSPComsConfig(){
configUpdate = ComsConfigChangeState.ccIdle;
}

Version 0.0.3
Android SSP API

SetComsBufferWritten
Function void SetComsBufferWritten(boolean cr)

Description Sets or clears a flag to show object that system has written bhytes to
communciations buffer
Parameters cr: Boolean, true buffer has been written, false buffer has not been
wrriten
Default none

Example use ssp.SetComsBufferWritten(true); // set written to true

Return none

GetNewData
Function int GetNewData(byte[] data)

Description Call from the loop thread handle to poll the SSPSystem object for any
data that needs to be transmitted.
Parameters data: byte array ref to copy the data into . When downloading this needs
to be a 4K (4096 byte) buffer.
Default none

Example use int ret = ssp.GetNewData(new byte[] data[]); // enable for escrow mode

Return int: the length of data to be transmitted

ProcessResponse
Function void ProcessResponse(byte[] data, int length)

Description Send any received bytes to this function so the SSPSystem object can
decode the responses;
Parameters data: byte array of coms response buffer, length: the length of the data
in the buffer
Default none

Example use ssp.ProcessResponse(data,6); // The response buffer has 6 bytes

Return none

Version 0.0.3
Android SSP API

SetDownload
Function boolean SetDownload(SSPUpdate update)

Description Sets the update class to the SSPSystem class reference and initiate the
download process
Parameters SSPUpdate object populated with update file information

Default none

Example use
SSPUpdate sspUpdate = new SSPUpdate(flname);
// path = full file path string
final File up = new File(path);
// init the object data array
sspUpdate.fileData = new byte[(int) up.length()];

// load the file binary data in to the object

DataInputStream dis = new DataInputStream(new
FileInputStream(up));
dis.readFully(sspUpdate.fileData);
dis.close();
sspUpdate.SetFileData();

bool ret = ssp.SetDownload(sspUpdate);

Return Boolean: true download has been set, false download has not been
initialised.

Version 0.0.3
Android SSP API

GetBillPositions
Function ArrayList<ItlCurrencyValue> GetStoredBillPositions()

Description For NoteFloat (NV11,CBA11) only. Returns a list showing the order of
bills stored in the device.
Parameters none

Default none

Example use ArrayList<ItlCurrencyValue> cvals = ssp.GetStoredBillPositions();

Return ArrayList<ItlCurrencyValue>: list of stored currencies in the order of last

bill first.

BillPayoutAction
Function BillPayoutAction(BillActionRequest request);

Description For NoteFloat (NV11,CBA11) only. Stacks or Payout the last bill in the
note float store.
Parameters BillActionRequest.Stack :- stacks the bill.
BillActionRequest.Payout :- pays out the bill.
Default none

Example use ssp.BillPayoutAction(BillActionRequest.Payout) :- pay the bill.

Return none

Version 0.0.3