Renesas PTX1xxR IoT-Reader API (non-OS) Version 7.3.1
Renesas Software Stack for IoT-Reader Applications (non-OS)
Renesas PTX1xxR IoT-Reader API (non-OS)

Introduction

The purpose of this document is to describe the IoT-Reader (NON_OS) Stack SDK for the PTX1xxR-Reader products PTX100R and PTX105R (both further referenced as PTX1xxR).
The IoT-Reader (NON_OS) SDK provides a reference implementation of an IoT-Reader with multiple card type detection capability, running on a Renesas RA4M2 MCU as example host target platform.

The provided SDK is implemented in C and the source code can be easily ported to any target MCU or host platform. The RA4M2 reference shall be regarded only as an example implementation. Information about the porting to other MCU and host platforms is provided in this document.

This solution is intended for platforms without an Operating System and without a file system. In addition to the IoT-Reader (NON_OS) stack, the delivery also contains an example application for simultaneous discovery of multiple card types, which shows the correct usage of the IoT-Reader (NON_OS) Stack.

The intended audience for this document are

  • SW architects
  • SW engineers
  • SW integrators

NSC Software Stack Architecture with IoT-Reader API

The IoT-Reader (NON_OS) System follows component-based approach which increases modularity and usability. The components are divided into two main groups:

  1. Hardware/Platform independent:
    It is suitable to run on Application processors where there is neither Operating System nor File System. Those components are IoT-Reader and NSC.
  2. Hardware/Platform dependent:
    This part needs to be adapted to a specific MCU/platform used as Application processor. Reference implementation is provided in this SDK, refer to Chapter 6 for more info about it. PLAT component belongs to this group.

The IoT-Reader (NON_OS) Stack is implemented in ANSI C in order to maximize its portability. Following picture shows the main components of this system.

This component- and layered-based approach allows a simplified target integration as well as an easy way for adding extensions and / or customized features.

PTX IoT-Reader API Architecture


COMPONENT DESCRIPTIONS

IoT-Reader API
The PTX NSC IoT-Reader API defines the system functionalities exposed by the IoT-Reader (NON_OS) Stack to the application on top.
The IoT-Reader API provides a set of functions:

  • initialize the IOTRD API and NSC Stack
  • initialize the PTX-Chip
  • discover cards according to NFC Forum incl. support for “Low-Power-Card-Detection”
  • select a specific card in case multiple cards and / or protocols were discovered
  • retrieve card details like technical and / or activation parameters etc.
  • exchange RF-data and -bitstreams
  • stop RF-communication
  • optionally update RF- and System-configuration parameters at runtime
  • optionally put PTX-Chip into and wake up from stand-by mode
  • control various GPIO pins of the PTX-Chip (input, output, can be used any state from READY onwards)
  • perform Host Card Emulation using the PTX HCE API
  • perform FeliCa performance tests
  • enable various RF test-sequences (e.g. PRBS9, PRBS15, ...)
  • ...

Add-on APIs Component
This layer contains various optional add-on APIs which can be used on top of the PTX NSC IoT-Reader API such as

IoT-Reader Component
This layer contains the actual implementation of the PTX NSC IoT-Reader API functions. It configures the NSC component to operate as multiprotocol NFC Reader device using the PTX-Chip.

NSC Component
The PTX NSC Stack Component exposes to the upper layer the set of functions that abstract the PTX-Chip NFC functionality.
This layer represents the actual core of the NSC (NON_OS) Stack and provides mainly the following functionalities:

  • PTX-Chip configuration and initialization
  • PTX-Chip RF discovery loop
  • PTX-Chip RF card activation detection
  • PTX-Chip RF data exchange
  • ...

Platform API
This API defines the platform/MCU dependent functionalities required by the NSC (NON_OS) Stack.

The PTX NSC Platform API enables:

  • transfer bytes to/from PTX-Chip,
  • wait synchronously (e.g. blocking) for the IRQ pin to be triggered by PTX-Chip,
  • capturing asynchronously the IRQ pin triggered by PTX-Chip (e.g. not-blocking),
  • put the SW execution to sleep for certain time.

Platform Component
The PTX NSC Platform Component is dependent on the platform/MCU which is used as application processor. It depends as well on the used physical HW interface (SPI, I2C or UART) between the application processor platform and the PTX-Chip.

The Platform component includes the following submodules:

  • Interface. It implements the driver for the physical interface used for communication with PTX-Chip,
  • GPIO. It implements the driver for the GPIO used for IRQ. This submodule is needed when SPI or I2C are used as physical interface; if UART is used, IRQ is not required,
  • Timer. It implements a wrapper for a HW Timer in order to provide time-out functionality for the IoT-Reader (NON_OS) Stack.

Note: The delivered SDK contains a reference implementation for Platform component used on RA4M2 application processor. This layer needs to be adapted/ported for different targets.

IoT-Reader API State Machine

The figure below below shows an example flow of how the IoT-Reader API should be used.

PTX IoT-Reader API States

Note:
All IoT-Reader API functions return a 16-bit status word indicating the status of the requested operation. If an operation succeeded, the status word is set to 0x0000 (= SUCCESS). In any other case the upper 8 bit of the status word indicate the (sub-)component identifier of where the error occurred and the lower 8 bit indicate the exact error code. Details of the status word definition can be found in the source file “ptxStatus.h”.

STATE DESCRIPTIONS

State: START
The system needs to be initialized first via a call to ptxIoTRd_Init(). This will initialize the SW Stack and the PTX-Chip to be ready for NFC operations.

State: READY
After IC initialization, the IoT-Reader API is ready to poll for cards in the field via a call to ptxIoTRd_Initiate_Discovery(). The behavior of the discovery-loop is configurable where a user can change for example:
- poll for Type-A
- poll for Type-B
- poll for Type-F (Parameter "PollTypeF212" == 1 for 212 kBit/s, "PollTypeF212" == 1 and "PollTypeF424" == 1 for 424 kBit/s)
- poll for Type-V
- use Low-Power-Card-Detection ("LPCD")
- ...

Note:
The call to ptxIoTRd_Initiate_Discovery() is non-blocking i.e. it returns immediately to the caller while the actual polling operation is handled in the background.

Attention:
If enabled in the System-configuration parameters, the PTX-Chip supports detection of critical errors like over current and temperature. In case such an error occurs, the PTX-Chip shuts down automatically all relevant HW-blocks and informs the stack about the changed state. This state can be read via a call to ptxIoTRd_Get_Status_Info() (Status Type == System).

It is strongly recommended to call ptxIoTRd_Get_Status_Info() (Status Type == System) periodically from state READY onwards!

In addition, the following optional functions can be executed exclusively in this state:
– ptxIoTRd_Update_ChipConfig()
– ptxIoTRd_Set_Power_Mode()
– ptxIoTRd_Get_Revision_Info()
– ptxFeliCa_DTE* (except API/component (un)initialization)
– ptxRF_Test* (except API/component (un)initialization)

Note:
A call to ptxIoTRd_Update_ChipConfig() requires a following call to ptxIoTRd_SWReset() and ptxIoTRd_Init() to apply the changed configuration.

The IoT-Reader also supports higher bitrates for Type-A and Type-B polling. The default configuration only supports 106kbit/s. Higher bitrates can be configured by a call to ptxIoTRd_ConfigHBR(). The higher bitrate is only used if the card supports it. If the card does not support the configured higher bit rates, the reader uses the default speed of 106kbit/s.

State: TEST (Optional)
This optional state allows the application to perform various system and / or RF-tests using the add-on APIs described in this document. The transition from and back to state READY is shown in the figure below.

Test States

State: POLLING
The current status of the polling operation can be retrieved via a call to ptxIoTRd_Get_Status_Info() (Status Type == Discover).

This function returns that:

  • a single card was discovered and activated.
    A call to function ptxIoTRd_Get_Card_Registry() should be used to retrieve details on the discovered card (e.g. serial number, information on used RF-protocol, etc.) to determine for example,
    if a card supports the ISO-DEP protocol (see ISO 14443-4, T=CL).
  • multiple cards were discovered, and the RF discovery is still ongoing.
    This state is for information purposes only.
  • multiple cards were discovered, and the RF discovery has finished.
    A call to ptxIoTRd_Get_Card_Registry() should be used to retrieve the internal card registry to get the number of discovered cards including detailed information.
  • nothing was discovered,
  • the low power card detection (LPCD) triggered.

An ongoing polling operation can be stopped via a call to ptxIoTRd_Reader_Deactivation().

State: HOST CARD EMULATION
This state is reached if an external field is discovered. Once entered this state, the application communicates with the external reader device and only leaves this state if the external field is turned off again. All data and notifications are written into a message queue and can then be processed by the HCE API. The application uses ptxHce_Get_Event() to receive the next event in the queue, and processes it according to the event type. Possible event types can be

  • External Field On
  • External Field Off
  • Activated Listen for Type A
  • Data Exchange
Note
: Once the external field is turned off, the application returns to the POLLING state.

State: WAIT FOR SELECTION
This state is reached if multiple cards were previously discovered or if a specific card was deactivated. The application can use the function ptxIoTRd_Get_Card_Registry() to gather information about all available cards. To select a specific card and / or to activate a specific RF-protocol, a call to ptxIoTRd_Activate_Card() is required before an actual RF data exchange can be executed.

State: DATA EXCHANGE
In this state RF data can be exchanged with the active card via

Note
: Using the function ptxIoTRd_Bits_Exchange() needs to be enabled prior the first usage in this state via a call to ptxIoTRd_Bits_Exchange_Mode() and disabled after the last call.

The RF-protocols ISO- and NFC-DEP are handled internally by the PTX-Chip, all other (NFC-Forum) protocols like T1T, T2T, T3T and T5T have to be handled by the application and / or the add-on APIs on top.
The API contains additionally the following functions which may / have to be used in this state:

  • ptxIoTRd_RF_PresenceCheck()
    This is an optional function to perform a presence during an active data-exchange session with ISO-DEP cards or NFC-DEP targets.
  • ptxIoTRd_T5T_IsolatedEoF()
    This is an optional function which may be used to send an isolated EoF-packet to a T5T card which may be required for certain commands.
  • ptxIoTRd_T3T_SENSFRequest()
    This is an optional function which allows to send a T3T-SENSF_REQ with given parameters in the current state.
    The data contained in the provided output buffer contains the concatenated responses of each detected card with a prepended length.

The delivered demo application provides a few examples of how the different RF-technologies and -protocols are handled for single and multiple available cards. The demo application selects
the first card found in the field which is also stored first in the internal card registry.

A special case is RF-technology Type-A where the card response parameter SEL_RES (also referred to as SAK-byte in ISO 14443-3) may indicate support for the RF-protocols ISO-DEP and NFC-DEP.
In this case, the single remote NFC-peer device is treated internally as two devices. like with cards, a specific protocol can be selected via a call to ptxIoTRd_Activate_Card() in state WAIT FOR SELECTION.

Note:
Like in state "POLLING", completed RF-exchanges can be stopped via a call to ptxIoTRd_Reader_Deactivation().

State: FINISHED
Once the complete IoT-Reader application shall be stopped or shut-down, it is required to call function ptxIoTRd_Deinit() to free previously allocated system ressources like memory, drivers etc.

HCE State Machine

The internal Host Card Emulation (HCE) component is initialized together with the IoT-Reader API and ready to use when the IoT-Reader API is. The HCE component will be active if in the polling configuration the ListenTypeA parameter is set to 1. This parameter enables the listen mode and allows the API to receive listen events. The HCE component uses a message queue, to queue received events and processes them in ptxIoTRdInt_DemoState_HostCardEmulation().

Note
An application can use the functions of the HCE component also directly (usage of the DemoState-extension is not mandatory).

The following section describes the states used in ptxIoTRdInt_DemoState_HostCardEmulation(). The states START, RESET, INIT, and READY are the same as in IoT-Reader API State Machine. All transitions between the states are done via ptxHce_Get_Event().

PTX HCE API States


State: FIELD ON
The message queue contains this state if the PTX-Chip detects an external field from a reader. The PTX-Chip can now receive and send data.


State: FIELD OFF
The message queue contains this state if the PTX-Chip does not detect an external field. No more transactions are possible.


State: ACTIVATED LISTEN A
The message queue contains this state if the external reader has successfully activated the emulated card. The PTX-Chip receives the protocol information which should be activated.


State: DATA
The message queue contains this state if the external reader is sending data to the emulated card on a protocol level. The emulated card receives the command from the reader, processes it, and returns the requested data together with a status code.


State: DEACTIVATED
The message queue contains this state if the emulated card is deactivated. Currently there are three possible reasons:
- a DESELECT command is received
- a RELEASE command is received
- The reader has turned off the external field


State: NO DATA AVAILABLE
The message queue contains this event if the transmission from the reader does not contain any data.

IoT-Reader API References

See PTX NSC IoT-Reader Component

IoT-Reader Add-On API References

See PTX NSC Native-Tag API Component
See PTX NSC NDEF API Component
See PTX HCE API
See GPIO Operation API
See RF Test API
See FeliCa DTE API
See Transparent Mode API
See Transparent Data Channel (TDC) API

Disclaimer


Version History

Version Date Comment
1.0.0 April 2020 Initial Version
1.1.0 June 2020 SDK-Release V1.1.0 including extended feature-set
1.2.0 September 2020 SDK-Release V1.2.0 including NativeTag- and NDEF-API references
2.0.0 December 2020 SDK-Release V2.0.0 including refactored API-functions
3.0.0 April 2021 SDK-Release V3.0.0 refactored demo examples
4.0.0 June 2021 SDK-Release V4.0.0 Host Card Emulation API-functions
5.0.0 September 2021 SDK-Release V5.0.0 including higher bit rates
6.0.0 December 2021 SDK-Release V6.0.0 including NFC Forum compliance, FeliCa compliance, GPIO-control, low-power mode for HCE
6.0.1 January 2022 SDK-Release V6.0.1 bug-fix for PRBS-test
6.1.0 February 2022 SDK-Release V6.1.0 INTERNAL RELEASE: Switch from Renesas S128 MCU platform to Renesas RA4M2 MCU for non-OS Stacks
6.2.0 February 2022 SDK-Release V6.2.0 including new Revision-Info type (Product ID), fixed bitrate card parameter, change meta-info for RF-Config
6.3.0 July 2022 SDK-Release V6.3.0 including removal of function ptx[POS | IoTRd]_Send_Data (deprecated, ptxHCE_Send_Data shall be used instead), added support for LPCD-notification, extended FeliCa-DTE by "FeliCa Reader/Writer Digital Protocol" test-sequences
6.3.1 August 2022 SDK-Release V6.3.1 INTERNAL RELEASE: Rework of FeliCa-DTE.
6.3.2 September 2022 SDK-Release V6.3.2 INTERNAL RELEASE: Changed format of output data of "ptx[POS | IoTRd]_T3T_SENSFRequest" (indicates a collision within same timeslot).
7.0.0 December 2022 SDK-Release V7.0.0 Added I2C and UART reference implementation for Renesas RA4M2-MCU incl. refactored Stack-initialization. Bug-fix added to FeliCa-DTE API (424 kBit/s now supported too). Corrected issue in HCE-mode where RF-On/-Off was not correctly indicated on some systems.
7.1.0 April 2023 SDK-Release V7.1.0 Upgraded project files to Renesas E2 Studio 2022-10 and FSP 4.2. Added Transparent-Mode API.
7.2.0 May 2024 SDK-Release V7.2.0 Improved description of API Init-/Open-functions. Fixed issue related to EMV-collision if multiple Type-B cards used (POS-SDK only). Added support for B-Prime RF-Technology in Transparent-Mode API. Integrated Transparent Data Channel (TDC).
7.3.0 September 2025 SDK-Release V7.3.0 Removed usage of VLAs. Fixed too high current conumption in CE + LPCD mode. Fixed and exposed FeliCa polling parameters. Added sanity checks in FeliCa-DTE.
7.3.1 January 2026 SDK-Release V7.3.1 Improved handling of Temperature-sensor inside FW (no functional change).
Generated by doxygen 1.10.0