/
Host Card Emulation SDK Examples

Host Card Emulation SDK Examples

Apr 03, 2025

Host Card Emulation API

The Host Card Emulation (HCE) API is used in two different examples int the POS/IOT Reader OS/non-OS SDK. The API is found under SRC\COMPS\HCE. Code snippets in this article are taken from the non-OS IOT Reader SDK. Both examples are included in the main app of the respective SDK:

  • IOT Reader SDK: SRC\EXAMPLE\IOT_APP\ptx_IOT_RD_Main.c

  • POS SDK: SRC\EXAMPLE\POS_APP\ptxEMVCO_LOOPBACK.c

The HCE API is based on states and corresponding events:

All transitions between states are done by calling ptxHce_Get_Event(). When an external field is detected, and the PTX is activated as a card, data can be exchanged in the "DATA" state. Communication is always initiated by the external reader. Please note, that the PTX needs to be powered on and the SDK example needs to be running on the host in order to use HCE.

Emulate T4T with NDEF

The HCE T4T example emulates a Type-4 tag with a default NDEF (NFC Data Exchange Format) message. When a reader, like a smartphone, is held to the antenna, this message will be transmitted by the PTX. In order to use HCE, discovery must be configured for listening for Type-A cards. Polling for cards may be disabled entirely:

Discovery config
ptxStatus_t st = ptxStatus_Success; ptxIoTRd_DiscConfig_t rf_disc_config; (void)memset(&rf_disc_config, 0, sizeof(ptxIoTRd_DiscConfig_t)); rf_disc_config.ListenTypeA = 1u; rf_disc_config.IdleTime = 100u; st = ptxIoTRd_Initiate_Discovery (&iotRd, &rf_disc_config);

The default NDEF message is defined the following way:

Default NDEF message
static uint8_t NDEF_FILE_TEMPLATE[] = { 0xD1, 0x01, 0x10, 0x55, 0x01, 0x70, 0x61, 0x6E, 0x74, 0x68, 0x72, 0x6F, 0x6E, 0x69, 0x63, 0x73, 0x2E, 0x63, 0x6F, 0x6D};

This translates to "https://renesas.com". Each NDEF message consists of a record header and a payload. In the example above, the header consists of the 4 most significant bytes:

  • 0xD1  - Type Name Format + flags: the message is a Well-Known TNF and it’s a short record

  • 0x01  - type length

  • 0x0C  - payload length (decimal 12)

  • 0x55  - record type: URI

The payload consists of the least significant 12 bytes:

  • 0x04  - URI prefix: https:// 

  • the remaining 11 bytes are the ASCII-encoded characters for renesas.com 

The default NDEF message can also be updated at runtime by calling ptxT4T_UpdateNDEFMessage().

For more information about the format of NDEF messages, please refer to external sources, like the book Beginning NFC published by O’Reilly Media.

HCE Loopback

In the non-OS SDK example, the macro USE_PTX_HCE_LOOPBACK_DEMO must be defined. The OS SDK example works with command line arguments. The HCE loopback can be used to exchange custom data, similar to peer-to-peer communication. The difference is, that communication can only be initiated by the external reader. The source code of the loopback is found in ptxHce_Loopback.c.

When the HceEvent_Data is received, ptxHce_LoopbackProcessData() is called to process the received data and prepare the data to be transmitted accordingly. Data is then transmitted by calling ptxHce_Send_Data(). 

 

Site Policy