ACR89U-A1 Handheld Smart Card Reader Reference Manual V1.04 Subject to change without prior notice info@acs.com.hk www.acs.com.
Table of Contents 1.0. Introduction ............................................................................................................... 4 1.1. Document Overview .............................................................................................................. 4 2.0. Hardware Design ....................................................................................................... 5 2.1. 2.2. 2.3. 2.4. 2.5. Architecture ......................................................
List of Tables Table 1 : USB Interface Wiring ............................................................................................................... 5 Table 2 : CCID Error and Status Code ................................................................................................. 31 Table 3 : Keypad Input Format ............................................................................................................. 52 Table 4 : DLL Error Codes .............................................
1.0. Introduction This manual describes the use of ACR89 software programming interface to control the built-in accessories of the ACR89 multi-functional card reader. Built-in accessories are defined to be the keypad, LCD display, LEDs, buzzer and real-time clock, embedded in ACR89. Such components are not controlled through the smart card reader library. There are two ways to control the ACR89 peripherals: 1.
2.0. Hardware Design 2.1. Architecture The architecture of the ACR89 library can be visualized as the following diagram: PC Reader Application acr89.dll OS PC/SC OS Application Program DLL Program acr89fnc.sys Driver Program acr89bus.sys Driver Program CCID Layer USB Figure 1: ACR89U-A1 Architecture 2.2. USB Interface The ACR89U-A1 is connected to a computer through USB following the USB standards. 2.3.
bytes) Bulk IN – For commands to be sent from ACR89U-A1 to host (data packet size is 64 bytes) Interrupt IN – For card status message to be sent from ACR89U-A1 to host (data packet size is 8 bytes) 2.5. Contact Smart Card Interface The interface between the ACR89U-A1 and the inserted smart card follows the specifications of ISO 7816-3 with certain restrictions or enhancements to increase the practical functionality of the ACR89U-A1. 2.5.1.
3.0. ACR89U-A1 USB Communication Protocol ACR89U-A1 interfaces with host (in PC-Linked mode) with USB connection. CCID specifications have been released within the industry defining such protocol for the USB chip-card interface devices. CCID covers all the protocols required for operating smart cards and PIN. However, it does not define the protocol for operating other peripheral features that ACR89U-A1 also has.
Offset Field Size Value Description ACR89 supports the following features: 40 dwFeatures 4 000204B2h • Automatic parameter configuration based on ATR data • Automatic ICC clock frequency change according to parameters • Automatic baud rate change according to frequency and FI, DI parameters • Automatic PPS made by the ACR89 according to the current parameters • Automatic IFSD • Short APDU level exchange with ACR89 Maximum message length accepted by ACR89 is 272 bytes 44 dwMaxCCIDMessa
3.3.1. Command Summary 3.3.1.1. PC_to_RDR_IccPowerOn Activates the card slot and returns ATR from the card. Offset Field Size Value Description 0 bMessageType 1 62h - 1 dwLength 4 00000000h 2 bSlot 1 - Identifies the slot number for this command 5 bSeq 1 - Sequence number for command Size of extra bytes of this message 6 bPowerSelect 1 - Voltage that is applied to the ICC 00h – Automatic Voltage Selection 01h – 5 volts 02h – 3 volts 03h – 1.
3.3.1.4. PC_to_RDR_XfrBlock Transfers data block to the ICC. Offset Field Size Value Description 0 bMessageType 1 6Fh - 1 dwLength 4 - Size of abData field of this message 5 bSlot 1 - Identifies the slot number for this command 6 bSeq 1 - Sequence number for command Used to extend the CCIDs Block Waiting Timeout for this current transfer. The CCID will timeout the block after “this number multiplied by the Block Waiting Time” has expired.
3.3.1.7. PC_to_RDR_SetParameters Sets slot parameters. Offset Field Size Value Description 0 bMessageType 1 61h - 1 dwLength 4 - Size of extra bytes of this message 5 bSlot 1 - Identifies the slot number for this command 6 bSeq 1 - Sequence number for command 7 bProtocolNum 1 - Specifies what protocol data structure follows. 00h = Structure for protocol T=0 01h = Structure for protocol T=1 The following values are reserved for future use.
Offset 14 Field Size Value Description - ICC Clock Stop Support 00h = Stopping the Clock is not allowed 01h = Stop with Clock signal Low 02h = Stop with Clock signal High 03h = Stop with Clock either High or Low 1 bClockStop Protocol Data Structure for Protocol T=1 (dwLength=00000007h) Offset 10 Field Size Value 1 bmFindexDindex Description - B7-4 – FI – Index into the table 7 in ISO/IEC 7816-3:1997 selecting a clock rate conversion factor B3-0 – DI - Index into the table 8 in ISO/IEC 78
Offset Field Size Value Description 5 Bslot 1 - Identifies the slot number for this command 6 Bseq 1 - Sequence number for command 7 AbRFU 3 - Reserved for future use 10 AbData Byte array - Commands specified in Section 3.5.2 The response to this message is the RDR_to_PC_Escape message. This message could return any of the following ACR89 specific errors. Further qualification of error is provided in the extended response.
Offset Field Size Value Description Used to indicate the PIN operation: 00h = PIN Verification 01h = PIN Modification 02h = Transfer PIN from secure CCID 10 1 bPINOperation - buffer 03h = Wait ICC response 04h = Cancel PIN function 05h = Re-send last I-Block, valid only if protocol in use is T=1. 06h = Send next part of APDU, valid only if protocol in use is T=1.
3.4.1. Message Summary 3.4.1.1. RDR_to_PC_DataBlock This message is sent by ACR89 in response to PC_to_RDR_IccPowerOn, PC_to_RDR_XfrBlock and PC_to_RDR_Secure messages. Offset Field Size Value 0 bMessageType 1 80h 1 dwLength 4 - Size of abData field of this message 5 BSlot 1 - Same value as in Bulk-OUT message 6 BSeq 1 - Same value as in Bulk-OUT message 7 bStatus 1 - Slot status and error register as defined in Section 3.7.
Offset Field Size Value Description Value: 00h = Clock running 9 bClockStatus 1 - 01h = Clock stopped in state L 02h = Clock stopped in state H 03h = Clock stopped in an unknown state All other values are RFU. 3.4.1.3. RDR_to_PC_Parameters This message is sent by ACR89 in response to PC_to_RDR_GetParameters, PC_to_RDR_ResetParameters and PC_to_RDR_SetParameters messages.
3.4.1.4. RDR_to_PC_Escape This message is sent by ACR89 in response to PC_to_RDR_Escape message. Offset Field Size Value Description 0 bMessageType 1 83h - 1 dwLength 4 - Size of abData field of this message 5 bSlot 1 - Same value as in Bulk-OUT message 6 bSeq 1 - Same value as in Bulk-OUT message 7 bStatus 1 - Slot status and error register as defined in Section 3.7 8 bError 1 - Slot status and error register as defined in Section 3.
PC Request Message Code PC_to_ACR89_AuthoInfo 3.5.1. 0x38h ACR89 Response Message ACR89_to_PC_AuthInfo Code 0xB4h Extended Command Pipe Bulk-OUT Message The command format defined in this section will be the abData field to be filled in the PC_to_RDR_Escape message. Similar to the CCID message structure, the command format consists of fixed length Command Header and variable length Command Data portion. The command header is fixed to 5 bytes in length.
Offset 15 16 Field Name bKeyInputMode bTimeoutValue Type Size Bin 1 Hex 1 Value Description - B0 – Input mode (b0=0 for single key input, b0=1 for key string input). In key string input mode, the key string input is considered completed when “Enter” key is pressed. B1 – Keyboard mode (b1=0 for numeric input, b1=1 for alphanumeric input) B3 to b2 – Key display (b2=0 for key display disabled, b2=1 for key display enabled.
3.5.2.3. PC_to_ACR89_SetBacklight This command configures the LCD display. This command context is slot independent. Offset Field Name Type Size Value Description 10 BCmdCode Hex 1 19h - 11 wCmdLength Hex 2 0001h Size of command data (in big endian) 13 AbRfu Hex 2 0000 Reserved for future 15 BBacklight Hex 1 00h or 01h 00h = turns off backlight 01h = turns on backlight Others values RFU The response to this command is the ACR89_to_PC_DisplayStatus message. 3.5.2.4.
Offset Field Name Type Size Value 17 AbData Hex Var - Description Bitmap data of a row of the graphic to be displayed BIT-MAP BYTE M BIT-MAP BYTE N … Row 7 ….. Row 2 BIT-MAP BYTE BIT-MAP BYTE Row 1 BIT-MAP BYTE 1 BIT-MAP BYTE 2 MSB LSB Row 0 The sum of wCmdLength and bColumnPosition cannot exceed the column number of LCD (128). 0 1 2 127 …… Column Figure 3: PC_to_ACR89_DisplayGraphic – Bitmap Format The response to this command is the ACR89_to_PC_DisplayStatus message. 3.5.2.6.
3.5.2.7. PC_to_ACR89_ClearDisplay This command clears one or more rows on the LCD display. The cursor will be moved to the position at the starting point of the cleared block after executing this command. This command context is slot independent.
Offset Field Name Type Size Value Description 15 bRTCValue BCD 6 - New real time clock value. Format in YY, MM, DD, HH, MI and SS The response to this command is the ACR89_to_PC_TimeStamp message. 3.5.2.10.
Offset Field Name Type Size Value 23 bEeprom Data Hex Var.. - Description EEPROM data The response to this command is the ACR89_to_PC_DataBlock message. 3.5.2.12. PC_to_ACR89_SetLED The command allows user to switch on/off of Power, slot1 and slot2 on card reader with color red and green.
3.5.2.14. PC_to_ACR89_ProgramSPIFlash This command writes 256 bytes data to a page of the SPI flash. Offset Field Name Type Size Value Description 10 bCmdCode Hex 1 33h 11 AbAddress Hex 4 xxxxxx00h 15 AbData Hex 256 - Data write to a flash page 271 bCheckSum Hex 1 - Checksum of AbData Command Code Start address of flash page (in little endian) The response to this command is the ACR89_to_PC_ExMemStatus message. 3.5.2.15.
additional features that CCID does not cover. These messages are always responded using RDR_to_PC_Escape Bulk-IN message in standard CCID session 4.2.2.4. The response format defined in this section will be the abData to be filled in the RDR_to_PC_Escape messages. Similar to CCID message structure, the response format consists of fixed length Response Header and variable length Response Data portion. The response header is fixed to 5 bytes in length.
3.5.4.3. ACR89_to_PC_TimeStamp This message is sent by ACR89 PC_to_ACR89_SetRTC commands. in response to Offset Field Name Size Value Description 10 BRespType 1 84h - 11 wReturnCode 2 - 13 wRespLength 2 0006h 15 bTimeStamp 6 - 3.5.4.4. and PC_to_ACR89_ReadRTC Command response code (in big endian) Size of response data (in big endian) Current real time clock value.
Offset Field Name Size Value 15 AbData 256 - 271 bCheckSum Hex 1h Description Data read from a flash page Checksum of AbData Note: There will be no AbData and bCheckSum parts when command failed. 3.5.4.7. ACR89_to_PC_VersionInfo This message is sent by ACR89 in response to PC_to_ACR89_GetVersion command.
Response Code Value Description INVALID_COMMAND_CODE FFFEh Command code in the extended command (offset 10) is invalid. INVALID_COMMAND_LENGTH FFFDh Wrong length in the extended command. CANNOT_EXECUTE_COMMAND FFFCh Extended command cannot be executed. TIMEOUT FFFBh Timeout for executing the extended command. SCRIPT_ERROR FFFAh Cannot execute the script.
Offset 1 Field Size bmSlotICCState - Value Description - This field is reported on byte granularity. The size is ( 2 bits * number of slots ) rounded up to the nearest byte. Each slot has 2 bits. The least significant bit reports the current state of the slot (0b= no ICC present, 1b = ICC present). The most significant bit reports whether the slot has changed state since the last RDR_to_PC_NotifySlotChange message was sent (0b = no change, 1b = change).
Error Name Error Code Possible Cause PIN_TIMEOUT F0h - PIN_CANCELLED EFh - CMD_SLOT_BUSY E0h A second command was sent to a slot, which was already processing a command. ACR89_ERROR 10h Error code defined in ACR89 response header instead of this error register. DEVICE_VOID 11h ACR89 is not initialized. Either in manufacturer mode waiting for vendor personalization or the device has been tampered. INVALID_SECRET_KEY 12h Wrong secret key is presented.
4.0. Dynamic Link Library (DLL) ACR89 DLL is implemented as a library completely independent of the PC/SC sub-system of Windows. The library does not use any PC/SC to communicate between built-in accessories of ACR89 and the application program. 4.1. ACR89 DLL API Declarations 4.1.1. Enumerators 4.1.1.1.
4.1.1.3. Data Member Value Description LED_OFF 0x01h Turn the LED off. LED_RED 0x02h Switch the LED on and make it red. LED_GREEN 0x03h Switch the LED on and make it green. LED_YELLOW 0x04h Switch the LED on and make it yellow. EEPROM_ACCESS typedef enum _EEPROM_ACCESS { READ_EEPROM = 0x00, WRITE_EEPROM = 0x01 } EEPROM_ACCESS; Used by AS_AccessEEProm to select reading or writing from/to the internal EEProm of the ACR89. 4.1.1.4.
Data Member Value cbMaxKeyString 00h to 0Fh Maximum number of keys allowed for a key string in key string input mode (see Section 3.5.2.1 PC_to_ACR89_InputKey command). KeyDisplayRow 00h to 03h Starting row number on the LCD for displaying the keys input. 4.1.2.2.
4.1.2.3. Data Member Value CbTimeout 0 to 255 Description Key input timeout time value counted in 100ms (e.g. 100 stands for 10 seconds). LCDCURSOR typedef struct _LCD_CURSOR { BYTE cbRowPosition; // 0 - 7 BYTE cbColPosition; // 0 - 83 } LCDCURSOR, *PLCDCURSOR; Used in AS_SetLcdCursor to position the cursor position on the LCD screen. 4.1.2.4.
4.1.2.6. LCDMESSAGE typedef struct _LCD_MESSAGE { BYTE cbCharCoding; LPCTSTR pMessage; USHORT wMessageLen; } LCDMESSAGE, *PLCDMESSAGE; Used by AS_SetLcdDisplayMessage. Data Member 4.1.2.7. Value Description cbCharCoding 00h Data encoding format used in the pMessage field. Character size depends on data format.
4.1.2.9. LED typedef struct _LED { BYTE cbLedPower; BYTE cbLedSlot1; BYTE cbLedSlot2; } LED, *PLED; // see LED_OPTION // see LED_OPTION // see LED_OPTION Used by AS_SetLED to control the LED’s of the ACR89.
4.1.3. Reader Response Data 4.1.3.1. AS_STATUS typedef struct _AS_STATUS { DLL_ERROR DllError; W32Error; LONG } AS_STATUS; Data Member Value DllError 00h – 20h W32Error Win32 Error Code 4.1.3.2. Description Contains the error code set by the DLL during command execution. See also Appendix A. Contains the error code set by Windows system during the execution of Win32 API.
4.1.3.4. DISPLAYSTATUS typedef struct _DISPLAY_STATUS { BYTE cbRowPosition; BYTE cbColumnPosition; } DISPLAYSTATUS, *PDISPLAYSTATUS; Returned by AS_SetLcdCursor, AS_SetLcdBacklight, AS_SetLcdDisplayGraphics AS_SetLcdDisplayMessage, AS_SetLcdSetContrast and AS_ClearLcdDisplay. 4.1.3.5.
4.1.4.2. ACCESSEEPROM typedef struct _ACCESS_EEPROM { BYTE cbFunction; BYTE cbDeviceNumber; DWORD dwAddress; USHORT wDataLength; PBYTE pData } ACCESSEEPROM, *PACCESSEEPROM; Used in AS_AccessEEPROM to read or write the data to the EEPROM memory of the ACR89.
Note: 1. The area to write into must be erased first. 2. The erase operation is in unit of block where the size of each block is 64 kbytes. 3. For erase operation, only the higher significant two bytes is used. The low significant two bytes of the address is ignored. i.e. 64 kbytes address aligned. 4.2. ACR89 DLL API Functions 4.2.1. General Description All functions return a status code AS_STATUS, which is a structure consisting of a DLL defined error and a WIN32 error. See also section 2.3.
error, if any. See also Appendix A or the possible return codes. Example: INT nDid; AS_STATUS status; //open a connection to the ACR89 status = AS_Open(ACR89,AS_USB1,&nDid); if(status.DllError == CMD_SUCCESS) { // connection success, do something with the ACR89 } Else { // error occurred return status; } 4.2.2.2. AS_Close This function closes a logical connection to ACR89. AS_STATUS AS_DECL AS_Close ( IN INT nDevId); Parameters nDevId [in] Handle returned by a previous call to AS_Open.
4.2.3. Device Functions Device Functions allow the initialization and retrieval of various parameters to and from the ACR89. 4.2.3.1. AS_GetInfo This function retrieves general information of the ACR89. AS_STATUS AS_DECL AS_GetInfo ( IN INT nDevId, OUT PINFO pInfo); Parameters: nDevId [in] Handle returned by a previous call to AS_Open. pInfo [out] Pointer to an INFO structure that saves the general information of the ACR89 device. See also Section 4.1.3.
4.2.3.2. AS_AccessEEProm This function allows user to write or read data to/from the EEPROM. Maximum allowed data length is 256 bytes. AS_STATUS AS_DECL AS_AccessEEPRom ( IN INT nDevId, IN PACCESSEEPROM pEEPRom); Parameters: nDevId [in] Handle returned by a previous call to AS_Open. pEEPRom [in] Pointer to an ACCESSEEPROM structure that contains the data to be written to ACR89. or the data read from the ACR89. See also Section 4.1.4.2 for more information about the ACCESSEEPROM structure.
Parameters: nDevId [in] Handle returned by a previous call to AS_Open. pSerialFlash [in] Pointer to an ACCESSSERIALFLASH structure that contains the data to be written to ACR89 or the data read from the ACR89. See also Section 4.2.3.3 for more information about the ACCESSSERIALFLASH structure. Return Values: AS_STATUS This functions returns different values depending on whether it succeeds or fails. AS_STATUS.DllError contains the status as returned by the DLL. AS_STATUS.
pDisplayStatus [out] Pointer to a DISPLAYSTATUS structure that saves the newly set position parameters. See also Section 4.1.3.4 for more information about the DISPLAYSTATUS structure. Return Values: AS_STATUS This functions returns different values depending on whether it succeeds or fails. AS_STATUS.DllError contains the status as returned by the DLL. AS_STATUS.W32Error contains the Win32 error code associated with the DLL error, if any. See also Appendix A for the possible return codes.
Example: LCDBACKLIGHT DISPLAYSTATUS AS_STATUS lcdLight; lcdStatus; status; //turn on the LCD backlight //assumed is that a connection has already been established. lcdLight.bEnableBackLight = TRUE; status = AS_SetLcdBacklight(nDid, &lcdLight, &lcdStatus); 4.2.4.3. AS_SetLcdDisplayGraphic BIT-MAP BYTE N LSB … MSB BIT-MAP BYTE 2 Row 1 BIT-MAP BYTE 1 Row 0 This function transfers bitmap graphics to ACR89 and displays the graphics on the LCD from the current cursor position.
Example: LCDGRAPHICS lcdGrafx; DISPLAYSTATUS lcdStatus; AS_STATUS status; //display a bitmap file called “MyLogo.bmp”. //assumed is that a connection has already been established. lcdGrafx.szBitmapFile = “MyLogo.bmp”; status = AS_SetLcdDisplayGraphics(nDid, &lcdGrafx, &lcdStatus); 4.2.4.4. AS_SetLcdDisplayMessage This function displays a string of characters using the ACR89 built-in font library. The string will be displayed horizontally from the current cursor position.
4.2.4.5. AS_SetLcdSetContrast This function sets the contrast level of the LCD. AS_STATUS AS_DECL AS_SetLcdSetContrast ( IN INT nDevId, IN PLCDCONTRAST pLcdContrast, OUT PDISPLAYSTATUS pDisplayStatus); Parameters: nDevId [in] Handle returned by a previous call to AS_Open. pLcdContrast [in] Pointer to a LCDCONTRAST structure that specifies the path to the bitmap file. See also Section 4.1.2.7 for more information about the LCDCONTRAST structure.
DISPLAYSTATUS structure. Return Values: AS_STATUS This functions returns different values depending on whether it succeeds or fails. AS_STATUS.DllError contains the status as returned by the DLL. AS_STATUS.W32Error contains the Win32 error code associated with the DLL error, if any. See also Appendix A for the possible return codes. Example: LCDCLEAR lcdClear; DISPLAYSTATUS lcdStatus; AS_STATUS status; //clear the full LCD screen //assumed is that a connection has already been established lcdClear.
Example: (Not available for preliminary API) N/A 4.2.5.2. AS_ConfigureKeyPad (Definition of API is at preliminary stage) This function configures the keypad of the ACR89. AS_STATUS AS_DECL AS_ConfigureKeyPad ( IN INT nDevId, IN PKEYPADCONFIG pKeypadConfig, OUT PKEYPADSTATUS pKeypadStatus); Parameters: nDevId [in] Handle returned by a previous call to AS_Open. pKeypadConfig [in] Pointer to KEYPADCONFIG structure that specifies keypad configuration to set in ACR89 keypad. See also Section 4.1.2.
Example: (Not available for preliminary API) N/A 4.2.5.3. AS_GetKeyInput This function enables key input on the ACR89. This can be single key input or string input depending on the options set in the KEYPADINPUT structure.
Parameters: nDevId [in] Handle returned by a previous call to AS_Open. pKeypadInput [in] Pointer to a KEYPADINPUT structure that specifies the options to use when ACR89 captures key input. See also section 2.2.3 for more information about the KEYPADINPUT structure. pDataBlock [out] Pointer to a DATABLOCK structure that contains the pressed keys (if any). See also Section 4.1.3.5 for more information about the DATABLOCK structure.
Return Values: AS_STATUS This functions returns different values depending on whether it succeeds or fails. AS_STATUS.DllError contains the status as returned by the DLL. AS_STATUS.W32Error contains the Win32 error code associated with the DLL error, if any. See also Appendix A for the possible return codes. Example: AS_STATUS status; TIMESTAMP tsRTC; char szTime[81]; //read the RTC of the ACR89 //assumed is that a connection has already been established status = AS_ReadRTC(nDevId, &tsRTC); if(status.
Example: AS_STATUS TIMESTAMP TIMESTAMP status; newTime; chkTime; //set the RTC of the ACR89 using the values in the abTime array //assumed is that a connection has already been established CopyMemory(newTime.szRTCValue, abTime, 6); Status = AS_SetRTC(pDevId, &newTime, &chkTime); 4.2.7. Other Functions The following functions allow the user to control the buzzer of the LEDs of ACR89. 4.2.7.1. AS_SetBuzzer This function enables or disables the buzzer of the ACR89.
4.2.7.2. AS_SetLed This function enables or disables any of the LEDs of the ACR89. AS_STATUS AS_DECL AS_ SetLED ( IN INT nDevId, IN PLED pLed); Parameters: nDevId [in] Handle returned by a previous call to AS_Open. pBuzzer [in] Pointer to a LED structure that contains the state to set the LEDs of the ACR89. See also Section 4.1.2.9 LED for more information about the LED structure. Return Values: AS_STATUS This functions returns different values depending on whether it succeeds or fails. AS_STATUS.
Appendix A. Error Codes (DLL Errors) Only DLL Errors are listed below. For details of Win32 Errors, please refer to MSDN.
