NfcTagClass Class
NfcTagClass Class
Description
Defines a class for managing NFC functionality of Ameba.
Syntax
class NfcTagClass
Members
| Public Constructors | |
| The public constructor should not be used as this class is intended to be a singleton class. Access member functions using the object instance named NFC tag. |
| Public Methods | |
| NfcTagClass::begin | Start NFC firmware. |
| NfcTagClass::end | Stop NFC firmware. |
| NfcTagClass::appendRtdText | Create and append a text NDEF record. |
| NfcTagClass::appendRtdUri | Create and append URI NDEF record. |
| NfcTagClass::appendVcard | Create and append V-Card record. |
| NfcTagClass::appendAndroidPlayApp | Create and append AAR record. |
| NfcTagClass::clearNdefMessage | Clear cached NDEF records. |
| NfcTagClass::isUidValid | Check if UID field is valid. |
| NfcTagClass::convertNdefToRaw | Convert the cached NDEF messages into NFC format. |
| NfcTagClass::convertRawToNdef | Convert the NFC tag content into NDEF messages. |
| NfcTagClass::convertRawToCache | Update the NFC tag content into NFC firmware. |
| NfcTagClass::getLastUpdateTimestamp | Return the timestamp when the NFC cache was last updated. |
| NfcTagClass::setWriteProtect | Set protection that prevents modification of NFC tag content. |
| NfcTagClass::getNdefSize | Get current stored NDEF message size. |
| NfcTagClass::getNdefData | Get current stored NDEF messages. |
NfcTagClass::begin
Description
Start NFC firmware.
Syntax
void begin(void);
Parameters
The function requires no input parameter.
Returns
The function returns nothing.
Example Code
Example: GetTagContent
This example demonstrates get NFC content when tag content has been programmed.
/*
* Pre-requirement:
* (1) By default the NFC antenna is not connected. You have to weld it.
* (2) The Android phone needs have NFC function.
*
* Use Android NFC application which supports NFC write function.
* Try to write something on it, then Ameba will dump the message on log.
*/
#include <NfcTag.h>
uint32_t last_update_time;
const struct NDEF *pNdefMsg;
void setup() {
NfcTag.appendRtdText("0");
NfcTag.begin();
last_update_time = NfcTag.getLastUpdateTimestamp();
}
void loop() {
if (NfcTag.getLastUpdateTimestamp() > last_update_time)
{
last_update_time = NfcTag.getLastUpdateTimestamp() ;
dumpTagContent();
}
delay(1000);
}
void dumpTagContent() {
pNdefMsg = NfcTag.getNdefData();
for (int i=0; i<NfcTag.getNdefSize(); i++)
{
// print the ndef data
Serial.print("NDEF message ");
Serial.println(i);
Serial.print("\tMB: ");
Serial.print( (pNdefMsg[i].TNF_flag & TNF_MESSAGE_BEGIN) ? 1 : 0);
Serial.print("\tME: ");
Serial.print( (pNdefMsg[i].TNF_flag & TNF_MESSAGE_END) ? 1 : 0);
Serial.print("\tCF: ");
Serial.print( (pNdefMsg[i].TNF_flag & TNF_MESSAGE_CHUNK_FLAG) ? 1 : 0);
Serial.print("\tSR: ");
Serial.print( (pNdefMsg[i].TNF_flag & TNF_MESSAGE_SHORT_RECORD) ? 1 : 0);
Serial.print("\tIL: ");
Serial.print( (pNdefMsg[i].TNF_flag & TNF_MESSAGE_ID_LENGTH_IS_PRESENT) ? 1 : 0);
Serial.println();
Serial.print("\tTNF Type: ");
switch( pNdefMsg[i].TNF_flag & 0x07 ) {
case TNF_EMPTY: Serial.println("EMPTY"); break;
case TNF_WELL_KNOWN: Serial.println("WELL_KNOWN"); break;
case TNF_MIME_MEDIA: Serial.println("MIME_MEDIA"); break;
case TNF_ABSOLUTE_URI: Serial.println("ABSOLUTE_URI"); break;
case TNF_EXTERNAL_TYPE: Serial.println("EXTERNAL_TYPE"); break;
case TNF_UNCHANGED: Serial.println("UNCHANGED"); break;
case TNF_RESERVED: Serial.println("RESERVED"); break;
default: Serial.println(); break;
}
Serial.print("\ttype length: ");
Serial.println(pNdefMsg[i].type_len);
Serial.print("\ttype: ");
Serial.println((char *)(pNdefMsg[i].payload_type));
Serial.print("\tpayload length: ");
Serial.println(pNdefMsg[i].payload_len);
Serial.print("\tpayload: ");
Serial.println((char *)(pNdefMsg[i].payload));
}
}
Notes and Warnings
NA
NfcTagClass::end
Description
Stop NFC firmware.
Syntax
void end(void);
Parameters
The function requires no input parameter.
Returns
The function returns nothing.
Example Code
NA
Notes and Warnings
NA
NfcTagClass::appendRtdText
Description
Create and append a text NDEF record.
Syntax
void appendRtdText(const char *text, unsigned char encodeType, const char *IANALanguageCode);
void appendRtdText(const char *text);
Parameters
text: the text message to add
encodeType: The encoding type in UTF8 or UTF16
IANALanguageCode: The coding of language
Returns
The function returns nothing.
Example Code
Example: StoreTagContent
This example demonstrates store NFC content to flash and restore it when the device bootup.
/*
* Pre-requirement:
* (1) By default the NFC antenna is not connected. You have to weld it.
* (2) The Android phone needs have NFC function.
*
* Use Android NFC application which supports NFC write function.
* Try to write something on it and reboot Ameba to check if the content still exists.
*/
#include <NfcTag.h>
#include <FlashMemory.h>
int previousUpdateTimestamp;
bool isValidUid() {
// UID has 2 byte checksum, and use it to check if flash content is valid
if (FlashMemory.buf[3] != (0x88 ^ FlashMemory.buf[0] ^ FlashMemory.buf[1] ^ FlashMemory.buf[2])) {
return false;
}
if (FlashMemory.buf[8] != (FlashMemory.buf[4] ^ FlashMemory.buf[5] ^ FlashMemory.buf[6] ^ FlashMemory.buf[7])) {
return false;
}
return true;
}
void setup() {
FlashMemory.read();
if (isValidUid()) {
Serial.println("Valid flash content and load to nfc");
memcpy(NfcTag.nfc_tag_content, FlashMemory.buf, NFC_MAX_PAGE_NUM*4);
} else {
Serial.println("Invalid flash content, init as Hello World!");
NfcTag.appendRtdText("Hello World!");
}
NfcTag.begin();
previousUpdateTimestamp = NfcTag.getLastUpdateTimestamp();
}
void loop() {
if (NfcTag.getLastUpdateTimestamp() > previousUpdateTimestamp) {
Serial.println("nfc content has been update, store content to flash");
previousUpdateTimestamp = NfcTag.getLastUpdateTimestamp();
memcpy(FlashMemory.buf, NfcTag.nfc_tag_content, NFC_MAX_PAGE_NUM*4);
FlashMemory.update();
}
delay(1000);
}
Notes and Warnings
encodeType defaults to NDEF_TEXT_ENCODE_UTF8 if not specified.
IANALanguageCode defaults to NDEF_IANA_ENGLISH if not specified.
NfcTagClass::appendRtdUri
Description
Create and append the URI NDEF record.
Syntax
void appendRtdUri(const char *text, unsigned char uriIdentifierCode);
void appendRtdUri(const char *text);
Parameters
text: The URI string
uriIdentifierCode: The URI code corresponding to the desired URI header
Returns
The function returns nothing.
Example Code
Example: UriWebPage
This example demonstrates an open web page on an android phone by tapping the NFC antenna on Ameba.
/*
* Pre-requirement:
* (1) By default the NFC antenna is not connected. You have to weld it.
* (2) The Android phone needs have NFC function.
*
* Android framework support NDEF (NFC Data Exchange Format) data message.
* As we configure NDEF message on Ameba's NFC firmware, tap phone on it,
* then Android framework will parse the NDEF messages and performs
* correspond actions.
*
* This sketch demonstrates how to configure NDEF message that makes Android
* phone opens web page "http://www.amebaiot.com" on the browser.
*
*/
#include <NfcTag.h>
void setup() {
NfcTag.appendRtdUri("amebaiot.com");
NfcTag.begin();
}
void loop() {
delay(1000);
}
Notes and Warnings
uriIdentifierCode defaults to RTD_URI_HTTP_WWW if not specified, which is the “http://www.” header.
NfcTagClass::appendVcard
Description
Create and append the V-Card record.
Syntax
void appendVcard(const char *vcard, int vcard_len);
Parameters
vcard: The V-Card string content
vcard_len: The length of the V-Card content
Returns
The function returns nothing.
Example Code
Example: VCardContact
This example demonstrates adding a contact on android phone by tapping an NFC antenna on Ameba.
/*
* Pre-requirement:
* (1) By default the NFC antenna is not connected. You have to weld it.
* (2) The Android phone needs have NFC function.
*
* Android framework support NDEF (NFC Data Exchange Format) data message.
* As we configure NDEF message on Ameba's NFC firmware, tap phone on it,
* then Android framework will parse the NDEF messages and performs
* correspond actions.
*
* This sketch demonstrates how to configure NDEF message that makes Android
* phone adds contact.
*/
#include <NfcTag.h>
#define MAX_VCARD_LEN 110
char vcard_buf[MAX_VCARD_LEN];
char name[] = "Forrest Gump";
char family_name[] = "Forrest";
char given_name[] = "Gump";
char additional_name[] = "";
char honorific_prefix[] = "";
char honorific_suffixes[] = "Mr.";
char phone[] = "(111) 555-1212";
void setup() {
int vcard_len = 0;
vcard_len = sprintf( vcard_buf, "BEGIN:VCARD\r\nVERSION:1.0\r\nN:%s\r\nFN:%s;%s;%s;%s;%s\r\nTEL;VOICE:%s\r\nEND:VCARD\r\n",
name,
family_name, given_name, additional_name, honorific_prefix, honorific_suffixes,
phone
);
if (vcard_len <= MAX_VCARD_LEN) {
NfcTag.appendVcard(vcard_buf, vcard_len);
NfcTag.begin();
} else {
Serial.println("ERR: Invalid length of vCard!");
}
}
void loop() {
delay(1000);
}
Notes and Warnings
NA
NfcTagClass::appendAndroidPlayApp
Description
Create and append AAR(Android Application Record) record.
Syntax
void appendAndroidPlayApp(const char *appName);
Parameters
appName: The application name in Android Google Play.
Returns
The function returns nothing.
Example Code
Example: GooglePlayApp
#include <NfcTag.h>
void setup() {
NfcTag.appendAndroidPlayApp("com.facebook.katana");
NfcTag.begin();
}
void loop() {
delay(1000);
}
Notes and Warnings
NA
NfcTagClass::clearNdefMessage
Description
Clear cached NDEF records in NfcTag object.
Syntax
void clearNdefMessage(void);
Parameters
The function requires no input parameter.
Returns
The function returns nothing.
Example Code
Example: UpdateTagContent
This example demonstrates update NFC content dynamically.
/*
* Pre-requirement:
* (1) By default the NFC antenna is not connected. You have to weld it.
* (2) The Android phone needs have NFC function.
*
* Use Android NFC application which supports NFC read function.
* This sketch update add-one counter at every second.
* Use Android NFC reader application to get this value.
*/
#include <NfcTag.h>
int counter = 1;
char mybuf[10];
void setup() {
NfcTag.appendRtdText("0");
NfcTag.begin();
}
void loop() {
counter++;
Serial.print("counter:");
Serial.println(counter);
sprintf(mybuf, "%d", counter);
NfcTag.clearNdefMessage();
NfcTag.appendRtdText(mybuf);
NfcTag.convertNdefToRaw();
NfcTag.updateRawToCache();
delay(1000);
}
Notes and Warnings
Only clears cached NDEF records in NfcTag object, does not affect records in NFC firmware.
NfcTagClass::isUidValid
Description
Check the contents and verify the UID field.
Syntax
bool isUidValid(void);
Parameters
The function requires no input parameter.
Returns
False – UID is invalid
True – UID is valid
Example Code
NA
Notes and Warnings
NA
NfcTagClass::convertNdefToRaw
Description
Convert the cached NDEF messages into the NFC Tag Type2 format.
Syntax
void convertNdefToRaw(void);
Parameters
The function requires no input parameter.
Returns
The function returns nothing.
Example Code
Example: UpdateTagContent
This example demonstrates update NFC content dynamically. Details of the code can be found in the previous section of NfcTagClass::clearNdefMessage.
Notes and Warnings
NA
NfcTagClass::convertRawToNdef
Description
Convert the raw NFC Tag Type2 format data into NDEF messages.
Syntax
void convertRawToNdef(void);
Parameters
The function requires no input parameter.
Returns
The function returns nothing.
Example Code
NA
Notes and Warnings
NA
NfcTagClass::updateRawToCache
Description
Update raw NFC data into NFC firmware.
Syntax
void updateRawToCache(void);
Parameters
The function requires no input parameter.
Returns
The function returns nothing.
Example Code
Example: UpdateTagContent
This example demonstrates update NFC content dynamically. Details of the code can be found in the previous section of NfcTagClass::clearNdefMessage.
Notes and Warnings
NA
NfcTagClass::getLastUpdateTimestamp
Description
Return the timestamp when the NFC cache was last updated.
Syntax
uint32_t getLastUpdateTimestamp(void);
Parameters
The function requires no input parameter.
Returns
32 bit unsigned integer representing milliseconds
Example Code
Example: GetTagContent
This example demonstrates get NFC content when tag content has been programmed. Detail of the code can be found in the previous section of NfcTagClass:: begin.
Notes and Warnings
NA
NfcTagClass::setWriteProtect
Description
Set protection to enable/disable modifying of NFC tag content on Ameba by an NFC reader.
Syntax
void setWriteProtect(bool enable);
Parameters
enable: set to true to enable write protection
Returns
The function returns nothing.
Example Code
NA
Notes and Warnings
NA
NfcTagClass::getNdefSize
Description
Get the currently stored NDEF message size.
Syntax
unsigned char getNdefSize(void);
Parameters
The function requires no input parameter.
Returns
The size of currently stored NDEF messages.
Example Code
Example: GetTagContent
This example demonstrates get NFC content when tag content has been programmed. Detail of the code can be found in the previous section of NfcTagClass:: begin.
Notes and Warnings
NA
NfcTagClass::getNdefData
Description
Get the currently stored NDEF messages.
Syntax
const struct NDEF *getNdefData(void);
Parameters
The function requires no input parameter.
Returns
The NDEF struct array pointer.
Example Code
Example: GetTagContent
This example demonstrates get NFC content when tag content has been programmed. Detail of the code can be found in the previous section of NfcTagClass:: begin.
Notes and Warnings
NA
