The T4T emulation library interface. More...

Macros
#define	NFC_T4T_MAX_PAYLOAD_SIZE 0xFFF0U
	Emulation mode. More...

Typedefs
typedef void(*	nfc_t4t_callback_t) (void p_context, nfc_t4t_event_t event, const uint8_t p_data, size_t data_length, uint32_t flags)
	Callback to pass events from NFCLib to application. More...

Enumerations
enum	nfc_t4t_emu_mode_t { NFC_T4T_EMUMODE_NDEF , NFC_T4T_EMUMODE_PICC }

enum	nfc_t4t_event_t { NFC_T4T_EVENT_NONE , NFC_T4T_EVENT_FIELD_ON , NFC_T4T_EVENT_FIELD_OFF , NFC_T4T_EVENT_NDEF_READ , NFC_T4T_EVENT_NDEF_UPDATED , NFC_T4T_EVENT_DATA_TRANSMITTED , NFC_T4T_EVENT_DATA_IND }

enum	nfc_t4t_data_ind_flags_t { NFC_T4T_DI_FLAG_NONE = 0x00 , NFC_T4T_DI_FLAG_MORE = 0x01 }

enum	nfc_t4t_param_id_t { NFC_T4T_PARAM_TESTING , NFC_T4T_PARAM_FWI , NFC_T4T_PARAM_SELRES , NFC_T4T_PARAM_NFCID1 }

Functions
ret_code_t	nfc_t4t_setup (nfc_t4t_callback_t callback, void *p_context)
	Register the application callback for event signaling. More...

ret_code_t	nfc_t4t_ndef_rwpayload_set (uint8_t *p_emulation_buffer, size_t buffer_length)
	Set emulation buffer and content for a NDEF Tag emulation that is Read/Writable. More...

ret_code_t	nfc_t4t_ndef_staticpayload_set (const uint8_t *p_emulation_buffer, size_t buffer_length)
	Set emulationBuffer and Content for a NDEF Tag emulation that is Read-Only. More...

ret_code_t	nfc_t4t_response_pdu_send (const uint8_t *p_pdu, size_t pdu_length)
	Send a raw response PDU after getting a Request PDU callback. More...

ret_code_t	nfc_t4t_parameter_set (nfc_t4t_param_id_t id, void *p_data, size_t data_length)
	Set an NFC parameter. More...

ret_code_t	nfc_t4t_parameter_get (nfc_t4t_param_id_t id, void p_data, size_t p_max_data_length)
	Query an NFC parameter value. More...

ret_code_t	nfc_t4t_emulation_start (void)
	Activate the NFC frontend. More...

ret_code_t	nfc_t4t_emulation_stop (void)
	Deactivate the NFC frontend. More...

ret_code_t	nfc_t4t_done (void)
	Release reference to application callback. More...

Detailed Description

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.

E.g. NDEF emulation
- nfc_t4t_setup
- nfc_t4t_ndef_rwpayload_set or nfc_t4t_ndef_staticpayload_set
- nfc_t4t_emulation_start
- ... running in NDEF emulation mode ...
E.g. RAW mode
- nfc_t4t_setup
- nfc_t4t_emulation_start
- ... running in RAW emulation mode ...

Macro Definition Documentation

◆ NFC_T4T_MAX_PAYLOAD_SIZE

#define NFC_T4T_MAX_PAYLOAD_SIZE 0xFFF0U

Emulation mode.

Definition at line 87 of file nfc_t4t_lib.h.

Typedef Documentation

◆ nfc_t4t_callback_t

typedef void(* nfc_t4t_callback_t) (void *p_context, nfc_t4t_event_t event, const uint8_t *p_data, size_t data_length, uint32_t flags)

Callback to pass events from NFCLib to application.

Parameters

[out]	p_context	Application context for callback execution.
[out]	event	The event that occurred. see nfc_t4t_event_t.
[out]	p_data	Data to send to the application (event specific).
[out]	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.
[out]	flags	Some events deliver flags. see nfc_t4t_event_t for details.

Definition at line 183 of file nfc_t4t_lib.h.

Enumeration Type Documentation

◆ nfc_t4t_data_ind_flags_t

enum nfc_t4t_data_ind_flags_t

Enumerator
NFC_T4T_DI_FLAG_NONE	Dummy value.
NFC_T4T_DI_FLAG_MORE	This signals that more data is expected to be received.

Definition at line 153 of file nfc_t4t_lib.h.

◆ nfc_t4t_emu_mode_t

enum nfc_t4t_emu_mode_t

Enumerator
NFC_T4T_EMUMODE_NDEF	Emulated NDEF AID and EF-Files.
NFC_T4T_EMUMODE_PICC	Run just ISO-DEP, deliver I-Frames up.

Definition at line 88 of file nfc_t4t_lib.h.

◆ nfc_t4t_event_t

enum nfc_t4t_event_t

Enumerator

NFC_T4T_EVENT_NONE

This ID is never used. Dummy value for completeness.

NFC_T4T_EVENT_FIELD_ON

External Reader polling detected.

NFC_T4T_EVENT_FIELD_OFF

External Reader polling ended.

NFC_T4T_EVENT_NDEF_READ

External Reader has read static NDEF-Data from Emulation.

A Read operation happened on last byte of NDEF-Data.

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).

Parameters

[out]	data	Pointer to current data of NDEF message
[out]	data_length	Current value of NDEF content length information i.e. 'NLEN' field.

NFC_T4T_EVENT_DATA_TRANSMITTED

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

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).

Parameters

[out]	p_data	Pointer to the fragment of APDU.
[out]	data_length	Length of data.
[out]	flags	nfc_t4t_data_ind_flags_t.

Definition at line 96 of file nfc_t4t_lib.h.

◆ nfc_t4t_param_id_t

enum nfc_t4t_param_id_t

Enumerator
NFC_T4T_PARAM_TESTING	Internal usage only for Unit-Testing.
NFC_T4T_PARAM_FWI	Frame Wait Time parameter.
NFC_T4T_PARAM_SELRES	Parameter for setting 'Protocol' bits for SEL_RES packet.
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.

Definition at line 162 of file nfc_t4t_lib.h.

Function Documentation

◆ nfc_t4t_done()

ret_code_t 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 p_ndef pointer is no longer considered valid.

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

Return values

NRF_SUCCESS Always succeeds.

◆ nfc_t4t_emulation_start()

ret_code_t nfc_t4t_emulation_start ( void )

Activate the NFC frontend.

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

Return values

NRF_SUCCESS	Success.
NRF_ERROR_INVALID_STATE	Already started.

◆ nfc_t4t_emulation_stop()

ret_code_t 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

NRF_SUCCESS	Success.
NRF_ERROR_INVALID_STATE	Emulation was already stopped

◆ nfc_t4t_ndef_rwpayload_set()

ret_code_t nfc_t4t_ndef_rwpayload_set	(	uint8_t *	p_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 is finished. To perform this procedure safely use critical sections or disable the interrupts.

Parameters

[in]	p_emulation_buffer	Buffer pointer
[in]	buffer_length	Length of buffer (maximum writable NDEF size)

Return values

NRF_SUCCESS	Success.
NRF_ERROR_DATA_SIZE	Invalid argument (e.g. wrong data length).
NRF_ERROR_INVALID_PARAM	Invalid argument (e.g. NULL pointer).
NRF_ERROR_NOT_SUPPORTED	If the new buffer has a different length than the first one.
NRF_ERROR_INVALID_DATA	If the provided buffer is the currently used buffer.

◆ nfc_t4t_ndef_staticpayload_set()

ret_code_t nfc_t4t_ndef_staticpayload_set	(	const uint8_t *	p_emulation_buffer,
		size_t	buffer_length
	)

Set emulationBuffer and Content for a 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

[in]	p_emulation_buffer	Const buffer pointer
[in]	buffer_length	Length of contained NDEF payload message

Return values

NRF_SUCCESS	Success.
NRF_ERROR_DATA_SIZE	Invalid argument (e.g. wrong data length).
NRF_ERROR_INVALID_PARAM	Invalid argument (e.g. NULL pointer).
NRF_ERROR_INVALID_STATE	Emulation is in running stated.

◆ nfc_t4t_parameter_get()

ret_code_t nfc_t4t_parameter_get	(	nfc_t4t_param_id_t	id,
		void *	p_data,
		size_t *	p_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, p_max_data_length will contain the required buffer size. If the buffer is big enough, p_max_data_length will contain the actual size of the data.

Parameters

[in]	id	ID of the parameter to query.
[out]	p_data	Pointer to a buffer receiving the queried data.
[out]	p_max_data_length	Size of the buffer, receives actual size of queried data.

Return values

NRF_SUCCESS	Success.
NRF_ERROR_DATA_SIZE	Invalid argument (e.g. wrong data length).
NRF_ERROR_INVALID_PARAM	Invalid argument (e.g. NULL pointer).

◆ nfc_t4t_parameter_set()

ret_code_t nfc_t4t_parameter_set	(	nfc_t4t_param_id_t	id,
		void *	p_data,
		size_t	data_length
	)

Set an NFC parameter.

Allows to set an NFC configuration parameter.

Parameters

[in]	id	ID of the parameter to set.
[in]	p_data	Pointer to a buffer containing the data to set.
[in]	data_length	Size of the buffer containing the data to set.

Return values

NRF_SUCCESS	Success.
NRF_ERROR_DATA_SIZE	Invalid argument (e.g. wrong data length).
NRF_ERROR_INVALID_PARAM	Invalid argument (e.g. NULL pointer).

◆ nfc_t4t_response_pdu_send()

ret_code_t nfc_t4t_response_pdu_send	(	const uint8_t *	p_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

[in]	p_pdu	Const PDU pointer.
[in]	pdu_length	Length of PDU.

Return values

NRF_SUCCESS	Success.
NRF_ERROR_DATA_SIZE	Invalid argument (e.g. wrong data length).
NRF_ERROR_INVALID_PARAM	Invalid argument (e.g. NULL pointer).
NRF_ERROR_INVALID_STATE	Emulation is in running state.

◆ nfc_t4t_setup()

ret_code_t nfc_t4t_setup	(	nfc_t4t_callback_t	callback,
		void *	p_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

[in]	callback	Function pointer to the callback.
[in]	p_context	Pointer to a memory area used by the callback for execution (optional).

Return values

NRF_SUCCESS	Success.
NRF_ERROR_INVALID_STATE	If emulation is in running state.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ NFC_T4T_MAX_PAYLOAD_SIZE

Typedef Documentation

◆ nfc_t4t_callback_t

Enumeration Type Documentation

◆ nfc_t4t_data_ind_flags_t

◆ nfc_t4t_emu_mode_t

◆ nfc_t4t_event_t

◆ nfc_t4t_param_id_t

Function Documentation

◆ nfc_t4t_done()

◆ nfc_t4t_emulation_start()

◆ nfc_t4t_emulation_stop()

◆ nfc_t4t_ndef_rwpayload_set()

◆ nfc_t4t_ndef_staticpayload_set()

◆ nfc_t4t_parameter_get()

◆ nfc_t4t_parameter_set()

◆ nfc_t4t_response_pdu_send()

◆ nfc_t4t_setup()