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.h
lib/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.
- Returns 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.
- Returns 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.
- Returns 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.
- Returns 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.
- Returns 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.
- Returns 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).
- Returns 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).
- Returns 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).
- Returns 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.
- Returns 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.
- Returns 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
-
struct
st25r3911b_nfca_crc
¶ - #include <st25r3911b_nfca.h>
NFCA_A CRC structure.
Public Members
-
uint8_t
crc
[2]¶ CRC - 16.
-
uint8_t
-
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.
- Parameters
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.
- Parameters
tag_info – NFC-A Tag information.
err – Procedure error.
-
void (*
transfer_completed
)(const uint8_t *data, size_t len, int err)¶ NFC-A transceive operation completed.
- Parameters
data – Received data from tag.
len – Received data length.
err – Transfer error. If 0, the transfer was successful.
-
void (*
rx_timeout
)(bool tag_sleep)¶ NFC-A receive time-out.
- Parameters
tag_sleep – If set, the tag is in sleep mode.
-
void (*
tag_sleep
)(void)¶ NFC-A tag sleep state notification.
-
void (*
-