NTAG API

NOTE:
The NTAG library is not included with the standard Cafe SDK from SDK 2.12.12.
Developers who require this library should contact your local Nintendo developer support group.
The NFP library is recommended to use instead of the NTAG library.

Introduction

The NTAG library is used for reading and writing features of the NOFT (Nintendo's proprietary tag format), an NFC feature in the GamePad.

Process Flow

NTAG Module Initialization

To initialize the GamePad's NFC module, call the NTAGInit function.

Registering Format Settings

When reading a NOFT, you must first use the NTAGSetFormatSettings function to register the company code and information about the NOFT format version being used with the library. Be careful when making these settings, because if they are set incorrectly, the company information or format version in the tag might not match when the tag is read, causing an error and resulting in failure to read or write data.

Registering the Callback for When Tags Are Detected

Register the callback to call when tags are detected with the NTAGSetTagDetectCallback function. With the callback registered with this function, you can determine when tags are detected and when a tag has been removed.

Enabling Advancement for the NFC Communication Process

To enable the NFC communication process to advance, you must call the NTAGProc function at every frame. From within this function, you can call processes for reading and writing data for tags and the various callback functions that can be registered with the API.

Specifications for Creating NFC Tags in Nintendo's Proprietary Format

To use this library for reading and writing, you must use proprietary tags (NFC Forum Type 1 Tags) based on a format prepared by Nintendo. For more information about Nintendo's proprietary-format NFC tags (NOFT), see Nintendo's Proprietary Tag Format. All of the conversions, encryption, and decryption related to the tag format are handled within the NTAG library. Applications do not need to track these things.

NFC Library Specifications

NFC Module Initialization

When using NFC features, first call the NTAGInit function to confirm that the initialization has been finalized. Initialization takes approximately one second. To check whether initialization has been finalized, use the NTAGIsInit function. If the NFC module is initialized, the GamePad's power consumption increases. When not performing NFC processes, use the NTAGShutdown function to shut down the NTAG library, and then reinitialize the NFC features again when needed.

Restricting Writing Using the UID

For the functions that read and write data for tags, it is possible to specify the uid (or the uid_mask, depending on the function) in the arguments and restrict writing and reading based on the UID. Using this feature, you can limit data writing to a tag with a specific UID. For example, to enable data to be read-only from the card with a UID of 0x01020304050607 (this UID is an example), specify the relevant UID for the uid argument and set a uid_mask of 0xFFFFFFFFFFFFFF. Also, if All 0x00 is specified for the uid_mask, the UID mask specification is disabled. When using the NTAGWrite and NTAGFormat functions, however, you must always specify the UID. (The uid_mask is internally fixed at 0xFFFFFFFFFFFFFF
to prevent writing to or formatting an incorrect tag.

Polling Tags

To read from and write to tags, you must poll the tags. With all of the functions provided in the NFC library, you can perform basic polling to find tags and the subsequent writing as a set. You can specify the polling time in the time_out argument for each function. If 0 is specified, the function continues to wait indefinitely. If you want to set a time limit, set the argument within the range of 1 through 65,535 milliseconds. Also, to stop polling partway through the process, use the NTAGAbort function.

Reading Tags

Use the NTAGRead function to read data from tags. The reading result can be received with the callback function. If function calls fail, the NTAGRead function returns a negative value. Also, if the data cannot be read because the tag data is corrupted, a value other than 0 is set in error_code for NTAGReadCallback. Be sure to perform the appropriate error handling.

Writing to Tags

Use the NTAGWrite function to write to tags. The writing result can be received with the callback function. If function calls fail, the NTAGWrite function returns a negative value. Also, if the information cannot be written, a value other than 0 is set in error_code for NTAGResultCheckCallback. If the tag is removed while writing is in progress, the writing to the tag fails and the format is corrupted. In such cases, you must use the NTAGFormat function to format the tag, and then write the data again. Note that it is not possible to write to or read from the tag if it is not reformatted.

Formatting Tags

Use the NTAGFormat function to format tags. The formatting result can be received with the callback function. If function calls fail, the NTAGFormat function returns a negative value. Also, if the formatting fails, a value other than 0 is set in error_code for NTAGResultCheckCallback.

Setting Tags to Read-Only

To prevent the unintended rewriting of tag data, the NTAGSetReadOnly function can be used to set tags to read-only. Note that this function only enables a read-only setting to be set in the software; if the read-only state is removed, it will be possible to write data again.

Ending Processes

Use the NTAGAbort function to end the process of reading and writing data for tags. By using this function, tag polling by each function can be ended. Note that if this function is called while data is being written to a tag, that process is not ended, and it is handled as if the NTAGAbort process failed. (The data is successfully written to the tag.) Be careful about the timing at which this function is called. Only the polling processes can be ended.

Cautions

Using Simultaneously With Other GamePad Features

If you plan on using the NFC features at the same time as the GamePad's camera, microphone, or similar features, contact your local Nintendo developer support group. Also contact Nintendo if there is a chance that features other than AV playback might be used at the same time as NFC features.

Special Processing During the NFC Communication Process

For system-related reasons, processing might be ended or stopped during NFC communications, so you must consider the following cases during implementation.

When Disconnecting the Wireless Connection Between the GamePad and the Wii U Console

When the wireless connection between the GamePad and the Wii U console is disconnected, the NFC module in the GamePad reverts to its default state. Accordingly, when redoing the connection, you must call the NTAGInit function again to perform initialization.

When the TV Control Button Is Pressed

If the TV control button is pressed during the tag polling process, the NTAGAbort function is called internally, and the process is ended. As an example, in this case, NTAG_ERR_ABORT is returned from the callback to the NTAGRead function.

When the HOME Button Is Pressed

When the HOME Button is pressed, in the same way as when the TV control button is pressed, the NTAGAbort function is called internally, and the process is ended. To prevent read and write operations from being ended, prohibit the functionality of the HOME Button as necessary.

Revision History

2014/10/29 NTAG library is eliminated from the standard Cafe SDK.
2013/05/08 Automated cleanup pass.
2012/12/19 Added a description of NTAGSetFormatSettings.
2012/11/15 Initial version.


CONFIDENTIAL