nci_nwk.h File Reference

NCI Network NDEF reading and writing (interface) More...

#include <jendefs.h> #include "nfc_nwk.h"

Go to the source code of this file.

Enumerations
enum	teNciNwkStatus {   E_NCI_NWK_IDLE, E_NCI_NWK_READING, E_NCI_NWK_READ_FAIL, E_NCI_NWK_READ_OK,   E_NCI_NWK_WRITING, E_NCI_NWK_WRITE_FAIL, E_NCI_NWK_WRITE_OK }

Functions
PUBLIC teNciNwkStatus	NCI_NWK_eRead (uint32 *pu32ReadAddress, tsNfcNwkPayload *psNfcNwkPayloadStart)
	Requests read of NWK NDEF data from an NTAG in the reader's field. More...
PUBLIC teNciNwkStatus	NCI_NWK_eWrite (uint32 *pu32WriteAddress, tsNfcNwkPayload *psNfcNwkPayloadStart)
	Requests write of NWK NDEF data to an NTAG in the reader's field. More...
PUBLIC teNciNwkStatus	NCI_NWK_eStop (void)
	Stops processing of NCI NWK NDEF data. More...
PUBLIC teNciNwkStatus	NCI_NWK_eStatus (void)
	Returns the status of the NCI NWK NDEF processing. More...
PUBLIC teNciNwkStatus	NCI_NWK_eTick (uint32 u32TickMs)
	Timer function to drive NCI NWK NDEF processing. More...

Detailed Description

NCI Network NDEF reading and writing (interface)

nci_nwk.h contains high level APIs for reading and writing a network NDEF to the NTAGs placed in the reader's field which is suitable for use in commissioning devices into IEEE 802.15.4 based networks.

The typical set up sequence is the same for the data APIs (described in nci.h).

A typical sequence to read data is shown below. Data must be read when the NTAG is placed into the field usually in response to the E_NCI_EVENT_PRESENT event.

• NCI_vTick() is called by the application
• APP_NciCbEvent(E_NCI_EVENT_PRESENT) is called in the application when an NTAG is placed into the field.
• NCI_NWK_eRead() is called by the application, handing control of the low-level data APIs over to the NDEF data module. A pointer to be filled in with the address of the read and a pointer to store the NDEF payload is provided. This function call will return E_NCI_NWK_READING if the request is successful.
• NCI_NWK_eTick() should then be called regularly by the application (replacing the calls to NCI_vTick()).
• If NCI_NWK_eTick() returns E_NCI_NWK_READ_OK the read was successful. The NDEF payload and the address of the read will have been placed into the pointers provided in the NCI_NWK_eRead() call.
• If NCI_NWK_eTick() returns E_NCI_NWK_READ_FAIL the read was unsuccessful.
• If the interaction with the NDEF data is finished NCI_NWK_eStop() should be called followed by a call to NCI_vRegCbEvent() to reclaim the NCI event callback, followed by regular calls to NCI_vTick(). NCI_NWK_eStop() includes a call to NCI_bEnd().

A typical sequence to write the NDEF payload data is shown below. Data must be written when the NTAG is in the field. Data may be written following a successful read as shown below:

• NCI_NWK_eTick() returns E_NCI_NWK_READ_OK indicating a successful read.
• The NDEF payload contents are updated for writing.
• NCI_NWK_eWrite() is called by the application, handing control of the low-level data APIs over to the NDEF data module. A pointer with the address of the write and a pointer to NDEF payload data to be written is provided. This function call will return E_NCI_NWK_WRITING if the request is successful.
• NCI_NWK_eTick() should then be called regularly by the application (continuing to replace the calls to NCI_vTick()).
• If NCI_NWK_eTick() returns E_NCI_NWK_WRITE_OK the write was successful.
• If NCI_NWK_eTick() returns E_NCI_NWK_WRITE_FAIL the write was unsuccessful.
• If the interaction with the NDEF data is finished NCI_NWK_eStop() should be called followed by a call to NCI_vRegCbEvent() to reclaim the NTAG event callback, followed by regular calls to NCI_vTick(). NCI_NWK_eStop() includes a call to NCI_bEnd().

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

Enumeration Type Documentation

teNciNwkStatus

enum teNciNwkStatus

NCI NWK status type

Enumerator
E_NCI_NWK_IDLE	NCI NWK processing is idle
E_NCI_NWK_READING	NCI NWK is reading data
E_NCI_NWK_READ_FAIL	NCI NWK read has failed
E_NCI_NWK_READ_OK	NCI NWK read was successful
E_NCI_NWK_WRITING	NCI NWK is writing data
E_NCI_NWK_WRITE_FAIL	NCI NWK write has failed
E_NCI_NWK_WRITE_OK	NCI NWK write was successful

Function Documentation

NCI_NWK_eRead()

PUBLIC teNciNwkStatus NCI_NWK_eRead	(	uint32 *	pu32ReadAddress,
		tsNfcNwkPayload *	psNfcNwkPayloadStart
	)

Requests read of NWK NDEF data from an NTAG in the reader's field.

If the request is successful the final outcome of the read request is returned by NCI_NWK_eTick() returning a status of E_NCI_NWK_READ_OK. The byte address the NWK NDEF was read from is placed in the pu32ReadAddress pointer and the payload data in the psNfcNwkPayloadStart pointer.

When the request is accepted the NCI event callback function, set by NCI_vRegCbEvent(), is overridden to allow the NCI NWK code to process NCI events. When the request completes NCI_NWK_eStop() should be called to end the processing and the NTAG event callback function can be reclaimed by the application.

Return values

E_NCI_NWK_READING	Request accepted
E_NCI_NWK_READ_FAIL	Request failed

Parameters

pu32ReadAddress	Pointer where byte address of NTAG NWK NDEF is placed if successful
psNfcNwkPayloadStart	Pointer where NTAG NWK NDEF payload data is placed if successful

NCI_NWK_eWrite()

PUBLIC teNciNwkStatus NCI_NWK_eWrite	(	uint32 *	pu32WriteAddress,
		tsNfcNwkPayload *	psNfcNwkPayloadStart
	)

Requests write of NWK NDEF data to an NTAG in the reader's field.

If the request is successful the final outcome of the write request is returned by NCI_NWK_eTick() returning a status of E_NCI_NWK_WRITE_OK. The byte address to write the NWK NDEF record should be in the pu32ReadAddress pointer and the payload data in the psNfcNwkPayloadStart pointer.

When the request is accepted the NCI event callback function, set by NCI_vRegCbEvent(), is overridden to allow the NCI NWK code to process NCI events. When the request completes NCI_NWK_eStop() should be called to end the processing and the NCI event callback function can be reclaimed by the application.

Return values

E_NCI_NWK_WRITING	Request accepted
E_NCI_NWK_WRITE_FAIL	Request failed

Parameters

pu32WriteAddress	Pointer to byte address to write data
psNfcNwkPayloadStart	Pointer to payload to write

NCI_NWK_eStop()

PUBLIC teNciNwkStatus NCI_NWK_eStop

(

void

)

Stops processing of NCI NWK NDEF data.

This function should be called when the processing of the NCI NWK NDEF data is complete, the NCI event callback function can be reclaimed by the application after calling NCI_NWK_eStop().

Return values

E_NCI_NWK_IDLE

NCI_NWK NDEF processing is idle

NCI_NWK_eStatus()

PUBLIC teNciNwkStatus NCI_NWK_eStatus

(

void

)

Returns the status of the NCI NWK NDEF processing.

Returns

Status of NCI NWK NDEF processing

NCI_NWK_eTick()

PUBLIC teNciNwkStatus NCI_NWK_eTick

(

uint32

u32TickMs

)

Timer function to drive NCI NWK NDEF processing.

Should be called regularly, every 5ms is recommended.

Warning

This function calls NCI_bTick() internally, there is no need to call NCI_bTick() from the application when NCI NWK NDEF processing is taking place.

Returns

Status of NCI NWK NDEF processing

Parameters

u32TickMs

Time in ms since previous call