API documentation

NFC tag 2 type emulation library

group nfc_t2t_lib

The T2T emulation library interface.

Defines

NFC_T2T_SIZEOF_INTERNAL_BYTES

T2T internal byte size.

NFC_T2T_MAX_PAYLOAD_SIZE

Maximum NDEF message size. No NDEF-TLV and no implicit lock bytes at the end.

NFC_T2T_MAX_PAYLOAD_SIZE_RAW

Typedefs

typedef void (*nfc_t2t_callback_t)(void *context, enum nfc_t2t_event event, const u8_t *data, size_t data_length)

Callback to pass events from NFC T2T Library to application.

Parameters
  • context: Application context for callback execution.

  • event: The event that occurred.

  • data: Data to send to the application (event specific).

  • data_length: Length of the data.

Enums

enum nfc_t2t_event

Events passed to the callback function.

Values:

NFC_T2T_EVENT_NONE

Not used.

NFC_T2T_EVENT_FIELD_ON

NFC tag has detected external NFC field and was selected by an NFC polling device.

NFC_T2T_EVENT_FIELD_OFF

External NFC field has been removed.

NFC_T2T_EVENT_DATA_READ

NFC polling device has read all tag data. Repeated reading in the same session i.e. before NFC_T2T_EVENT_FIELD_OFF event, will not trigger another NFC_T2T_EVENT_DATA_READ event.

NFC_T2T_EVENT_STOPPED

Reference to the application NFC callback has been released using nfc_t2t_done.

enum nfc_t2t_param_id

Values:

NFC_T2T_PARAM_TESTING

Used for unit tests.

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

Functions

int nfc_t2t_setup(nfc_t2t_callback_t callback, void *context)

Function for registering the application callback for event signaling.

The callback will be called by NFC T2T Library to notify the application of relevant events. It will be called from the HAL_NFC callback context.

Parameters
  • callback: Function pointer to the callback.

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

Return Value
  • 0: If the application callback was registered successfully. If one of the arguments was invalid, an error code is returned.

int nfc_t2t_parameter_set(enum nfc_t2t_param_id id, void *data, size_t data_length)

Function for setting an NFC parameter.

This function 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 Value
  • Zero: on success or (negative) error code otherwise.

int nfc_t2t_parameter_get(enum nfc_t2t_param_id id, void *data, size_t *max_data_length)

Function for querying 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 Value
  • Zero: on success or (negative) error code otherwise.

int nfc_t2t_payload_set(const u8_t *payload, size_t payload_length)

Function for registering the payload to send on reception of a READ request.

The payload is considered to only contain the NDEF message to deliver to a reader. The required NDEF TLV will be created implicitly by NFC T2T Library.

The pointer to the payload must stay valid for the duration of the library execution, or until it is explicitly released.

If the pointer is not NULL, but the length is zero, the paypload is considered to be an empty NDEF message.

If a new payload is registered, the previously registered one is considered released.

Passing a NULL pointer releases the current payload without registering a new one.

If an invalid size is given (too big), the function returns with an error and the currently registered payload is left unchanged.

Note

Provided pointer must point to RAM region.

Parameters
  • payload: Pointer to the memory area in RAM containing the payload to send.

  • payload_length: Size of the payload in bytes.

Return Value
  • Zero: on success or (negative) error code otherwise.

int nfc_t2t_payload_raw_set(const u8_t *payload, size_t payload_length)

Function for registering the raw payload to send on reception of a READ request.

The payload will be delivered directly as-is to the reader, without implicitly adding an NDEF TLV container. This can be used if the application wants to define the TLVs itself, for example, to provide a different memory layout.

The pointer to the payload must stay valid for the duration of the library execution, or until it is explicitly released.

If a new payload is registered, the previously registered one is considered released.

Passing a NULL pointer releases the current payload, without registering a new one.

If an invalid size is given (too big), the function returns with an error and the currently registered payload is left unchanged.

Note

Provided pointer must points to RAM region.

Parameters
  • payload: Pointer to the memory area in RAM containing the payload to send.

  • payload_length: Size of the payload in bytes.

Return Value
  • 0: If the operation was successful. If one of the arguments was invalid, an error code is returned.

int nfc_t2t_internal_set(const u8_t *data, size_t data_length)

Function for registering the sequence of internal bytes.

This refers to the first 10 bytes of the tag memory. The library will set a sensible default for these bytes. The application can use this function to override the default.

Passing a NULL pointer reverts back to the default sequence. The data will be copied by NFC T2T Library, so the memory does not have to remain valid after the function returns.

Note

When modifying the internal bytes, remember that they must be consistent with the NFC hardware register settings (see nfc_t2t_format_internal).

Parameters
  • data: Pointer to the memory area containing the data.

  • data_length: Size of the data in bytes.

Return Value
  • 0: If the operation was successful. If the data was not NULL and the data length was not 10, an error code is returned.

int nfc_t2t_emulation_start(void)

Function for activating the NFC frontend.

You must call this function so that events are posted to the application callback.

Return Value
  • 0: If the NFC frontend was activated successfully. If the lower layer could not be started, an error code is returned.

int nfc_t2t_emulation_stop(void)

Function for deactivating the NFC frontend.

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

Return Value
  • 0: If the NFC frontend was deactivated successfully. If the lower layer could not be stopped, an error code is returned.

int nfc_t2t_done(void)

Function for releasing the reference to the application callback.

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

Return Value
  • 0: This function always succeeds.

NFC tag 4 type emulation library

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.

  • 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

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 listed in nfc_fixes.h

Defines

NFC_T4T_MAX_PAYLOAD_SIZE

Emulation mode.

Typedefs

typedef void (*nfc_t4t_callback_t)(void *context, enum nfc_t4t_event event, const u8_t *data, size_t data_length, u32_t flags)

Callback to pass events from NFCLib to application.

Parameters
  • context: Application context for callback execution.

  • event: The event that occurred. see nfc_t4t_event.

  • data: Data to send to the application (event specific).

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

  • flags: Some events deliver flags. see nfc_t4t_event for details.

Enums

enum nfc_t4t_emu_mode

Values:

NFC_T4T_EMUMODE_NDEF

Emulated NDEF AID and EF-Files.

NFC_T4T_EMUMODE_PICC

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

enum nfc_t4t_event

Values:

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
  • data: Pointer to current data of NDEF message

  • 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
  • data: Pointer to the fragment of APDU.

  • data_length: Length of data.

  • flags: nfc_t4t_data_ind_flags.

enum nfc_t4t_data_ind_flags

Values:

NFC_T4T_DI_FLAG_NONE = 0x00

Dummy value.

NFC_T4T_DI_FLAG_MORE = 0x01

This signals that more data is expected to be received.

enum nfc_t4t_param_id

Values:

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.

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 Value
  • 0: Success.

  • -ENOTSUP: If emulation is in running state.

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

Parameters
  • emulation_buffer: Buffer pointer

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

Return Value
  • 0: Success.

  • -EINVAL: Invalid argument (e.g. wrong data length).

  • -EINVAL: Invalid argument (e.g. NULL pointer).

  • -ENOTSUP: If the new buffer has a different length than the first one.

  • -EFAULT: If the provided buffer is the currently used buffer.

int nfc_t4t_ndef_staticpayload_set(const u8_t *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
  • emulation_buffer: Const buffer pointer

  • buffer_length: Length of contained NDEF payload message

Return Value
  • 0: Success.

  • -EINVAL: Invalid argument (e.g. wrong data length).

  • -EINVAL: Invalid argument (e.g. NULL pointer).

  • -ENOTSUP: Emulation is in running stated.

int nfc_t4t_response_pdu_send(const u8_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 Value
  • 0: Success.

  • -EINVAL: Invalid argument (e.g. wrong data length).

  • -EINVAL: Invalid argument (e.g. NULL pointer).

  • -ENOTSUP: Emulation is in running state.

int nfc_t4t_parameter_set(enum nfc_t4t_param_id 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 Value
  • 0: Success.

  • -EINVAL: Invalid argument (e.g. wrong data length).

  • -EINVAL: Invalid argument (e.g. NULL pointer).

int nfc_t4t_parameter_get(enum nfc_t4t_param_id 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 Value
  • 0: Success.

  • -EINVAL: Invalid argument (e.g. wrong data length).

  • -EINVAL: Invalid argument (e.g. 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 Value
  • 0: Success.

  • -ENOTSUP: 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 Value
  • 0: Success.

  • -ENOTSUP: 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 Value
  • 0: Always succeeds.