NFC Reader ST25R3911B
The NFC Device ST25R3911B can be used to read and write NFC-A compatible tags (tags that support the ISO/IEC 14443 standard), creating an NFC polling device.
This driver is intended to be used with the NFC Reader ST25R3911B Nucleo expansion board (X-NUCLEO-NFC05A1).
The driver is used in the NFC: Tag reader sample.
NFC Reader hardware
The X-NUCLEO-NFC05A1 is an Arduino-compatible shield that can be used to communicate over NFC. It contains the NFC Reader chip ST25R3911B.
The ST25R3911B can both generate its own field to read and write NFC tags and behave like a tag itself. It is a slave device, and the external microcontroller initiates all communication.
Communication is performed by 4-wire Serial Pheripheral Interface (SPI). The ST25R3911B sends an interrupt request (pin IRQ) to the microcontroller. For the documentation of the NFC chip, see the ST25R3911B chip documentation.
Functionality
The driver provides the following functionality:
Detecting ISO/IEC 14443 A tags and reading their UID
Performing automatic collision resolution
Data exchange with the tag (write/read) with manually set Frame Delay Time
With auto-generated CRC
With manually generated CRC
Putting the tag to sleep
The driver currently supports only NFC-A technology.
Architecture
The driver consists of four layers:
Layer responsible for SPI communication
Layer to manage ST25R3911B interrupts
Layer with common reader functionality that can be shared by all NFC technologies
NFC-A layer, which is responsible for NFC-A technology activities
The driver requires calling its specific function periodically.
API documentation
include/st25r3911b_nfca.hlib/st25r3911b/- group st25r3911b_nfca
API for the ST25R3911B NFC Reader NFC-A Technology.
Defines
-
ST25R3911B_NFCA_EVENT_CNT
NFC-A Events count.
-
ST25R3911B_NFCA_CRC_LEN
NFC-A CRC length.
-
ST25R3911B_NFCA_NFCID1_MAX_LEN
NFC-A NFCID1 maximum length.
Enums
Functions
-
int st25r3911b_nfca_init(struct k_poll_event *events, uint8_t cnt, const struct st25r3911b_nfca_cb *cb)
Initialize NFC Reader NFC-A technology.
This function initializes everything that is required, like interrupts and common reader functionality.
- Parameters
events – [out] NFC-A Events.
cnt – [in] Event count. This driver needs 2 events.
cb – [in] Callback structure.
- Return values
0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-
int st25r3911b_nfca_field_on(void)
Switch on the NFC Reader field.
If the field is switched on successfully, the nfca_cb.field_on() callback is called.
- Return values
0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-
int st25r3911b_nfca_field_off(void)
Switch off the NFC Reader field.
If the field is switched off successfully, the nfca_cb.field_off() callback is called.
- Return values
0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-
int st25r3911b_nfca_tag_detect(enum st25r3911b_nfca_detect_cmd cmd)
Detect tag by sending a detection command.
The command is sent according to NFC Forum Digital 2.0 6.6. After success, the nfca_cb.tag_detected() callback is called.
- Parameters
cmd – Command.
- Return values
0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-
int st25r3911b_nfca_anticollision_start(void)
NFC-A collision resolution procedure.
The collision resolution procedure is described in NFC Forum Activity 2.0 9.4.4. After this procedure, nfca_cb.anticollision_completed() is called.
- Return values
0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-
int st25r3911b_nfca_transfer(const struct st25r3911b_nfca_buf *tx, const struct st25r3911b_nfca_buf *rx, uint32_t fdt, bool auto_crc)
Exchange the specified amount of data.
This is a generic function for NFC-A data exchange.
- Parameters
tx – [in] TX data buffer.
rx – [inout] RX data buffer.
fdt – [in] Maximum frame delay time (according to NFC Forum Digital 2.0 6.10.1).
auto_crc – [in] If set, the CRC is generated automatically by the NFC Reader. Otherwise, the CRC must be added manually to the TX buffer.
- Return values
0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-
static inline int st25r3911b_nfca_transfer_with_crc(const struct st25r3911b_nfca_buf *tx, const struct st25r3911b_nfca_buf *rx, uint32_t fdt)
Exchange the specified amount of data with an automatically generated CRC.
- Parameters
tx – [in] TX data buffer.
rx – [inout] RX data buffer.
fdt – [in] Maximum frame delay time (according to NFC Forum Digital 2.0 6.10.1).
- Return values
0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-
static inline int st25r3911b_nfca_transfer_without_crc(const struct st25r3911b_nfca_buf *tx, const struct st25r3911b_nfca_buf *rx, uint32_t fdt)
Exchange the specified amount of data with a manually generated CRC.
The CRC must be added manually to the TX buffer.
- Parameters
tx – [in] TX data buffer.
rx – [inout] RX data buffer.
fdt – [in] Maximum frame delay time (according to NFC Forum Digital 2.0 6.10.1).
- Return values
0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-
int st25r3911b_nfca_tag_sleep(void)
Send NFC-A tag sleep command.
This function sends the tag sleep command (according to NFC Forum Digital 2.0 6.9).
- Return values
0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-
int st25r3911b_nfca_crc_calculate(const uint8_t *data, size_t len, struct st25r3911b_nfca_crc *crc_val)
Calculate CRC 16 for NFC-A payload.
This function generates an NFC-A CRC (according to NFC Forum Digital 2.0 6.4.1.3).
- Parameters
data – [in] Payload data.
len – [in] Data length.
crc_val – [out] NFC-A CRC value.
- Return values
0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-
int st25r3911b_nfca_process(void)
Process NFC-A library.
This function must be called periodically from thread to process the NFC reader state and interrupts.
- Return values
0 – If the operation was successful. Otherwise, a (negative) error code is returned.
-
struct st25r3911b_nfca_buf
- #include <st25r3911b_nfca.h>
NFC-A transceiver buffer.
-
struct st25r3911b_nfca_sens_resp
- #include <st25r3911b_nfca.h>
NFC-A SENS response.
-
struct st25r3911b_nfca_tag_info
- #include <st25r3911b_nfca.h>
NFC-A Tag information.
Public Members
-
enum st25r3911b_nfca_tag_type type
Tag type.
-
struct st25r3911b_nfca_sens_resp sens_resp
SENS response.
-
uint8_t sel_resp
SEL response.
-
uint8_t nfcid1_len
NFCID1 length.
-
uint8_t nfcid1[10]
NFCID1.
-
bool sleep
Tag sleep.
-
enum st25r3911b_nfca_tag_type type
-
struct st25r3911b_nfca_crc
- #include <st25r3911b_nfca.h>
NFCA_A CRC structure.
Public Members
-
uint8_t crc[2]
CRC - 16.
-
uint8_t crc[2]
-
struct st25r3911b_nfca_cb
- #include <st25r3911b_nfca.h>
NFC-A callback.
This structure is used for tracking and synchronized NFC-A operation.
Public Members
-
void (*field_on)(void)
Field on indication callback.
Field is on, reader is ready to next operation.
-
void (*field_off)(void)
Field off indication callback.
-
void (*tag_detected)(const struct st25r3911b_nfca_sens_resp *sens_resp)
Tag detected callback.
The SENS response is received.
- Param sens_resp
Response to ALL request or SENS request.
-
void (*anticollision_completed)(const struct st25r3911b_nfca_tag_info *tag_info, int err)
Collision resolution procedure completed.
- Param tag_info
NFC-A Tag information.
- Param err
Procedure error.
-
void (*transfer_completed)(const uint8_t *data, size_t len, int err)
NFC-A transceive operation completed.
- Param data
Received data from tag.
- Param len
Received data length.
- Param err
Transfer error. If 0, the transfer was successful.
-
void (*rx_timeout)(bool tag_sleep)
NFC-A receive time-out.
- Param tag_sleep
If set, the tag is in sleep mode.
-
void (*tag_sleep)(void)
NFC-A tag sleep state notification.
-
void (*field_on)(void)
-
ST25R3911B_NFCA_EVENT_CNT