Type 4 Tag

The Type 4 Tag implementation is based on the NFC Forum document Type 4 Tag Technical Specification Version 1.0 2017-08-28 [T4T].

A Type 4 Tag must contain at least the NDEF tag application. This application provides a file system that consists of at least two Elementary Files (EFs):

Capability container (CC)

The CC is a read-only metafile that contains the version of the implemented specification, communication parameters of the tag, and properties of all the other EF files that are present on a Type 4 Tag platform.

NDEF file

The NDEF file (see NDEF file format) contains the NDEF message, which can be read or re-written depending on its file properties, which are defined in the CC file.

The Type 4 Tag library uses application protocol data units (APDUs) to communicate over the ISO-DEP (ISO14443-4A) protocol with any polling NFC device. As with Type 2 Tag, Type 4 Tag also supports NFC-A listen mode. In this mode, the tag can only wait for polling devices, but it does not actively start a connection.

The Type 4 Tag library supports three different modes of emulation:

Mode type

Description

Raw ISO-DEP exchanges

All APDUs are signaled through the callback.

Read-only T4T NDEF tag

The NDEF file cannot be modified. Only NFC field status and NFC_T4T_EVENT_NDEF_READ can be signaled through the callback.

Read-write T4T NDEF tag

The NDEF file can be modified. The changes to the NDEF content are signaled through the callback.

NDEF file format

The NDEF file is a file type that can be present in a Type 4 Tag platform. It consists of following fields:

Field

Length

Description

NLEN

2 bytes

Length of the NDEF message in big-endian format.

NDEF Message

NLEN bytes

NDEF message. See NFC Data Exchange Format (NDEF).

As you see, the NDEF file adds one additional field in comparison to the raw NDEF message. It is called NLEN and is required for an NDEF file. This field encodes the total length of the NDEF message.

API documentation

group nfc_t4t_lib

The T4T emulation library interface.

This is the NFC Forum NDEF tag 4 type emulation library. It implements the ISO14443-4A protocol (ISO-DEP) and additionally can emulate a read-writable NDEF content. If the emulation of the NDEF content is not needed, the library works in a raw mode where all APDUs are delivered to the user, who is then responsible to generate a timely RPDU as a response.

The sequence of initializing functions determines whether the NDEF emulation will run or whether the raw mode is used.

Note

If you are using nRF52832 chip (in IC rev. Engineering B or Engineering C) or if You are using nRF52840 chip (in IC rev. Engineering A, B or C) library will use TIMER 4 to apply workarounds for the anomalies.

Defines

NFC_T4T_MAX_PAYLOAD_SIZE

Emulation mode.

Typedefs

typedef void (*nfc_t4t_callback_t)(void *context, nfc_t4t_event_t event, const uint8_t *data, size_t data_length, uint32_t flags)

Callback to pass events from NFCLib to application.

Param context:

Application context for callback execution.

Param event:

The event that occurred. see nfc_t4t_event.

Param data:

Data to send to the application (event specific).

Param data_length:

Length of the data. In case of NFC_T4T_EVENT_NDEF_UPDATED, this parameter contains the value of the ‘NLEN’ field of the NDEF File; if the value is non-zero, it corresponds to the new size of the NDEF Message in the updated NDEF File.

Param flags:

Some events deliver flags. see nfc_t4t_event for details.

Enums

enum nfc_t4t_emu_mode_t

Values:

enumerator NFC_T4T_EMUMODE_NDEF

Emulated NDEF AID and EF-Files.

enumerator NFC_T4T_EMUMODE_PICC

Run just ISO-DEP, deliver I-Frames up.

enum nfc_t4t_event_t

Values:

enumerator NFC_T4T_EVENT_NONE

This ID is never used. Dummy value for completeness.

enumerator NFC_T4T_EVENT_FIELD_ON

External Reader polling detected.

enumerator NFC_T4T_EVENT_FIELD_OFF

External Reader polling ended.

enumerator NFC_T4T_EVENT_NDEF_READ

External Reader has read static NDEF-Data from Emulation. A Read operation happened on last byte of NDEF-Data.

enumerator NFC_T4T_EVENT_NDEF_UPDATED

External Reader has written to length information of NDEF-Data from Emulation. The usual behavior of a Reader-Writer that accesses NDEF information for update is to set the length to zero at the beginning of the update process. It then writes the content of NDEF-Data. When all content is written it will update the length information inside the NDEF file. This event will be generated every time an update to the length is happening. This length information is residing in the first 2 bytes of the NDEF-Content container and is called ‘NLEN’. Since this callback is triggered on any access to these bytes the returned data_length information might not be consistent (e.g. in case of only a single byte write to the length).

Param data:

Pointer to current data of NDEF message

Param data_length:

Current value of NDEF content length information i.e. ‘NLEN’ field.

enumerator NFC_T4T_EVENT_DATA_TRANSMITTED

In Raw mode it signals that the data from nfc_t4t_response_pdu_send have been sent out.

enumerator NFC_T4T_EVENT_DATA_IND

In Raw mode delivers the APDU fragments All NFC_T4T_EVENT_DATA_IND events that have the NFC_T4T_DI_FLAG_MORE flag set belong to the same APDU. The first NFC_T4T_EVENT_DATA_IND without NFC_T4T_DI_FLAG_MORE flag signals the completeness of the APDU. The Application then has to reply with a call to nfc_t4t_response_pdu_send. The library will handle internally the fragmentation of the response towards the Reader-Writer. The data of the response PDU must be kept valid until the next callback from the library happens (e.g. next NFC_T4T_EVENT_DATA_IND or NFC_T4T_EVENT_FIELD_OFF).

Param data:

Pointer to the fragment of APDU.

Param data_length:

Length of data.

Param flags:

nfc_t4t_data_ind_flags.

enum nfc_t4t_data_ind_flags_t

Values:

enumerator NFC_T4T_DI_FLAG_NONE

Dummy value.

enumerator NFC_T4T_DI_FLAG_MORE

This signals that more data is expected to be received.

enum nfc_t4t_fwi_max_val_t

Values:

enumerator NFC_T4T_FWI_MAX_VAL_EMV

Value specified by the EMV specification.

enumerator NFC_T4T_FWI_MAX_VAL_NFC

Value specified by the NFC specification.

enum nfc_t4t_param_id_t

Values:

enumerator NFC_T4T_PARAM_FWI

Frame Wait Time parameter. The maximum allowed value is limited by the NFC_T4T_PARAM_FWI_MAX parameter. In case of nRF52832 the maximum allowed value is 4, setting the parameter higher will result in silent truncation to 4.

enumerator NFC_T4T_PARAM_FDT_MIN

Frame Delay Time Min parameter The parameter controls the frame transmission timing during collision resolution.

enumerator NFC_T4T_PARAM_SELRES

Parameter for setting ‘Protocol’ bits for SEL_RES packet

enumerator NFC_T4T_PARAM_NFCID1

NFCID1 value, data can be 4, 7, or 10 bytes long (single, double, or triple size). To use default NFCID1 of specific length pass one byte containing requested length. Default 7-byte NFCID1 will be used if this parameter was not set. This parameter can be set before nfc_t2t_setup() to set initial NFCID1 and it can be changed later.

enumerator NFC_T4T_PARAM_FWI_MAX

Maximum value for the Frame Wait time Integer. Valid parameter values are 7 and 8. The default value is 8. This parameter can be used to limit the maximum FWI value to 7, to align the implementation with the EMV specifications.

Functions

int nfc_t4t_setup(nfc_t4t_callback_t callback, void *context)

Register the application callback for event signaling.

The callback will be called by NFCLib to notify the application of relevant events. It will be called from the HAL_NFC callback context. The library support 3 different Modes of Emulation:

  • Raw ISO-Dep exchanges. All PDUs are signaled through the callback.

  • Read-Only T4T NDEF-Tag. A static buffer is served. Only Field-Status callbacks.

  • Read-Write T4T NDEF-Tag. A mutable buffer is used. Only Field-Status callbacks.

The default mode is Raw ISO-Dep mode. The two other NDEF T4T modes are activated through the corresponding nfc_t4t_ndef_rwpayload_set/ nfc_t4t_ndef_staticpayload_set functions. The mode is locked in with a call to nfc_t4t_emulation_start.

Parameters:
  • callback – Function pointer to the callback.

  • context – Pointer to a memory area used by the callback for execution (optional).

Return values:
  • 0 – Success.

  • -NRF_EINVAL – Invalid argument (e.g. wrong data length, NULL pointer))

  • -NRF_EOPNOTSUPP – If emulation is in running state.

int nfc_t4t_ndef_rwpayload_set(uint8_t *emulation_buffer, size_t buffer_length)

Set emulation buffer and content for a NDEF Tag emulation that is Read/Writable.

The buffer needs to be kept accessible for the lifetime of the emulation. If an external Reader-Writer changes the NDEF content it is signaled through the app-callback. Buffer can be changed during the lifetime of the emulation, when NDEF READ or UPDATE procedure is pending, and it will be changed after this procedure has completed. To perform this procedure safely, make sure to disable NFC interrupts.

Parameters:
  • emulation_buffer – Buffer pointer

  • buffer_length – Length of buffer (maximum writable NDEF size)

Return values:
  • 0 – Success.

  • -NRF_EINVAL – Invalid argument (for example, wrong data length, NULL pointer).

  • -NRF_EOPNOTSUPP – If the new buffer has a different length than the first one.

  • -NRF_EFAULT – If the provided buffer is the currently used buffer.

int nfc_t4t_ndef_staticpayload_set(const uint8_t *emulation_buffer, size_t buffer_length)

Set emulation buffer and content for an NDEF Tag emulation that is Read-Only.

The buffer needs to be kept accessible for the lifetime of the emulation. Since no write access is done to the buffer, the content could reside in flash memory.

Parameters:
  • emulation_buffer – Const buffer pointer

  • buffer_length – Length of contained NDEF payload message

Return values:
  • 0 – Success.

  • -NRF_EINVAL – Invalid argument (for example, wrong data length, NULL pointer).

  • -NRF_EOPNOTSUPP – Emulation is in running stated.

int nfc_t4t_response_pdu_send(const uint8_t *pdu, size_t pdu_length)

Send a raw response PDU after getting a Request PDU callback.

When the library works in raw ISO-DEP mode it will signal request PDUs through the callback. The application then has to answer with a response PDU. It will use this function to send back the response PDU. This function can not be used in T4T NDEF (RW / STATIC) emulation modes.

The lower ISODEP layer will handle the defragmentation of a long response PDU into smalleR pieces that the PCD can understand.

Parameters:
  • pdu – Const PDU pointer.

  • pdu_length – Length of PDU.

Return values:
  • 0 – Success.

  • -NRF_EINVAL – Invalid argument (for example, wrong data length, NULL pointer).

  • -NRF_EOPNOTSUPP – Emulation is in running state.

int nfc_t4t_parameter_set(nfc_t4t_param_id_t id, void *data, size_t data_length)

Set an NFC parameter.

Allows to set an NFC configuration parameter.

Parameters:
  • id – ID of the parameter to set.

  • data – Pointer to a buffer containing the data to set.

  • data_length – Size of the buffer containing the data to set.

Return values:
  • 0 – Success.

  • -NRF_EINVAL – Invalid argument (for example, wrong data length, NULL pointer).

int nfc_t4t_parameter_get(nfc_t4t_param_id_t id, void *data, size_t *max_data_length)

Query an NFC parameter value.

The queried value will be placed into the passed data buffer. If the buffer is too small, max_data_length will contain the required buffer size. If the buffer is big enough, max_data_length will contain the actual size of the data.

Parameters:
  • id – ID of the parameter to query.

  • data – Pointer to a buffer receiving the queried data.

  • max_data_length – Size of the buffer, receives actual size of queried data.

Return values:
  • 0 – Success.

  • -NRF_EINVAL – Invalid argument (for example, wrong data length, NULL pointer).

int nfc_t4t_emulation_start(void)

Activate the NFC frontend.

Only after calling this function, events will be posted to the application callback.

Return values:
  • 0 – Success.

  • -NRF_EOPNOTSUPP – Already started.

int nfc_t4t_emulation_stop(void)

Deactivate the NFC frontend.

After calling this function, no more events will be posted to the application callback.

Return values:
  • 0 – Success.

  • -NRF_EOPNOTSUPP – Emulation was already stopped.

int nfc_t4t_done(void)

Release reference to application callback.

After calling this function, the passed callback pointer is no longer considered valid. After calling this function, the passed ndef pointer is no longer considered valid.

You need to restart with nfc_t4t_setup to run a new Emulation.

Return values:
  • 0 – Success.

  • -NRF_EOPNOTSUPP – The NFC T4T has been de-initialized already.