Renesas PTX1xxR IoT-Reader API Version 7.3.1
Renesas Software Stack for IoT-Reader Applications
Renesas PTX1xxR IoT-Reader API

Introduction

This document describes the PTX IoT-Reader API library for the PTX1xxR-Reader products PTX100R and PTX105R (both further referenced as PTX1xxR).
The corresponding IoT-Reader API is intended to be used for general reader applications based on various different RF-technologies and -protocols.

The intended audience for this document are

  • SW architects
  • SW engineers
  • SW integrators

IoT-Reader API Requirements

In order to integrate / execute the IoT-Reader API incl. the PTX "NSC Software Stack" the following requirements must be fullfilled by the target platform:

NSC Software Stack Architecture with IoT-Reader API

The IoT-Reader API is based on the PTX "NSC Software Stack" which consists of multiple layers and components and has been written in ANSI C.
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


Application Layer
This layer implements the PTX NSC IoT-Reader API Component which is the main software interface for the target application.
The IoT-Reader API provides a variety of methods to

  • initialize the software
  • initialize the PTX1xxR
  • start the RF-discovery procedure according to NFC-Forum (incl. LPCD (Low Power Card Detection))
  • select a specific card in case multiple cards (or protocols) were detected during RF-discovery
  • get details of detected cards
  • exchange RF-data (protocol based and raw access)
  • exchange RF-bitstreams (NFC-A technology)
  • stop / deactivate any RF-communication
  • update RF- and System-configuration
  • put the PTX1xxR into and wake up from Stand-by mode
  • control various GPIO pins of the PTX1xxR (input, output, can be used any state from READY onwards)
  • perform Host Card Emulation using the 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 NSC IoT-Reader API such as

A detailed flow of how to use the IoT-Reader API is shown in IoT-Reader API State Machine.

Integration Layer ("INT")
This layer implements a collection of all APIs of the NSC component including all its submodules.

Component Layer ("COMPS")
This layer implements the API to the internal NSC component which provides the following functionality:

  • PTX1xxR initialization and configuration
  • RF configuration and communication (incl. callbacks for asynchronous events / notifications and error handling)
  • Factory subcomponent to allow easy configuration and parametrization of the Software Stack itself
  • extensive Logging capabilities to ease system integration
  • internal HW-access request handler ("IORQ")


Hardware- and Operating System Abstraction Layer
This layer implements the SW interfaces for the

  • PTX NSC Hardware Abstraction Layer (HAL) This component is dependent on the used physical HW interface (SPI, I2C or UART) to the host controller of the target platform.
    It is required by the integrator to use or implement a native driver for the selected HW interface.
  • PTX NSC Operating System Abstraction Layer (OSAL) This component is dependent on the Operating System of the target platform.
    It is required by the integrator to use or implement a wrapper for the functions accessing resources of the used Operating System.

    Note
    The PTX "NSC Software Stack" is a multi-threaded based solution which requires access to the following resources of an Operating System:
    – Threads
    – Dynamic Memory Allocation
    – Mutexes
    – Semaphores
    – Timers

IoT-Reader API State Machine

The PTX NSC IoT-Reader API Component follows a object-oriented approach where a so called "Stack-Object" needs to be allocated first.
This object contains all the internal data structures and information which is further used in every following API call.

PTX IoT-Reader API States


State: START
A "Stack-Object" needs to be allocated via a call to ptxIoTRd_Allocate_Stack().

State: RESET
Initialize the IoT-Reader API and the internal NSC components via a call to ptxIoTRd_Init_Stack().
This call takes parameters to initialize the intended host-interface including characteristics and the file path to the mandatory RF- and SYSTEM-configuration files "NSC_RF_CONFIG.dat" and "NSC_SYS_CONFIG.dat"

State: INITIALIZED
Once the IoT-Reader API and the NSC components themselves have been initialized, the PTX1xxR needs to be initialized and configured (handled automatically) via a call to ptxIoTRd_Init_NSC().

State: READY
After IC initialization, the IoT-Reader API is ready to discover 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.

If enabled in the System-configuration parameters, the PTX1xxR supports detection of critical errors like over current and temperature. In case such an error occurs,
the PTX1xxR 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).

Note
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)
– ptxTransparent_Mode* (except API/component (un)initialization)

Note
A call to ptxIoTRd_Update_ChipConfig() requires a following call to ptxIoTRd_SWReset() and ptxIoTRd_Init_NSC() 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 provides the information whether

  • a single card was discovered and activated.
    A call to function ptxIoTRd_Get_Card_Registry() should be used to retrieve the internal card registry to get details on the discovered card (e.g. serial number, information on used RF-protocol, etc.) to
    determine for example, if a card is supports the ISO-DEP protocol (see ISO 14443-4, T=CL).
  • multiple cards were discovered and the RF discovery is still ongoing.
    This is state is for information purposes only.
  • multiple cards were discovered and the RF discovery has finished.
    A call to function 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 discover 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_GetEvent() 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 PTX1xxR, all other (NFC-Forum) protocols like 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.

Like in state "POLLING", completed RF data 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_Close_Stack() 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_GetEvent().

PTX HCE API States


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


State: FIELD OFF
The message queue contains this state if the PTX1xxR 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 PTX1xxR 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 API Component

IoT-Reader Add-On API References

See PTX NSC Native-Tag API Component
See PTX NSC NDEF API Component
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 February 2020 Initial SDK-Release with basic RF-functionality
1.0.1 April 2020 SDK-Release V1.0.0 including system-features
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, FeliCa-DTE- and RF-Test API
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 reference implementation for Linux 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 Added UART reference implementation for Linux. 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