ISO14443-4 Protocol

Functions
UFR_STATUS DL_API	SetSpeedPermanently (unsigned char tx_speed, unsigned char rx_speed)
UFR_STATUS DL_API	GetSpeedParameters (VAR unsigned char *tx_speed, VAR unsigned char *rx_speed)
UFR_STATUS DL_API	SetISO14443_4_Mode (void)
UFR_STATUS DL_API	SetISO14443_4_Mode_GetATS (OUT uint8_t ats[MAX_ATS_LEN], VAR uint8_t *ats_len, OUT uint8_t uid[MAX_UID_LEN], VAR uint8_t *uid_len, VAR uint8_t *sak)
UFR_STATUS DL_API	uFR_APDU_Transceive (uint8_t cls, uint8_t ins, uint8_t p1, uint8_t p2, IN uint8_t *data_out, uint8_t data_out_len, OUT uint8_t *data_in, uint32_t max_data_in_len, VAR uint32_t *response_len, uint8_t send_le, OUT uint8_t *apdu_status)
UFR_STATUS DL_API	APDUHexStrTransceive (IN const char *c_apdu, OUT char **r_apdu)
UFR_STATUS DL_API	APDUPlainTransceive (IN const uint8_t *c_apdu, uint32_t c_apdu_len, OUT uint8_t *r_apdu, VAR uint32_t *r_apdu_len)
UFR_STATUS DL_API	APDUTransceive (uint8_t cls, uint8_t ins, uint8_t p1, uint8_t p2, IN const uint8_t *data_out, uint32_t Nc, OUT uint8_t *data_in, VAR uint32_t *Ne, uint8_t send_le, OUT uint8_t *apdu_status)
UFR_STATUS DL_API	i_block_trans_rcv_chain (uint8_t chaining, uint8_t timeout, uint8_t block_length, IN uint8_t *snd_data_array, VAR uint8_t *rcv_length, OUT uint8_t *rcv_data_array, VAR uint8_t *rcv_chained, VAR uint32_t *ufr_status)
UFR_STATUS DL_API	r_block_transceive (uint8_t ack, uint8_t timeout, VAR uint8_t *rcv_length, OUT uint8_t *rcv_data_array, VAR uint8_t *rcv_chained, VAR uint32_t *ufr_status)
UFR_STATUS DL_API	s_block_deselect (uint8_t timeout)

Detailed Description

Function Documentation

SetSpeedPermanently()

UFR_STATUS DL_API SetSpeedPermanently	(	unsigned char	tx_speed,
		unsigned char	rx_speed )

This function is used for setting communication speed between reader and ISO144443-4 cards. For other card types, a default speed of 106 kbps is in use.

Parameters

tx_speed	setup value for transmit speed
rx_speed	setup value for receive speed

Returns

Operation status

GetSpeedParameters()

UFR_STATUS DL_API GetSpeedParameters	(	VAR unsigned char *	tx_speed,
		VAR unsigned char *	rx_speed )

Returns baud rate configured with previous function.

Parameters

tx_speed	pointer to variable, returns configured value for transmit speed
rx_speed	pointer to variable, returns configured value for receive speed

Returns

Operation status

SetISO14443_4_Mode()

UFR_STATUS DL_API SetISO14443_4_Mode

(

void

)

Call SetISO14443_4_Mode() or SetISO14443_4_Mode_GetATS(). ISO 14443-4 tag in a field will be selected and RF field polling will be stopped.

Returns

Operation status

SetISO14443_4_Mode_GetATS()

UFR_STATUS DL_API SetISO14443_4_Mode_GetATS	(	OUT uint8_t	ats[MAX_ATS_LEN],
		VAR uint8_t *	ats_len,
		OUT uint8_t	uid[MAX_UID_LEN],
		VAR uint8_t *	uid_len,
		VAR uint8_t *	sak )

Call SetISO14443_4_Mode() or SetISO14443_4_Mode_GetATS(). ISO 14443-4 tag in a field will be selected and RF field polling will be stopped.

Parameters

ats	After successful function execution, buffer on which this pointer points to will contain ATS returned from the TAG (historical bytes included). Before calling this function, you have to allocate MAX_ATS_LEN bytes for the ats buffer. MAX_ATS_LEN macro is defined in uFCoder.h (#define MAX_ATS_LEN 25).
ats_len	After successful function execution, variable on which this pointer points to will contain actual ATS length.
uid	After successful call to this function, buffer on which this pointer points to will contain TAG UID. Before calling this function, you have to allocate MAX_UID_LEN bytes for the ats buffer. MAX_UID_LEN macro is defined in uFCoder.h (#define MAX_UID_LEN 10).
uid_len	After successful function execution, variable on which this pointer points to will contain actual UID length.
sak	After successful function execution, variable on which this pointer points to will contain SAK (Select Acknowledge) of the TAG in field.

Returns

Operation status

uFR_APDU_Transceive()

UFR_STATUS DL_API uFR_APDU_Transceive	(	uint8_t	cls,
		uint8_t	ins,
		uint8_t	p1,
		uint8_t	p2,
		IN uint8_t *	data_out,
		uint8_t	data_out_len,
		OUT uint8_t *	data_in,
		uint32_t	max_data_in_len,
		VAR uint32_t *	response_len,
		uint8_t	send_le,
		OUT uint8_t *	apdu_status )

Used to transmit C-APDU and receive R-APDU packets per defined parameters

Parameters

cls	APDU CLA (class byte)
ins	APDU command code (instruction byte)
p1	parameter byte
p2	parameter byte
data_out	APDU command data field. Use NULL if data_out_len is 0
data_out_len	number of bytes in the APDU command data field (Lc field)
data_in	buffer for receiving APDU response. There should be allocated at least (send_le + 2) bytes before function call.
max_data_in_len	size of the receiving buffer. If the APDU response exceeded size of buffer, then function returns error
response_len	value of the Le fied if send_le is not 0. After successful execution location pointed by the response_len will contain number of bytes in the APDU response.
send_le	if this parameter is 0 then APDU Le field will not be sent. Otherwise Le field will be included in the APDU message. Value response_len pointed to, before function call will be value of the Le field.
apdu_status	APDU error codes SW1 and SW2 in 2 bytes array

Returns

Operation status

APDUHexStrTransceive()

UFR_STATUS DL_API APDUHexStrTransceive	(	IN const char *	c_apdu,
		OUT char **	r_apdu )

Sends C–APDU in the c_string (zero terminated) format, containing pairs of the hexadecimal digits. Pairs of the hexadecimal digits can be delimited by any of the punctuation characters or white space.

Parameters

c_apdu	C-APDU hexadecimal c_string
*r_apdu	Received R-APDU as a hexadecimal c_string

Returns

Operation status

APDUPlainTransceive()

UFR_STATUS DL_API APDUPlainTransceive	(	IN const uint8_t *	c_apdu,
		uint32_t	c_apdu_len,
		OUT uint8_t *	r_apdu,
		VAR uint32_t *	r_apdu_len )

Binary alternative function to the APDUHexStrTransceive(). C-APDU and R-APDU are sent and receive in the form of the byte arrays. There is obvious need for a c_apdu_len and r_apdu_len parameters which represents length of the *c_apdu and *r_apdu byte arrays, respectively

Parameters

c_apdu	Array containing the C-APDU
c_apdu_len	length of the c_apdu array
r_apdu	Array containing received R-APDU
r_apdu_len	length of the received r_apdu array

Returns

Operation status

APDUTransceive()

UFR_STATUS DL_API APDUTransceive	(	uint8_t	cls,
		uint8_t	ins,
		uint8_t	p1,
		uint8_t	p2,
		IN const uint8_t *	data_out,
		uint32_t	Nc,
		OUT uint8_t *	data_in,
		VAR uint32_t *	Ne,
		uint8_t	send_le,
		OUT uint8_t *	apdu_status )

This is “exploded binary” alternative function intended for support APDU commands in ISO 14443- 4A tags. APDUTransceive() receives separated parameters which are an integral part of the C– APDU. There are parameters cls, ins, p0, p1 of the uint8_t type.

Parameters

cls
ins
p1
p2
data_out
Nc
data_in
Ne
send_le
apdu_status

Returns

Operation status

i_block_trans_rcv_chain()

UFR_STATUS DL_API i_block_trans_rcv_chain	(	uint8_t	chaining,
		uint8_t	timeout,
		uint8_t	block_length,
		IN uint8_t *	snd_data_array,
		VAR uint8_t *	rcv_length,
		OUT uint8_t *	rcv_data_array,
		VAR uint8_t *	rcv_chained,
		VAR uint32_t *	ufr_status )

I-block used to convey information for use by the application layer

Parameters

chaining	1 - chaining in use, 0 - no chaining
timeout	timeout for card reply
block_length	inf block length
snd_data_array	pointer to array of data that will be send
rcv_length	length of received data
rcv_data_array	pointer to array of data that will be received
rcv_chained	1 received packet is chained, 0 received packet is not chained
ufr_status	card operation status

Returns

Operation status

r_block_transceive()

UFR_STATUS DL_API r_block_transceive	(	uint8_t	ack,
		uint8_t	timeout,
		VAR uint8_t *	rcv_length,
		OUT uint8_t *	rcv_data_array,
		VAR uint8_t *	rcv_chained,
		VAR uint32_t *	ufr_status )

R-block used to convey positive or negative acknowledgements. An R-block never contains an INF field. The acknowledgement relates to the last received block.

Parameters

ack	1 ACK, 0 NOT ACK
timeout	timeout for card reply
rcv_length	length of received data
rcv_data_array	pointer to array of data that will be received
rcv_chained	1 received packet is chained, 0 received packet is not chained
ufr_status	card operation status

Returns

Operation status

s_block_deselect()

UFR_STATUS DL_API s_block_deselect

(

uint8_t

timeout

)

Used to deselect tag and restore RF field polling. This call is mandatory after using SetISO14443_4_Mode() and its variants.

Parameters

timeout

timeout in [ms]

Returns

Operation status