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

Header file: include/st25r3911b_nfca.h
Source files: 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

enum st25r3911b_nfca_tag_type

NFC-A Tag types.

Values:

enumerator ST25R3911B_NFCA_TAG_TYPE_T2T
enumerator ST25R3911B_NFCA_TAG_TYPE_T4T
enumerator ST25R3911B_NFCA_TAG_TYPE_NFCDEP
enumerator ST25R3911B_NFCA_TAG_TYPE_T4T_NFCDEP
enumerator ST25R3911B_NFCA_TAG_TYPE_T1T
enum st25r3911b_nfca_detect_cmd

NFC-A Tag detect command.

Values:

enumerator ST25R3911B_NFCA_DETECT_CMD_ALL_REQ
enumerator ST25R3911B_NFCA_DETECT_CMD_SENS_REQ

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

  • [out] events: NFC-A Events.

  • [in] cnt: Event count. This driver needs 2 events.

  • [in] cb: Callback structure.

Return Value

  • 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 Value

  • 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 Value

  • 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 Value

  • 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 Value

  • 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

  • [in] tx: TX data buffer.

  • [inout] rx: RX data buffer.

  • [in] fdt: Maximum frame delay time (according to NFC Forum Digital 2.0 6.10.1).

  • [in] auto_crc: If set, the CRC is generated automatically by the NFC Reader. Otherwise, the CRC must be added manually to the TX buffer.

Return Value

  • 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

  • [in] tx: TX data buffer.

  • [inout] rx: RX data buffer.

  • [in] fdt: Maximum frame delay time (according to NFC Forum Digital 2.0 6.10.1).

Return Value

  • 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

  • [in] tx: TX data buffer.

  • [inout] rx: RX data buffer.

  • [in] fdt: Maximum frame delay time (according to NFC Forum Digital 2.0 6.10.1).

Return Value

  • 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 Value

  • 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

  • [in] data: Payload data.

  • [in] len: Data length.

  • [out] crc_val: NFC-A CRC value.

Return Value

  • 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 Value

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

Public Members

uint8_t *data

Data to TX/RX.

size_t len

Data length.

struct st25r3911b_nfca_sens_resp
#include <st25r3911b_nfca.h>

NFC-A SENS response.

Public Members

uint8_t anticollison

Anticollision data.

uint8_t platform_info

Platform information data.

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.

struct st25r3911b_nfca_crc
#include <st25r3911b_nfca.h>

NFCA_A CRC structure.

Public Members

uint8_t crc[2]

CRC - 16.

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.