NXP NFC Reader Library  v4.040.05.011646
Tag Operation 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.

TOP_BlockDiagram.png

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_SUCCESSOperation successful.
PHAL_TOP_ERR_UNSUPPORTED_TAGTag does not support NDEF formatting.
PHAL_TOP_ERR_FORMATTED_TAGTag is already NDEF formatted.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParamsPointer 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_SUCCESSOperation successful.
PHAL_TOP_ERR_INVALID_STATETag is not is any valid state (i.e. when check NDEF failed or has not been called before.)
PHAL_TOP_ERR_EMPTY_NDEFTag is in initialized state (i.e. no NDEF / empty NDEF)
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParamsPointer to this layer's parameter structure.
[out]pDataNDEF data from the Tag. User has to allocate memory accordingly
[out]pLengthNDEF 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_SUCCESSOperation successful.
PH_ERR_INVALID_PARAMETERwLength is 0 or wLength is more than supported max length.
PHAL_TOP_ERR_INVALID_STATETag is not is any valid state (i.e. when check NDEF failed).
PHAL_TOP_ERR_READONLY_TAGTag is in read only state.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParamsPointer to this layer's parameter structure.
[in]pDataNDEF data to be written to tag. User has to allocate memory accordingly
[in]wLengthLength 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_SUCCESSOperation successful.
PHAL_TOP_ERR_NON_NDEF_TAGTag don�t indicate NDEF presence
PHAL_TOP_ERR_UNSUPPORTED_VERSIONTag indicates NDEF presence but NDEF version mentioned in tag is not supported by reader library.
PHAL_TOP_ERR_MISCONFIGURED_TAGTag indicates NDEF presence but the NDEF CC or NDEF attribute information is wrongly configured
PHAL_TOP_ERR_UNSUPPORTED_TAGTag uses some proprietary or RFU or unsupported configuration
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParamsPointer to this layer's parameter structure.
[out]pTagStateState 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_SUCCESSOperation successful.
Parameters
[in]pDataParamsPointer 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_SUCCESSOperation successful.
PHAL_TOP_ERR_INVALID_STATETag is not is any valid state (i.e. when check NDEF failed)
PHAL_TOP_ERR_READONLY_TAGTag is in read only state.
PHAL_TOP_ERR_EMPTY_NDEFTag is in initialized state (i.e. no NDEF / empty NDEF)
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParamsPointer 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_SUCCESSOperation successful.
PH_ERR_INVALID_PARAMETERParameter value is invalid.
Parameters
[in]pDataParamsPointer to this layer's parameter structure.
[in]wConfigConfiguration Identifier.
[in]wValueConfiguration 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_SUCCESSOperation successful.
PH_ERR_INVALID_PARAMETERParameter value is invalid.
Parameters
[in]pDataParamsPointer to this layer's parameter structure.
[in]wConfigConfiguration Identifier.
[out]pValueConfiguration Value.