NXP NFC Reader Library v4.040.05.011646

Modules | Macros | Functions
Tag Operation Layer
Application Layer

This Component implements tag operations for different NFC Tag types T1T, T2T, T3T,T4T and T5T. More...

Collaboration diagram for Tag Operation Layer:

## Modules
| Component : Software

## Macros
#define | PHAL_TOP_T1T_TAG_MEMORY_TYPE_STATIC 0x00U
| Static memory type.
#define | PHAL_TOP_T1T_TAG_MEMORY_TYPE_DYNAMIC 0x01U
| Dynamic memory type.
#define | PHAL_TOP_T2T_TAG_MEMORY_TYPE_STATIC 0x00U
| Static memory type.
#define | PHAL_TOP_T2T_TAG_MEMORY_TYPE_DYNAMIC 0x01U
| Dynamic memory type.

## Functions
phStatus_t | phalTop_FormatNdef (void *pDataParams)
| Format a new non-NDEF tag as NDEF tag. More...
phStatus_t | phalTop_ReadNdef (void *pDataParams, uint8_t *pData, uint16_t *pLength)
| Read NDEF message from Tag. More...
phStatus_t | phalTop_WriteNdef (void *pDataParams, uint8_t *pData, uint16_t wLength)
| Write NDEF message into Tag. More...
phStatus_t | phalTop_CheckNdef (void *pDataParams, uint8_t *pTagState)
| Does the NDEF detection procedure as per NFC Tag Operation specifications for each tag type. More...
phStatus_t | phalTop_Reset (void *pDataParams)
| Reset Tag Operation parameters. More...
phStatus_t | phalTop_EraseNdef (void *pDataParams)
| Erase a valid NDEF message with an empty NDEF. More...
phStatus_t | phalTop_SetConfig (void *pDataParams, uint16_t wConfig, uint16_t wValue)
| Set configuration parameter. More...
phStatus_t | phalTop_GetConfig (void *pDataParams, uint16_t wConfig, uint16_t *pValue)
| Get configuration parameter. More...

## Tag types
Tag types are used to set Tag used using phalTop_SetConfig with PHAL_TOP_CONFIG_TAG_TYPE Type
#define | PHAL_TOP_TAG_TYPE_T1T_TAG 0x01U
| Type 1 Tag. More...
#define | PHAL_TOP_TAG_TYPE_T2T_TAG 0x02U
| Type 2 Tag. More...
#define | PHAL_TOP_TAG_TYPE_T3T_TAG 0x03U
| Type 3 Tag. More...
#define | PHAL_TOP_TAG_TYPE_T4T_TAG 0x04U
| Type 4 Tag. More...
#define | PHAL_TOP_TAG_TYPE_T5T_TAG 0x05U
| Type 5 Tag. More...

## Configuration types
Use these Macro in phalTop_SetConfig to configure Tags.
#define | PHAL_TOP_CONFIG_TAG_TYPE 0x51U
| Set/Get Tag type. More...
#define | PHAL_TOP_CONFIG_TAG_STATE 0x52U
| Get tag state. More...
#define | PHAL_TOP_CONFIG_NDEF_LENGTH 0x53U
| Get current NDEF message Length. More...
#define | PHAL_TOP_CONFIG_MAX_NDEF_LENGTH 0x54U
| Get Max support NDEF Length by tag. More...
#define | PHAL_TOP_CONFIG_NDEF_VERSION 0x55U
| Get NDEF Version Number. More...
#define | PHAL_TOP_CONFIG_T1T_TMS 0x03U
| Set tag memory size. More...
#define | PHAL_TOP_CONFIG_T1T_TERMINATOR_TLV 0x05U
| Set Terminator TLV presence. More...
#define | PHAL_TOP_CONFIG_T2T_TMS 0x09U
| Set tag memory size. More...
#define | PHAL_TOP_CONFIG_T4T_NDEF_FILE_ID 0x15U
| Set NDEF file ID. More...
#define | PHAL_TOP_CONFIG_T4T_NDEF_FILE_SIZE 0x18U
| Set Max NDEF length. More...
#define | PHAL_TOP_CONFIG_T4T_MLE 0x19U
| Set MLe. More...
#define | PHAL_TOP_CONFIG_T4T_MLC 0x1AU
| Set MLc. More...
#define | PHAL_TOP_CONFIG_T5T_MLEN 0x1DU
| Set T5T NDEF data area. More...
#define | PHAL_TOP_CONFIG_T5T_MBREAD 0x20U
| Set T5T multiple block read support. More...
#define | PHAL_TOP_CONFIG_T5T_LOCKBLOCK 0x21U
| Set T5T Lock block command support. More...
#define | PHAL_TOP_CONFIG_T5T_SPL_FRM 0x22U
| Set T5T special frame support. More...
#define | PHAL_TOP_CONFIG_T5T_OPTION_FLAG 0x26U
| Set T5T option Flag. More...
#define | PHAL_TOP_CONFIG_T5T_TERMINATOR_TLV 0x1FU
| Set Terminator TLV presence. More...

## Tag States
#define | PHAL_TOP_STATE_NONE 0x00U
| Default initial state. More...
#define | PHAL_TOP_STATE_INITIALIZED 0x01U
| Initialized state. More...
#define | PHAL_TOP_STATE_READONLY 0x02U
| Read Only state. More...
#define | PHAL_TOP_STATE_READWRITE 0x04U
| Read/Write state. More...

## Detailed Description

This Component implements tag operations for different NFC Tag types T1T, T2T, T3T,T4T and T5T.

To perform any operation like Read, Write, Lock, format and erase operation on the tag. The Tag should be activated first as shown in the below block diagram. Any Read/Write operation is possible on the Tag only if the tag is NDEF format. Refer NFC Forum Tag operation Specifications.

## Macro Definition Documentation

## § PHAL_TOP_TAG_TYPE_T1T_TAG

#define PHAL_TOP_TAG_TYPE_T1T_TAG 0x01U

Type 1 Tag.

## § PHAL_TOP_TAG_TYPE_T2T_TAG

#define PHAL_TOP_TAG_TYPE_T2T_TAG 0x02U

Type 2 Tag.

## § PHAL_TOP_TAG_TYPE_T3T_TAG

#define PHAL_TOP_TAG_TYPE_T3T_TAG 0x03U

Type 3 Tag.

## § PHAL_TOP_TAG_TYPE_T4T_TAG

#define PHAL_TOP_TAG_TYPE_T4T_TAG 0x04U

Type 4 Tag.

## § PHAL_TOP_TAG_TYPE_T5T_TAG

#define PHAL_TOP_TAG_TYPE_T5T_TAG 0x05U

Type 5 Tag.

## § PHAL_TOP_CONFIG_TAG_TYPE

#define PHAL_TOP_CONFIG_TAG_TYPE 0x51U

Set/Get Tag type.

Should be configured before calling CheckNdef.

## § PHAL_TOP_CONFIG_TAG_STATE

#define PHAL_TOP_CONFIG_TAG_STATE 0x52U

Get tag state.

This shall be also used to set tag to read-only state.

## § PHAL_TOP_CONFIG_NDEF_LENGTH

#define PHAL_TOP_CONFIG_NDEF_LENGTH 0x53U

Get current NDEF message Length.

## § PHAL_TOP_CONFIG_MAX_NDEF_LENGTH

#define PHAL_TOP_CONFIG_MAX_NDEF_LENGTH 0x54U

Get Max support NDEF Length by tag.

## § PHAL_TOP_CONFIG_NDEF_VERSION

#define PHAL_TOP_CONFIG_NDEF_VERSION 0x55U

Get NDEF Version Number.

## § PHAL_TOP_CONFIG_T1T_TMS

#define PHAL_TOP_CONFIG_T1T_TMS 0x03U

Set tag memory size.

Set before format operation.

## § PHAL_TOP_CONFIG_T1T_TERMINATOR_TLV

#define PHAL_TOP_CONFIG_T1T_TERMINATOR_TLV 0x05U

Set Terminator TLV presence.

Set before format/write operation to enable writing terminator TLV at end of NDEF TLV.

## § PHAL_TOP_CONFIG_T2T_TMS

#define PHAL_TOP_CONFIG_T2T_TMS 0x09U

Set tag memory size.

Set before format operation.

## § PHAL_TOP_CONFIG_T4T_NDEF_FILE_ID

#define PHAL_TOP_CONFIG_T4T_NDEF_FILE_ID 0x15U

Set NDEF file ID.

Set before format operation.

## § PHAL_TOP_CONFIG_T4T_NDEF_FILE_SIZE

#define PHAL_TOP_CONFIG_T4T_NDEF_FILE_SIZE 0x18U

Set Max NDEF length.

Set before format operation.

## § PHAL_TOP_CONFIG_T4T_MLE

#define PHAL_TOP_CONFIG_T4T_MLE 0x19U

Set MLe.

Set before format operation.

## § PHAL_TOP_CONFIG_T4T_MLC

#define PHAL_TOP_CONFIG_T4T_MLC 0x1AU

Set MLc.

Set before format operation.

## § PHAL_TOP_CONFIG_T5T_MLEN

#define PHAL_TOP_CONFIG_T5T_MLEN 0x1DU

Set T5T NDEF data area.

Set before format operation.

## § PHAL_TOP_CONFIG_T5T_MBREAD

#define PHAL_TOP_CONFIG_T5T_MBREAD 0x20U

Set T5T multiple block read support.

Set before format operation.

## § PHAL_TOP_CONFIG_T5T_LOCKBLOCK

#define PHAL_TOP_CONFIG_T5T_LOCKBLOCK 0x21U

Set T5T Lock block command support.

Set before format operation.

## § PHAL_TOP_CONFIG_T5T_SPL_FRM

#define PHAL_TOP_CONFIG_T5T_SPL_FRM 0x22U

Set T5T special frame support.

Set before format operation.

## § PHAL_TOP_CONFIG_T5T_OPTION_FLAG

#define PHAL_TOP_CONFIG_T5T_OPTION_FLAG 0x26U

Set T5T option Flag.

Set before format operation.

## § PHAL_TOP_CONFIG_T5T_TERMINATOR_TLV

#define PHAL_TOP_CONFIG_T5T_TERMINATOR_TLV 0x1FU

Set Terminator TLV presence.

Set before format/write operation to enable writing terminator TLV at end of NDEF TLV.

## § PHAL_TOP_STATE_NONE

#define PHAL_TOP_STATE_NONE 0x00U

Default initial state.

## § PHAL_TOP_STATE_INITIALIZED

#define PHAL_TOP_STATE_INITIALIZED 0x01U

Initialized state.

## § PHAL_TOP_STATE_READONLY

#define PHAL_TOP_STATE_READONLY 0x02U

Read Only state.

## § PHAL_TOP_STATE_READWRITE

#define PHAL_TOP_STATE_READWRITE 0x04U

Read/Write state.

## Function Documentation

## § phalTop_FormatNdef()

phStatus_t phalTop_FormatNdef | ( | void * | pDataParams | ) |

Format a new non-NDEF tag as NDEF tag.

FormatNdef shall be used for formatting a non-NDEF tag as NDEF tag if needed when CheckNdef returns error. Before formatting, tag parameters like max. NDEF size etc., shall be specified by the application. If not specified tag will be formatted with default values. FormatNdef shall be called only once for a tag. Once formatted, tag will become a NDEF tag. To remove NDEF format if needed, application needs to over write / delete NDEF format using tag specific read/write commands.

This is only a utility function not specified by NFC Forum. Please note that for T4T, this will attempt to use MIFARE DESFire proprietary commands to format the tag. If T4T is not MIFARE DESFire tag then format will not succeed.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PHAL_TOP_ERR_UNSUPPORTED_TAG | Tag does not support NDEF formatting.
  PHAL_TOP_ERR_FORMATTED_TAG | Tag is already NDEF formatted.
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.

## § phalTop_ReadNdef()

phStatus_t phalTop_ReadNdef | ( | void * | pDataParams,
|  | uint8_t * | pData,
|  | uint16_t * | pLength
| ) |  |

Read NDEF message from Tag.

ReadNdef shall only be called after CheckNdef returned success. If it is an empty NDEF message(i.e. initialized state) then this will return empty NDEF error.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PHAL_TOP_ERR_INVALID_STATE | Tag is not is any valid state (i.e. when check NDEF failed or has not been called before.)
  PHAL_TOP_ERR_EMPTY_NDEF | Tag is in initialized state (i.e. no NDEF / empty NDEF)
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.
  [out] | pData | NDEF data from the Tag. User has to allocate memory accordingly
  [out] | pLength | NDEF data length.

## § phalTop_WriteNdef()

phStatus_t phalTop_WriteNdef | ( | void * | pDataParams,
|  | uint8_t * | pData,
|  | uint16_t | wLength
| ) |  |

Write NDEF message into Tag.

WriteNdef shall be used to write a new NDEF message to tag if check NDEF returned success. If tag is in read only state, write NDEF will return error. The tag is expected to be a formatted NDEF tag for this to succeed.

WriteNDEF will update the NDEF message TLV or the capability container with the length of the data written to the tag.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PH_ERR_INVALID_PARAMETER | wLength is 0 or wLength is more than supported max length.
  PHAL_TOP_ERR_INVALID_STATE | Tag is not is any valid state (i.e. when check NDEF failed).
  PHAL_TOP_ERR_READONLY_TAG | Tag is in read only state.
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.
  [in] | pData | NDEF data to be written to tag. User has to allocate memory accordingly
  [in] | wLength | Length of NDEF data to be written.

## § phalTop_CheckNdef()

phStatus_t phalTop_CheckNdef | ( | void * | pDataParams,
|  | uint8_t * | pTagState
| ) |  |

Does the NDEF detection procedure as per NFC Tag Operation specifications for each tag type.

The caller has to ensure that Tag activation is done before calling this API. Also phalTop_SetConfig should be called before to configure the Tag type PHAL_TOP_CONFIG_TAG_TYPE. Only after phalTop_CheckNdef is called any other NDEF operation on Tag can be performed.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PHAL_TOP_ERR_NON_NDEF_TAG | Tag don�t indicate NDEF presence
  PHAL_TOP_ERR_UNSUPPORTED_VERSION | Tag indicates NDEF presence but NDEF version mentioned in tag is not supported by reader library.
  PHAL_TOP_ERR_MISCONFIGURED_TAG | Tag indicates NDEF presence but the NDEF CC or NDEF attribute information is wrongly configured
  PHAL_TOP_ERR_UNSUPPORTED_TAG | Tag uses some proprietary or RFU or unsupported configuration
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.
  [out] | pTagState | State of tag

## § phalTop_Reset()

phStatus_t phalTop_Reset | ( | void * | pDataParams | ) |

Reset Tag Operation parameters.

User has to call phalTop_Reset to reset all the Software parameters. This shall be called after performing all NDEF operations if needed.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.

## § phalTop_EraseNdef()

phStatus_t phalTop_EraseNdef | ( | void * | pDataParams | ) |

Erase a valid NDEF message with an empty NDEF.

EraseNdef shall be used to erase a valid NDEF message by writing an empty NDEF (i.e. NDEF length as 0) to tag. This will change the tag from read/write state to initialized state. If tag is already in initialized state this API will return error.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PHAL_TOP_ERR_INVALID_STATE | Tag is not is any valid state (i.e. when check NDEF failed)
  PHAL_TOP_ERR_READONLY_TAG | Tag is in read only state.
  PHAL_TOP_ERR_EMPTY_NDEF | Tag is in initialized state (i.e. no NDEF / empty NDEF)
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.

## § phalTop_SetConfig()

phStatus_t phalTop_SetConfig | ( | void * | pDataParams,
|  | uint16_t | wConfig,
|  | uint16_t | wValue
| ) |  |

Set configuration parameter.

Refer to PHAL_TOP_CONFIG_TAG_TYPE from where the configurable parameters are listed.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PH_ERR_INVALID_PARAMETER | Parameter value is invalid.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.
  [in] | wConfig | Configuration Identifier.
  [in] | wValue | Configuration Value.

## § phalTop_GetConfig()

phStatus_t phalTop_GetConfig | ( | void * | pDataParams,
|  | uint16_t | wConfig,
|  | uint16_t * | pValue
| ) |  |

Get configuration parameter.

After calling phalTop_CheckNdef, phalTop_WriteNdef, phalTop_ReadNdef or phalTop_EraseNdef, user can call phalTop_GetConfig to get different parameters.

Refer to PHAL_TOP_CONFIG_TAG_TYPE from where the configurable parameters are listed.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PH_ERR_INVALID_PARAMETER | Parameter value is invalid.

Parameters

  [in] | pDataParams | Pointer to this layer's parameter structure.
  [in] | wConfig | Configuration Identifier.
  [out] | pValue | Configuration Value.