ntag.h File Reference

NTAG driver for reading and writing data (interface) More...

#include <jendefs.h>

Go to the source code of this file.

Typedefs
typedef void(*	tprNtagCbEvent) (teNtagEvent eNtagEvent, uint32 u32Address, uint32 u32Length, uint8 *pu8Data)

Enumerations
enum	teNtagEvent {   E_NTAG_EVENT_ABSENT, E_NTAG_EVENT_PRESENT, E_NTAG_EVENT_READ_FAIL, E_NTAG_EVENT_READ_OK,   E_NTAG_EVENT_WRITE_FAIL, E_NTAG_EVENT_WRITE_OK, E_NTAG_EVENT_READ_REG_FAIL, E_NTAG_EVENT_READ_REG_OK,   E_NTAG_EVENT_WRITE_REG_FAIL, E_NTAG_EVENT_WRITE_REG_OK }

Functions
PUBLIC void	NTAG_vInitialise (uint8 u8Address, bool_t bLocation, uint32 u32FrequencyHz, uint8 u8InputFd)
	Initialises NTAG data and hardware. More...
PUBLIC void	NTAG_vRegCbEvent (tprNtagCbEvent prRegCbEvent)
	Registers callback for NTAG events. More...
PUBLIC void	NTAG_vTick (uint32 u32TickMs)
	Timer function to drive NTAG processing. More...
PUBLIC bool_t	NTAG_bRead (uint32 u32ReadAddress, uint32 u32ReadLength, uint8 *pu8ReadData)
	Requests read of NTAG data. More...
PUBLIC bool_t	NTAG_bReadVersion (uint32 u32ReadLength, uint8 *pu8ReadData)
	Requests read of NTAG version data. More...
PUBLIC bool_t	NTAG_bWrite (uint32 u32WriteAddress, uint32 u32WriteLength, uint8 *pu8WriteData)
	Requests write of NTAG data. More...
PUBLIC bool_t	NTAG_bReadReg (uint32 u32ReadAddress, uint32 u32ReadLength, uint8 *pu8ReadData)
	Requests read of NTAG register data. More...
PUBLIC bool_t	NTAG_bWriteReg (uint32 u32WriteAddress, uint32 u32WriteLength, uint8 *pu8WriteData)
	Requests write of NTAG register data. More...
PUBLIC uint32	NTAG_u32Ntag (void)
	Returns the NTAG model. More...
PUBLIC uint32	NTAG_u32Config (void)
	Returns the byte address of the NTAG's configuration registers. More...
PUBLIC uint32	NTAG_u32Session (void)
	Returns the byte address of the NTAG's session registers. More...
PUBLIC uint32	NTAG_u32Sram (void)
	Returns the byte address of the NTAG's SRAM. More...
PUBLIC uint8 *	NTAG_pu8Header (void)
	Returns the 16 header bytes of the NTAG's memory. More...
PUBLIC uint8 *	NTAG_pu8Version (void)
	Returns the 8 version information bytes for the NTAG. More...

Detailed Description

NTAG driver for reading and writing data (interface)

ntag.h contains low level APIs for reading and writing raw data to the NTAG.

The typical set up sequence is as follows:

• NTAG_vInitialise() is called to initialise the hardware.
• NTAG_vRegCbEvent() is called to register the event callback function in the application the library should call to inform the application of NTAG events. APP_NtagCbEvent() is used in these examples.
• NTAG_vTick() should be called regularly (recommended every 5ms) to provide processing time to the library.
• APP_NtagCbEvent() will be called by the library to pass events to the application layer. The E_NTAG_EVENT_ABSENT and E_NTAG_EVENT_PRESENT events will be raised when the NTAG is removed from and placed into an NFC reader's field.

A typical sequence to read data is shown below. It is recommended that data is read when the NTAG is removed from a field (as the data in the NTAG may have been altered whilst in the field) in response to the E_NTAG_EVENT_ABSENT event. When the callback function is registered at initialisation the E_NTAG_EVENT_ABSENT will be raised if the NTAG is not in field thus triggering a read of data that may have been changed while the device was powered down.

• NTAG_vTick() is called by the application
• APP_NtagCbEvent(E_NTAG_EVENT_ABSENT) is called in the application
• NTAG_bRead() is called by the application, the byte address and length of data to be read from the NTAG is provided along with a buffer to store the read data in. This call will return TRUE if the request is accepted.
• NTAG_vTick() continues to be called regularly by the application.
• APP_NtagCbEvent(E_NTAG_EVENT_READ_OK) is called in the application if the read is successful. The data read from the NTAG will be in the buffer provided by the call to NTAG_bRead(), this data pointer is also provided as a parameter to APP_NtagCbEvent()
• APP_NtagCbEvent(E_NTAG_EVENT_READ_FAIL) is called in the application if the read is unsuccessful.

A typical sequence to write data is shown below. It is recommended that data is written when the NTAG is not in a field (as a reader may be writing whilst in the field). Data may also be written following a successful read as shown below:

• NTAG_vTick() is called by the application
• APP_NtagCbEvent(E_NTAG_EVENT_READ_OK) is called in the application following a successful read.
• NTAG_bWrite() is called by the application, the byte address and length of data to be written to the NTAG is provided along with a buffer containing the data to be written. This call will return TRUE if the request is accepted.
• NTAG_vTick() continues to be called regularly by the application.
• APP_NtagCbEvent(E_NTAG_EVENT_WRITE_OK) is called in the application if the write is successful.
• APP_NtagCbEvent(E_NTAG_EVENT_WRITE_FAIL) is called in the application if the write is unsuccessful.

The message sequence chart below shows a sequence of function calls for initialisation, a data read and a data write:

Typedef Documentation

tprNtagCbEvent

typedef void(* tprNtagCbEvent) ( teNtagEvent eNtagEvent, uint32 u32Address, uint32 u32Length, uint8 *pu8Data)

NTAG Event Callback function

Enumeration Type Documentation

teNtagEvent

enum teNtagEvent

NTAG Events - Passed to application by library calling the registerd callback function

Enumerator
E_NTAG_EVENT_ABSENT	Tag has been removed from reader
E_NTAG_EVENT_PRESENT	Tag has been presented to reader
E_NTAG_EVENT_READ_FAIL	Read request failed
E_NTAG_EVENT_READ_OK	Read request succeeded
E_NTAG_EVENT_WRITE_FAIL	Write request failed
E_NTAG_EVENT_WRITE_OK	Write request succeeded
E_NTAG_EVENT_READ_REG_FAIL	Read register request failed
E_NTAG_EVENT_READ_REG_OK	Read register request succeeded
E_NTAG_EVENT_WRITE_REG_FAIL	Write register request failed
E_NTAG_EVENT_WRITE_REG_OK	Write register request succeeded

Function Documentation

NTAG_vInitialise()

PUBLIC void NTAG_vInitialise	(	uint8	u8Address,
		bool_t	bLocation,
		uint32	u32FrequencyHz,
		uint8	u8InputFd
	)

Initialises NTAG data and hardware.

Parameters

u8Address	Reader I2C address (0xFF for automatic detection)
bLocation	Use alternative I2C pins
u32FrequencyHz	Frequency in Hz
u8InputFd	Input DIO for field detect

NTAG_vRegCbEvent()

PUBLIC void NTAG_vRegCbEvent

(

tprNtagCbEvent

prRegCbEvent

)

Registers callback for NTAG events.

Parameters

prRegCbEvent

Pointer to event callback function

NTAG_vTick()

PUBLIC void NTAG_vTick

(

uint32

u32TickMs

)

Timer function to drive NTAG processing.

Should be called regularly, every 5ms is recommended.

Parameters

u32TickMs

Number of ms since previous call

NTAG_bRead()

PUBLIC bool_t NTAG_bRead	(	uint32	u32ReadAddress,
		uint32	u32ReadLength,
		uint8 *	pu8ReadData
	)

Requests read of NTAG data.

If the request is successful the final outcome of the read request is indicated by a call to the NTAG event callback function, along with the data if successful.

Return values

TRUE	Request accepted
FALSE	Request failed

Parameters

u32ReadAddress	Byte address of data to read
u32ReadLength	Number of bytes to read
pu8ReadData	Buffer to read data into

NTAG_bReadVersion()

PUBLIC bool_t NTAG_bReadVersion	(	uint32	u32ReadLength,
		uint8 *	pu8ReadData
	)

Requests read of NTAG version data.

If the request is successful the final outcome of the read request is indicated by a call to the NTAG event callback function, along with the data if successful.

The version information is always 8 bytes in size the buffer and length needs to be set appropriately.

Return values

TRUE	Request accepted
FALSE	Request failed

Parameters

u32ReadLength	Number of bytes to read (minimum 8)
pu8ReadData	Buffer to read data into

NTAG_bWrite()

PUBLIC bool_t NTAG_bWrite	(	uint32	u32WriteAddress,
		uint32	u32WriteLength,
		uint8 *	pu8WriteData
	)

Requests write of NTAG data.

If the request is successful the final outcome of the write request is indicated by a call to the NTAG event callback function, along with the data if successful.

Return values

TRUE	Request accepted
FALSE	Request failed

Parameters

u32WriteAddress	Byte address of write
u32WriteLength	Number of bytes to write
pu8WriteData	Buffer to write data from

NTAG_bReadReg()

PUBLIC bool_t NTAG_bReadReg	(	uint32	u32ReadAddress,
		uint32	u32ReadLength,
		uint8 *	pu8ReadData
	)

Requests read of NTAG register data.

If the request is successful the final outcome of the read request is indicated by a call to the NTAG event callback function, along with the data if successful.

The register data is always 1 byte, the data length and buffer need to be sized appropriately.

Return values

TRUE	Request accepted
FALSE	Request failed

NTAG_bWriteReg()

PUBLIC bool_t NTAG_bWriteReg	(	uint32	u32WriteAddress,
		uint32	u32WriteLength,
		uint8 *	pu8WriteData
	)

Requests write of NTAG register data.

If the request is successful the final outcome of the write request is indicated by a call to the NTAG event callback function, along with the data if successful.

The register data is always 2 bytes, the data length and buffer need to be sized appropriately. The first byte specifies a mask of bits to be written to the register, the second byte specifies the values to set the bits specified by the mask.

Return values

TRUE	Request accepted
FALSE	Request failed

Parameters

u32WriteAddress	Byte address of write
u32WriteLength	Number of bytes to write
pu8WriteData	Buffer to write data from: [0] = RegMask, [1] = RegValue

NTAG_u32Ntag()

PUBLIC uint32 NTAG_u32Ntag

(

void

)

Returns the NTAG model.

The NTAG_bReadVersion() function must have been called previously in order to detect the NTAG model.

Return values

NFC_NTAG_UNKNOWN	Unknown NTAG model
NFC_NTAG_NT3H1101	NT3H1101 NTAG model
NFC_NTAG_NT3H1201	NT3H1201 NTAG model
NFC_NTAG_NT3H2111	NT3H2111 NTAG model
NFC_NTAG_NT3H2211	NT3H2211 NTAG model

NTAG_u32Config()

PUBLIC uint32 NTAG_u32Config

(

void

)

Returns the byte address of the NTAG's configuration registers.

The NTAG_bReadVersion() function must have been called previously in order to determine the address.

Returns

Byte address of configuration registers

NTAG_u32Session()

PUBLIC uint32 NTAG_u32Session

(

void

)

Returns the byte address of the NTAG's session registers.

The NTAG_bReadVersion() function must have been called previously in order to determine the address.

Returns

Byte address of session registers

NTAG_u32Sram()

PUBLIC uint32 NTAG_u32Sram

(

void

)

Returns the byte address of the NTAG's SRAM.

The NTAG_bReadVersion() function must have been called previously in order to determine the address.

Returns

Byte address of SRAM

NTAG_pu8Header()

PUBLIC uint8* NTAG_pu8Header

(

void

)

Returns the 16 header bytes of the NTAG's memory.

The NTAG_bRead() function must have been called previously with a read of these first 16 bytes from address 0.

Returns

Pointer to header data

NTAG_pu8Version()

PUBLIC uint8* NTAG_pu8Version

(

void

)

Returns the 8 version information bytes for the NTAG.

The NTAG_bReadVersion() function must have been called previously.

Returns

Pointer to version data