The NTAG library is used for reading and writing features of the NOFT (Nintendo's proprietary tag format), an NFC feature in the GamePad.
To initialize the GamePad's NFC module, call the
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.
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.
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.
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.
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.
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
0xFFFFFFFFFFFFFF. Also, if
All 0x00 is specified for the
uid_mask, the UID mask specification is disabled. When using the
NTAGFormat functions, however, you must always specify the UID. (The
uid_mask is internally fixed at
to prevent writing to or formatting an incorrect tag.
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
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
NTAGReadCallback. Be sure to perform the appropriate error handling.
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
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.
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
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.
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.
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.
For system-related reasons, processing might be ended or stopped during NFC communications, so you must consider the following cases during implementation.
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.
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
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.
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
2012/11/15 Initial version.