ACS ACR122T, Programming Manual

Page 1: ...Subject to change without prior notice info acs com hk www acs com hk Application Programming Interface V2 02 ACR122T USB Token NFC Reader ...

Page 2: ...1 Direct Transmit 21 6 2 Bi color LED and Buzzer Control 22 6 3 Get the Firmware Version of the Reader 24 6 4 Get the PICC Operating Parameter 25 6 5 Set the PICC Operating Parameter 26 7 0 Basic Program Flow for Contactless Applications 27 7 1 How to Access PC SC compliant Tags ISO 14443 4 28 7 2 How to Access DESFire Tags ISO 14443 4 29 7 3 How to Access FeliCa Tags ISO 18092 30 7 4 How to Acces...

Page 3: ...le 2 ATR Format for ISO 14443 Part 3 PICCs 8 Table 3 ATR Format for ISO 14443 Part 4 PICCs 9 Table 4 Mifare 1K Memory Map 14 Table 5 Mifare 4K Memory Map 14 Table 6 Mifare Ultralight Memory Map 15 Table 7 Bi color LED and Buzzer Control Format 1 Byte 22 Table 8 Current LED State 1 Byte 23 Table 9 PICC Operating Parameter Default Value FFh 26 ...

Page 4: ...DUs for contactless tags following the PCSC Specification and makes use of pseudo APDUs in sending commands for ISO 18092 tags and controlling the device peripherals This document will discuss how you can use the ACR122T in your smart card system 1 1 Features USB 2 0 Full Speed Interface CCID Compliance Smart Card Reader o Read Write speed of up to 424 kbps o Built in antenna for contactless tag a...

Page 5: ...s specified in the USB Specification 1 1 The ACR122T is working in Full speed mode i e 12 Mbps Pin Signal Function 1 VBUS 5V power supply for the reader Max 200 mA Normal 100 mA 2 D Differential signal transmits data between ACR122T and PC 3 D Differential signal transmits data between ACR122T and PC 4 GND Reference voltage level for power supply Table 1 USB Interface ...

Page 6: ...22U NFC Reader which is discussed in this section The Standard Microsoft CCID and PCSC drivers are used Therefore no ACS drivers are required because the drivers are already built inside the Windows operating system You also have to modify your computer s registry settings to be able to use the full capabilities of the ACR122T NFC Reader See Appendix A for more details Figure 1 Communication Flow ...

Page 7: ...k Version 2 02 www acs com hk Page 7 of 45 2 2 Smart Card Reader Interface Overview Just click the Device Manager to find out the ACR122T PICC Interface The standard Microsoft USB CCID Driver is used Figure 2 Smart Card Reader Interface on the Device Manager ...

Page 8: ...ans T 0 3 01h TD2 Higher nibble 0 means no TA3 TB3 TC3 TD3 following Lower nibble 1 means T 1 4 To 3 N 80h T1 Category indicator byte 80 means A status indicator may be present in an optional COMPACT TLV data object 4Fh Tk Application identifier Presence Indicator 0Ch Length RID Registered Application Provider Identifier RID A0 00 00 03 06h SS Byte for standard C0 C1h Bytes for card name 00 00 00 ...

Page 9: ...A1 TB1 TC1 only TD1 is following Lower nibble N is the number of historical bytes HistByte 0 to HistByte N 1 2 80h TD1 Higher nibble 8 means no TA2 TB2 TC2 only TD2 is following Lower nibble 0 means T 0 3 01h TD2 Higher nibble 0 means no TA3 TB3 TC3 TD3 following Lower nibble 1 means T 1 4 to 3 N XXh T1 Historical Bytes ISO 14443A The historical bytes from ATS response Refer to the ISO14443 4 spec...

Page 10: ...eve the full ATS if available The ATS is returned for ISO 14443A 3 or ISO 14443B 3 4 PICCs Another example would be the ATR for ST19XRC8E which is ST19XRC8E ATR 3B 8C 80 01 50 12 23 45 56 12 53 54 4E 33 81 C3 55h ATR Initial Header T0 TD1 TD2 ATQB T1 Tk TCK 3Bh 86h 80h 01h 50h 12 23 45 56 12 53 54 4E 33 81 C3h 55h Since this card follows ISO 14443 Type B the response would be ATQB which is 50 12 2...

Page 11: ... Response Format UID 2 Bytes if P1 0x00h Response Data Out Result UID LSB UID MSB SW1 SW2 Get ATS of a ISO 14443 A card ATS 2 Bytes if P1 0x01h Response Data Out Result ATS SW1 SW2 Response Codes Results SW1 SW2 Meaning Success 90 00h The operation completed successfully Error 63 00h The operation failed Error 6A 81h Function not supported Example 1 To get the serial number of the connected PICC U...

Page 12: ...ss INS P1 P2 Lc Data In Load Authentication Keys FFh 82h Key Structure Key Number 06h Key 6 Bytes Where Key Structure 1 Byte 0x00h Key is loaded into the reader volatile memory Other Reserved Key Number 1 Byte 0x00h 0x01h Key Location The keys will disappear once the reader is disconnected from the PC Key 6 Bytes The key value loaded into the reader E g FF FF FF FF FF FFh Load Authentication Keys ...

Page 13: ...block to be authenticated Key Type 1 Byte 0x60h Key is used as a TYPE A key for authentication 0x61h Key is used as a TYPE B key for authentication Key Number 1 Byte 0x00h 0x01h Key Location Note For Mifare 1K Card it has totally 16 sectors and each sector consists of 4 consecutive blocks E g Sector 0x00h consists of Blocks 0x00h 0x01h 0x02h and 0x03h Sector 0x01h consists of Blocks 0x04h 0x05h 0x...

Page 14: ...K Memory Map Sectors Total 32 sectors Each sector consists of 4 consecutive blocks Data Blocks 3 blocks 16 bytes per block Trailer Block 1 block 16 bytes Sector 0 0x00 0x02h 0x03h Sector 1 0x04 0x06h 0x07h Sector 30 0x78 0x7Ah 0x7Bh Sector 31 0x7C 0x7Eh 0x7Fh Sectors Total 8 sectors Each sector consists of 16 consecutive blocks Data Blocks 15 blocks 16 bytes per block Trailer Block 1 block 16 byte...

Page 15: ...a20 Data21 Data22 Data23 9 Data read write Data24 Data25 Data26 Data27 10 Data read write Data28 Data29 Data30 Data31 11 Data read write Data32 Data33 Data34 Data35 12 Data read write Data36 Data37 Data38 Data39 13 Data read write Data40 Data41 Data42 Data43 14 Data read write Data44 Data45 Data46 Data47 15 Table 6 Mifare Ultralight Memory Map Example 1 To authenticate the Block 0x04h with a TYPE ...

Page 16: ...e Block Number 1 Byte The block to be accessed Number of Bytes to Read 1 Byte Maximum 16 bytes Read Binary Block Response Format N 2 Bytes Response Data Out Result 0 N 16 SW1 SW2 Response Codes Results SW1 SW2 Meaning Success 90 00h The operation completed successfully Error 63 00h The operation failed Example 1 Read 16 bytes from the binary block 0x04h Mifare 1K or 4K APDU FF B0 00 04 10h 2 Read ...

Page 17: ... Bytes for Mifare 1K 4K Where Block Number 1 Byte The starting block to be updated Number of Bytes to Update 1 Byte 16 bytes for Mifare 1K 4K 4 bytes for Mifare Ultralight Block Data 4 or 16 Bytes The data to be written into the binary block blocks Update Binary Block Response Codes 2 Bytes Results SW1 SW2 Meaning Success 90 00h The operation completed successfully Error 63 00h The operation faile...

Page 18: ...e value block to be manipulated VB_OP 1 Byte 0x00h Store the VB_Value into the block The block will then be converted to a value block 0x01h Increment the value of the value block by the VB_Value This command is only valid for value block 0x02h Decrement the value of the value block by the VB_Value This command is only valid for value block VB_Value 4 Bytes The value used for value manipulation Th...

Page 19: ...lock Number 1 Byte The value block to be accessed Read Value Block Response Format 4 2 Bytes Response Data Out Result Value MSB LSB SW1 SW2 Where Value 4 Bytes The value returned from the card The value is a signed long integer 4 bytes Example 1 Decimal 4 0xFFh 0xFFh 0xFFh 0xFCh Value MSB LSB FFh FFh FFh FCh Example 2 Decimal 1 0x00h 0x00h 0x00h 0x01h Value MSB LSB 00h 00h 00h 01h Response Codes R...

Page 20: ...source and target value blocks must be in the same sector Restore Value Block Response Format 2 Bytes Response Data Out Result SW1 SW2 Response Codes Results SW1 SW2 Meaning Success 90 00h The operation completed successfully Error 63 00h The operation failed Example 1 Store a value 1 into block 0x05h APDU FF D7 00 05 05 00 00 00 00 01h Answer 90 00h 2 Read the value block 0x05h APDU FF B1 00 05 0...

Page 21: ...f the tag is already connected Or the Pseudo APDUs can be sent by using Escape Command if the tag is not presented yet 6 1 Direct Transmit This is the Payload to be sent to the tag or reader Direct Transmit Command Format Length of the Payload 5 Bytes Command Class INS P1 P2 Lc Data In Direct Transmit 0xFFh 0x00h 0x00h 0x00h Number of Bytes to send Payload Where Lc 1 Byte Number of Bytes to Send M...

Page 22: ...sk 1 Update the State 0 No change Bit 4 Initial Red LED Blinking State 1 On 0 Off Bit 5 Initial Green LED Blinking State 1 On 0 Off Bit 6 Red LED Blinking Mask 1 Blink 0 Not Blink Bit 7 Green LED Blinking Mask 1 Blink 0 Not Blink Table 7 Bi color LED and Buzzer Control Format 1 Byte Data In Blinking Duration Control Bi color LED Blinking Duration Control Format 4 Bytes Byte 0 Byte 1 Byte 2 Byte 3 ...

Page 23: ...ed after the LED Blinking operation is completed 2 The LED will not be changed if the corresponding LED Mask is not enabled 3 The LED will not be blinking if the corresponding LED Blinking Mask is not enabled Also the number of repetition must be greater than zero 4 T1 and T2 duration parameters are used for controlling the duty cycle of LED blinking and Buzzer Turn On duration For example if T1 1...

Page 24: ...are Version of the Reader This is used to retrieve the firmware version of the reader Command Format 5 Bytes Command Class INS P1 P2 Le Get Firmware Version 0xFFh 0x00h 0x48h 0x00h 0x00h Response Format 10 Bytes Response Data Out Result Firmware Version E g Response 41 43 52 31 32 32 55 32 30 31h Hex ACR122T201 ASCII ...

Page 25: ...5 of 45 6 4 Get the PICC Operating Parameter This is used to retrieve the PICC Operating Parameter of the reader Command Format 5 Bytes Command Class INS P1 P2 Le Get PICC Operating Parameter 0xFFh 0x00h 0x50h 0x00h 0x00h Response Format 1Byte Response Data Out Result PICC Operating Parameter ...

Page 26: ...er Description Option 7 Auto PICC Polling To enable the PICC Polling 1 Enable 0 Disable 6 Auto ATS Generation To issue ATS Request whenever an ISO14443 4 Type A tag is activated 1 Enable 0 Disable 5 Polling Interval To set the time interval between successive PICC Polling 1 250 ms 0 500 ms 4 FeliCa 424K The Tag Types to be detected during PICC Polling 1 Detect 0 Skip 3 FeliCa 212K 1 Detect 0 Skip ...

Page 27: ...ndix A for more details Step 1 The first thing is to connect the ACR122T PICC Interface Step 2 Access the PICC by sending APDU commands Step N Disconnect the ACR122T PICC Interface Shut down the application Note 1 The antenna can be switched off in order to save the power Turn off the antenna power FF 00 00 00 04 D4 32 01 00h Turn on the antenna power FF 00 00 00 04 D4 32 01 01h 2 Standard and Non...

Page 28: ...gh the T CL emulation Just simply treat the Mifare tags as standard ISO 14443 4 tags For more information please refer to topic PICC Commands for Mifare Classic Memory Tags ISO 7816 4 APDU Format Command Class INS P1 P2 Lc Data In Le ISO 7816 Part 4 Command Length of the Data In Expected length of the Response Data ISO 7816 4 Response Format Data 2 Bytes Response Data Out Result Response Data SW1 ...

Page 29: ... details Example 2 DESFire Frame Level Chaining ISO 7816 wrapping mode In this example the application has to do the Frame Level Chaining To get the version of the DESFire card Step 1 Send an APDU 90 60 00 00 00h to get the first frame INS 0x60h Answer 04 01 01 00 02 18 05 91 AFh 91AFh Step 2 Send an APDU 90 AF 00 00 00h to get the second frame INS 0xAFh Answer 04 01 01 00 06 18 05 91 AFh 91AFh St...

Page 30: ... 18092 Typical sequence may be 1 Present the FeliCa tag and connect the PICC Interface 2 Read Update the memory of the tag Step 1 Connect the tag The ATR 3B 8F 80 01 80 4F 0C A0 00 00 03 06 03 F0 11 00 00 00 00 8Ah In which F0 11 FeliCa 212K Step 2 Read the memory block without using Pseudo APDU 10 06h 8 byte NFC ID 01 09 01 01 80 00h 1D 07h 8 byte NFC ID 00 00 01 00 AA 55 AA 55 AA 55 AA 55 AA 55 ...

Page 31: ...tep 2 Read the memory address 08h Block 1 Byte 0 without using Pseudo APDU 01 08h 18h 90 00h In which Response Data 18h or Step 2 Read the memory address 08h Block 1 Byte 0 using Pseudo APDU FF 00 00 00 05 D4 40 01 01 08h In which 05h is the length of the Pseudo APDU Data D4 40 01 01 08h D4 40 01h is the DataExchange Command 01 08h is the data to be sent to the tag D5 41 00 18h 90 00h In which Res...

Page 32: ...acs com hk Page 32 of 45 Memory Address Block No 8 Byte No E g Memory Address 08h hex 1 x 8 0 Block 1 Byte 0 Data0 E g Memory Address 10h hex 2 x 8 0 Block 2 Byte 0 Data8 Figure 4 Topaz Memory Map Please refer to the Jewel and Topaz specification for more detailed information ...

Page 33: ... 00 00 80 90 00h Err is an error code corresponding to the latest error detected Field indicates if an external RF field is present and detected Field 0x01h or not Field 0x00h NbTg is the number of targets The default value is 1 Tg logical number BrRx bit rate in reception 0x00h 106 kbps 0x01h 212 kbps 0x02h 424 kbps BrTx bit rate in transmission 0x00h 106 kbps 0x01h 212 kbps 0x02h 424 kbps Type m...

Page 34: ...ed 3 Press the button Connect to establish a connection between the PC and the ACR122T reader 4 Enter 3500 in the Command Text Box 5 Enter the PCSC Escape Command e g FF 00 48 00 00h and press the button Send to send the command to the reader Get the firmware version 6 Press the button Disconnect to break the connection 7 In order to send or receive Escape commands to a reader follow the instructi...

Page 35: ...g instructions enumerate the steps to enable the PC SC Escape command 1 Execute the regedit in the Run Command Menu of Windows 2 Add a DWORD EscapeCommandEnable under HKLM SYSTEM CCS Enum USB Vid_07 2F Pid_2200 Device Parameters For Vista the path is Computer HKEY_LOCAL_MACHINE SYS TEMS CurrentControlSet Enum USB ...

Page 36: ...e 36 of 45 3 Look for VID_072F PID_2200 Then expand the node Look under Device parameters 4 Create a DWORD entry 32 bit with the name EscapeCommandEnable 5 To modify the value of the EscapeCommandEnable double click on the entry and input 1 in the Value data with the base set in Hexadecimal ...

Page 37: ...and and Response Flow PC Sequences Reader USB Interface 12 Mbps Tag RF Interface 13 56 MHz 1 The command is sent Contactless Related Command APDU Command e g 00 84 00 00 08h Get Challenge Tag specific Command Frame APDU Command embedded in ISO 14443 Frame 2 The response is received Contactless Related Response APDU Response e g 11 22 33 44 55 66 77 88h 90 00h Tag specific Response Frame APDU Respo...

Page 38: ...terface 13 56 MHz 1 The command is sent Contactless Related Command Native Command e g 01 08h read memory address 08h or Pseudo APDU Command Native Command e g FF 00 00 00 05 D4 40 01h 01 08h Tag specific Command Frame Native Command embedded in ISO 18092 Frame 2 The response is received Contactless Related Response Native Response e g 00h 90 00h or Pseudo APDU Response Native Response e g D5 41 0...

Page 39: ...fore has automatically switched off the antenna drivers 0x0Eh Internal buffer overflow 0x10h Invalid parameter range format 0x12h DEP Protocol The chip configured in target mode does not support the command received from the initiator the command received is not one of the following ATR_REQ WUP_REQ PSL_REQ DEP_REQ DSL_REQ RLS_REQ ref 1 0x13h DEP Protocol Mifare ISO IEC 14443 4 The data format does...

Page 40: ...om hk Page 40 of 45 Error Code Error 0x2Bh ISO IEC 14443 3B only the card previously activated has disappeared 0x2Ch Mismatch between the NFCID3 initiator and the NFCID3 target in DEP 212 424 kbps passive 0x2Dh An over current event has been detected 0x2Eh NAD missing in DEP frame ...

Page 41: ... turn on RED and Green Color LEDs Assume both Red and Green LEDs are OFF initially Not link to the buzzer APDU FF 00 40 0F 04 00 00 00 00h Response 90 03h RED and Green LEDs are ON To turn off both RED and Green LEDs APDU FF 00 40 0C 04 00 00 00 00h Example 3 To turn off the RED Color LED only and leave the Green Color LED unchanged Assume both Red and Green LEDs are ON initially Not link to the b...

Page 42: ...the Green LED is initially ON The Red LED and buzzer will turn on during the T1 duration while the Green LED will turn off during the T1 duration 1 Hz 1000 ms Time Interval 500 ms ON 500 ms OFF T1 Duration 2000 ms 0x14h T2 Duration 0 ms 0x00h Number of repetition 0x01h Link to Buzzer 0x01h APDU FF 00 40 50 04 14 00 01 01h Response 90 02h T1 2000 ms T2 0 ms Red LED On Red LED Off Green LED Off Buzz...

Page 43: ...will be blinking The buzzer will turn on during the T1 duration while the Green LED will turn off during both the T1 and T2 duration After the blinking the Green LED will turn ON The Red LED will resume to the initial state after the blinking 1 Hz 1000 ms Time Interval 500 ms ON 500 ms OFF T1 Duration 500 ms 0x05h T2 Duration 500 ms 0x05h Number of repetition 0x03h Link to Buzzer 0x01h APDU FF 00 ...

Page 44: ...initially OFF Both Initial Red and Green Blinking States are ON The buzzer will turn on during both the T1 and T2 duration 1 Hz 1000 ms Time Interval 500 ms ON 500 ms OFF T1 Duration 500 ms 0x05h T2 Duration 500 ms 0x05h Number of repetition 0x03h Link to Buzzer 0x03h APDU FF 00 40 F0 04 05 05 03 03h Response 90 00h T1 500 ms T2 500 ms Red LED On Red LED Off Green LED On Green LED Off Buzzer On Bu...

Page 45: ... OFF The Initial Red Blinking State is ON The Initial Green Blinking States is OFF The buzzer will turn on during the T1 duration 1 Hz 1000 ms Time Interval 500 ms ON 500 ms OFF T1 Duration 500 ms 0x05h T2 Duration 500 ms 0x05h Number of repetition 0x03h Link to Buzzer 0x01h APDU FF 00 40 D0 04 05 05 03 01h Response 90 00h T1 500 ms Red LED On Red LED Off Green LED On Green LED Off Buzzer Off Buzz...