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
