ContactLAB
Responses to common questions about connection, installation and use of ContactLAB, including RGPA interface and controls specific to ContactLAB.
- Which licenses/options are installed and what is the serial number of my ContactLAB?
- Which software version is installed
- After installation, why isn't ContactLAB in the Device Manager list?
- What does the error message "SWP SPY license not available" mean?
- What does the error message "ISO7816 SPY license not available" mean?
- Why won't the card and NFC device communicate whilst spying?
- What are the differences between the ISO7816 methods that send frames to the card?
- How do I write my first script to control ContactLAB?
- Where are the ContactLAB scripts?
Q: Which licenses/options are installed and what is the serial number of my ContactLAB?
A: To know your product details:
- Plug in your ContactLAB and start the RGPA software.
- Go to Acquisition Tool (CTRL + F5)
- Click on Configure.
- A panel displays all the version numbers, the serial numbers and the available licenses.
Q: Which software version is installed?
A: To find the software version installed on your computer, start RGPA and open the dialog box with the menu "Help | About".
Q: After the installation, why isn't ContactLAB displayed in the Device Manager?
A: When plugged in and turned on, the ContactLAB should appear in the Device Manager list. Depending on the version of the software, you may find it under:
- "Jungo" or
- "Smart Card Readers"
If not, please contact us at: sc-support@raisonance.com
Q: What does the error "SWP SPY license not available" mean?
A: This error message is displayed in the output window of RGPA when a spying session was configured to spy on the SWP interface while the hardware used does not have the SWP SPY license. Please deactivate the SWP SPY in one of the following ways:
- Via the interface: in Setup, uncheck SWP in the Enable Spy frame
- Via script: ContactLAB.Spy.Analyzer.SWPSpy = 0
This should not happen if the ContactLAB software version is later than 1.2.0.3000.
Q: What does the error "ISO7816 SPY license not available" mean?
A: This error message is displayed in the output window of RGPA when a spying session was configured to spy on the ISO7816 interface while the hardware used does not have the ISO7816 spy license. Please deactivate the ISO7816 spy in one of the following ways:
- Via the interface: in Setup, uncheck ISO7816 in the Enable Spy frame
- Via script: ContactLAB.Spy.Analyzer.ISO7816Spy = 0
This should not happen if the ContactLAB software version is later than 1.2.0.3000.
Q: Why won't the card and NFC device communicate whilst spying?
A: When spying, the ContactLAB prevents communication between a card and an NFC device.
- Check that the ContactLAB is in Spy Only mode, in Setup.
- Try to perform a LoadDefaultConfig() by clicking the Default button in Setup. Then put the ContactLAB in Spy Only mode.
- If it still does not work, then problem may come from the ISO7816 signal. In Spy Only mode, the contacts C2, C3 and C7 are not driven by the ContactLAB, but if they are not driven by any other device, then the ContactLAB may apply an undefined voltage to these contacts, which may lead to unexpected behavior of the SWP interface.
To prevent this, you should drive C2, C3 and C7 at 0V.
Q: What are the differences between the ISO7816 methods used to send frames to the card?
A: There are several functions that send a frame to the card, each of them handle different layers of the communication protocol.
- SendTransparentFrame / SendTsp_Nb / SendTsp_Wwt
- SendTPDU_In / SendTPDU_Out
- SendAPDU
- T1.SendFrame
- SendTransparentFrame, SendTsp_Nb and SendTsp_Wwt
These methods just send the array of bytes transmitted in parameter and get the answer of the smart card, without further processing. It is recommended to use either:
SendTsp_Wwt (where you can specify the timeout in parameter) or
SendTsp_Nb (where you can specify the number of awaited bytes in parameter).
JScript Example:
var request = new Array(0x00,0xA4,0x04,0x00,0x07);
var answer = new Array();
wwt = 10000000;
SendTsp_Wwt(request, 0, wwt, answer);
// - A4 04 00 07
// <-- A4
// The method just sent the block and received the card's answer
// no protocol processing is handled
request = [0xA0,0x00,0x00,0x00,0x18,0x43,0x4D];
SendTsp_Wwt(request, 0, wwt, answer);
// - 00 00 00 18 43 4D
// <-- 61 22
Bear in mind that a "transparent frame" is a succession of bytes sent without any protocol processing. All bytes are sent in a row, then every byte answered by the card is returned. - SendTPDU_In and SendTPDU_Out
These two T=0 specific commands handle the T=0 protocol. First, the frame given in the parameter is evaluated to see if it matches a TPDUin or a TPDUout, as defined in the ISO7816 standard. Then, the T=0 protocol is handled at hardware level.
JScript example:
var request = new Array();
request = [0x00,0xA4,0x04,0x00,0x07,0xA0,0x00,0x00,0x00,0x18,0x43,0x4D];
var answer = new Array();
SendTPDU_Out(request, answer);
// - A4 04 00 07
// <-- A4
// - 00 00 00 18 43 4D
// <-- 61 22
// The hardware first sends the 5 header bytes, gets the ACK of the
// card and then sends its 7 data bytes automatically, before returning
// the status word of the card - T1.SendFrame
This T=1 specific command handles the T=1 communication protocol. Errors, block retransmission and automatic deactivation are handled at software level. This is the T=1 equivalent of SendTPDU_In and SendTPDU_Out.
JScript example:
var request = new Array();
request = [0x00,0xA4,0x00,0x00,0x02,0x01,0x01,0x04];
var answer = new Array();
T1.SendFrame(request, answer);
// - 00 08 00 A4 00 00 02 01 01 04 AA I(0,0)
// <-- 00 92 00 92 R(1)-Other error
// - 82 00 82 R(0)-Other error
// <-- 00 00 04 01 02 90 00 97 I(0,0)
// The hardware first sends an I-block containing the command
// then the cards send an unexpected R-block
// then the reader sends an R-block as this behavior was unexpected
// and finally, the card transmits its answer to the first I-block. - SendAPDU
This method may be called either in T=0 or in T=1 mode.
- In T=0, it is one layer on top of the TPDU layer. One APDU may be split into several TPDUs, and depending on the card's answer and on the current protocol (ISO, EMV, GSM), the ContactLAB may automatically emit the necessary TPDUs to get the card's final answer.
- In T=1, it is one layer on top of the SendFrame method: the content of the APDU is checked before being transmitted. Extended APDUs are supported in T=1.
JScript Example for T=0:
var request = new Array();
request = [0x00,0xA4,0x04,0x00,0x07,0xA0,0x00,0x00,0x00,0x18,0x43,0x4D,0xF5];
var answer = new Array();
SendAPDU(request, answer);
// - A4 04 00 07 //first TPDU (out)
// <-- A4
// - 00 00 00 18 43 4D
// <-- 61 22
// - C0 00 00 22 (automaic GET RESPONSE TPDU)
// <-- C0
// - 20 84 0F A0 00 00 00 18 43 4D 08 09 0A 0B 0C
// 00 00 00 A5 0D 9F 6E 06 12 91 FF FF 01 00 9F 65
// 01 FF 90 00
// This an APDU case 4S as described in the ISO7816-3 (2006) standard.
Refer to the IEC ISO 7816-3:2006 (E) document for more details about the difference between an APDU and a TPDU.
Q: How do I write my first script to control ContactLAB?
A: Getting started: The easiest way to write your first script with the ContactLAB is to use the script recording functionality. You can then edit the script file generated and use it as a base for your future developments. It works like recording a MACRO in various programs:
- In RGPA, click on Scripts recording (F4)
- Choose an output JScript file name and path
- You may enter a title and a description (optional)
- You may parameter the delay between the actions:
- No delay
- Actual delay (if you waited 1 second between 2 actions, then a 1 second delay is added in the recorded script)
- Constant delay (added after any action) - Click OK
- From now on, every action done in the ContactLAB control panel is recorded into the JScript file you selected, until you stop the recording by Scripts recording (F4)
- To replay the script, simply double click on the file generated from the Explorer.
Q: Where are the ContactLAB scripts?
A: ContactLAB is delivered with a set of script examples which (unless you changed the installation directory) are located in: C:\Program Files\Raisonance\RGPA\Tools\ContactLAB\Examples\ .
- Most of the examples are written in JScript, but basic examples are also provided in C/C++, Python and VBScript and VB.Net.. Have a look at the following file, it may provide a solid base for your future scripts: "\Examples\JScript\ISO7816\ISO7816_SendAPDU.js".
- The programming guide details all the ContactLAB methods and properties. It is installed along with the ContactLAB here (unless you changed the installation directory): "C:\Program Files\Raisonance\RGPA\Tools\contactlab\Doc\ContactLAB Programming Guide.pdf".
