IDTech Windows SDK Guide  3.2.4.393
API reference for Visual Studio .Net
IDTechSDK.IDT_PIP Class Reference

Public Member Functions

RETURN_CODE config_getSerialNumber (ref string response, string ident="")
 
RETURN_CODE device_retrieveAIDList (ref byte[][] response, string ident="")
 
RETURN_CODE device_sendDataCommand (string cmd, bool calcLRC, ref byte[] response, string ident="")
 
RETURN_CODE device_sendDataCommand_ext (string cmd, bool calcLRC, ref byte[] response, int timeout, bool noResponse, string ident="")
 
RETURN_CODE device_getFirmwareVersion (ref string response, string ident="")
 
RETURN_CODE device_getMerchantRecord (int index, ref byte[] record, string ident="")
 
RETURN_CODE device_setPIPMode (int mode, string ident="")
 
RETURN_CODE device_getPIPMode (ref int mode, string ident="")
 
RETURN_CODE device_getRKIStatus (bool isProd, bool isMultiKey, ref string status, ref Dictionary< string, RKI_KEY_TYPE > keys, string ident="")
 
RETURN_CODE device_getAnyRKIStatus (bool isMultiKey, ref string status, ref Dictionary< string, RKI_KEY_TYPE > keys, string ident="")
 
RETURN_CODE device_getTransactionResults (ref IDTTransactionData results, string ident="")
 
RETURN_CODE device_pingDevice (string ident="")
 
RETURN_CODE device_controlUserInterface (byte[] values, string ident="")
 
RETURN_CODE device_sendVivoCommandP2 (byte command, byte subCommand, byte[] data, ref byte[] response, string ident="")
 
RETURN_CODE device_sendVivoCommandP2_ext (byte command, byte subCommand, byte[] data, ref byte[] response, int timeout, bool noResponse, string ident="")
 
RETURN_CODE ctls_retrieveAIDList (ref byte[][] response, string ident="")
 
RETURN_CODE ctls_getAllConfigurationGroups (ref byte[][] response, string ident="")
 
RETURN_CODE ctls_retrieveApplicationData (byte[] AID, ref byte[] tlv, string ident="")
 
RETURN_CODE ctls_removeApplicationData (byte[] AID, string ident="")
 
RETURN_CODE ctls_setApplicationData (byte[] tlv, string ident="")
 
RETURN_CODE ctls_setDefaultConfiguration (string ident="")
 
RETURN_CODE ctls_setConfigurationGroup (byte[] tlv, string ident="")
 
RETURN_CODE ctls_retrieveTerminalData (ref byte[] tlv, string ident="")
 
RETURN_CODE ctls_setTerminalData (byte[] tlv, string ident="")
 
RETURN_CODE ctls_trySetTerminalData (byte[] tlv, ref byte[] rejectedTLV, ref byte[] convertedTLV, string ident="")
 
RETURN_CODE ctls_getConfigurationGroup (int group, ref byte[] tlv, string ident="")
 
RETURN_CODE ctls_removeConfigurationGroup (int group, string ident="")
 
RETURN_CODE device_startTransaction (double amount, double amtOther, int exponent, int type, int timeout, byte[] tags, byte[] options=null, bool isFastEMV=false, int transMode=0, string ident="")
 
RETURN_CODE device_activateTransaction (int timeout, byte[] tags, byte[] options=null, bool isFastEMV=false, string ident="")
 
RETURN_CODE ctls_startTransaction (double amount, double amtOther, int exponent, int type, int timeout, byte[] tags, bool forceOnline=false, bool isFastEMV=false, string ident="")
 
RETURN_CODE ctls_updateBalance (byte statusCode, byte[] authCode, byte[] date, byte[] time, string ident="")
 
RETURN_CODE ctls_activateTransaction (int timeout, byte[] tags, bool forceOnline=false, bool isFastEMV=false, string ident="")
 
RETURN_CODE ctls_cancelTransaction (string ident="")
 
RETURN_CODE device_setBurstMode (byte mode, string ident="")
 
RETURN_CODE device_setMerchantRecord (int index, bool enabled, string merchantID, string merchantURL, string ident="")
 
RETURN_CODE device_pollForToken (byte seconds, ref byte card, ref byte[] serialNumber, string ident="")
 
RETURN_CODE device_setPollMode (byte mode, string ident="")
 
RETURN_CODE device_updateDeviceFirmware (byte[] firmwareData, string ident="")
 
RETURN_CODE device_enablePassThrough (bool enablePassThrough, string ident="")
 
RETURN_CODE ctls_nfcCommand (byte[] nfcCmdPkt, ref byte[] response, string ident="")
 
RETURN_CODE felica_requestService (byte[] nodeCode, ref byte[] response, string ident="")
 
RETURN_CODE device_updateFirmwareFromZip (byte[] zipfile, string ident="", bool isForeground=false)
 
RETURN_CODE device_sendConfigurationFromZip (byte[] zip, string filename, VC_OPERATION_TYPE type, bool matchFW, string ident="", bool isForeground=false)
 
RETURN_CODE device_sendConfiguration (string filename, VC_OPERATION_TYPE type, bool matchFW, string ident="", bool isForeground=false)
 
RETURN_CODE device_readConfigurationToMemory (string memo, Configs.InstallRules rules, List< Configs.DeviceCommand > cmds, string ident="", bool isForeground=false)
 
RETURN_CODE device_getConfigurationFromMemory (ref string json, string ident="")
 
RETURN_CODE device_RemoteKeyInjection (RKI_KEY_TYPE type, string keyName, string ident="", bool performOnForeground=false)
 

Static Public Member Functions

static int getCommandTimeout (string ident="")
 
static void setCommandTimeout (int milliseconds, string ident="")
 
static void initSC ()
 
static void setCallback (CallBack my_Callback)
 
static void setCallback (IntPtr my_Callback, SynchronizationContext context)
 
static String SDK_Version ()
 
static void lcd_retrieveMessage (DisplayMessages.DISPLAY_MESSAGE_LANGUAGE lang, DisplayMessages.DISPLAY_MESSAGE_IDENTIFIER id, ref string line1, ref string line2)
 

Properties

static IDT_PIP SharedController [get]
 

Detailed Description

Class for PIP ICC reader

Member Function Documentation

RETURN_CODE IDTechSDK.IDT_PIP.config_getSerialNumber ( ref string  response,
string  ident = "" 
)

Polls device for Serial Number

Parameters
responseReturns Serial Number
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString
RETURN_CODE IDTechSDK.IDT_PIP.ctls_activateTransaction ( int  timeout,
byte[]  tags,
bool  forceOnline = false,
bool  isFastEMV = false,
string  ident = "" 
)

Start CTLS Transaction Request

Authorizes the CTLS transaction

The tags will be returned in the callback routine.

Parameters
timeoutTimeout value in seconds.
tagsThe tags to be included in the request. Passed as TLV Data. Example, tag 9F02 with amount 0x000000000100 would be 0x9F0206000000000100
forceOnlineNot used for PIP. Parameter included for API compability with other IDTech Devices
isFastEMVNot used for PIP. Parameter included for API compability with other IDTech Devices
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()

NOTE ON APPLEPAY VAS: To enable ApplePay VAS, first a merchant record must be defined in one of the six available index positions (1-6) using device_setMerchantRecord, then container tag FFEE06 must be sent as part of the additional tags parameter of ctls_startTransaction. Tag FFEE06 must contain tag 9F26 and 9F22, and can optionanally contain tags 9F2B and DFO1. Example FFEE06189F220201009F2604000000009F2B050100000000DF010101 9F22 = two bytes = ApplePay Terminal Applicaiton Version Number. Hard defined as 0100 for now. (required, string ident = "") 9F26 = four bytes = ApplePay Terminal Capabilities Information (required, string ident = "")

  • Byte 1 = RFU
  • Byte 2 = Terminal Type
  • - Bit 8 = VAS Support (1=on, 0 = off, string ident = "")
  • - Bit 7 = Touch ID Required (1=on, 0 = off, string ident = "")
  • - Bit 6 = RFU
  • - Bit 5 = RFU
  • - Bit 1,2,3,4
  • - - 0 = Payment Terminal
  • - - 1 = Transit Terminal
  • - - 2 = Access Terminal
  • - - 3 = Wireless Handoff Terminal
  • - - 4 = App Handoff Terminal
  • - - 15 = Other Terminal
  • Byte 3 = RFU
  • Byte 4 = Terminal Mode
  • - 0 = ApplePay VAS OR ApplePay
  • - 1 = ApplePay VAS AND ApplePay
  • - 2 = ApplePay VAS ONLY
  • - 3 = ApplePay ONLY 9F2B = 5 bytes = ApplePay VAS Filter. Each byte filters for that specific merchant index (optional, string ident = "") DF01 = 1 byte = ApplePay VAS Protocol. (optional, string ident = "")
  • - Bit 1 : 1 = URL VAS, 0 = Full VAS
  • - Bit 2 : 1 = VAS Beeps, 0 = No VAS Beeps
  • - Bit 3 : 1 = Silent Comm Error, 2 = EMEA Comm Error
  • - Bit 4-8 : RFU
RETURN_CODE IDTechSDK.IDT_PIP.ctls_cancelTransaction ( string  ident = "")

Cancel EMV Transaction

Cancels the currently executing EMV transaction.

Parameters
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_PIP.ctls_getAllConfigurationGroups ( ref byte  response[][],
string  ident = "" 
)

Retrieve All Configuration Groups

Returns all the Configuration Groups installed on the terminal for CTLS

Parameters
responsearray of CTLS groups as TLV bytes
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.ctls_getConfigurationGroup ( int  group,
ref byte[]  tlv,
string  ident = "" 
)

Get Configuration Group

Retrieves the Configuration for the specified Group.

Parameters
groupConfiguration Group
tlvreturn data
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_PIP.ctls_nfcCommand ( byte[]  nfcCmdPkt,
ref byte[]  response,
string  ident = "" 
)

NFC Command

This command uses nfcCmdPkt[0] in command data field to implement different functions. This command should be used in Pass-Through mode and command with “Poll for a NFC Tag” data should be used first. Command with other data can only be used once the “Poll for a NFC Tag” command has indicated that a NFC tag is present.

Parameters
nfcCmdPktSystem Code
  • Poll for NFC Tag: nfcCmdPkt[0] = 0xff, nfcCmdPkt[1] = timeout value (in seconds, string ident = "")
  • Tag1 Static Get All Data: nfcCmdPkt[0] = 0x11
  • Tag1 Static Read a Byte: nfcCmdPkt[0] = 0x12, nfcCmdPkt[1] = Address of Data
  • Tag1 Static Write a Byte: nfcCmdPkt[0] = 0x13 nfcCmdPkt[1] = Address of Data, nfcCmdPkt[2] = Data to be written
  • Tag1 Static Write a Byte NE: nfcCmdPkt[0] = 0x14, nfcCmdPkt[1] = Address of Data, nfcCmdPkt[2] = Data to be written
  • Tag1 Dynamic Read a Segment: nfcCmdPkt[0] = 0x15, nfcCmdPkt[1] = Address of Segment
  • Tag1 Dynamic Read 8 Bytes: nfcCmdPkt[0] = 0x16, nfcCmdPkt[1] = Address of Data
  • Tag1 Dynamic Write 8 Bytes: nfcCmdPkt[0] = 0x17, nfcCmdPkt[1] = Address of Data, nfcCmdPkt[2]~nfcCmdPkt[9] = Data to be written
  • Tag1 Dynamic Write 8 Bytes NE: nfcCmdPkt[0] = 0x18, nfcCmdPkt[1] = Address of Data, nfcCmdPkt[2]~nfcCmdPkt[9] = Data to be written
  • Tag2 Read Data (16 bytes): nfcCmdPkt[0] = 0x21, nfcCmdPkt[1] = Address of Data
  • Tag2 Write Data (4 bytes): nfcCmdPkt[0] = 0x22, nfcCmdPkt[1] = Address of Data, nfcCmdPkt[2]~nfcCmdPkt[5] = Data to be written
  • Tag2 Select Sect: nfcCmdPkt[0] = 0x23, nfcCmdPkt[1] = Sect number
  • Tag3 Read Data: – nfcCmdPkt[0] = 0x41, – nfcCmdPkt[1] = Number of services, value n – nfcCmdPkt[2]~nfcCmdPkt[2n+1]: Service code list – nfcCmdPkt[2n+2]: Number of blocks, value m. – nfcCmdPkt[2n+3....]: Block list, length is 2m~3m
  • Tag3 Write Data: – nfcCmdPkt[0] = 0x41, – nfcCmdPkt[1] = Number of services, value n – nfcCmdPkt[2]~nfcCmdPkt[2n+1]: Service code list – nfcCmdPkt[2n+2]: Number of blocks, value m. – nfcCmdPkt[2n+3....]: Block list, length is 2m~3m – nfcCmdPkt[...]: Block data, length is 16m
  • Tag4 Command: nfcCmdPkt[0] = 0x81, nfcCmdPkt[1]~nfcCmdPkt[n]:data
responseResponse as explained in FeliCA Lite-S User's Manual
ipIP Address of target device (optional, string ident = "")
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.ctls_removeApplicationData ( byte[]  AID,
string  ident = "" 
)

Remove Application Data by AID

Removes the Application Data for CTLS as specified by the AID name passed as a parameter

Parameters
AIDName of ApplicationID Must be between 5 and 16 bytes
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.ctls_removeConfigurationGroup ( int  group,
string  ident = "" 
)

Remove Configuration Group

Removes the Configuration as specified by the Group. Must not by group 0

Parameters
groupConfiguration Group
Return values
RETURN_CODEReturn codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_BTPay::device_getResponseCodeString:( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.ctls_retrieveAIDList ( ref byte  response[][],
string  ident = "" 
)

Retrieve AID list

Returns all the AID names and their assigned groups installed on the terminal for CTLS.

Parameters
responsearray of 2-tag TLV data objects: FFE4 (group name) followed by 9F06 (AID, string ident = "")
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.ctls_retrieveApplicationData ( byte[]  AID,
ref byte[]  tlv,
string  ident = "" 
)

Retrieve Application Data by AID

Retrieves the CTLS Application Data as specified by the AID name passed as a parameter.

Parameters
AIDName of ApplicationID. Must be between 5 and 16 bytes
tlvThe TLV elements of the requested AID
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_PIP.ctls_retrieveTerminalData ( ref byte[]  tlv,
string  ident = "" 
)

Retrieve Terminal Data

Retrieves the Terminal Data for CTLS. This is configuration group 0 (Tag FFEE - > FFEE0100). The terminal data can also be retrieved by ctls_getConfigurationGroup(0).

Parameters
tlvResponse returned as a TLV
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_PIP.ctls_setApplicationData ( byte[]  tlv,
string  ident = "" 
)

Set Application Data by AID

Sets the Application Data for CTLS as specified by TLV data

Parameters
tlvApplication data in TLV format The first tag of the TLV data must be the group number (FFE4). The second tag of the TLV data must be the AID (9F06)

Example valid TLV, for Group #2, AID a0000000035010: "ffe401029f0607a0000000051010ffe10101ffe50110ffe30114ffe20106"

Parameters
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_PIP.ctls_setConfigurationGroup ( byte[]  tlv,
string  ident = "" 
)

Set Configuration Group

Sets the Configuration Group for CTLS as specified by the TLV data

Parameters
tlvConfiguration Group Data in TLV format The first tag of the TLV data must be the group number (FFE4). A second tag must exist
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_PIP.ctls_setDefaultConfiguration ( string  ident = "")

Set Default Configuration Group

Resets the device to default CTLS configuration group settings

Parameters
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()
RETURN_CODE IDTechSDK.IDT_PIP.ctls_setTerminalData ( byte[]  tlv,
string  ident = "" 
)

Set Terminal Data

Sets the Terminal Data for CTLS as specified by the TLV. The first TLV must be Configuration Group Number (Tag FFE4). The terminal global data is group 0, so the first TLV would be FFE40100. Other groups can be defined using this method (1 or greater), and those can be retrieved with emv_getConfigurationGroup(int group), and deleted with emv_removeConfigurationGroup(int group). You cannot delete group 0.

Parameters
tlvTerminalData configuration data
Return values
RETURN_CODEReturn codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_BTPay::device_getResponseCodeString:( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.ctls_startTransaction ( double  amount,
double  amtOther,
int  exponent,
int  type,
int  timeout,
byte[]  tags,
bool  forceOnline = false,
bool  isFastEMV = false,
string  ident = "" 
)

Start CTLS Transaction Request

The tags will be returned in the callback routine.

Parameters
amountTransaction amount value (tag value 9F02, string ident = "")
amtOtherOther amount value, if any (tag value 9F03, string ident = "")
typeTransaction type (tag value 9C).
timeoutTimeout value in seconds.
tagsAny other tags to be included in the request. Passed as TLV data. Example, tag 9F02 with amount 0x000000000100 would be 0x9F0206000000000100 If tags 9F02 (amount),9F03 (other amount), or 9C (transaction type) are included, they will take priority over these values supplied as individual parameters to this method.
forceOnlineNot used for PIP. Parameter included for API compability with other IDTech Devices
isFastEMVNot used for PIP. Parameter included for API compability with other IDTech Devices
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()

NOTE ON APPLEPAY VAS: To enable ApplePay VAS, first a merchant record must be defined in one of the six available index positions (1-6) using device_setMerchantRecord, then container tag FFEE06 must be sent as part of the additional tags parameter of ctls_startTransaction. Tag FFEE06 must contain tag 9F26 and 9F22, and can optionanally contain tags 9F2B and DFO1. Example FFEE06189F220201009F2604000000009F2B050100000000DF010101 9F22 = two bytes = ApplePay Terminal Applicaiton Version Number. Hard defined as 0100 for now. (required, string ident = "") 9F26 = four bytes = ApplePay Terminal Capabilities Information (required, string ident = "")

  • Byte 1 = RFU
  • Byte 2 = Terminal Type
  • - Bit 8 = VAS Support (1=on, 0 = off, string ident = "")
  • - Bit 7 = Touch ID Required (1=on, 0 = off, string ident = "")
  • - Bit 6 = RFU
  • - Bit 5 = RFU
  • - Bit 1,2,3,4
  • - - 0 = Payment Terminal
  • - - 1 = Transit Terminal
  • - - 2 = Access Terminal
  • - - 3 = Wireless Handoff Terminal
  • - - 4 = App Handoff Terminal
  • - - 15 = Other Terminal
  • Byte 3 = RFU
  • Byte 4 = Terminal Mode
  • - 0 = ApplePay VAS OR ApplePay
  • - 1 = ApplePay VAS AND ApplePay
  • - 2 = ApplePay VAS ONLY
  • - 3 = ApplePay ONLY 9F2B = 5 bytes = ApplePay VAS Filter. Each byte filters for that specific merchant index (optional, string ident = "") DF01 = 1 byte = ApplePay VAS Protocol. (optional, string ident = "")
  • - Bit 1 : 1 = URL VAS, 0 = Full VAS
  • - Bit 2 : 1 = VAS Beeps, 0 = No VAS Beeps
  • - Bit 3 : 1 = Silent Comm Error, 2 = EMEA Comm Error
  • - Bit 4-8 : RFU
RETURN_CODE IDTechSDK.IDT_PIP.ctls_trySetTerminalData ( byte[]  tlv,
ref byte[]  rejectedTLV,
ref byte[]  convertedTLV,
string  ident = "" 
)

Try to Set CTLS Terminal Data

Atempts to set the CTLS Terminal Data. Use this functions to attempt to set the terminal data to the device. This function will allow the cross-device tag compatible writing of IDTech Legacy/New tag definitions

Parameters
tlvTerminalData TLV Data
rejectedTLVContains the tags (if any) that were rejected by the firmware
convertedTLVContains the tags (if any) that were converted and accepted by the firmware
identOptional identifier
Return values
RETURN_CODEReturn codes listed as typedef enum in IDTCommon:RETURN_CODE. Values can be parsed with IDT_BTPay::device_getResponseCodeString:()
RETURN_CODE IDTechSDK.IDT_PIP.ctls_updateBalance ( byte  statusCode,
byte[]  authCode,
byte[]  date,
byte[]  time,
string  ident = "" 
)

Update Balance

This command is the authorization response sent by the issuer to the terminal including the Authorization Status (OK or NOT OK).

This command is also being used in some implementations (i.e. EMEA) to communicate the results of Issuer Authentication to the reader in order to display the correct LCD messages. With this command, the POS passes the authorization result (OK/NOT OK), and possibly the Authorization Code (Auth_Code)/Date/Time to the terminal.

Parameters
statusCode00: OK, 01: NOT OK, 02: (ARC response 89 for Interac, string ident = "")
authCodeAuthorization code from host. Six bytes. Optional
dateTransaction date. If null, uses current terminal date. 3 bytes compressed numeric YYMMDD (tag value 9A).
timeTransaction time. If null, uses current terminal time. 3 bytes compressed numeric HHMMSS (tag value 9F21).
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString
RETURN_CODE IDTechSDK.IDT_PIP.device_activateTransaction ( int  timeout,
byte[]  tags,
byte[]  options = null,
bool  isFastEMV = false,
string  ident = "" 
)

Start CTLS Transaction Request

Authorizes the CTLS transaction

The tags will be returned in the callback routine.

Parameters
timeoutTimeout value in seconds.
tagsThe tags to be included in the request. Passed as TLV Data. Example, tag 9F02 with amount 0x000000000100 would be 0x9F0206000000000100
optionsNot used for PIP. Parameter included for API compability with other IDTech Devices
isFastEMVNot used for PIP. Parameter included for API compability with other IDTech Devices
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()

NOTE ON APPLEPAY VAS: To enable ApplePay VAS, first a merchant record must be defined in one of the six available index positions (1-6) using device_setMerchantRecord, then container tag FFEE06 must be sent as part of the additional tags parameter of ctls_startTransaction. Tag FFEE06 must contain tag 9F26 and 9F22, and can optionanally contain tags 9F2B and DFO1. Example FFEE06189F220201009F2604000000009F2B050100000000DF010101 9F22 = two bytes = ApplePay Terminal Applicaiton Version Number. Hard defined as 0100 for now. (required, string ident = "") 9F26 = four bytes = ApplePay Terminal Capabilities Information (required, string ident = "")

  • Byte 1 = RFU
  • Byte 2 = Terminal Type
  • - Bit 8 = VAS Support (1=on, 0 = off, string ident = "")
  • - Bit 7 = Touch ID Required (1=on, 0 = off, string ident = "")
  • - Bit 6 = RFU
  • - Bit 5 = RFU
  • - Bit 1,2,3,4
  • - - 0 = Payment Terminal
  • - - 1 = Transit Terminal
  • - - 2 = Access Terminal
  • - - 3 = Wireless Handoff Terminal
  • - - 4 = App Handoff Terminal
  • - - 15 = Other Terminal
  • Byte 3 = RFU
  • Byte 4 = Terminal Mode
  • - 0 = ApplePay VAS OR ApplePay
  • - 1 = ApplePay VAS AND ApplePay
  • - 2 = ApplePay VAS ONLY
  • - 3 = ApplePay ONLY 9F2B = 5 bytes = ApplePay VAS Filter. Each byte filters for that specific merchant index (optional, string ident = "") DF01 = 1 byte = ApplePay VAS Protocol. (optional, string ident = "")
  • - Bit 1 : 1 = URL VAS, 0 = Full VAS
  • - Bit 2 : 1 = VAS Beeps, 0 = No VAS Beeps
  • - Bit 3 : 1 = Silent Comm Error, 2 = EMEA Comm Error
  • - Bit 4-8 : RFU
RETURN_CODE IDTechSDK.IDT_PIP.device_controlUserInterface ( byte[]  values,
string  ident = "" 
)

Control User Interface

Controls the User Interface: Display, Beep, LED

@param values Four bytes to control the user interface
Byte[0] = LCD Message
Messages 00-07 are normally controlled by the reader. 
- 00h: Idle Message (Welcome, string ident = "")
- 01h: Present card (Please Present Card, string ident = "")
- 02h: Time Out or Transaction cancel (No Card, string ident = "")
- 03h: Transaction between reader and card is in the middle (Processing...) 
- 04h: Transaction Pass (Thank You, string ident = "")
- 05h: Transaction Fail (Fail, string ident = "")
- 06h: Amount (Amount $ 0.00 Tap Card, string ident = "")
- 07h: Balance or Offline Available funds (Balance $ 0.00) Messages 08-0B are controlled by the terminal
- 08h: Insert or Swipe card (Use Chip & PIN, string ident = "")
- 09h: Try Again(Tap Again, string ident = "")
- 0Ah: Tells the customer to present only one card (Present 1 card only) 
- 0Bh: Tells the customer to wait for authentication/authorization (Wait) 
- FFh: indicates the command is setting the LED/Buzzer only.
Byte[1] = Beep Indicator
- 00h: No beep
- 01h: Single beep
- 02h: Double beep
- 03h: Three short beeps
- 04h: Four short beeps
- 05h: One long beep of 200 ms 
- 06h: One long beep of 400 ms 
- 07h: One long beep of 600 ms 
- 08h: One long beep of 800 ms
Byte[2] = LED Number
- 00h: LED 0 (Power LED) 01h: LED 1
- 02h: LED 2
- 03h: LED 3
- FFh: All LEDs
Byte[3] = LED Status
- 00h: LED Off 
- 01h: LED On
Parameters
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.device_enablePassThrough ( bool  enablePassThrough,
string  ident = "" 
)

Enable Pass Through

Enables Pass Through Mode for direct communication with L1 interface (power on icc, send apdu, etc).

Parameters
enablePassThroughtrue = pass through ON, false = pass through OFF
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.device_getAnyRKIStatus ( bool  isMultiKey,
ref string  status,
ref Dictionary< string, RKI_KEY_TYPE >  keys,
string  ident = "" 
)

Get RKI Status Polls the RKI servers to validate device RKI eligiblity. Note: if device type is known in advance (production or demo device), it is more efficient to use device_getRKIStatus instead

Parameters
isMultiKeyTrue = MultiKey, False = SingleKey
statusRKI status returned as a string
keysReturns all available keys
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString(). When no data is available, return code = RETURN_CODE_NO_DATA_AVAILABLE
RETURN_CODE IDTechSDK.IDT_PIP.device_getConfigurationFromMemory ( ref string  json,
string  ident = "" 
)

Read Device Configuration From Memory Retrieves the ViVOconfig configuration data from memory after a successful device_readConfigurationToMemory

Parameters
jsonReturns the .json file data that can be saved to disk
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString(). When no data is available, return code = RETURN_CODE_NO_DATA_AVAILABLE
RETURN_CODE IDTechSDK.IDT_PIP.device_getFirmwareVersion ( ref string  response,
string  ident = "" 
)

Polls device for Firmware Version

Parameters
responseResponse returned of Firmware Version
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.device_getMerchantRecord ( int  index,
ref byte[]  record,
string  ident = "" 
)

Get Merchant Record Gets the merchant record for ApplePay VAS

Parameters
indexMerchant Record index, valid values 1-6
recordData returned containing 99 bytes: Byte 0 = Merchand Index Byte 1 = Merchant Enabled (1 = enabled, string ident = "") Byte 2 - 33 = Merchant Protocol Hash-256 value Byte 34 = Length of Merchant URL Bytes 35 - 99 = URL
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.device_getPIPMode ( ref int  mode,
string  ident = "" 
)

Get Device Mode Gets the device operating mode for PIP

Parameters
mode0 = HID, 1 = KB, 3 = HID+KB
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString(). When no data is available, return code = RETURN_CODE_NO_DATA_AVAILABLE
RETURN_CODE IDTechSDK.IDT_PIP.device_getRKIStatus ( bool  isProd,
bool  isMultiKey,
ref string  status,
ref Dictionary< string, RKI_KEY_TYPE >  keys,
string  ident = "" 
)

Get RKI Status From Specified Server Polls the RKI server to validate device RKI eligiblity

Parameters
isProdTRUE = poll production RKI server, FALSE = poll demo RKI server
isMultiKeyTrue = MultiKey, False = SingleKey
statusRKI status returned as a string
keysReturns dictionary of available keys
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString(). When no data is available, return code = RETURN_CODE_NO_DATA_AVAILABLE
RETURN_CODE IDTechSDK.IDT_PIP.device_getTransactionResults ( ref IDTTransactionData  results,
string  ident = "" 
)

Get Transaction Results Gets the transaction results when the reader is functioning in "Auto Poll" mode

Parameters
resultsThe transaction results
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString(). When no data is available, return code = RETURN_CODE_NO_DATA_AVAILABLE
RETURN_CODE IDTechSDK.IDT_PIP.device_pingDevice ( string  ident = "")

Ping Device

Pings the reader. If connected, returns success. Otherwise, returns timeout.

Parameters
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.device_pollForToken ( byte  seconds,
ref byte  card,
ref byte[]  serialNumber,
string  ident = "" 
)

Poll for Token

Once Pass-Through Mode is started, ViVOpay will not poll for any cards until the “Poll for Token” command is received. This command tells ViVOpay to start polling for a Type A or Type B PICC until a PICC is detected or a timeout occurs.

This command automatically turns the RF Antenna on.

If a PICC is detected within the specified time limit, ViVOpay activates it and responds back to the terminal with card related data such as the Serial Number. If no PICC is detected within the specified time limit, ViVOpay stops polling and responds back indicating that no card was found. No card related data is returned in this case

Parameters
timeoutTimeout, in seconds to wait for card to be detected
cardCard Type:
  • 00h None (Card Not Detected or Could not Activate, string ident = "")
  • 01h ISO 14443 Type A (Supports ISO 14443-4 Protocol, string ident = "")
  • 02h ISO 14443 Type B (Supports ISO 14443-4 Protocol, string ident = "")
  • 03h Mifare Type A (Standard, string ident = "")
  • 04h Mifare Type A (Ultralight, string ident = "")
  • 05h ISO 14443 Type A (Does not support ISO 14443-4 Protocol)
  • 06h ISO 14443 Type B (Does not support ISO 14443-4 Protocol)
  • 07h ISO 14443 Type A and Mifare (NFC phone, string ident = "")
serialNumberSerial Number or the UID of the PICC
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString
RETURN_CODE IDTechSDK.IDT_PIP.device_readConfigurationToMemory ( string  memo,
Configs.InstallRules  rules,
List< Configs.DeviceCommand >  cmds,
string  ident = "",
bool  isForeground = false 
)

Read Device Configuration To Memory Executes a ViVOconfig read of device settings and stores the results in memory

Once a ViVOconfig read starts, all messages will be returned to the callback as DeviceState.ViVOconfig. The ViVOconfig operation is complete when the return code from a DeviceState.ViVOconfig message is one of the following values:

  • RETURN_CODE_SDK_VIVOCONFIG_READ_CONFIG_SUCCESS = Read process completed successfully. Execute device_getConfigurationFromMemory to retrieve the configuration data
  • RETURN_CODE_SDK_VIVOCONFIG_READ_CONFIG_FAILED = Read process FAILED.

    Parameters
    memoOptional: populates the memo field of the captured .json file
    rulesOptional: populates the .json file with available install rules
    cmdsOptional: populates the .json file with commands to execute
    identDevice ID to send command to. If not specified, current SDK default device will be used.
    isForegroundIf TRUE, will block program until update complete. Otherwise, FALSE performs update on background.
    Returns
    RETURN_CODE: Values can be parsed with errorCode.getErrorString(). When no data is available, return code = RETURN_CODE_NO_DATA_AVAILABLE
RETURN_CODE IDTechSDK.IDT_PIP.device_RemoteKeyInjection ( RKI_KEY_TYPE  type,
string  keyName,
string  ident = "",
bool  performOnForeground = false 
)

Remote Key Injection Performs a remote key injection for the device

Parameters
typeRemote Key Injection Type
keyNameName of key (optional)
identDevice ID to send command to. If not specified, current SDK default device will be used.
performOnForegroundTRUE = block during process (default is false)
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString(). When no data is available, return code = RETURN_CODE_NO_DATA_AVAILABLE
RETURN_CODE IDTechSDK.IDT_PIP.device_retrieveAIDList ( ref byte  response[][],
string  ident = "" 
)

Retrieve AID list

Returns all the AID names and their assigned groups installed on the terminal for CTLS/CONTACT.

Parameters
responsearray of TLV data objects: FFE4 (group name) followed by 9F06 (AID), and DFEE4F (Interface 01 = CTLS, 02 = CONTACT, string ident = "")
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.device_sendConfiguration ( string  filename,
VC_OPERATION_TYPE  type,
bool  matchFW,
string  ident = "",
bool  isForeground = false 
)

Send Configuration Executes a ViVOconfig update or verify to a device

Once a ViVOconfig write or verify starts, all messages will be returned to the callback as DeviceState.ViVOconfig. The ViVOconfig operation is complete when the return code from a DeviceState.ViVOconfig message is one of the following values:

  • RETURN_CODE_SDK_VIVOCONFIG_VERIFY_SUCCESS = Verification process completed successfully. No differences found.
  • RETURN_CODE_SDK_VIVOCONFIG_VERIFY_SUCCESS_WITH_WARNING = Verification process completed with warnings.
  • RETURN_CODE_SDK_VIVOCONFIG_VERIFY_FAILED = Verification process FAILED
  • RETURN_CODE_SDK_VIVOCONFIG_WRITE_SUCCESS = Write process completed successfully.
  • RETURN_CODE_SDK_VIVOCONFIG_WRITE_SUCCESS_WITH_WARNING = Write process completed with warnings
  • RETURN_CODE_SDK_VIVOCONFIG_WRITE_FAILED = Write process FAILED

    Parameters
    filenameThe .json configuration file to update the device with NOTE: You can also use this parameter to pass the path of where the .json file is located at on local storage instead
    filenameThe name of the .json configuration file
    typeVC_OPERATION_TYPE
  • VC_OPERATION_TYPE_WRITE = Write File To Device, Hash must validate
  • VC_OPERATION_TYPE_VERIFY = Verify Device With File
  • VC_OPERATION_TYPE_WRITE_IGNORE_HASH = Write File To Device, Ignore Hash
  • VC_OPERATION_TYPE_WRITE_FIX_HASH = Write File To Device, Fix Hash If Necessary
    Parameters
    matchFWTRUE = Device FW must match file FW, FALSE = Don't validate device FW against file
    identDevice ID to send command to. If not specified, current SDK default device will be used.
    isForegroundIf TRUE, will block program until update complete. Otherwise, FALSE performs update on background.
    Returns
    RETURN_CODE: Values can be parsed with errorCode.getErrorString(). When no data is available, return code = RETURN_CODE_NO_DATA_AVAILABLE
RETURN_CODE IDTechSDK.IDT_PIP.device_sendConfigurationFromZip ( byte[]  zip,
string  filename,
VC_OPERATION_TYPE  type,
bool  matchFW,
string  ident = "",
bool  isForeground = false 
)

Send Configuration From Zip Executes a ViVOconfig update or verify to a device using files from a .zip archive

Once a ViVOconfig write or update starts, all messages will be returned to the callback as DeviceState.ViVOconfig. The ViVOconfig operation is complete when the return code from a DeviceState.ViVOconfig message is one of the following values:

  • RETURN_CODE_SDK_VIVOCONFIG_VERIFY_SUCCESS = Verification process completed successfully. No differences found.
  • RETURN_CODE_SDK_VIVOCONFIG_VERIFY_SUCCESS_WITH_WARNING = Verification process completed with warnings.
  • RETURN_CODE_SDK_VIVOCONFIG_VERIFY_FAILED = Verification process FAILED
  • RETURN_CODE_SDK_VIVOCONFIG_WRITE_SUCCESS = Write process completed successfully.
  • RETURN_CODE_SDK_VIVOCONFIG_WRITE_SUCCESS_WITH_WARNING = Write process completed with warnings
  • RETURN_CODE_SDK_VIVOCONFIG_WRITE_FAILED = Write process FAILED

    Parameters
    zip.Zip archive containing the .json configuration file and also any associated image assets NOTE: You can also use this parameter to pass the path of where the .zip file is located at on local storage instead
    filenameThe name of the .json configuration file
    typeVC_OPERATION_TYPE
  • VC_OPERATION_TYPE_WRITE = Write File To Device, Hash must validate
  • VC_OPERATION_TYPE_VERIFY = Verify Device With File
  • VC_OPERATION_TYPE_WRITE_IGNORE_HASH = Write File To Device, Ignore Hash
  • VC_OPERATION_TYPE_WRITE_FIX_HASH = Write File To Device, Fix Hash If Necessary
    Parameters
    matchFWTRUE = Device FW must match file FW, FALSE = Don't validate device FW against file
    identDevice ID to send command to. If not specified, current SDK default device will be used.
    isForegroundIf TRUE, will block program until update complete. Otherwise, FALSE performs update on background.
    Returns
    RETURN_CODE: Values can be parsed with errorCode.getErrorString(). When no data is available, return code = RETURN_CODE_NO_DATA_AVAILABLE
RETURN_CODE IDTechSDK.IDT_PIP.device_sendDataCommand ( string  cmd,
bool  calcLRC,
ref byte[]  response,
string  ident = "" 
)

Send a data command to the device

Sends a command to the device.

Parameters
cmdString representation of command to execute
calcLRCIf TRUE, this will wrap command with start/length/lrc/sum/end: '{STX}{Len_Low}{Len_High} data {CheckLRC} {CheckSUM} {ETX}'
responseResponse data
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString
RETURN_CODE IDTechSDK.IDT_PIP.device_sendDataCommand_ext ( string  cmd,
bool  calcLRC,
ref byte[]  response,
int  timeout,
bool  noResponse,
string  ident = "" 
)

Send a data command to the device - extended

Sends a command to the device.

Parameters
cmdString representation of command to execute
calcLRCIf TRUE, this will wrap command as NGA with start/length/lrc/sum/end: '{STX}{Len_Low}{Len_High} data {CheckLRC} {CheckSUM} {ETX}'
responseResponse data
timeoutTimeout value waiting for response, in milliseconds (1000 = 1 second, string ident = "")
noResponseif TRUE, this will not wait for a response and immediately return SUCCESS
calcITPIf TRUE, this will wrap command as ITP with start/end/lrc: '{STX} data {ETX}{CheckLRC}'
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with device_getResponseCodeString
RETURN_CODE IDTechSDK.IDT_PIP.device_sendVivoCommandP2 ( byte  command,
byte  subCommand,
byte[]  data,
ref byte[]  response,
string  ident = "" 
)

Send Vivo Command Protocol 2

Sends a protocol 2 command to Vivo readers (IDG/NEO, string ident = "")

Parameters
commandCommand
subCommandSub-Command
dataData. May be null
responseResponse
ipOptional IP
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.device_sendVivoCommandP2_ext ( byte  command,
byte  subCommand,
byte[]  data,
ref byte[]  response,
int  timeout,
bool  noResponse,
string  ident = "" 
)

Send Vivo Command Protocol 2 Extended

Sends a protocol 2 command to Vivo readers (IDG/NEO, string ident = "")

Parameters
commandCommand
subCommandSub-Command
dataData. May be null
responseResponse
timeoutTimeout, in milliseconds (3000 = 3 seconds, string ident = "")
noResponseTRUE = don't wait for response, FALSE = wait for response defined by timeout
ipOptional IP
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.device_setBurstMode ( byte  mode,
string  ident = "" 
)

Send Burst Mode

Sets the burst mode forthe device.

Parameters
mode0 = OFF, 1 = Always On, 2 = Auto Exit
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.device_setMerchantRecord ( int  index,
bool  enabled,
string  merchantID,
string  merchantURL,
string  ident = "" 
)

Set Merchant Record Sets the merchant record for ApplePay VAS

Parameters
indexMerchant Record index, valid values 1-6
enabledMerchant Enabled/Valid flag
merchantIDMerchant unique identifer registered with Apple. Example com.idtechproducts.applePay
merchantURLMerchant URL, when applicable
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.device_setPIPMode ( int  mode,
string  ident = "" 
)

Set Device Mode Sets the device operating mode for PIP

Parameters
mode0 = HID, 1 = KB, 3 = HID+KB
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString(). When no data is available, return code = RETURN_CODE_NO_DATA_AVAILABLE
RETURN_CODE IDTechSDK.IDT_PIP.device_setPollMode ( byte  mode,
string  ident = "" 
)

Send Poll Mode

Sets the poll mode forthe device. Auto Poll keeps reader active, Poll On Demand only polls when requested by terminal

Parameters
mode0 = Auto Poll, 1 = Poll On Demand
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.device_startTransaction ( double  amount,
double  amtOther,
int  exponent,
int  type,
int  timeout,
byte[]  tags,
byte[]  options = null,
bool  isFastEMV = false,
int  transMode = 0,
string  ident = "" 
)

Start CTLS Transaction Request

The tags will be returned in the callback routine.

Parameters
amountTransaction amount value (tag value 9F02, string ident = "")
amtOtherOther amount value, if any (tag value 9F03, string ident = "")
typeTransaction type (tag value 9C).
timeoutTimeout value in seconds.
tagsAny other tags to be included in the request. Passed as TLV data. Example, tag 9F02 with amount 0x000000000100 would be 0x9F0206000000000100 If tags 9F02 (amount),9F03 (other amount), or 9C (transaction type) are included, they will take priority over these values supplied as individual parameters to this method.
optionsNot used for PIP. Parameter included for API compability with other IDTech Devices
isFastEMVNot used for PIP. Parameter included for API compability with other IDTech Devices
transModeNot used for PIP. Parameter included for API compability with other IDTech Devices
ipNot used for PIP. Parameter included for API compability with other IDTech Devices
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString()

NOTE ON APPLEPAY VAS: To enable ApplePay VAS, first a merchant record must be defined in one of the six available index positions (1-6) using device_setMerchantRecord, then container tag FFEE06 must be sent as part of the additional tags parameter of ctls_startTransaction. Tag FFEE06 must contain tag 9F26 and 9F22, and can optionanally contain tags 9F2B and DFO1. Example FFEE06189F220201009F2604000000009F2B050100000000DF010101 9F22 = two bytes = ApplePay Terminal Applicaiton Version Number. Hard defined as 0100 for now. (required, string ident = "") 9F26 = four bytes = ApplePay Terminal Capabilities Information (required, string ident = "")

  • Byte 1 = RFU
  • Byte 2 = Terminal Type
  • - Bit 8 = VAS Support (1=on, 0 = off, string ident = "")
  • - Bit 7 = Touch ID Required (1=on, 0 = off, string ident = "")
  • - Bit 6 = RFU
  • - Bit 5 = RFU
  • - Bit 1,2,3,4
  • - - 0 = Payment Terminal
  • - - 1 = Transit Terminal
  • - - 2 = Access Terminal
  • - - 3 = Wireless Handoff Terminal
  • - - 4 = App Handoff Terminal
  • - - 15 = Other Terminal
  • Byte 3 = RFU
  • Byte 4 = Terminal Mode
  • - 0 = ApplePay VAS OR ApplePay
  • - 1 = ApplePay VAS AND ApplePay
  • - 2 = ApplePay VAS ONLY
  • - 3 = ApplePay ONLY 9F2B = 5 bytes = ApplePay VAS Filter. Each byte filters for that specific merchant index (optional, string ident = "") DF01 = 1 byte = ApplePay VAS Protocol. (optional, string ident = "")
  • - Bit 1 : 1 = URL VAS, 0 = Full VAS
  • - Bit 2 : 1 = VAS Beeps, 0 = No VAS Beeps
  • - Bit 3 : 1 = Silent Comm Error, 2 = EMEA Comm Error
  • - Bit 4-8 : RFU
RETURN_CODE IDTechSDK.IDT_PIP.device_updateDeviceFirmware ( byte[]  firmwareData,
string  ident = "" 
)

Update Firmware

Updates the firmware .

Parameters
firmwareDataSigned binary data of a firmware file provided by IDTech
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")

After you pass the firmwareData file, a new thread will start to execute the firmware download. You will receive status of the progress through callbacks to the IDTechSDK.Callback() delegate. The following parameters will be passed back:

  • sender = IDT_DEVICE_Types.IDT_DEVICE_AUGUSTA
  • state = DeviceState.FirmwareUpdate
  • transactionResultCode = status of the firmware update (starting, entering bootloader, applying update, block success, firmware success, string ident = "")
  • data = File Progress. Four bytes, with bytes [0][1] = current block, and bytes [2][3] = total blocks. 0x00030010 = block 3 of 16

Example code starting a firmware update

OpenFileDialog diag = new OpenFileDialog( ident);
diag.Filter = "NGA FW Files|*.fm";
if (diag.ShowDialog() == DialogResult.OK, string ident = "")
{
byte[] file = File.ReadAllBytes(diag.FileName, ident);
RETURN_CODE rt = IDT_Device.SharedController.device_updateDeviceFirmware(file, ident);
if (rt == RETURN_CODE.RETURN_CODE_DO_SUCCESS, string ident = "")
{
//Was a success
}
else
{
//Error starting firmware download
}
}

Example monitoring firmware update status / success

private void MessageCallBack(IDTechSDK.IDT_DEVICE_Types type, DeviceState state, byte[] data, IDTTransactionData cardData, EMV_Callback emvCallback, RETURN_CODE transactionResultCode, string ident = "")
{
switch (state, string ident = "")
{
case DeviceState.FirmwareUpdate:
switch (transactionResultCode, string ident = "")
{
case RETURN_CODE.RETURN_CODE_FW_STARTING_UPDATE:
SetOutputText("Starting Firmware Update\n", ident);
break;
case RETURN_CODE.RETURN_CODE_DO_SUCCESS:
SetOutputText("Firmware Update Successful\n", ident);
break;
case RETURN_CODE.RETURN_CODE_APPLYING_FIRMWARE_UPDATE:
SetOutputText("Applying Firmware Update....\n", ident);
break;
case RETURN_CODE.RETURN_CODE_ENTERING_BOOTLOADER_MODE:
SetOutputText("Entering Bootloader Mode....\n", ident);
break;
case RETURN_CODE.RETURN_CODE_BLOCK_TRANSFER_SUCCESS:
int start = data[0] * 0x100 + data[1];
int end = data[2] * 0x100 + data[3];
SetOutputText("Sent block " + start.ToString() + " of " + end.ToString() + "\n", ident);
break;
default:
SetOutputText("Firmware Update Error Code: " + "0x" + String.Format("{0:X}", (ushort)transactionResultCode) + ": " + IDTechSDK.errorCode.getErrorString(transactionResultCode) + "\r\n", ident);
break;
}
break;
}
}
RETURN_CODE IDTechSDK.IDT_PIP.device_updateFirmwareFromZip ( byte[]  zipfile,
string  ident = "",
bool  isForeground = false 
)

Update Firmware From Zip

Performs one or more device firmware updates from firmware files passed as a compressed archive with a valid configuration file (.json format)

Parameters
zipfileZip file containing on or more firmware update files and a .json configuration file
identDevice ID to send command to. If not specified, current SDK default device will be used.
isForegroundIf TRUE, will block program until firmware update complete. Otherwise, FALSE performs FW update on background.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString(string ident = "")
RETURN_CODE IDTechSDK.IDT_PIP.felica_requestService ( byte[]  nodeCode,
ref byte[]  response,
string  ident = "" 
)

FeliCa Request Service

Perform functions a Felica Request Service

NOTE: The reader must be in Pass Through Mode for FeliCa commands to work.

Parameters
nodeCodeNode Code
responseResponse as explained in FeliCA Lite-S User's Manual
identDevice ID to send command to. If not specified, current SDK default device will be used.
Returns
RETURN_CODE: Values can be parsed with errorCode.getErrorString( string ident = "")
static int IDTechSDK.IDT_PIP.getCommandTimeout ( string  ident = "")
static

Get Command Timeout

Gets the default timeout (in milliseconds) waiting for a blocking command response

Return values
timeTime
static void IDTechSDK.IDT_PIP.lcd_retrieveMessage ( DisplayMessages.DISPLAY_MESSAGE_LANGUAGE  lang,
DisplayMessages.DISPLAY_MESSAGE_IDENTIFIER  id,
ref string  line1,
ref string  line2 
)
static

Retrieve LCD Message

Returns the string value for a message ID returned for LCD messaging

Parameters
langLanguage.
idMessage ID
line1Line 1 string value
line2Line 2 string value
static String IDTechSDK.IDT_PIP.SDK_Version ( )
static

SDK Version

  • All Devices

Returns the current version of SDK

Returns
Framework version
static void IDTechSDK.IDT_PIP.setCallback ( CallBack  my_Callback)
static

Set Callback

Sets the class callback
static void IDTechSDK.IDT_PIP.setCallback ( IntPtr  my_Callback,
SynchronizationContext  context 
)
static

Set Callback

Sets the class callback

Parameters
my_CallbackThe callback function to receive the response message from device. defined as follows. public unsafe delegate void MFCCallBack(Parameters parameters, ident);
contextThe context of the UI thread
static void IDTechSDK.IDT_PIP.setCommandTimeout ( int  milliseconds,
string  ident = "" 
)
static

Set Command Timeout

Sets the default timeout (in milliseconds) waiting for a blocking command response

Parameters
millisecondsTime

Property Documentation

IDT_PIP IDTechSDK.IDT_PIP.SharedController
staticget

Singleton Instance

Establishes an singleton instance of IDT_PIP class.

Returns
Instance of IDT_PIP

The documentation for this class was generated from the following file: