Documentation

Upgrading to SPI 2.4

To upgrade to this version of SPI from a lower version, you will need to make a few changes.

Suggest Edits

SPI Client 2.4 is a major release and includes some significant changes from previous versions.

When upgrading from a previous SPI version to SPI client library 2.4 or higher there are a number of changes that need to be addressed.

EFTPOS Terminal Version

SPI Client 2.4 requires a EFTPOS terminal application version of 2.4.0 or later. You can check your terminal application version by pressing Enter + 8 on your EFTPOS terminal under "App ver:". If your terminal is on a lower version please contact your mx51 integration engineer.

.NET 4.5 Framework & Windows 7

The SPI Client library 2.4 is compiled using .NET 4.5. If you are using the .NET library your POS will need to support the .NET framework version 4.5 or above. The .NET framework 4.5 is only available on Windows 7 or above and prohibits usage on Windows XP and Windows POSReady 2009.

Auto IP Address Resolution / WSS

The major feature release for 2.4 is Auto IP Address Resolution. This feature allows users to pair the SPI client to the EFTPOS terminal using the serial number of the EFTPOS terminal. This removes any network issues associated with changing IP addresses. This feature requires the POS to have an internet connection as it connects to an external server to obtain the IP address.

This release also includes support for Secure WebSockets for browser-based POS that serve content over HTTPS.

Required Changes - Pairing UI

As a result of the additional features UI changes are required by the POS.

Below is a UI sample:

1084

Things to note:

  • The addition of the S/N (Serial Number) field, Automatic tick box and Test Mode tick box

  • If the EFTPOS ADDRESS Automatic tick box is selected then the EFTPOS serial number is required. If not then the user can pair with an IP address as in previous versions.

  • TEST MODE refers to the server the library will obtain the EFTPOS terminal IP address. If TEST MODE is selected the library will query the test environment. This is used only for testing.

Required Changes - Code

As part of the update there is a requirement to provide an additional argument when instantiating the library and some extra values as part of the DeviceAddressService class. These have been defined below:

// As the first argument in the SPI instantiation 
string serialNumber // The Serial Number of the EFTPOS terminal used when
                    // instantiating the SPI client. Can be left blank but 
                    // a value needs to be included. 

// As part of the DeviceAddressService class  
string apiKey       // Required to identify you termnial. Ask your Assembly
                    // contact for your apiKey.
string acquirerCode // Set this to "wbc".
bool isTestMode     // Set to "true" when using a development termial 
                    // and false for production terminals.

To receive an apiKey please contact your mx51 contact

Triggering the Auto Device Resolution

A number of scenarios will trigger the SPI Client to obtain an IP address based on a provided serial number. These are good to understand when completing the development for the Auto Device Resolution:

  • SetSerialNumber - When unpaired, if the serial number changes, the library will resolve the device address.
  • SetAutoAddressResolution - When paired and disconnected, if auto address resolution is enabled, the library will resolve the device address.
  • SetTestMode - When unpaired, toggling the test mode will resolve the device address.
  • Disconnection - When disconnected the library will try and re-connect - When disconnected, the mode will switch to PairedConnecting and if auto address resolution is enabled and the number of retries (normal reconnect) is more than 5, the library will resolve the device address and try to re-connect.

Updated about 1 year ago