NFC ZigBee 3.0 Modules and Libraries: ntag.h File Reference

NFC ZigBee 3.0

NFC ZigBee 3.0 Modules and Libraries
NFC Commissioning using ZigBee Installation Codes
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:

msc_inline_mscgraph_3

Typedef Documentation

◆ tprNtagCbEvent

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

NTAG Event Callback function

Enumeration Type Documentation

◆ 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
u8AddressReader I2C address (0xFF for automatic detection)
bLocationUse alternative I2C pins
u32FrequencyHzFrequency in Hz
u8InputFdInput DIO for field detect

◆ NTAG_vRegCbEvent()

PUBLIC void NTAG_vRegCbEvent ( tprNtagCbEvent  prRegCbEvent)

Registers callback for NTAG events.

Parameters
prRegCbEventPointer 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
u32TickMsNumber 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
TRUERequest accepted
FALSERequest failed
Parameters
u32ReadAddressByte address of data to read
u32ReadLengthNumber of bytes to read
pu8ReadDataBuffer 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
TRUERequest accepted
FALSERequest failed
Parameters
u32ReadLengthNumber of bytes to read (minimum 8)
pu8ReadDataBuffer 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
TRUERequest accepted
FALSERequest failed
Parameters
u32WriteAddressByte address of write
u32WriteLengthNumber of bytes to write
pu8WriteDataBuffer 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
TRUERequest accepted
FALSERequest 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
TRUERequest accepted
FALSERequest failed
Parameters
u32WriteAddressByte address of write
u32WriteLengthNumber of bytes to write
pu8WriteDataBuffer 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_UNKNOWNUnknown NTAG model
NFC_NTAG_NT3H1101NT3H1101 NTAG model
NFC_NTAG_NT3H1201NT3H1201 NTAG model
NFC_NTAG_NT3H2111NT3H2111 NTAG model
NFC_NTAG_NT3H2211NT3H2211 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
Generated by   doxygen 1.8.13