ACR122S. Serial NFC Reader. Application Programming Interface V2.02. Subject to change without prior notice.

Transcription

1 ACR122S Serial NFC Reader Applicatin Prgramming Interface V2.02 Subject t change withut prir ntice

2 Table f Cntents 1.0. Intrductin Features Applicatin Prgramming Interface Overview Reader Define Dcumentatin Functin Dcumentatin LED Functin Dcumentatin Card Functin Dcumentatin Appendix A. Data Structures Appendix A.1. _ACR122_TIMEOUTS Struct Reference Appendix A.2. _ACR122_LED_CONTROL Struct Reference Appendix B. Errr Cdes returned by high-level APIs List f Figures Figure 1 : ACR122S Library Architecture... 3 Page 2 f 23

3 1.0. Intrductin This API dcument describes the use f ACR122S interface sftware t facilitate applicatin develpment with the ACR122S reader. This interface sftware is supplied in the frm f 32-bit and 64-bit DLL (Dynamic Link Library which can be prgrammed using ppular develpment tls like Java, Delphi, Visual Basic, Visual C++, Visual C# and Visual Basic.NET. ACR122S can be cnnected t the PC thrugh the RS-232 interface. The architecture f the ACR122S library can be visualized as the fllwing diagram: Reader PC Applicatin Prgram ACR122S Windws Driver Prgram Operating System RS-232 Layer Figure 1: ACR122S Library Architecture Page 3 f 23

4 2.0. Features Serial RS-232 Interface: Baud Rate = bps, 8-N-1 USB interface fr pwer supply CCID-like fram frmat (Binary frmat Smart Card Reader: Read/Write speed f up t 424 kbps Built-in antenna fr cntactless tag access, with card reading distance f up t 50 mm (depending n tag type Supprt fr ISO Part 4 Type A and B cards, Mifare, FeliCa, and all fur types f NFC (ISO/IEC tags Built-in anti-cllisin feature (nly ne tag is accessed at any time ISO 7816-cmpliant SAM slt Built-in Peripherals: Tw user-cntrllable LEDs User-cntrllable buzzer Cmpliant with the fllwing standards: ISO CE FCC KC VCCI RHS Page 4 f 23

5 3.0. Applicatin Prgramming Interface Overview The ACR122S DLL is a set f high-level functins prvided fr the applicatin sftware use. It supplies a cnsistent API (Applicatin Prgramming Interface fr the applicatin t perate n ACR122S and n the crrespnding presented card. The DLL cmmunicates with the ACR122S via the cmmunicatin prt facilities prvided by the perating system. The ACR122S API defines a cmmn way f accessing the ACR122S. Applicatin prgrams invke the ACR122S thrugh the interface functins and perfrm peratins n the presented card. The header file ACR122.h is available fr the prgram develper, which cntains all the functin prttypes and macrs as described belw Reader Define Dcumentatin ACR122_GetFirmwareVersin and ACR122_GetFirmwareVersinA ACR122_GetFirmwareVersin will be mapped t ACR122_GetFirmwareVersinW( functin if Unicde is defined. Otherwise, it will be mapped t ACR122_GetFirmwareVersinA( functin. #define ACR122_GetFirmwareVersin ACR122_GetFirmwareVersinA ACR122_Open and ACR122_OpenA ACR122_Open will be mapped t ACR122_OpenW( functin if Unicde is defined. Otherwise, it will be mapped t ACR122_OpenA( functin. #define ACR122_Open ACR122_OpenA Functin Dcumentatin ACR122_OpenA This functin is used t pen the reader and return a handle value as a reference. DWORD WINAPI ACR122_OpenA ( LPCSTR prtname, LPHANDLE phreader [in] prtname [ut] phreader Descriptin Prt name. "\\.\COM1" means that the reader is cnnected t COM1 in Windws. Pinter t the HANDLE variable. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Page 5 f 23

6 ACR122_OpenW This functin is used t pen a reader and return a handle value as reference. DWORD WINAPI ACR122_OpenW ( LPCWSTR prtname, LPHANDLE phreader [in] prtname [ut] phreader Descriptin Prt name. "\\.\COM1" means that the reader is cnnected t COM1 in Windws. Pinter t the HANDLE variable. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Surce Cde Example HANDLE hreader; // Open reader using COM1 ret = ACR122_Open(TEXT("\\\\.\\COM1", &hreader; ACR122_Clse This functin is used t clse the reader and release the resurces. DWORD WINAPI ACR122_Clse ( HANDLE hreader Descriptin A reference value returned frm ACR122_Open( functin. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Surce Cde Example // Clse reader ret = ACR122_Clse(hReader; Page 6 f 23

7 ACR122_GetNumSlts This functin is used t retrieve the number f slts. DWORD WINAPI ACR122_GetNumSlts ( HANDLE hreader, LPDWORD pnumslts [ut] pnumslts Descriptin A reference value returned frm ACR122_Open( functin. Pinter t a DWORD variable in which the number f slts is returned. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Surce Cde Example DWORD numslts; // Get number f slts ret = ACR122_GetNumSlts(hReader, &numslts; ACR122_GetBaudRate This functin is used t retrieve the baud rate f reader. DWORD WINAPI ACR122_GetBaudRate ( HANDLE hreader, LPDWORD pbaudrate [ut] pbaudrate Descriptin A reference value returned frm ACR122_Open( functin. Pinter t a DWORD variable in which the baud rate is returned. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Surce Cde Example DWORD baudrate; // Get baud rate ret = ACR122_GetBaudRate(hReader, &baudrate; Page 7 f 23

8 ACR122_SetBaudRate This functin is used t set the cmmunicatin baud rate f reader. The reader supprts 9600 bps and bps. DWORD WINAPI ACR122_SetBaudRate ( HANDLE hreader, DWORD baudrate [in] baudrate Descriptin A reference value returned frm ACR122_Open( functin. Baud rate must be 9600 bps r bps. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Surce Cde Example // Set baud rate t bps ret = ACR122_SetBaudRate(hReader, ; ACR122_GetTimeuts This functin is used t retrieve the timeut parameters fr status and respnse peratins f the reader. DWORD WINAPI ACR122_GetTimeuts ( HANDLE hreader, PACR122_TIMEOUTS ptimeuts [ut] ptimeuts Descriptin A reference value returned frm ACR122_Open( functin. Pinter t a ACR122_TIMEOUTS structure in which the timeut infrmatin is returned. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Nte: Fr PACR122_TIMEOUTS, please see Appendix A.1 _ACR122_TIMEOUTS Struct Reference. Page 8 f 23

9 Surce Cde Example ACR122_TIMEOUTS timeuts; // Get timeuts ret = ACR122_GetTimeuts(hReader, &timeuts; ACR122_SetTimeuts This functin is used t set the timeut parameters fr status and respnse peratins n the reader. DWORD WINAPI ACR122_SetTimeuts ( HANDLE hreader, cnst PACR122_TIMEOUTS ptimeuts [in] ptimeuts Descriptin A reference value returned frm ACR122_Open( functin. Pinter t a ACR122_TIMEOUTS structure that cntains the new timeut values The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Nte: Fr PACR122_TIMEOUTS, please see Appendix A.1 _ACR122_TIMEOUTS Struct Reference. Surce Cde Example ACR122_TIMEOUTS timeuts; // Get timeuts //... // Mdify status timeut t 100 ms timeuts.statustimeut = 100; // Set timeuts ret = ACR122_SetTimeuts(hReader, &timeuts; ACR122_GetFirmwareVersinA This functin is used t retrieve the firmware versin in ANSI string f the slt. DWORD WINAPI ACR122_GetFirmwareVersinA ( HANDLE hreader, DWORD sltnum, LPSTR firmwareversin, LPDWORD pfirmwareversinlen Descriptin A reference value returned frm ACR122_Open( functin. Page 9 f 23

10 [in] sltnum Slt number. Descriptin [ut] firmwareversin [in,ut] pfirmwareversinlen A pinter t the buffer that receives the firmware versin returned frm the reader. The length in number f bytes f the firmware versin parameter and receives the actual number f bytes received frm the reader. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes ACR122_GetFirmwareVersinW This functin is used t retrieve the firmware versin in Unicde string f the slt. DWORD WINAPI ACR122_GetFirmwareVersinW ( HANDLE hreader, DWORD sltnum, LPWSTR firmwareversin, LPDWORD pfirmwareversinlen [in] sltnum [ut] firmwareversin [in,ut] pfirmwareversinlen Descriptin A reference value returned frm ACR122_Open( functin. Slt number. A pinter t the buffer that receives the firmware versin returned frm the reader. The length in number f bytes f the firmware versin parameter and receives the actual number f bytes received frm the reader. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Surce Cde Example TCHAR firmwareversin[20]; DWORD firmwareversinlen; // Get firmware versin firmwareversinlen = sizef(firmwareversin / sizef(tchar; ret = ACR122_GetFirmwareVersin(hReader, firmwareversin, &firmwareversinlen; Page 10 f 23

11 3.2. LED Functin Dcumentatin ACR122_SetLedStatesWithBeep This functin is used t cntrl LED0, LED1 and buzzer peratin f the reader. DWORD WINAPI ACR122_SetLedStatesWithBeep ( HANDLE hreader, PACR122_LED_CONTROL cntrls, DWORD numcntrls, DWORD t1, DWORD t2, DWORD numtimes, DWORD buzzermde [in] cntrls Descriptin A reference value returned frm ACR122_Open( functin. A pinter t the array f ACR122_LED_CONTROL data structure. [in] numcntrls Number f cntrls must be 2. [in] t1 T1 in millisecnds. The value must be frm 0 t [in] t2 T2 in millisecnds. The value must be frm 0 t [in] numtimes Number f times. The values must be frm 0 t 255. A bitmask f buzzer mde. Pssible values may be cmbined with the OR peratin. [in] buzzermde Value ACR122_BUZZER_MODE_O FF ACR122_BUZZER_MODE_O N_T1 ACR122_BUZZER_MODE_O N_T2 Meaning The buzzer will nt turn n. The buzzer will turn n during T1 duratin. The buzzer will turn n during T2 duratin. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Nte: Fr PACR122_LED_CONTROL, please see Appendix A.2 _ACR122_LED_CONTROL Struct Reference. Page 11 f 23

12 Surce Cde Example ACR122_LED_CONTROL cntrls[2]; // Set LED0 t ON cntrls[0].finalstate = ACR122_LED_STATE_ON; cntrls[0].updateenabled = TRUE; cntrls[0].initialblinkingstate = ACR122_LED_STATE_OFF; cntrls[0].blinkenabled = FALSE; // Set LED1 t blink cntrls[1].finalstate = ACR122_LED_STATE_OFF; cntrls[1].updateenabled = FALSE; cntrls[1].initialblinkingstate = ACR122_LED_STATE_OFF; cntrls[1].blinkenabled = TRUE; // Beep n T1 where T1 and T2 are equal t 100 ms ret = ACR122_SetLedStatesWithBeep(hReader, cntrls, 2, 100, 100, ACR122_BUZZER_MODE_ON_T1; Page 12 f 23

13 3.3. Card Functin Dcumentatin ACR122_DirectTransmit This functin is used t send tag cmmand and receive respnse frm the cntactless interface f the reader. DWORD WINAPI ACR122_DirectTransmit ( HANDLE cnst LPBYTE sendbuffer, DWORD sendbufferlen, LPBYTE recvbuffer, LPDWORD precvbufferlen hreader, [in] sendbuffer [in] sendbufferlen [in] recvbuffer [in,ut] precvbufferlen Descriptin A reference value returned frm ACR122_Open( functin. A pinter t the actual data t be written t the card. The length in number f bytes f the sendbuffer parameter. A pinter t any data returned frm the card. The length in number f bytes f the recvbuffer parameter and receives the actual number f bytes received frm the card. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Surce Cde Example BYTE cmmand[] = { 0xD4, 0x4A, 0x01, 0x00 }; // Pll Type A card DWORD cmmandlen = sizef(cmmand; BYTE respnse[300]; DWORD respnselen = sizef(respnse; ret = ACR122_DirectTransmit(hReader, cmmand, cmmandlen, respnse, &respnselen; Page 13 f 23

14 This API is used fr exchanging cmmands and respnses with the cntactless interface. Sme pssible cmmand grups are: Grup 1. PICC Plling fr different Tag Types. E.g. ISO Type A, ISO Type B, FeliCa and Mifare Case: ISO Type A ============================================================================= Cmmand = {D4 4A 01 00} Respnse = {D5 4B F A F } In which, Number f Tag fund = [01] Target number = 01 SENS_RES = SEL_RES = 28 Length f the UID = 4 UID = F A0 ATS = F Operatin Finished = r Respnse = {D5 4B } (n tag fund Case: ISO Type B ============================================================================= Cmmand = {D4 4A } Respnse = {D5 4B F } In which, Number f Tag fund = [01] Target number = 01 ATQB = F ATTRIB_RES Length = 01 ATTRIB_RES = 21 Operatin Finished = r Respnse = {D5 4B } (n tag fund Case: Mifare 1K/4K/Ultralight ============================================================================= Cmmand = {D4 4A 01 00} Respnse = {D5 4B E 0C A1 BF } In which, Number f Tag fund = [01] Target number = 01 SENS_RES = Page 14 f 23

15 SEL_RES = 00 Length f the UID = 7 UID = 04 6E 0C A1 BF Operatin Finished = r Respnse = {D5 4B } (n tag fund Nte: The tag type can be determined by recgnizing the SEL_RES. SEL_RES f sme cmmn tag types: 00 = MIFARE Ultralight 08 = MIFARE 1K 09 = MIFARE MINI 18 = MIFARE 4K 20 = MIFARE DESFIRE 28 = JCOP30 98 = Gemplus MPCOS Case: FeliCa 212 K ============================================================================= Cmmand = {D4 4A FF FF 00 00} Respnse = {D5 4B B 02 4F 49 8A 8A } In which, Number f Tag fund = [01] Target number = 01 POL_RES Length = 14 Respnse Cde = 01 NFCID2 = PAD = B 02 4F 49 8A 8A Operatin Finished = r Respnse = {D5 4B } (n tag fund Case: FeliCa 424K ============================================================================= Cmmand = {D4 4A FF FF 00 00} Respnse = {D5 4B B 02 4F 49 8A 8A } In which, Number f Tag fund = [01] Target number = 01 POL_RES Length = 14 Page 15 f 23

16 Respnse Cde = 01 NFCID2 = PAD = B 02 4F 49 8A 8A Operatin Finished = r Respnse = {D5 4B }(n tag fund Grup 2. Exchange Tag Cmmands and Respnses fr ISO cmpliant tags. C_APDU = Cmmand = {D } Respnse = {D5 41 [00] ED C B } In which, Respnse Data = ED C B Grup 3. Exchange FeliCa Cmmands and Respnses, e.g. Read the memry blck. Cmmand = {D } Respnse = {D5 41 [00] 1D AA 55 AA 55 AA 55 AA 55 AA 55 AA 55 AA 55 AA 90 00} Nte: Please refer t FeliCa specificatin fr details. Grup 4. Exchange Mifare 1K/4K Classic Cmmands and Respnse Example 1: CMD fr KEY A Authenticatin Blck 04 KEY = FF FF FF FF FF FF UID = F6 8E 2A 99 Cmmand = {D FF FF FF FF FF FF F6 8E 2A 99} Respnse = {D5 41 [00] 90 00} Example 2: CMD fr KEY B Authenticatin Blck 04 KEY = FF FF FF FF FF FF UID = F6 8E 2A 99 Cmmand = {D FF FF FF FF FF FF F6 8E 2A 99} Respnse = {D5 41 [00] 90 00} Example 3: CMD fr Read Data Blck Read the cntent f Blck 04 Cmmand = {D } Respnse = {D5 41 [00] } In which, Blck Data = Page 16 f 23

17 Example 4: CMD fr Update Data Blck Update the cntent f Blck 04 Cmmand = {D A A 0B 0C 0D 0E 0F 10} Respnse = {D5 41 [00] 90 00} Nte: The errr cde [XX] will be returned. [00] = Valid Other = Errr Please refer t Errr Cdes Table fr mre details. Grup 5. Exchange Mifare 1K/4K Classic Value Blck Cmmands and Respnse The value blcks are used fr perfrming electrnic purse functins. E.g. Increment, Decrement, Restre and Transfer, etc. The value blcks have a fixed data frmat which permits errr detectin and crrectin and a backup management. Byte Number Descriptin Value Value Value Adr Adr Adr Adr Where: Value Adr A signed 4-byte value. The lwest significant byte ff a value is stred in the lwest address byte. Negative values are stred in standard 2 s cmplement frmat. 1-Byte address which can be used t save the strage address f a blck (ptinal. Example: Value 100 (decimal = 64 (Hex, assume Blck = 0x05 The frmatted value blck = B FF FF FF FA 05 FA 1. Update the cntent f Blck 05 with a value 100 (dec Cmmand = {D A B FF FF FF FA 05 FA} Respnse = {D5 41 [00] 90 00} 2. Increment the value f Blck 05 by 1 (dec Cmmand = {D C } Respnse = {D5 41 [00] 90 00} Nte: Decrement the value f Blck 05 by 1 (dec Cmmand = {D C } Page 17 f 23

18 3. Transfer the prir calculated value f Blck 05 (dec Cmmand = {D B0 05} Respnse = {D5 41 [00] 90 00} 4. Restre the value f Blck 05 (cancel the prir Increment r Decrement peratin Cmmand = {D C2 05} 5. Read the cntent f Blck 05 Cmmand = {D } Respnse = {D5 41 [00] A FF FF FF FA 05 FA 90 00} In which, the value = 101 (dec 6. Cpy the value f Blck 05 t Blck 06 (dec Cmmand = {D C2 05} Respnse = {D5 41 [00] 90 00} Cmmand = {D B0 06} Respnse = {D5 41 [00] 90 00} 7. Read the cntent f Blck 06 Cmmand = {D } Respnse = {D5 41 [00] A FF FF FF FA 05 FA 90 00} In which, the value = 101 (dec. The Adr 05 FA 05 FA tells us the value is cpied frm Blck 05. Grup 6: PICC Operatin parameters setting. Example 1: CMD fr PICC Plling Retry Time Cmmand = {D [00]} // retry time = 00 Respnse = {D5 33} Example 2: CMD fr Enable ISO Type A Activatin. E.g. T enter the ISO mde f JCOP Cmmand = {D } Respnse = {D5 12} Example 3: CMD fr Disable ISO Type A Activatin. E.g. T enter the MIFARE emulatin mde f JCOP Cmmand = {D } Respnse = {D5 12} Page 18 f 23

19 Example 4: CMD fr Turn On PICC Antenna Cmmand = {D } Respnse = {D5 33} Example 5: CMD fr Turn Off PICC Antenna Cmmand = {D } Respnse = {D5 33} ACR122_ExchangeApdu This functin is used t send an APDU cmmand and receive an APDU respnse frm the card. DWORD WINAPI ACR122_ExchangeApdu ( HANDLE hreader, DWORD sltnum, cnst LPBYTE sendbuffer, DWORD sendbufferlen, LPBYTE recvbuffer, LPDWORD precvbufferlen [in] sltnum [in] sendbuffer [in] sendbufferlen [ut] recvbuffer [in,ut] precvbufferlen Descriptin A reference value returned frm ACR122_Open( functin. Slt number. A pinter t the actual data t be written t the card. The length in number f bytes f the sendbuffer parameter. A pinter t any data returned frm the card. The length in number f bytes f the recvbuffer parameter and receives the actual number f bytes received frm the card. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Surce Cde Example BYTE cmmand[] = { 0x80, 0x84, 0x00, 0x00, 0x08 }; DWORD cmmandlen = sizef(cmmand; BYTE respnse[300]; DWORD respnselen = sizef(respnse; // Exchange APDU n slt 0 ret = ACR122_ExchangeApdu(hReader, 0, cmmand, cmmandlen, respnse, &respnselen; Page 19 f 23

20 ACR122_PwerOffIcc This functin is used t pwer ff the card in the slt. DWORD WINAPI ACR122_PwerOffIcc ( HANDLE hreader, DWORD sltnum [in] sltnum Descriptin A reference value returned frm ACR122_Open( functin. Slt number. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Surce Cde Example // Pwer ff slt 0 ret = ACR122_PwerOffIcc(hReader, 0; ACR122_PwerOnIcc This functin is used t pwer n the card in the slt and then return the ATR string frm the card. DWORD WINAPI ACR122_PwerOnIcc ( HANDLE hreader, DWORD sltnum, LPBYTE atr, LPDWORD patrlen [in] sltnum [ut] atr [in,ut] patrlen Descriptin A reference value returned frm ACR122_Open( functin. Slt number. A pinter t the buffer that receives the ATR string returned frm the card. The length in number f bytes f the atr parameter and receives the actual number f bytes received frm the card. The peratin cmpleted An errr cde. See Windws API errr cdes and ACR122 errr cdes. Page 20 f 23

21 Surce Cde Example BYTE atr[64]; DWORD atrlen = sizef(atr; // Pwer n slt 0 ret = ACR122_PwerOnIcc(hReader, 0, atr, &atrlen; Page 21 f 23

22 Appendix A. Data Structures Appendix A.1. _ACR122_TIMEOUTS Struct Reference This data structure is used in ACR122_GetTimeuts( and ACR122_SetTimeuts( functin. DWORD _ACR122_TIMEOUTS::numRespnseRetries Number f respnse retries. Default is 1. DWORD _ACR122_TIMEOUTS::numStatusRetries Number f status retries. Default is 1. DWORD _ACR122_TIMEOUTS::respnseTimeut Respnse timeut in millisecnds. Default is ms. DWORD _ACR122_TIMEOUTS::statusTimeut Status timeut in millisecnds. Default is 2000 ms. Appendix A.2. _ACR122_LED_CONTROL Struct Reference This data structure is used in ACR122_SetLedStatesWithBeep( functin. BOOL _ACR122_LED_CONTROL::blinkEnabled Enable blink. Set t TRUE t enable blink. Otherwise, set t FALSE. DWORD _ACR122_LED_CONTROL::finalState Final state. Pssible values are ACR122_LED_STATE_OFF and ACR122_LED_STATE_ON. DWORD _ACR122_LED_CONTROL::initialBlinkingState Initial blinking state. Pssible values are ACR122_LED_STATE_OFF and ACR122_LED_STATE_ON. BOOL _ACR122_LED_CONTROL::updateEnabled Enable update. Set t TRUE t update the state. Otherwise, set t FALSE t keep the state unchanged. Page 22 f 23

23 Appendix B. Errr Cdes returned by high-level APIs ACR122_ERROR_NO_MORE_HANDLES ((DWORD 0x L The handle is invalid. ACR122_ERROR_UNKNOWN_STATUS ((DWORD 0x L Reader unknwn errr. ACR122_ERROR_OPERATION_FAILURE ((DWORD 0x L Operatin failed. ACR122_ERROR_OPERATION_TIMEOUT ((DWORD 0x L Timeut peratin. ACR122_ERROR_INVALID_CHECKSUM ((DWORD 0x L Checksum calculatin errr ACR122_ERROR_INVALID_PARAMETER ((DWORD 0x L Incrrect parameter input. Page 23 f 23