ISO-DEP protocol

This library is an NFC ISO-DEP protocol implementation for an NFC polling device.

You can use the NFC Reader ST25R3911B library to transmit and receive frames with a tag in NFC-A technology. To start data transfer, a polling device must activate the ISO-DEP protocol by sending the RATS command to the tag. After receiving a response (ATS) from the tag, data can be exchanged.

The ISO-DEP protocol defines three frame types:

  • I-block - used to convey information to the application layer

  • R-block - used to carry positive or negative acknowledgments

  • S-block - used to exchange protocol control information

The library automatically decides which frame type to use and provides full protocol support including error recovery and chaining mechanism.

API documentation

Header file: include/nfc/t4t/isodep.h
Source file: subsys/nfc/t4t/isodep.c
group nfc_t4t_isodep

NFC Type 4 Tag ISO-DEP API.

Defines

NFC_T4T_ISODEP_HIST_MAX_LEN

Maximum historical bytes count in RATS Response.

Enums

enum nfc_t4t_isodep_fsd

NFC Type 4 Tag ISO-DEP frame size.

Values:

enumerator NFC_T4T_ISODEP_FSD_16

16-byte frame size.

enumerator NFC_T4T_ISODEP_FSD_24

24-byte frame size.

enumerator NFC_T4T_ISODEP_FSD_32

32-byte frame size.

enumerator NFC_T4T_ISODEP_FSD_40

40-byte frame size.

enumerator NFC_T4T_ISODEP_FSD_48

48-byte frame size.

enumerator NFC_T4T_ISODEP_FSD_64

64-byte frame size.

enumerator NFC_T4T_ISODEP_FSD_96

96-byte frame size.

enumerator NFC_T4T_ISODEP_FSD_128

128-byte frame size.

enumerator NFC_T4T_ISODEP_FSD_256

256-byte frame size.

Functions

int nfc_t4t_isodep_rats_send(enum nfc_t4t_isodep_fsd fsd, uint8_t did)

Send a Request for Answer to Select (RATS).

This function sends a RATS command according to NFC Forum Digital Specification 2.0 14.6.1. The RATS command is used by Reader/Writer to negotiate the maximum frame size and the bit rate divisors with the Listener. This function must be called before nfc_t4t_isodep_transmit.

Note

According to NFC Forum Digital Specification 2.0, FSD must be set to 256 bytes.

Parameters

  • fsd – [in] Frame size for the Reader/Writer.

  • did – [in] Logical number of the addressed Listener. Usually it should be set to 0 in case of communication with one Listener.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int nfc_t4t_isodep_tag_deselect(void)

Send a Deselect command.

Function for sending S(DESELECT) frame according to NFC Forum Digital Specification 2.0 16.2.7. Reader/Writer deactivates a Listener by sending this command.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int nfc_t4t_isodep_data_received(const uint8_t *data, size_t data_len, int err)

Handle NFC ISO-DEP protocol received data.

Function for handling the received data. It should be called immediately upon receiving the data from Reader/Writer. In case of a transmission error, the error recovery procedure will be started.

Parameters

  • data – [in] Pointer to the received data.

  • data_len – [in] Received data length.

  • err – [in] Transmission error.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int nfc_t4t_isodep_transmit(const uint8_t *data, size_t data_len)

Exchange the specified amount of data.

This function can be called when a Tag is in selected state after calling nfc_t4t_isodep_rats_send.

Parameters

  • data – [in] Pointer to the data to transfer over ISO-DEP protocol.

  • data_len – [in] Length of the data to transmit.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

void nfc_t4t_isodep_on_timeout(void)

Handle a transmission timeout error.

This function must be called when a Reader/Writer detects a timeout in the Tag Response. When a timeout occurs, then the timeout error recovery procedure is started.

int nfc_t4t_isodep_init(uint8_t *tx_buf, size_t tx_size, uint8_t *rx_buf, size_t rx_size, const struct nfc_t4t_isodep_cb *cb)

Initialize NFC ISO-DEP protocol.

This function prepares a buffer for the ISO-DEP protocol and validates it size.

Parameters

  • tx_buf – [inout] Buffer for TX data. Data is set there before sending.

  • tx_size – [in] Size of the TX buffer.

  • rx_buf – [inout] Buffer for RX data. Data is set there after receiving valid data from an NFC Tag.

  • rx_size – [in] Size of the RX buffer.

  • cb – [in] Callback structure.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

struct nfc_t4t_isodep_tag
#include <isodep.h>

NFC Type 4 Tag data negotiated over RATS command exchange.

Public Members

uint32_t fwt

Frame Waiting Time.

uint32_t sfgt

Start-up Frame Guard Time

uint16_t fsc

Frame size for proximity card.

uint8_t did

Logical number of the addressed Listener.

uint8_t lp_divisor

Listener-Poller bit rate divisor.

uint8_t pl_divisor

Poller-Listener bit rate divisor.

uint8_t historical[15]

Historical bytes.

uint8_t historical_len

Historical bytes length.

bool did_supported

DID supported.

bool nad_supported

NAD supported.

struct nfc_t4t_isodep_cb
#include <isodep.h>

ISO-DEP Protocol callback structure.

This structure is used to control data exchange over ISO-DEP Protocol.

Public Members

void (*data_received)(const uint8_t *data, size_t data_len)

ISO-DEP data received callback.

The data exchange over ISO-DEP protocol is completed successfully.

Param data

[in] Pointer to the received data.

Param data_len

[in] Received data length.

void (*selected)(const struct nfc_t4t_isodep_tag *t4t_tag)

Type 4 Tag ISO-DEP selected callback.

A valid ATS frame from the tag was received.

void (*deselected)(void)

Type 4 Tag ISO-DEP deselected callback.

A valid Deselect Response from the tag was received.

void (*ready_to_send)(uint8_t *data, size_t data_len, uint32_t ftd)

ISO-DEP data ready to send a callback.

After receiving this callback, ISO-DEP protocol data should be sent by the Reader/Writer.

Param data

[in] Pointer to data to send by Reader/Writer.

Param data_len

[in] Data length.

Param ftd

[in] Maximum frame delay time.

void (*error)(int err)

ISO-DEP error callback.

ISO-DEP transfer has failed. Called when ISO-DEP protocol error occurred.

ISO-DEP protocol errors

group isodep_error

Defines

NFC_T4T_ISODEP_SYNTAX_ERROR

Correct frame was received with invalid content.

NFC_T4T_ISODEP_SEMANTIC_ERROR

Correct frame was received when it is not expected.

NFC_T4T_ISODEP_TRANSMISSION_ERROR

Unrecoverable transmission error.

NFC_T4T_ISODEP_TIMEOUT_ERROR

Unrecoverable timeout error.