TNEP for polling device

The poller library provides functionality to implement the Tag NDEF Exchange Protocol (TNEP) for a polling device.

The poller library is used in the NFC: TNEP poller sample.

Initialization

To initialize the poller library, call nfc_tnep_poller_init() and provide the TX buffer and callback structure as parameters. To ensure that the polling device discovers the tag, the initialization must be performed as required by the tag type.

Configuration

After reading the NDEF message from the NFC tag, the library can use the nfc_tnep_poller_svc_search() function to look for the initial NDEF message that contains the Service Parameters records.

If the initial message has valid Service Parameters records, the polling device can select a service using nfc_tnep_poller_svc_select().

After finishing all operations on the service, the service should be deselected by using one of the following options:

Exchanging data with single response communication mode

The polling device can use single response communication mode to exchange the NDEF message according to the NFC Forum TNEP specification (chapter 5).

Exchanging data is possible only when a service is selected. The data is exchanged in the NDEF read procedure or the NDEF write procedure.

To exchange data, use nfc_tnep_poller_svc_update() or nfc_tnep_poller_on_ndef_read().

Note

These operations are asynchronous.

When the polling device finishes the NDEF read procedure or the NDEF write procedure, the application should inform the library about this by calling nfc_tnep_poller_on_ndef_read() or nfc_tnep_poller_on_ndef_update(), respectively.

API documentation

Header file: include/tnep/poller.h
Source file: subsys/tnep/poller.c
group nfc_tnep_poller

TNEP Protocol for NFC Poller API.

Enums

enum nfc_tnep_tag_type

NFC TNEP Tag Type.

Values:

enumerator NFC_TNEP_TAG_TYPE_UNSUPPORTED

NFC unsupported Tag Type.

enumerator NFC_TNEP_TAG_TYPE_T2T

NFC Type 2 Tag.

enumerator NFC_TNEP_TAG_TYPE_T4T

NFC Type 4 Tag.

Functions

int nfc_tnep_poller_init(const struct nfc_tnep_buf *tx_buf)

Initialize the NFC TNEP Poller Device.

Parameters

  • tx_buf – [in] Pointer to TNEP Poller Tx buffer.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

void nfc_tnep_poller_cb_register(struct nfc_tnep_poller_cb *cb)

Register TNEP Poller callbacks.

Register callbacks to monitor the TNEP Poller data exchange.

Parameters

  • cb – Callback struct.

int nfc_tnep_poller_api_set(const struct nfc_tnep_poller_ndef_api *api, enum nfc_tnep_tag_type tag_type)

Set NDEF API for the NFC TNEP Poller Device.

This function provides API for NDEF operation and indicates the NFC Device Tag Type. API can be changed in runtime but it must be set immediately after NFC Poller Device detects Tag Type during the Device Activation Activity.

Parameters

  • api – [in] Pointer to the NDEF API structure.

  • tag_type – [in] NFC Device Tag Type.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

Search if NDEF Message contains TNEP Service Parameters Records.

Function for searching the TNEP Service Parameters Records in the given NDEF Message. NDEF Message has to be stored until all operations on services are finished.

Parameters

  • ndef_msg – [in] The NDEF Message which can be the Initial TNEP Message.

  • param – [out] Pointer to structure where found service parameters will be stored.

  • cnt – [inout] Count of service parameters which can be stored as an input. Count of found services parameters as an output.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int nfc_tnep_poller_svc_select(const struct nfc_tnep_buf *svc_buf, const struct nfc_ndef_tnep_rec_svc_param *svc, uint32_t max_ndef_area_size)

Select the TNEP Service.

Function for selecting the given service. After service is selected NFC Poller waits a specific amount of time to perform the NDEF Read procedure to get new data from the NFC Tag device. This operation is asynchronous.

Parameters

  • svc_buf – [in] Pointer to the buffer for new data from the NFC TNEP Tag Device. Buffer must be stored until the Select procedure is finished.

  • svc – [in] Pointer to The TNEP Service to select.

  • max_ndef_area_size – [in] Maximum size of NDEF Message.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int nfc_tnep_poller_svc_deselect(void)

Deselect the TNEP Service.

Function for deselecting the TNEP service. Service can be deselected also by selecting the other TNEP service without calling this function.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int nfc_tnep_poller_svc_read(const struct nfc_tnep_buf *svc_buf)

Read the TNEP Service data.

Function for reading the TNEP Service data. The Service must be selected first. This operation is asynchronous.

Parameters

  • svc_buf – [inout] Pointer to buffer for data to read. It must be kept until this operation is finished.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int nfc_tnep_poller_svc_write(const struct nfc_ndef_msg_desc *msg, const struct nfc_tnep_buf *resp_buf)

Write the TNEP Service data.

Function for writing the TNEP Service data. The Service must be selected first. After successful writing, library attempts to read new Service data after the specific amount of time. This operation is asynchronous.

Parameters

  • msg – [in] Pointer to the NDEF Message which will be written.

  • resp_buf – [in] Pointer to received data buffer. Buffer must be stored until the update procedure is finished.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int nfc_tnep_poller_on_ndef_read(const uint8_t *data, size_t len)

Indicate NDEF data read.

This function must be called immediately after NFC Reader/Writer Device read new NDEF message from NFC TNEP Tag Device.

Parameters

  • data – [in] NDEF Read raw data.

  • len – [in] Read data length.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

int nfc_tnep_poller_on_ndef_write(void)

Indicate NDEF data write operation finish.

This function must be called immediately after NFC Reader/Writer Device write NDEF message on NFC TNEP Tag Device.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

const struct nfc_ndef_tnep_rec_svc_param *active_service_get(void)

Get the selected/active service.

Return values

Pointer – to the selected/active service. If no selected/active service then NULL pointer is returned.

struct nfc_tnep_poller_msg
#include <poller.h>

TNEP Poller Message structure.

This structure contains NDEF Message pointer and TNEP status received from TNEP Status Message after the Tag Device received valid Service Select Message.

Public Members

enum nfc_tnep_status_value status

TNEP Status Type.

const struct nfc_ndef_msg_desc *msg

TNEP NDEF Message contains additional NDEF Records and NDEF Status Record.

struct nfc_tnep_poller_ndef_api
#include <poller.h>

TNEP Poller API structure.

This structure is used to provide an API for NFC NDEF Message operations like reading and writing. Depending on the connected tag type, appropriate API should be used.

Public Members

int (*ndef_read)(uint8_t *ndef_buf, uint16_t ndef_len)

Function used to read the NDEF Message.

It is called when TNEP Poller has to read NDEF data from NFC TNEP Tag Device.

Param ndef_buf

[out] Pointer to buffer where NDEF Message will be stored. This buffer has to be kept until the read operation is finished.

Param ndef_len

[in] Size of the NDEF Buffer

Retval 0

If the operation was successful. Otherwise, a (negative) error code is returned.

int (*ndef_update)(const uint8_t *ndef_buf, uint16_t ndef_len)

Function used to write the NDEF Message.

It is called when TNEP Poller attempts to update NDEF data on NFC TNEP Tag Device.

Param ndef_buf

[in] Buffer with NDEF Message to write. Buffer has to be kept until the write operation is finished.

Param ndef_len

[in] Length of NDEF Message to write.

Retval 0

If the operation was successful. Otherwise, a (negative) error code is returned.

struct nfc_tnep_poller_cb
#include <poller.h>

TNEP Poller callback structure.

Public Members

void (*svc_selected)(const struct nfc_ndef_tnep_rec_svc_param *param, const struct nfc_tnep_poller_msg *msg, bool timeout)

Function called when TNEP Service was selected.

Note

Service should be deselected in case of received timeout. The nfc_tnep_poller_svc_deselect should be used to it.

Param param

[in] Pointer to the selected service parameters.

Param msg

[in] Pointer to TNEP Poller Message structure contains status and received additional NDEF data.

Param timeout

[in] Indicates that TNEP Tag Device does not prepare NDEF Message within time.

void (*svc_deselected)(void)

Function called when current active TNEP Service was deselected.

void (*svc_received)(const struct nfc_ndef_tnep_rec_svc_param *param, const struct nfc_tnep_poller_msg *msg, bool timeout)

Function called when TNEP Service was read.

Note

Service should be deselected in case of received timeout. The nfc_tnep_poller_svc_deselect should be used to it.

Param param

[in] Pointer to the selected service parameters.

Param msg

[in] Pointer to TNEP Poller Message structure contains status and received additional NDEF data.

Param timeout

[in] Indicates that TNEP Tag Device does not prepare NDEF Message within time.

void (*svc_sent)(const struct nfc_ndef_tnep_rec_svc_param *param, const struct nfc_tnep_poller_msg *rsp_msg, bool timeout)

Function called when TNEP Service was written.

Note

Service should be deselected in case of received timeout. The nfc_tnep_poller_svc_deselect should be used to it.

Param param

[in] Pointer to the selected service parameters.

Param rsp_msg

[in] Pointer to TNEP Poller Message structure contains status and received response with additional NDEF data.

Param timeout

[in] Indicates that TNEP Tag Device does not prepare NDEF Message within time.

void (*error)(int err)

Function called when an internal error in TNEP Poller library was detected.

Param err

[in] Detected error code.

struct nfc_tnep_buf
#include <poller.h>

TNEP Poller buffer structure.

Public Members

uint8_t *data

Pointer to data.

size_t size

Buffer size.