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