Functions
fsp_err_t	RM_NFC_READER_PTX_Open (nfc_reader_ptx_instance_ctrl_t const p_ctrl, nfc_reader_ptx_cfg_t const const p_cfg)

fsp_err_t	RM_NFC_READER_PTX_DiscoveryStart (nfc_reader_ptx_instance_ctrl_t *const p_ctrl)

fsp_err_t	RM_NFC_READER_PTX_StatusGet (nfc_reader_ptx_instance_ctrl_t const p_ctrl, ptxIoTRd_StatusType_t status_type, uint8_t const p_status)

fsp_err_t	RM_NFC_READER_PTX_CardRegistryGet (nfc_reader_ptx_instance_ctrl_t const p_ctrl, ptxIoTRd_CardRegistry_t *pp_card_registry)

fsp_err_t	RM_NFC_READER_PTX_CardActivate (nfc_reader_ptx_instance_ctrl_t const p_ctrl, ptxIoTRd_CardParams_t const p_card_params, ptxIoTRd_CardProtocol_t protocol)

fsp_err_t	RM_NFC_READER_PTX_DataExchange (nfc_reader_ptx_instance_ctrl_t const p_ctrl, nfc_reader_ptx_data_info_t const p_data_info)

fsp_err_t	RM_NFC_READER_PTX_ReaderDeactivation (nfc_reader_ptx_instance_ctrl_t *const p_ctrl, nfc_reader_ptx_return_state_t return_state)

fsp_err_t	RM_NFC_READER_PTX_Close (nfc_reader_ptx_instance_ctrl_t *const p_ctrl)

Detailed Description

NFC Reader driver implementation using the PTX NFC module on RA MCUs.

Overview

This middleware module supplies an implementation for the NFC IoT Reader on the PTX module. The NFC functionalities are provided via a modular NFC Soft Controller (NCS) architecture, and this FSP module will include the NSC (aka NFC SDK). Functionality is provided in a split-stack architecture, where time-critical operations are running on the on-chip MCU, and the rest of the NFC logic is in the host controller to carry out applications such as IoT reader. The driver may also be adapted to further support next-generation PTX devices in future (which have not yet been released).

The NFC Reader module supports the following modules:

PTX105R

Features

The NFC Reader PTX driver supplies these features:

Initializes the IOTRD (IoT Reader) API and NSC stack
Initializes the PTX chip
Discovers cards according to NFC Forum
Selects a specific card in case multiple cards/protocols were discovered
Retrieves card details like technical/activation parameters
Exchanges RF data and bitstreams
Stops RF communication
Controls various GPIO pins of the PTX chip

Future support is considered for the following features:

Discovery support for “Low-Power-Card-Detection”
Optionally updates RF and System configuration parameters at runtime
Optionally puts the PTX chip into and wake up from stand-by mode
Plus several add-on features for additional operations and testing

Configuration

Build Time Configurations for rm_nfc_reader_ptx

The following build time configurations are defined in fsp_cfg/rm_nfc_reader_ptx_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.

Configurations for Networking > NFC IoT Reader on PTX (rm_nfc_reader_ptx)

This module can be added to the Stacks tab via New Stack > Networking > NFC IoT Reader on PTX (rm_nfc_reader_ptx).

Configuration	Options	Default	Description
NFC Poll Type
Type-A	Disabled Enabled	Enabled	Select to discover NFC Type-A tags
Type-B	Disabled Enabled	Enabled	Select to discover NFC Type-B tags
Type-V	Disabled Enabled	Enabled	Select to discover NFC Type-V tags
Type-F	Disabled Enabled	Enabled	Select to discover NFC Type-F tags
Temperature Sensor
Calibrate Sensor	Disabled Enabled	Enabled	Enable/Disable on-board temperature sensor calibration. Must be executed once per chip (lifetime), it is not needed after.
Shutdown Temperature (°C)	Must be an integer greater than 0 and less than 223	100	Set the expected thermal shutdown threshold value (Celsius).
Ambient Temperature (°C)	Must be an integer greater than 0 and less than 85	25	Set the ambient temperature value at which calibration takes place (Celsius).
Name	Name must be a valid C symbol	g_nfc_reader_ptx0	Module name.
NFC Interrupt Port	Refer to the RA Configuration tool for available options.	Disabled	Specify the interrupt port/pin used by the NFC chip to signal for SPI communications.
NFC Interrupt Pin	Refer to the RA Configuration tool for available options.	module.driver.nfc_reader_ptx.pin_control_pin.PIN_DISABLE	Specify the interrupt port/pin used by the NFC chip to signal for SPI communications.
Device Limit	Must be an integer greater than 0 and less than 50	5	Select the max number of tags to discover.
Idle Time	Must be an integer greater than 0 and less than 65535	100	Select idle time between polling cycles (ms).

Note: This module provides the basic configurations in the FSP Configurator required to discover, activate, and exchange data with an NFC tag. The user can then copy these configurations to a new structure if they want to connect to a new tag type/make changes to the configurations dynamically.

Interrupt Configuration

Refer to SPI (r_sci_spi). R_SCI_SPI_Open() is called by this module

Clock Configuration

Refer to SPI (r_sci_spi).

Pin Configuration

Refer to SPI (r_sci_spi). R_SCI_SPI_Open() is called by this module

Usage Notes

This module includes the NFC SDK which must be stored and compiled on the host RA MCU. The NFC IoT Reader claims that code size is roughly 39K B Code Flash (53 KB with the reference application) and 3-4 KB of Stack memory for the reference application. Consider this when looking at the device and the user application.
This module also requires a minimal amount of heap allocation (256 bytes). Be sure to allocate some heap size in the FSP Configurator BSP tab.
The NFC SDK provided with this module contains platform-specific and device-specific code related to using the FSP on RA devices. For other devices, the Platform API (ptxPLAT) must be implemented/ported.
When selecting the NFC tag protocol (Type-A, Type-B, Type-V, and Type-F), ensure that at least one type is selected.
For data exchange, the user must provide transmission/receive buffers with the exact data packet for the intended tag type. For information on commands, responses, and parameters, definitions can be found in the NFC Specification.
The NFC SDK contains a default RF waveform configuration file (ptxNSC_RfConfigVal.c) which is compatible with the PTX105RQC Pmod board. For custom boards, this configuration file will need to be generated with the GUI tool available on the module webpage.
The NFC chip provides an external interrupt pin which links to the ptxPLAT_GPIO_IsrCallback callback function. The same pin is also used during SPI communications for the NFC chip to signal it is ready and must be implemented in the FSP Configurator. The port/pin chosen for the interrupt pin should be the same for the NFC module properties and the External IRQ properties.

Limitations

The module will only support SPI for the first release, with other protocols (I2C, UART) planned for future releases.
The PTX105RQC Pmod board only supports SPI, so consider the evaluation kit (PTX105REK) for other interfaces.
The NFC chip reset pin (labeled as SEN pin) isn't supported in the FSP currently, and it does not have a pinout on the PTX105RQC Pmod board.

Examples

Basic Example

This is a basic example of minimal use of the NFC IoT Reader module in an application.

void nfc_basic_example (void)
{
    fsp_err_t                err        = FSP_SUCCESS;
    ptxIotRdInt_Demo_State_t demo_state = IoTRd_DemoState_WaitForActivation;
    err = RM_NFC_READER_PTX_Open(&g_rm_nfc_reader_ptx_instance, &g_nfc_reader_ptx_cfg);
    assert(FSP_SUCCESS == err);
    err = RM_NFC_READER_PTX_DiscoveryStart(&g_rm_nfc_reader_ptx_instance);
    assert(FSP_SUCCESS == err);
    ptxIoTRd_CardRegistry_t * card_registry = NULL;
    err = RM_NFC_READER_PTX_CardRegistryGet(&g_rm_nfc_reader_ptx_instance, &card_registry);
    assert(FSP_SUCCESS == err);
    /* T2T Protocol Example => READ BLOCK 0 */
    const uint8_t PROT_T2T_EXAMPLE[] = {0x30, 0x00};
    nfc_send_buf.tx_length = sizeof(PROT_T2T_EXAMPLE);
    memcpy(&nfc_tx_buf[0], &PROT_T2T_EXAMPLE[0], nfc_send_buf.tx_length);
    while (1)
    {
        /* Check regularly for critical system errors */
        uint8_t system_state = PTX_SYSTEM_STATUS_OK;
        err = RM_NFC_READER_PTX_StatusGet(&g_rm_nfc_reader_ptx_instance, StatusType_System, &system_state);
        assert(FSP_SUCCESS == err);
        if ((PTX_SYSTEM_STATUS_ERR_OVERCURRENT == system_state) || (PTX_SYSTEM_STATUS_ERR_TEMPERATURE == system_state))
        {
            /* Critical error detected, reset the device and stop */
            RM_NFC_READER_PTX_Close(&g_rm_nfc_reader_ptx_instance);
            while (1)
            {
                /* Do nothing */
            }
            ;
        }
        /* Check optionally if PA current-limiter got activated */
        uint8_t last_rf_error = PTX_RF_ERROR_NTF_CODE_NO_ERROR;
        err = RM_NFC_READER_PTX_StatusGet(&g_rm_nfc_reader_ptx_instance, StatusType_LastRFError, &last_rf_error);
        assert(FSP_SUCCESS == err);
        switch (demo_state)
        {
            case IoTRd_DemoState_WaitForActivation:
            {
                uint8_t discover_status = RF_DISCOVER_STATUS_NO_CARD;
                err = RM_NFC_READER_PTX_StatusGet(&g_rm_nfc_reader_ptx_instance, StatusType_Discover, &discover_status);
                assert(FSP_SUCCESS == err);
                switch (discover_status)
                {
                    case RF_DISCOVER_STATUS_NO_CARD:
                    {
                        /* Sleep */
                        R_BSP_SoftwareDelay(NFC_READER_NO_CARD_SLEEP_TIME, BSP_DELAY_UNITS_MILLISECONDS);
                        break;
                    }
                    case RF_DISCOVER_STATUS_CARD_ACTIVE:
                    {
                        /* Card activated */
                        /* Get card details to find the protocol/decide what data to send */
                        err = RM_NFC_READER_PTX_CardRegistryGet(&g_rm_nfc_reader_ptx_instance, &card_registry);
                        assert(FSP_SUCCESS == err);
                        demo_state = IoTRd_DemoState_DataExchange;
                        break;
                    }
                    case RF_DISCOVER_STATUS_DISCOVER_RUNNING:
                    {
                        /* Multiple Card(s) detected - resolving */
                        break;
                    }
                    case RF_DISCOVER_STATUS_DISCOVER_DONE:
                    {
                        /* Multiple Card(s) detected - resolved */
                        /* Get card details to find the protocol/decide what data to send */
                        err = RM_NFC_READER_PTX_CardRegistryGet(&g_rm_nfc_reader_ptx_instance, &card_registry);
                        assert(FSP_SUCCESS == err);
                        demo_state = IoTRd_DemoState_SelectCard;
                        break;
                    }
                    default:
                    {
                        /* Unknown Discover-Status */
                        break;
                    }
                }
                break;
            }
            case IoTRd_DemoState_SelectCard:
            {
                /* Case for detection of multiple cards */
                err =
                    RM_NFC_READER_PTX_CardActivate(&g_rm_nfc_reader_ptx_instance, &card_registry->Cards[0], Prot_T2T);
                assert(FSP_SUCCESS == err);
                demo_state = IoTRd_DemoState_DataExchange;
                break;
            }
            case IoTRd_DemoState_DataExchange:
            {
                /* Case for data exchange due to detected card */
                err = RM_NFC_READER_PTX_DataExchange(&g_rm_nfc_reader_ptx_instance, &nfc_send_buf);
                assert(FSP_SUCCESS == err);
                demo_state = IoTRd_DemoState_DeactivateReader;
                break;
            }
            case IoTRd_DemoState_DeactivateReader:
            {
                err =
                    RM_NFC_READER_PTX_ReaderDeactivation(&g_rm_nfc_reader_ptx_instance, NFC_READER_PTX_RETURN_DISCOVER);
                assert(FSP_SUCCESS == err);
                demo_state = IoTRd_DemoState_WaitForActivation;
                break;
            }
            case IoTRd_DemoState_SystemError:
            {
                /* System error */
                RM_NFC_READER_PTX_Close(&g_rm_nfc_reader_ptx_instance);
                while (1)
                {
                    /* Do nothing */
                }
                break;
            }
            default:
            {
                break;
            }
        }
    }
}

Data Structures
struct	nfc_reader_ptx_data_info_t

struct	nfc_reader_ptx_cfg_t

struct	nfc_reader_ptx_instance_ctrl_t

Enumerations
enum	nfc_reader_ptx_state_t

enum	nfc_reader_ptx_return_state_t

Data Structure Documentation

◆ nfc_reader_ptx_data_info_t

struct nfc_reader_ptx_data_info_t

NFC data exchange packet parameters

Data Fields
uint8_t *	p_tx_buf	Pointer to buffer holding data to send.
uint32_t	tx_length	Length of data to send.
uint8_t *	p_rx_buf	Pointer to buffer for data to receive.
uint32_t	rx_length	Length of data to receive.

◆ nfc_reader_ptx_cfg_t

struct nfc_reader_ptx_cfg_t

NFC Configuration

Data Fields
bool	poll_type_a	Flag to indicate enabling discovery for Type-A tags.
bool	poll_type_b	Flag to indicate enabling discovery for Type-B tags.
bool	poll_type_f	Flag to indicate enabling discovery for Type-F tags.
bool	poll_type_v	Flag to indicate enabling discovery for Type-V tags.
uint8_t	device_limit	Defines the maximum number of devices that can be connected at once.
uint32_t	idle_time_ms	RF-Discovery Loop. Idle time between polling cycles in milliseconds.
uint8_t	temp_sensor_calibrate	Flag to enable/disable temperature sensor calibration.
uint8_t	temp_sensor_shutdown	Expected thermal shutdown threshold value.
uint8_t	temp_sensor_ambient	Ambient temperature at which temperature sensor calibration takes place.
const bsp_io_port_pin_t	interrupt_pin	Interrupt pin for NFC chip to signal for communication.
ptxIoTRd_t *	iot_reader_context	Instance of the NFC SDK IoT Reader main structure.
rm_comms_instance_t *	p_comms_instance_ctrl	Pointer to the NFC module's Comms instance.
ioport_instance_t *	p_gpio_context	Pointer to the NFC module's GPIO instance.
external_irq_instance_t *	p_irq_context	Pointer to the NFC module's SPI external interrupt instance.
timer_instance_t *	p_timer_context	Pointer to the NFC module's sleep timer instance.
timer_instance_t *	p_app_timer	Pointer to the NFC module's Transparent Data Channel (TDC) timer instance.

◆ nfc_reader_ptx_instance_ctrl_t

struct nfc_reader_ptx_instance_ctrl_t

NFC_READER_PTX private control block. DO NOT MODIFY.

Data Fields
uint32_t	open	Flag to indicate if NFC has been opened.
nfc_reader_ptx_state_t	state_flag	Flag to track Idle/discovered/activated.
nfc_reader_ptx_cfg_t const *	p_cfg	Pointer to p_cfg for NFC.

Enumeration Type Documentation

◆ nfc_reader_ptx_state_t

enum nfc_reader_ptx_state_t

NFC state machine status

Enumerator
NFC_READER_PTX_IDLE	Idle state before starting discovery.
NFC_READER_PTX_POLLING	Polling state for discovering tags.
NFC_READER_PTX_DISCOVERED	Discovered state for tags that were found.
NFC_READER_PTX_ACTIVATED	Activated state for activating a discovered tag.

◆ nfc_reader_ptx_return_state_t

enum nfc_reader_ptx_return_state_t

NFC de-activation return state

Enumerator
NFC_READER_PTX_RETURN_IDLE	Rf-Deactivation Type 0 - Turn off RF-field.
NFC_READER_PTX_RETURN_DISCOVER	Rf-Deactivation Type 1 - Restart RF-Discovery.
NFC_READER_PTX_RETURN_SLEEP	Rf-Deactivation Type 2 - Put remote device to sleep.
NFC_READER_PTX_RETURN_SLEEP_NON_BLOCKING	Rf-Deactivation Type 3 - Put remote device to sleep (non-blocking)
NFC_READER_PTX_RETURN_NO_RF_RESET	Rf-Deactivation Type 4 - Common RF Deactivate but no Field Reset.
NFC_READER_PTX_RETURN_IDLE_PROTOCOL	Rf-Deactivation Type 5 - Use protocol-specific Deactivation, IDLE afterwards.
NFC_READER_PTX_RETURN_DISCOVER_PROTOCOL	Rf-Deactivation Type 6 - Use protocol-specific Deactivation, RF-Discovery started afterwards.

Function Documentation

◆ RM_NFC_READER_PTX_Open()

fsp_err_t RM_NFC_READER_PTX_Open	(	nfc_reader_ptx_instance_ctrl_t *const	p_ctrl,
		nfc_reader_ptx_cfg_t const *const	p_cfg
	)

Initializes the NFC IoT Reader.

Parameters

[in]	p_ctrl	Pointer to NFC IoT Reader control structure.
[in]	p_cfg	Pointer to NFC IoT Reader configuration structure.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_ASSERTION	Assertion error occurred.
FSP_ERR_INVALID_DATA	NFC SDK initialization data was incomplete.

◆ RM_NFC_READER_PTX_DiscoveryStart()

fsp_err_t RM_NFC_READER_PTX_DiscoveryStart ( nfc_reader_ptx_instance_ctrl_t *const p_ctrl )

Initiates discovery of NFC tags.

Parameters

[in] p_ctrl Pointer to NFC IoT Reader control structure.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_ASSERTION	Assertion error occurred.
FSP_ERR_NOT_OPEN	Module is not opened yet.
FSP_ERR_INVALID_STATE	NFC module is not in the idle state.
FSP_ERR_INVALID_DATA	NFC Discovery parameters were invalid or discovery was not started.

◆ RM_NFC_READER_PTX_StatusGet()

fsp_err_t RM_NFC_READER_PTX_StatusGet	(	nfc_reader_ptx_instance_ctrl_t *const	p_ctrl,
		ptxIoTRd_StatusType_t	status_type,
		uint8_t *const	p_status
	)

Gets the status information on the provided status identifier (system, discovery, etc.). Used during polling to confirm a card was discovered.

Parameters

[in]	p_ctrl	Pointer to NFC IoT Reader control structure.
[in]	status_type	Status identifier for target info.
[in]	p_status	Pointer to location to store NFC chip status flag.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_ASSERTION	Assertion error occurred.
FSP_ERR_NOT_OPEN	Module is not opened yet.
FSP_ERR_INVALID_STATE	NFC module is not in the polling state.
FSP_ERR_INVALID_ARGUMENT	Invalid input parameters to NFC Status function.

◆ RM_NFC_READER_PTX_CardRegistryGet()

fsp_err_t RM_NFC_READER_PTX_CardRegistryGet	(	nfc_reader_ptx_instance_ctrl_t *const	p_ctrl,
		ptxIoTRd_CardRegistry_t **	pp_card_registry
	)

Gets the internal card registry.

Parameters

[in]	p_ctrl	Pointer to NFC IoT Reader control structure.
[in]	pp_card_registry	Pointer to card registry for discovered cards.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_ASSERTION	Assertion error occurred.
FSP_ERR_INVALID_ARGUMENT	Invalid input parameters to NFC registry function.

◆ RM_NFC_READER_PTX_CardActivate()

fsp_err_t RM_NFC_READER_PTX_CardActivate	(	nfc_reader_ptx_instance_ctrl_t *const	p_ctrl,
		ptxIoTRd_CardParams_t *const	p_card_params,
		ptxIoTRd_CardProtocol_t	protocol
	)

Gets the details of the discovered card and connects to it.

Parameters

[in]	p_ctrl	Pointer to NFC IoT Reader control structure.
[in]	p_card_params	Parameters of the card to be activated.
[in]	protocol	The NFC protocol of the card to be activated.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_ASSERTION	Assertion error occurred.

◆ RM_NFC_READER_PTX_DataExchange()

fsp_err_t RM_NFC_READER_PTX_DataExchange	(	nfc_reader_ptx_instance_ctrl_t *const	p_ctrl,
		nfc_reader_ptx_data_info_t *const	p_data_info
	)

Sends and receives data to/from the activated card.

Parameters

[in]	p_ctrl	Pointer to NFC IoT Reader control structure.
[in]	p_data_info	Pointer to the NFC TX/RX data.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_ASSERTION	Assertion error occurred.

◆ RM_NFC_READER_PTX_ReaderDeactivation()

fsp_err_t RM_NFC_READER_PTX_ReaderDeactivation	(	nfc_reader_ptx_instance_ctrl_t *const	p_ctrl,
		nfc_reader_ptx_return_state_t	return_state
	)

Deactivates the activated card to return to the desired state (idle, discovery, etc.).

Parameters

[in]	p_ctrl	Pointer to NFC IoT Reader control structure.
[in]	return_state	Expectation for end state of NFC state machine.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_ASSERTION	Assertion error occurred.

◆ RM_NFC_READER_PTX_Close()

fsp_err_t RM_NFC_READER_PTX_Close ( nfc_reader_ptx_instance_ctrl_t *const p_ctrl )

Closes the FSP NFC module and resets all variables.

Parameters

[in] p_ctrl Pointer to NFC IoT Reader control structure.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_ASSERTION	Assertion error occurred.
FSP_ERR_NOT_OPEN	Close being called before the module is Open.

Functions

Detailed Description

Overview

Features

Configuration

Build Time Configurations for rm_nfc_reader_ptx

Configurations for Networking > NFC IoT Reader on PTX (rm_nfc_reader_ptx)

Interrupt Configuration

Clock Configuration

Pin Configuration

Usage Notes

Limitations

Examples

Basic Example

Data Structures

Enumerations

Data Structure Documentation

◆ nfc_reader_ptx_data_info_t

◆ nfc_reader_ptx_cfg_t

◆ nfc_reader_ptx_instance_ctrl_t

Enumeration Type Documentation

◆ nfc_reader_ptx_state_t

◆ nfc_reader_ptx_return_state_t

Function Documentation

◆ RM_NFC_READER_PTX_Open()

◆ RM_NFC_READER_PTX_DiscoveryStart()

◆ RM_NFC_READER_PTX_StatusGet()

◆ RM_NFC_READER_PTX_CardRegistryGet()

◆ RM_NFC_READER_PTX_CardActivate()

◆ RM_NFC_READER_PTX_DataExchange()

◆ RM_NFC_READER_PTX_ReaderDeactivation()

◆ RM_NFC_READER_PTX_Close()