For contactless integration, antenna management is crucial because that feature is part of the performance testing which represents the most critical criteria to meet for a contactless payment system during TAs. This statement leads to 2 remarks:
Any system porting Agnos shall be debugged before entering into a TA in regards with all time related test case being in the functional, performance, or cross testing category. These tests require specific tools and their results depend on different aspects beyond digital and functional ones
That section needs to be read carefully
Agnos CL payment applications are independent from the hardware platform. Moreover, they do not use any services related to the antenna (excepted gpiRemovalProcedure and - for kernel C-3/Visa only - gpiPowerOff on SW1SW2=6986). Services related to antenna management are:
tGPIError gpiInitPolling(const char* contactlessCardReaderName)
This primitive is optional and depends on the platform. It may be used to perform system’s antenna initialization. Usually, it is called once by the L3. It depends on the context of the integration.
tGPIError gpiTechnoPolling(const unsigned char technologies,const unsigned int timeout,unsigned char *technologyDetected)
This primitive is optional and should not be used – in contactless or dual systems - with framework 3.x versions in order to avoid double tap. This primitive allows selective card interface polling. It is usually called by L3 before initiating a transaction to detect whether a card has been inserted or swiped based on an interface selection filter (alias technologies) and a timeout.
tGPIError gpiPowerOn(const char* smartcardReaderName,tCardStatus* status,unsigned char* ATRBuffer,unsigned char* ATRLen)
This primitive is conditional. It may be used to power on the system’s antenna meaning that the field inducting a chip’s power is activated on that call. It’s an option because its call is encapsulated into gpiPolling. So, the implementation may choose to directly call a L1 primitive instead. In contactless, this primitive is never called by the L3 or the entry point. In contact, this primitive is called before application selection process. It becomes mandatory in that context.
tGPIError gpiPowerOff(const char* smartcardReaderName)
This primitive powers off the system’s antenna. It means that the field inducting the chip’s power is deactivated on that call. It is called by entry point and may be called by L3 to make sure that antenna is off. Important: This call is crucial for some functional test cases where field activation/deactivation is tested. See GPI Performance page.
tGPIError gpiPolling(const char* contactlessCardReaderName)
This primitive starts a discovery card, collision detection and any card type detection (include type A/B) processing. It is called by the entry point right after preprocessing (on start A), and on start B. Important: this call is crucial for some functional test cases where field activation/deactivation is tested. See GPI Performance page. It may raise the following status:
Error | Comment |
|---|---|
clcEMV_CARD | An EMV card has been detected. The entry point initiates a PPSE selection (normal case of execution) |
clcCOLLISION | L1 has detected that more than one card has been presented. Entry point displays a specific message and the polling is resumed after 1500 ms (gpiPolling is called again) |
polTIMEOUT | GPI (non-blocking case) or L1 (blocking case) detected that the timeout has been reached. Entry point stops the polling and raises an outcome with: |
scrINTERRUPTED | GPI (non-blocking case) or L1 (blocking case) detected that the polling has been cancelled. Entry point stops the polling and raises an outcome with: |
scrCARD_INSERTED | GPI detected that a card has been inserted. Entry point stops the polling and raises an outcome with: |
msrCARD_SWIPED | GPI detected that a card has been swiped. Entry point stops the polling and raises an outcome with: |
clcOTHER_CARD | A card different from type A/B has been detected (mifare, desfire, …), or an unexpected situation has been encountered (typically a system error). Entry point stops the polling and raises an outcome with: |
clcSYSTEM_ERROR | An unexpected situation has been encountered (typically a system error). Entry point stops the polling and raises an outcome with: |
tGPIError gpiResetContactless(const char* contactlessCardReaderName)
This primitive is optional and depends on the platform. A reset defines the antenna off time before reactivating the field. It is called only by the entry point. Important: this call is crucial for some functional test cases where field activation/deactivation is tested. See GPI Performance page.
tGPIError gpiRemovalProcedure(const char* contactlessCardReaderName, unsigned char holdtime)
This primitive is conditional depending on the context of the system acceptance. Removal timeout out maybe defined using GPI options. It is called only by the CL payment applications. Important: this call is crucial for some functional test cases where field activation/deactivation is tested. See GPI Performance page.
tGPIError enpGetLastCardDetectionStatus(void)
Use this primitive to discriminate errors like clcOTHER_CARD, clcSYSTEM_ERROR, … from L3.