Device Connection Configuration

Before attempting to connect to devices such as card readers and printers, the integrator has the option to set the specific connection criteria to use during the device search. This will ensure that Commerce SDK will only attempt to search for the devices specified by the integrator, which will result in a faster connection to the device. The connection criteria are also used for specifying the details of a connection over an IP channel, such as the IP address, port, and encryption type.

Setting the connection configuration is only required if IP connection parameters need to be specified. If not set, Commerce SDK will search for all other supported devices by default.

Note that this method is only used to setup the connection configuration that will be used for future device searches. For an example of performing an actual device search that will use the connection configuration set by this method, see Card Reader Connection .

error_outline
note

All data transferred over IP have a TLS (formerly known as SSL) encryption scheme where the card reader acts as a server and Commerce SDK is the client.

Timings: CSDK Find Devices vs CSDK 4.1

Pinpad Sample App Connection Type Find Devices- 1st SALE- Find Devices/Connect 4.1 1st SALE 4.1 Find/Connect
      Default Defined Values Default Defined Values    
Link 2500 C♯/CWS USB 3.59 secs 2.33 secs 2.39 secs (OnDemandApp-CardReaderSearch) 2.05 secs (OnDemandApp-CardReaderSearch) 3.39 secs 6.26 secs (OnDemandApp-CardReaderSearch)
Link 2500 C♯/CWS Wi-Fi 17.39 secs 16.89 secs 17.23 secs (OnDemandApp-CardReaderSearch) 15.64 secs (OnDemandApp-CardReaderSearch) 17.00 secs 2.60 secs (OnDemandApp-CardReaderSearch)
Link 2500 Android WI-FI 24 seconds (from starting SALE on sample app to Insert, Swipe or Tap screen) 17 seconds (from starting SALE on sample app to Insert, Swipe or Tap screen) 18 seconds (including time to select the device after initial find/connect to when it's initialized) 18 sec 13 seconds (including time to select the device after initial find/connect to when it's initialized) 9 sec 19 sec 16 sec
Link 2500 iOS WI-FI 5 seconds 5 seconds 6 seconds 4 seconds 10 seconds 8 seconds
Link 2500 IOS BT 6-7 seconds 5 seconds 5 seconds (including time to select the device after initial find/connect to when it's initialized) 5 seconds (including time to select the device after initial find/connect to when it's initialized) 12 secs (from starting SALE on sample app to Insert, Swipe or Tap screen) 9 seconds
ICMP Android BT 20 seconds (from starting SALE on sample app to Insert, Swipe or Tap screen) 8 seconds 19 seconds (including time to select the device after initial find/connect to when it's initialized) 7 seconds (including time to select the device after initial find/connect to when it's initialized) 16 seconds (from starting SALE on sample app to Insert, Swipe or Tap screen) 9 seconds
ICMP IOS BT 6 sec 5 seconds 6 seconds 6 seconds 12 secs (from starting SALE on sample app to Insert, Swipe or Tap screen) 11 sec
ICMP C♯/CWS USB 4.74 secs 2.23 secs 5.92 secs (OnDemandApp-CardReaderSearch) 2.46 secs (OnDemandApp-CardReaderSearch) 4.42 secs 7.54 secs (OnDemandApp-CardReaderSearch)
ROAM Android Audio 21 sec 13 sec 22 seconds 10 seconds 33 seconds 32 seconds
ROAM IOS BT 4 2.75sec 4.65 sec 2.71 sec 2.95 2.81sec
ISC250 C♯/CWS USB 5.78 secs 2.99 secs 2.59 secs (OnDemandApp-CardReaderSearch) 2.52 secs (OnDemandApp-CardReaderSearch) 5.47 secs 3.13 secs (OnDemandApp-CardReaderSearch)
ISC250 C♯/CWS IP 18.75 secs 11.49 secs 18.62 secs (OnDemandApp-CardReaderSearch) 20.61 secs (OnDemanApp-CardReaderSearch) 25.19 secs 18.15 secs (OnDemandApp-CardReaderSearch)
iSC250 iOS IP 6 seconds 5 seconds 5-6 seconds 5 seconds 11 seconds 11 seconds
IPP320 C♯/CWS USB 4.93 secs 2.64 secs 2.52 secs (OnDemandApp-CardReaderSearch) 2.44 secs (OnDemandApp-CardReaderSearch) 4.27 secs 2.25 secs (OnDemandApp-CardReaderSearch)
IPP320 C♯/CWS IP 21.30 secs 17.29 secs 6.59 secs (OnDemandApp-CardReaderSearch) 2.51 secs (OnDemandApp-CardReaderSearch) 22.03 secs 16.07 secs (OnDemandApp-CardReaderSearch)

error_outline
note

For C♯/CWS: CWS was stopped/restarted before every test run. Connection times reflect first transaction connection times.

Prerequisites for IP Configuration

  1. Configure the card reader to accept plain data transfer over IP.
  2. Establish IP-based communication channel between application and card reader.
  3. Enable SSL on the card reader (refer to the Client Certificate for IP Communication section of the appropriate integration method).

Code Samples

CWS

Request

method
string | required
setDeviceConnectionConfiguration
 
requestId
string | required
Transaction Request ID
 
targetType
string | required
api
 
parameters
JSONObject | required
All relevant parameters for card reader configuration.
 
connectionCriteria
JSONObject | required
Device Connection Criteria
Holds the device connection parameters.
providerTypes
array | required
Device Provider Types
Valid values:
  • INGENICO_RBA_UPP
  • ROAM_RUA
  • MAGTEK
  • STAR
  • EPSON
  • RDM
connectionTypes
array | required
Connection Types
Valid values:
  • USB
  • BT
  • IP
  • AUDIO
deviceTypes
array | required
Device Types
Valid values:
  • CARD_READER
  • PRINTER
  • CHECK_READER
inetAddress
JSONObject | optional
INET Address
Specifies the host, port, and encryption scheme of the INET address.
Important: Required if connectionTypes contains IP.
host
string | required
Host
IP Address
port
int | required
Port Number
 
encryptionScheme
string | required
Encryption Scheme
Indicates whether or not the IP channel is TLS-enabled.
Set to TLS_12 to encrypt the data.

Response

requestId
string
Transaction Request ID
As specified in the request.
statusDetails
string
Request Status
 
data
JSONObject
Object holding various responses.
 
completed
boolean
Request Result
Device configuration result.
Valid values:
  • true
  • false
error
string
If an error occurred.

Example

Request
{
  "method" : "setDeviceConnectionConfiguration",
  "requestId" : "1253881538",
  "targetType" : "api",
  "parameters" : {
    "connectionCriteria" : {
      "providerTypes" : ["INGENICO_RBA_UPP", "STAR"],
      "connectionTypes" : ["USB", "IP"],
      "deviceTypes" : ["CARD_READER", "PRINTER"],
      "inetAddress" : {
        "host" : "192.168.1.137",
        "port" : 12000,
        "encryptionScheme" : "NONE"/"TLS_12"
      }
    }
  }
}
Response
{
  "requestId" : "1253881538",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "completed" : true
  }
}

getDeviceConnectionConfiguration

There is additional request/response for getDeviceConnectionConfiguration:

Request
method
string | required
getDeviceConnectionConfiguration
 
requestId
string | required
Transaction Request ID
 
targetType
string | required
api
 
Response
requestId
string
Transaction Request ID
As specified in the request.
statusDetails
string
Request Status
 
data
JSONObject
Object holding various responses.
 
completed
boolean
Request Result
Get Connection Configuration result.
connectionCriteria
JSONObject
Object holding the current connection criteria.
providerTypes
array
Array of Provider Types
 
connectionTypes
array
Array of Connection Types
 
deviceTypes
array
Array of Device Types
 
inetAddress
JSONObject
INET Address
Specifies the host, port, and encryption scheme of the INET address.
host
string
Host
IP Address
port
int
Port Number
 
encryptionScheme
string
Encryption Scheme
Indicates whether or not the IP channel is TLS-enabled.
Request
{
  "method" : "getDeviceConnectionConfiguration",
  "requestId" : "1253881539",
  "targetType" : "api"
}
Response
{
  "requestId" : "1253881539",
  "statusDetails" : "REQUEST_ACCEPTED",
  "data" : {
    "completed" : true
    "connectionCriteria" : {
      "providerTypes" : ["INGENICO_RBA_UPP", "STAR"],
      "connectionTypes" : ["USB", "IP"],
      "deviceTypes" : ["CARD_READER", "PRINTER"],
      "inetAddress" : {
        "host" : "192.168.1.137",
        "port" : 12000,
        "encryptionScheme" : "TLS_12"
      }
    }
  }
}

Java

Set Up

  1. Retrieve an instance of ECLConnectionConfiguration.

    The call to getInstance() returns a reference to a global singleton object, so you cannot have multiple ECLConnectionConfiguration at the same time.

  2. Create an ECLConnectionCriteria and set it.
  3. You can get the currently set ECLConnectionCriteria at any time.

Code Sample

ECLConnectionConfiguration config = ECLConnectionConfiguration.getInstance();
EnumSet<ECLDeviceProviderType> providerTypes = EnumSet.of(ECLDeviceProviderType.INGENICO_RBA_UPP, ECLDeviceProviderType.ROAM_RUA, ECLDeviceProviderType.STAR);
EnumSet<ECLConnectionType> connectionTypes = EnumSet.of(ECLConnectionType.AUDIO, ECLConnectionType.BT, ECLConnectionType.IP);
EnumSet<ECLDeviceType> deviceTypes = EnumSet.of(ECLDeviceType.CARD_READER, ECLDeviceType.PRINTER);
ECLConnectionCriteria.Builder criteriaBuilder = new ECLConnectionCriteria.Builder();
ECLConnectionCriteria criteria = criteriaBuilder
     .setEnabledDeviceProviderTypes(providerTypes)
     .setEnabledConnectionTypes(connectionTypes)
     .setEnabledDeviceTypes(deviceTypes)
     .setInetAddress(new ECLInetAddress(ip, port, ECLEncryptionScheme.TLS_12))
     .build();

try
{
     config.setConnectionCriteria(criteria);
}
catch (ECLCommerceException ece)
{
     showError("Connection Configuration Exception", "Error trying to set connection criteria: %s", ece.getCode().name());
}

//get
ECLConnectionCriteria currentCriteria = config.getConnectionCriteria();

Reset Connection Configuration

You can reset the connection configuration to the default, which will search for all supported devices.

try
{
     config.setConnectionCriteria(null);
}
catch (ECLCommerceException ece)
{
     //should not get this when setting to null
}

error_outline
note

Do not reset the connection configuration while a device search is in progress.

Objective-C (iOS)

Set Up

  1. Use ECLConnectionConfiguration:sharedInstance to retrieve the global ECLConnectionConfiguration instance. The call to ECLConnectionConfiguration:sharedInstance returns a reference to a global singleton object, so you cannot have multiple ECLConnectionConfiguration at the same time.
  2. Create an ECLConnectionCriteria object and set it.
  3. You can get the currently set ECLConnectionCriteria at any time, using ECLConnectionConfiguration:getConnectionCriteria:.

Code Sample

// Get ECLConnectionConfiguration global instance...
ECLConnectionConfiguration *connectionConfiguration = [ECLConnectionConfiguration sharedInstance];

// Define what device providers, connection types, and device types you wish to search for...
NSSet <NSNumber *> *enabledDeviceProviderTypes = [NSSet setWithArray:@[@(ECLDeviceProviderType_INGENICO_RBA_UPP),@(ECLDeviceProviderType_ROAM_RUA),@(ECLDeviceProviderType_STAR)]];
NSSet <NSNumber *> *enabledConnectionTypes = [NSSet setWithArray:@[@(ECLConnectionType_AUDIO),@(ECLConnectionType_BT),@(ECLConnectionType_IP)]];
NSSet <NSNumber *> *enabledDeviceTypes = [NSSet setWithArray:@[@(ECLDeviceType_CARD_READER),@(ECLDeviceType_PRINTER)]];
ECLConnectionCriteria *criteria = [ECLConnectionCriteria makeWithBuilder:^(ECLConnectionCriteriaBuilder *builder) { 
    builder.enabledDeviceProviderTypes = enabledDeviceProviderTypes;
    builder.enabledConnectionTypes = enabledConnectionTypes;
    builder.enabledDeviceTypes = enabledDeviceTypes;
    builder.inetAddress = [[ECLInetAddress alloc] initWithHost:@"192.168.1.1" port:@(12000) encryptionScheme:ECLEncryptionScheme_TLS_12];
}];

// Set the new search criteria for the global ECLConnectionConfiguration instance...
ECLError *error = [connectionConfiguration setConnectionCriteria:criteria];
if (error == nil)
{
    // No error? Then, the connection criteria has been successfully set!
}
else
{
    // If an error is returned, please see documentation for each possible ECLConnectionConfiguration:setConnectionCriteria: error (e.g. ECLConnectionCriteriaEmptyDeviceProviderTypes).
}

Reset Connection Configuration

You can reset the connection configuration to the default, just like in Java, which will search for all supported devices.

// Since the criteria is set to the default, ECLConnectionConfiguration:setConnectionCriteria: will always return nil.
ECLError *error = [connectionConfiguration setConnectionCriteria:nil];

C#

private void MySetDeviceConfigComplete(SetDeviceConfigResults crc)
{
     String statusDetails = crc.StatusDetails;
     if ((null != statusDetails) && (0 < statusDetails.Length))
         Log("Status Details: " + statusDetails);

     String error = crc.Error;
     if ((null != error) && (0 < error.Length))
         Log("Error: " + error);
     else
         Log("No error");
}

DeviceConnectionCriteria connCriteria = new DeviceConnectionCriteria();
connCriteria.providerTypes = new string[] { DeviceProviderType.INGENICO_RBA_UPP, DeviceProviderType.STAR };
connCriteria.connectionTypes = new string[] { ConnectionType.USB, ConnectionType.IP };
connCriteria.deviceTypes = new string[] { DeviceType.CARD_READER, DeviceType.PRINTER };
connCriteria.inetAddress = new InetAddress("121.121.12.12", 12000, EncryptionScheme.TLS_12);

DeviceConfigArgs args = new DeviceConfigArgs();
args.connectionCriteria = connCriteria;
m_CWS.StartSetDeviceConfig(args, MyNotifyCWSEvent, MySetDeviceConfigComplete);

// Get
private void MyGetDeviceConfigComplete(GetDeviceConfigResults crc)
{
     DeviceConnectionCriteria connCriteria = crc.GetConnectionCriteria;
}

m_CWS.StartGetDeviceConfig(MyNotifyCWSEvent, MyGetDeviceConfigComplete);