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¶
include/nfc/t4t/isodep.h
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.
-
enumerator
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.
- Returns 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.
- Returns 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.
- Returns 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.
- Returns 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.
- Returns 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.
-
uint32_t
-
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.
- Parameters
data – [in] Pointer to the received data.
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.
- Parameters
data – [in] Pointer to data to send by Reader/Writer.
data_len – [in] Data length.
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.
-
void (*
-
ISO-DEP protocol errors¶
-
group
isodep_error