NFC T4T ISO-DEP

This library is an NFC ISO-DEP protocol implementation for an NFC Reader/Writer.

You can use the NFC Reader ST25R3911B module to exchange data over the NFC ISO-DEP protocol. To start data transfer, a poller must select a tag by sending the RATS command. After receiving a response (ATS) from the tag, data can be exchanged.

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 acknowledgements.
  • S-block used to exchange protocol control information.

The library automatically decides which type of frame is to be used 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

NFC Type 4 Tag ISO-DEP API

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:

NFC_T4T_ISODEP_FSD_16 = 0

16-byte frame size.

NFC_T4T_ISODEP_FSD_24

24-byte frame size.

NFC_T4T_ISODEP_FSD_32

32-byte frame size.

NFC_T4T_ISODEP_FSD_40

40-byte frame size.

NFC_T4T_ISODEP_FSD_48

48-byte frame size.

NFC_T4T_ISODEP_FSD_64

64-byte frame size.

NFC_T4T_ISODEP_FSD_96

96-byte frame size.

NFC_T4T_ISODEP_FSD_128

128-byte frame size.

NFC_T4T_ISODEP_FSD_256

256-byte frame size.

Functions

int nfc_t4t_isodep_rats_send(enum nfc_t4t_isodep_fsd fsd, u8_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: Frame size for the Reader/Writer.
  • did: Logical number of the addressed Listener. Usually it should be set to 0 in case of communication with one Listener.
Return Value
  • 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 Value
  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int nfc_t4t_isodep_data_received(const u8_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: Pointer to the received data.
  • data_len: Received data length.
  • err: Transmission error.
Return Value
  • 0: If the operation was successful. Otherwise, a (negative) error code is returned.

int nfc_t4t_isodep_transmit(const u8_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: Pointer to the data to transfer over ISO-DEP protocol.
  • data_len: Length of the data to transmit.
Return Value
  • 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(u8_t *tx_buf, size_t tx_size, u8_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: Buffer for TX data. Data is set there before sending.
  • tx_size: Size of the TX buffer.
  • rx_buf: Buffer for RX data. Data is set there after receiving valid data from an NFC Tag.
  • rx_size: Size of the RX buffer.
  • cb: Callback structure.
Return Value
  • 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

u32_t fwt

Frame Waiting Time.

u32_t sfgt

Start-up Frame Guard Time

u16_t fsc

Frame size for proximity card.

u8_t did

Logical number of the addressed Listener.

u8_t lp_divisor

Listener-Poller bit rate divisor.

u8_t pl_divisor

Poller-Listener bit rate divisor.

u8_t historical[15]

Historical bytes.

u8_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 u8_t *data, size_t data_len)

ISO-DEP data received callback.

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

Parameters
  • data: Pointer to the received data.
  • data_len: 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)(u8_t *data, size_t data_len, u32_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.

Parameters
  • data: Pointer to data to send by Reader/Writer.
  • data_len: Data length.
  • ftd: 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 error

group isodep_error

Defines

NFC_T4T_ISODEP_SYNTAX_ERROR

Correct frame was received with invalid content.

NFC_T4T_ISODEP_SEMATIC_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.