Contactless Smart Card Reader

(1)

EZWave/HQM204

Contactless Smart Card Reader

Application Programming Interface Manual

Version 1.0 December 2004

(2)

EZWAVE/HQM204 CONTACTLESS SMART CARD READER API REFERENCE MANUAL V1.0

WARNING

Information in this document is subject to change without prior notice.

No part of this publication may be reproduced, transmitted, stored in a retrieval system, nor translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without the prior written permission of Castles Technology Co., LTD.

All trademarks mentioned are proprietary of their respective owners.

Revision History

Version Date Description

1.0 2004.12.10 Created

(3)

Table of Content

WARNING ... 1

REVISION HISTORY... 1

1 APPLICATION PROGRAMMING INTERFACE (API) ... 4

1.1 CAS_INITCOMM... 4

1.2 CAS_CLOSECOMM... 4

1.3 CAS_GETREADERTYPE... 5

1.4 CAS_LED... 6

1.5 CAS_LCD_CLEAR... 7

1.6 CAS_LCD_BACKLIGHT... 8

1.7 CAS_LCD_SHOWASCII... 8

1.8 CAS_LCD_SHOWBIGASCII ... 9

1.9 CAS_LCD_SHOWIMAGE... 10

1.10 CAS_BUZZER...11

1.11 CAS_ICC_GETSTATUS...11

1.12 CAS_ICC_POWERON... 12

1.13 CAS_ICC_POWEROFF... 13

1.14 CAS_ICC_APDU... 14

1.15 CAS_PCD_INIT... 15

1.16 CAS_PCD_POWERON... 15

1.17 CAS_PCD_POWEROFF... 16

1.18 CAS_PCD_GETTYPE... 16

1.19 CAS_MIFARE_REQUESTA... 17

1.20 CAS_MIFARE_WAKEUPA ... 17

1.21 CAS_MIFARE_ANTIA ... 18

1.22 CAS_MIFARE_SELECTA... 19

1.23 CAS_MIFARE_HALTA... 19

1.24 CAS_MIFARE_ACTIVEIDLE... 20

1.25 CAS_MIFARE_ACTIVEHALT... 21

1.26 CAS_MIFARE_READE2... 22

1.27 CAS_MIFARE_WRITEE2 ... 22

1.28 CAS_MIFARE_LOADKEYE2... 23

1.29 CAS_MIFARE_LOADKEY... 24

1.30 CAS_MIFARE_AUTH... 24

1.31 CAS_MIFARE_READBLOCK... 25

1.32 CAS_MIFARE_WRITEBLOCK... 26

(4)

1.33 CAS_MIFARE_INCREMENT... 26

1.34 CAS_MIFARE_DECREMENT... 27

1.35 CAS_MIFARE_RESTORE... 28

1.36 CAS_MIFARE_TRANSFER... 28

1.37 CAS_TCL_SETBAUDRATE... 29

1.38 CAS_TCL_TRANSPARENT... 30

1.39 CAS_TCL_RATS... 30

1.40 CAS_TCL_APDU ... 31

1.41 CAS_TCL_DESELECT... 32

2 TRANSACTION FLOW CHART ... 33

2.1 MIFARE TRANSACTION FLOW CHART... 33

2.2 T=CLTRANSACTION FLOW CHART... 34

2.3 ANTICOLLISION FLOW CHART... 35

3 STATUS CODE... 36

(5)

1 Application Programming Interface (API)

Filename:

♦ DLL: EZWaveAPI.DLL

♦ LIB: EZWaveAPI.LIB

♦ Header: EZWaveAPI.H

1.1 CAS_InitComm

Initialize the communication with HQM204.

ULONG CAS_InitComm (

IN ULONG PortNumber, OUT ULONG *hHandle );

PARAMETERS:

PortNumber

Port number of Host will communicate with Reader.

=d_COMM_COM1: RS232 Port 1

=d_COMM_USB1: USB Device 1

=d_COMM_USB4: USB Device 4 hHandle

Handle of the device that occupied by this cummunication.

RETURN VALUE:

d_NO_ERROR Success Others

Failure, please refer to status code list.

1.2 CAS_CloseComm

Close and release the com port and resource.

(6)

void CAS_CloseComm(

IN ULONG hHandle );

PARAMETERS:

hHandle

Handle of the device that would be closed.

RETURN VALUE:

1.3 CAS_GetReaderType

Get the Reader Type (16 bytes string).

ULONG CAS_GetReaderType(

IN ULONG hHandle,

OUT BYTE *baRdrType

);

(7)

PARAMETERS:

hHandle

Handle of the device that data would be sent into.

baRdrType

The reader type and the fireware version. “CAS-HQM204T-NNNN”

CAS: Vender name HQM204: Module name T: Interface type

=U: SUB

=R: RS232 NNNN : F/W version

RETURN VALUE:

1.4 CAS_LED

Control the on/off of the LED.

ULONG CAS_LED(

IN ULONG hHandle,

IN BYTE bMask,

IN BYTE bOnOff

);

(8)

PARAMETERS:

hHandle

bMask Bit 0 :

1 LED_1 on/off is indicated in bOnOff 0 LED_1 with the current state Bit 1 :

1 LED_4 on/off is indicated in bOnOff 0 LED_4 with the current state bOnOff

Bit 0 :

1 LED_1 on 0 LED_1 off Bit 1 :

1 LED_2 on 0 LED_2 off Bit 2 :

1 LED_3 on 0 LED_3 off Bit 3:

1 LED_4 on 0 LED_4 off

RETURN VALUE:

1.5 CAS_LCD_Clear

Clear the LCD display.

(9)

ULONG CAS_LCD_Clear(

IN ULONG hHandle );

PARAMETERS:

hHandle

RETURN VALUE:

1.6 CAS_LCD_BackLight

Turn on/off of the back light of the LCD.

ULONG CAS_LCD_BackLight(

IN ULONG hHandle, IN BYTE bOnOff );

PARAMETERS:

hHandle

bOnOff

=1 : On

=0 : Off

RETURN VALUE:

1.7 CAS_LCD_ShowASCII

Show the ASCII data on the LCD. ASCII font(8x16) is pre-defined in the reader.

The resolution of LCD is 122x32 graphic type. The unit of x position is 1 dot,

(10)

and the unit of y position is 8 dots. So, totally 15x2 data bytes can be shown on LCD once.

ULONG CAS_LCD_ShowASCII(

IN ULONG hHandle,

IN BYTE bX,

IN BYTE bY,

IN UINT uiLen,

IN BYTE *baData

);

PARAMETERS:

hHandle

bX

X position. Range From 0 To 121.

bY

Y position. Range From 0 To 3.

uiLen

The length of ascii stirng.

baData

Ascii string to be shown on LCD.

RETURN VALUE:

1.8 CAS_LCD_ShowBigASCII

Show the ASCII data( 0x21~0x7E ) on the LCD. ASCII font(13x16) is pre-defined in the reader.

ULONG CAS_LCD_ShowBigASCII ( IN ULONG hHandle,

IN BYTE bX,

IN BYTE bY,

IN UINT uiLen,

IN BYTE *baData

(11)

PARAMETERS:

hHandle

bX

bY

uiLen

The length of ascii stirng.

baData

Ascii string to be shown on LCD.

1.9 CAS_LCD_ShowImage

Show the pattern data on the LCD.

The resolution of LCD is 122x32 graphic type. The unit of x position is 1 dot, and the unit of y position is 8 dots. One byte of the pattern corresponds to 1x8 of the display area on the LCD.

ULONG CAS_LCD_ShowImage(

IN ULONG hHandle,

IN BYTE bX,

IN BYTE bY,

IN UINT uiLen,

IN BYTE *baData

);

PARAMETERS:

hHandle

bX

bY

uiLen

The length of pattern data.

baData

Pattern data to be shown on LCD.

(12)

EZWAVE/HQM204 CONTACTLESS SMART CARD READER API REFERENCE MANUAL V1.0 RETURN VALUE:

1.10 CAS_Buzzer

Play the sound.

ULONG CAS_Buzzer(

IN ULONG hHandle, IN UINT uiHertz,

IN UINT uiTimer

);

PARAMETERS:

hHandle

uiHertz

The frequency to play in hertz.

uiTimer

The time to play in 10ms.

RETURN VALUE:

1.11 CAS_ICC_GetStatus

Get the ICC/SAM status of the smart card in SAM socket.

ULONG CAS_ICC_GetStatus(

IN ULONG hHandle,

IN BYTE bSocket,

OUT BYTE *bStatus );

(13)

PARAMETERS:

hHandle

bSocket

The socket be detected. Possible value = {d_SAM1,d_SAM2, d_SAM3,d_SAM4, d_ICC: RFU}

bStatus

Bit 0 of Byte 0

=1 : ICC present

=0: ICC absent Bit 1 of Byte 0

=1 : ICC active

=0 : ICC not active

RETURN VALUE:

1.12 CAS_ICC_PowerOn

Reset the ICC and parse the ATR.

ULONG CAS_ICC_PowerOn(

IN ULONG hHandle,

IN BYTE bSocket,

OUT BYTE *bCardType,

OUT UINT *uiLen,

OUT BYTE *baATR

);

(14)

PARAMETERS:

hHandle

bSocket

bCardType ICC Type

=0: T=0 Card

=1: T=1 Card

=2: Synchronous ICC

=3: I²C Card uiLen

The length of ATR.

baATR

The content of ATR.

RETURN VALUE:

1.13 CAS_ICC_PowerOff

Power off the ICC.

ULONG CAS_ICC_PowerOff(

IN ULONG hHandle,

IN BYTE bSocket

);

PARAMETERS:

hHandle

bSocket

(15)

1.14 CAS_ICC_APDU

Send the APDU to the ICC and return the response block from ICC. T=0/T=1 protocol handling are done by reader.

ULONG CAS_ICC_APDU (

IN ULONG hHandle,

IN BYTE bSocket,

IN UINT uiSendLen,

IN BYTE *baAPDU,

OUT UINT *uiRecvLen,

OUT BYTE *baRspAPDU

);

PARAMETERS:

hHandle

bSocket

uiSendLen

The length of the APDU command to the PICC.

baAPDU

The APDU command to the PICC.

uiRecvLen

The length of the response of the PICC.

baRspAPDU

The response of the PICC.

RETURN VALUE:

(16)

1.15 CAS_PCD_Init

Initialize/Reset RC531.

ULONG CAS_PCD_Init (

IN ULONG hHandle );

PARAMETERS:

hHandle

RETURN VALUE:

1.16 CAS_PCD_PowerOn

Power on RC531.

ULONG CAS_PCD_PowerOn(

IN ULONG hHandle );

PARAMETERS:

hHandle

RETURN VALUE:

(17)

1.17 CAS_PCD_PowerOff

Power off RC531.

ULONG CAS_PCD_PowerOff(

IN ULONG hHandle );

PARAMETERS:

hHandle

RETURN VALUE:

1.18 CAS_PCD_GetType

Get RC531 information.

ULONG CAS_PCD_GetType(

IN ULONG hHandle,

OUT BYTE *sData

);

PARAMETERS:

hHandle

sData

Product information of RC531. [16 Bytes]

RETURN VALUE:

(18)

1.19 CAS_Mifare_RequestA

To Probe the field for one PICC of Type A. PICC should be in IDLE state.

ULONG CAS_Mifare_ReauestA (

IN ULONG hHandle,

OUT BYTE *sATQA

);

PARAMETERS:

hHandle

sATQA

Receives the answer of request A from one PICC. [2 Bytes]

RETURN VALUE:

1.20 CAS_Mifare_WakeupA

To Probe the field for one PICC of Type A. PICC should be in IDLE or HALT state.

ULONG CAS_Mifare_WakeupA (

IN ULONG hHandle,

OUT BYTE *sATQA

);

PARAMETERS:

hHandle

sATQA

Receives the answer of requestA from one PICC.[2 Bytes]

(19)

1.21 CAS_Mifare_AntiA

Try to find the UID of the PICCs of Type A.

ULONG CAS_Mifare_AntiA(

IN ULONG hHandle,

IN BYTE bSEL,

IN BYTE bNVB,

IN BYTE *sValidBits,

OUT BYTE *sCSN

);

PARAMETERS:

hHandle

bSEL

Select code. Possible values(0x93, 0x95, 0x97) bNVB

Number of Valid bits.

For Example:

sValidBits: 10011101b 1101b , bNVB: 12 sValidBits: 10011101b 110b , bNVB: 11 sValidBits

The valid bits of the CSN of one PICC.

sCSN

Unique identifier(Card Serial Number) of the PICCs in the field. [4 Bytes]

RETURN VALUE:

(20)

1.22 CAS_Mifare_SelectA

Select one PICC of Type A. Then the PICC will enter the ACTIVE state.

ULONG CAS_Mifare_SelectA(

IN ULONG hHandle,

IN BYTE bSEL,

IN BYTE *sValidBits,

OUT BYTE *bSAK

);

PARAMETERS:

hHandle

bSEL

Select code. Possible values(0x93, 0x95, 0x97) sValidBits

The valid bits of the CSN of one PICC. [4 Bytes]

bSAK

Select acknowledge. [2 Bytes]

RETURN VALUE:

1.23 CAS_Mifare_HaltA

Halt the PICC of Type A.

ULONG CAS_Mifare_HaltA (

IN ULONG hHandle );

PARAMETERS:

hHandle

None

(21)

1.24 CAS_Mifare_ActiveIdle

Activate a PICC from its IDLE state. After this command, the PICC is ready to enter the ISO14443-4.

ULONG CAS_Mifare_ActiveIdle (

IN ULONG hHandle,

IN BYTE bBR,

OUT BYTE *baATQA,

OUT BYTE *bSAK,

OUT BYTE *bCSN_Length,

OUT BYTE *baCSN

);

PARAMETERS:

hHandle

bBR

Set the desire Baud Rate.

=0: 106kBuad

=1: 212kBuad

=2: 424kBaud

=3: 848kBaud baATQA

Receives the answer of request A from one PICCS. (2 Bytes) bSAK

Select acknowledge. (1 Byte) bCSN_Length

The length of Card Serial Number. (1 Byte) baCSN

Unique identifier(Card Serial Number) of the PICCs in the field. [4/7/10 Bytes]

(22)

1.25 CAS_Mifare_ActiveHalt

Activate a PICC from its HALT state. After this command, the PICC is ready to enter the ISO14443-4.

ULONG CAS_Mifare_ActiveHalt (

IN ULONG hHandle,

IN BYTE bBR,

IN BYTE *bCSN_Length,

IN BYTE *baCSN

OUT BYTE *baATQA,

OUT BYTE *bSAK

);

PARAMETERS:

hHandle

bRecvBR

Set the RC531 Receiver Baud Rate.

bCSN_Length

The length of Card Serial Number. (1 Byte) baCSN

Unique identifier(Card Serial Number) of the PICCs in the field. (4/7/10 Bytes)

baATQA

Receives the answer of request A from one PICCS. (2 Bytes) bSAK

Select acknowledge. (1 Byte)

RETURN VALUE:

(23)

1.26 CAS_Mifare_ReadE2

Read the contents from the EEPROM of RC531.

ULONG CAS_Mifare_ReadE2 (

IN ULONG hHandle, IN UINT usAddress, IN BYTE bLen

OUT BYTE *sData

);

PARAMETERS:

hHandle

usAddress

The address that the data will be placed. (From 0x0080 To 0x01FF) bLen

Length of the contents.

sData

The contents of the data.

RETURN VALUE:

1.27 CAS_Mifare_WriteE2

Write the data into the EEPROM of RC531.

ULONG CAS_Mifare_WriteE2 (

IN ULONG hHandle, IN UINT usAddress, IN BYTE bLen IN BYTE *sData );

(24)

EZWAVE/HQM204 CONTACTLESS SMART CARD READER API REFERENCE MANUAL V1.0 PARAMETERS:

hHandle

usAddress

The address that the data will be placed. (From 0x0080 To 0x01FF) bLen

Length of the contents.

sData

The contents of the data.

RETURN VALUE:

1.28 CAS_Mifare_LoadKeyE2

Read the key from the EEPROM of RC531 and put it into the internal key buffer of RC531.

ULONG CAS_Mifare_LoadKeyE2 ( IN ULONG hHandle, IN UINT usAddress );

PARAMETERS:

hHandle

usAddress

The address that the keys be placed. (From 0x0080 To 0x01FF)

RETURN VALUE:

(25)

1.29 CAS_Mifare_LoadKey

Put the key info the internal key buffer of RC531.

ULONG CAS_Mifare_LoadKey (

IN ULONG hHandle,

IN BYTE *sKey

);

PARAMETERS:

hHandle

sKey

The contents of the key. Each nibble is stored twice on one byte and one of the nibbles is bit-wised inverted.

(12 Bytes, Key Format Ref RC531 Key Storage Format) For example:

Key Value = 0x12 0x34 0x56 0x78 0x9A 0xBC Contents (RC531 Format):

0xE1 0xD2 0xC3 0xB4 0xA5 0x96 0x87 0x78 0x69 0x5A 0x4B 0x3C

RETURN VALUE:

1.30 CAS_Mifare_Auth

Perform the CRYPTO1 (Mifare Classic) card authentication with the key in the internal key buffer. If authentication is successful, RC531 could operate the blocks in the same sector of the authenticated block.

ULONG CAS_Mifare_Auth (

IN ULONG hHandle,

IN BYTE bKeyType,

IN BYTE bNBlock,

IN BYTE *sCSN

);

(26)

hHandle

bKeyType

Authenticate with Key A or Key B.

d_KeyTypeA for Key A d_KeyTypeB for Key B bNBlock

The number of the block that need to be authenticated. (From #0 To # 63) 16 sectors with 4 blocks of 16 bytes each. Blocks in the same sector would be authenticated with the same key stored in sector trailer(Block#3, #7, ...,

#63).

sCSN

The card serial number of the PICC. [4 Bytes]

RETURN VALUE:

1.31 CAS_Mifare_ReadBlock

Read the content of the specific block (16 bytes) from the PICC.

ULONG CAS_Mifare_ReadBlock ( IN ULONG hHandle, IN BYTE bNBlock,

OUT BYTE *sData

);

PARAMETERS:

hHandle

bNBlock

The number of the block that be read from. (From #0 To # 63) sData

The contents of the block.(16 Bytes)

(27)

1.32 CAS_Mifare_WriteBlock

Write the content of the specific block (16 bytes) from the PICC.

ULONG CAS_Mifare_WriteBlock ( IN ULONG hHandle, IN BYTE bNBlock,

IN BYTE *sData

);

PARAMETERS:

hHandle

bNBlock

The number of the block that be written into. (From #1 To # 63).

Block #0 is manufacturer block(Read-Only).

sData

The contents of the block.[16 Bytes]

RETURN VALUE:

1.33 CAS_Mifare_Increment

Increases the value of the block and stores the result into the internal data register.

(28)

ULONG CAS_Mifare_Increment (

IN ULONG hHandle,

IN BYTE bNBlock,

IN int iValue );

PARAMETERS:

hHandle

bNBlock

The number of the block that be increased. (From #1 To # 63, except for sector trailers #3, #7, …,#63)

iValue

The amount to be added to the value block.

RETURN VALUE:

1.34 CAS_Mifare_Decrement

Decreases the value of the block and stores the result into the internal data register.

ULONG CAS_Mifare_Decrement ( IN ULONG hHandle,

IN BYTE bNBlock,

IN int iValue );

PARAMETERS:

hHandle

bNBlock

The number of the block that be decreased. (From #1 To # 63, except for sector trailers #3, #7, …,#63)

iValue

The amount to be subtracted from the value block.

(29)

1.35 CAS_Mifare_Restore

Read the contents of the block and stores the result into the internal data register.

ULONG CAS_Mifare_Restore (

IN ULONG hHandle,

IN BYTE bNBlock

);

PARAMETERS:

hHandle

bNBlock

The number of the block that be written. (From #1 To # 63, except for sector trailers #3, #7, …,#63)

RETURN VALUE:

1.36 CAS_Mifare_Transfer

Write the contents of the internal data register into the block.

ULONG CAS_Mifare_Transfer (

IN ULONG hHandle,

IN BYTE bNBlock

);

(30)

hHandle

bNCard

Receives the number of PICCs in the field. (From #1 To # 63, except for sector trailers #3, #7, …,#63)

RETURN VALUE:

1.37 CAS_TCL_SetBaudRate

Set the RC531 baud rates with comtactless cards.

ULONG CAS_Mifare_SetBuadRate ( IN ULONG hHandle,

IN BYTE bRecvBR,

IN BYTE bSendBR

);

PARAMETERS:

hHandle

bRecvBR

Set the RC531 Receiver Baud Rate.

bSendBR

Set the RC531 Sender Baud Rate.

=0: 106kBuad

=1: 212kBuad

=2: 424kBaud

=3: 848kBaud

RETURN VALUE:

(31)

1.38 CAS_TCL_Transparent

Send the data to the PICC of Type A.

ULONG CAS_TCLTransparent (

IN ULONG hHandle,

IN BYTE bMode,

IN ULONG ulSendLen, IN BYTE *sSendBuf, OUT ULONG *ulRecvLen,

OUT BYTE *sRecvBuf

);

PARAMETERS:

hHandle

bMode

=0: User padds the prologue field and epilogue field of INF.

=1: Auto padds epilogue field of INF.

ulSendLen

Length of the outgoing data.

sSendBuf

The outgoing data.

ulbRecvLen

Length of the incoming data.

sRecvBuf

The incoming data.

RETURN VALUE:

1.39 CAS_TCL_RATS

Exceute the ISO14443-4 RATS command, and get the ATS responds.

(32)

ULONG CAS_TCL_RATS (

IN ULONG hHandle,

IN BYTE bAutoBR,

OUT UINT *bRecvLen,

OUT BYTE *sRecvBuf

);

PARAMETERS:

hHandle

bAutoBR

Automatically select highest baudrate, after receiving the ATS.

bRecvLen

Length of the ATS.

sRecvBuf

The incoming data of ATS.

RETURN VALUE:

1.40 CAS_TCL_APDU

Exceute the APDU command, and receive the response from the PICC according the T=CL protocol defined in ISO14443-4.

ULONG CAS_TCL_APDU (

IN ULONG hHandle, IN UINT uiSendLen,

IN BYTE *sAPDU,

OUT UINT *uiRecvLen,

OUT BYTE *sRspAPDU

);

(33)

hHandle

uiSendLen

The length of the APDU command to the PICC.

sAPDU

The APDU command to the PICC.

uiRecvLen

The length of the response of the PICC.

sRspAPDU

The response of the PICC.

RETURN VALUE:

1.41 CAS_TCL_Deselect

Leave the ISO14443-4 state, and go to the HALT state.

ULONG CAS_TCL_Deselect (

IN ULONG hHandle );

PARAMETERS:

hHandle

RETURN VALUE:

(34)

2 Transaction Flow Chart

2.1 Mifare Transaction Flow Chart

!

"

#

$ % & ' (((

!

#

(35)

2.2 T=CL Transaction Flow Chart

) )

) *

!

) +*,

"

!

#

(36)

2.3 AntiCollision Flow Chart

(37)

3 Status Code

Format of status code:

0x00000000: No Error Byte1: 00

Byte2: 00

Byte3: The execution command ID.

Byte4: The response status byte.

Status Descriptions

0x00000000 No Error

0x0000xxyy Reference Byte3 and Byte4 Status 0x80000001 Initiali communication error

0x80000002 Invalid handle 0x80000003 Invalid parameter 0x80000004 Communication fail 0x80000005 Response length error 0x80000006 Response command error 0x80000007 Out of data length

Other RFU

Byte4 Descriptions

0x00 No Error

0xFE when RxCECEn, CRC is fail

0xFC Crypto1 not be activated, when auth 0xFB Parity check is detected

0xFA receive NACK, and not define this error status 0xF8 CRC or UID length or cascase level is not correct 0xF6 receive NACK (4 bits) == 0, not auth success 0xF5 receive bit length is not correct

0xF4 receive byte not equal the expected one 0xF1 try to write to the buffer when it is full 0xED fails to write to the PICC

0xEB SOF is incorrect

0xEA unknown mifare command

0xE9 fails to access the EEPROM of RC531.

0xE8 bit-collision is detected

0xE6 reset rc531 fail, regcommand should be 0 0xE5 RIC is not responding in time

0xE4 not provide a bitwise anticollision 0xE1 coding error on card side

0xCA baudrate not support by PCD 0xC4 the parameters of function incorrect 0x9C internal error - source not identified 0x84 receive NACK (4 bits) == 1 || 5

0x6C Command ID is not supported in given Command Type 0x6E Command Type not supported

0x6F invalid parameters

(38)