Tappy Communication Messaging Protocol (TCMP) command family for performing basic tag detection, reading, emulating, and writing operations.

Installation

Bower

bower install tappy-basicnfcfamily

NPM

npm install @taptrack/tappy-basicnfcfamily

Commands

Tag Detection Commands

varBasicNfc=require('tappy-basicnfcfamily');varCommands=BasicNfc.Commands;// All scan/stream commands take two parameters:// timeout: number of seconds to scan for (0 disables, max 255)// pollingMode: one of BasicNfc.PollingModes, defaults to GENERAL.// It is necessary to change to TYPE1 to detect NFC Forum Type 1// tags, while GENERAL covers Type 2 and 4.// Scan commands detect a single tag and then quit. Stream commands continue// until manually stopped or a fatal error occurs.// Tag detection only detects the UID and type of the tag entering the fieldvarscanTag=newCommands.ScanTag(timeout,BasicNfc.PollingModes.TYPE1);varstreamTags=newCommands.StreamTags(timeout);// NDEF detection only reports tags containing an NFC Forum compilant NDEF // messagevarscanNdef=newCommands.ScanNdef(timeout,BasicNfc.PollingModes.GENERAL);varstreamNdef=newCommands.StreamNdef(timeout);

Tag Writing Commands

// All write commands have the same first two parameters:// timeout: number of seconds to wait for a tag to be presented, 0->255// lock: boolean determining if the tag should be locked after writing// Writes a custom NDEF message to the tag. The data parameter should// be a Uint8Array containing the bytes of a full NDEF message, excluding// any tag technology-specific informationvarwriteCustom=newCommands.WriteNdefCustom(timeout,lockTag,ndefData);// Writes an NDEF message with a single text record to the tag. The data // should be a string containing the text to be written.varwriteText=newCommands.WriteNdefText(timeout,lockTag,textData);// Writes an NDEF message with a single URI record to the tag.// The last data parameter is an NDEF URI record prefix code, while// the URI data parameter contains the full URI without the prefix.varwriteUri=newCommands.WriteNdefUri(timeout,lockTag,uri,uriCode);

Tag Emulation Commands

// Emulation commands cause the Tappy to emulate a type 4 tag containing// user-specified NDEF data.// All emulate commands have the same first two parameters:// timeout: number of seconds to emulate for, 0->255 (0 disables)// maxScans: number of scans to emulate for, 0->255 (0 disables)// Causes the Tappy to emulate a type 4 tag containing a user-defined// NDEF message. The ndefData parameter should be a Uint8Array containing// all the bytes of a full NDEF message, excluding any tag technology-specific// information.varemulateCustom=newCommands.EmulateNdefCustom(timeout,maxScans,ndefData);// Causes the Tappy to emulate a type 4 tag containing an NDEF message// with a single text record. // The textData should be a string containing the text you wish the// emulated record to contain.varemulateText=newCommands.EmulateNdefText(timeout,maxScans,textData);// Causes the Tappy to emulate a type 4 tag containing an NDEF message// with a single URI record. // The last data parameter is an NDEF URI record prefix code, while// the uri data parameter contains the full uri without the prefix.varemulateUri=newCommands.EmulateNdefUri(timeout,maxScans,uri,uriCode);

Utility Commands

// Cancel any operation. Primarily used for stopping operations with a // long or indefinite timeout.varstop=newCommands.Stop();// Request that the tappy return the version of the BasicNfc// library that it supports.vargetLibraryVersion=newCommands.GetLibraryVersion();

Responses

Note: You should only manually construct responses as below for testing purposes. in practice, please use the resolver described later to convert raw TCMP messages received from the tappy into their corresponding concrete response types with the payloads parsed appropriately.

Utility Responses

// An error occured during a BasicNfc operation, has methodsvarapplicationError=newResponses.ApplicationError();// retrieve the command family-specific error code as per BasicNfc.ErrorCodes applicationError.getErrorCode();// retrieve the internal-use error code applicationError.getInternalErrorCode();// retrieve the status reported by the Tappy's NFC ControllerapplicationError.getReaderStatusCode();// retrieve the text message describing the error (may be empty string)applicationError.getErrorMessage();// Response reporting the version of the BasicNfc command family on// the tappyvarlibVersion=newResponses.LibraryVersion();libVersion.getMajorVersion();libVersion.getMinorVersion();

Tag Detection Responses

// Response notifying the client of an Ndef-containing tag being detectedvarndefFound=newResponses.NdefFound();// retrieve Tappy standard tag type codendefFound.getTagType();// retrieve Uint8Array of the tag's UIDndefFound.getTagCode();// retrieve Uint8Array of the tag's Ndef messagendefFound.getMessage();// Response notifying the client that an operation timed out without detecting// a tagvarscanTimeout=newResponses.ScanTimeout();// Response notifying the client of a tag being detectedvartagFound=newResponses.TagFound();// retrieve Tappy standard tag type codetagFound.getTagType();// retrieve Uint8Array of the tag's UIDtagFound.getTagCode();

Tag Writing Responses

// Response notifying the client that a tag was successfully writtenvartagWritten=newResponses.TagWritten();// retrieve Tappy standard tag type codetagWritten.getTagType();// retrieve Uint8Array of the tag's UIDtagWritten.getTagCode();

Tag Emulation Responses

// Response notifying that someone has scanned the emulated tagvaremulationScanSuccess=newResponses.EmulationScanSuccess()// Response notifying that emulation has ended varemulationComplete=newResponses.EmulationComplete();// retrieve the reason emulation completed, the// value is a single byte as below:// 0x01: timeout reached // 0x02: max scans reached// 0x03: new instruction was receivedemulationComplete.getReasonCode();// retrieve the number of times the emulated tag was scannedemulationComplete.getScanCount();

Resolver

While you can manually resolve raw TCMP messages received from the Tappy using getCommandFamily(), getCommandCode(), getPayload(), and parsePayload(), it is much more convenient to use the built-in resolvers and isTypeOf().

varresolver=newBasicNfc.Resolver();// First, check to see if the family is the Basic NFC command family.// This can be used to multiplex multiple resolvers from different families.if(resolver.checkFamily(responseMsg)){// This will throw if the command family doesn't match, so please check that// first. Additionally, this will return null if it does not recognize the// command code.varresolved=resolver.resolveResponse(responseMsg);if(resolved!==null&&BasicNfc.Responses.LibraryVersion.isTypeOf(resolved)){console.log("BasicNfc version v"+resolved.getMajorVersion()+"."+resolved.getMinorVersion());}}

There is a corresponding resolveCommand function for commands in case you are storing commands in a raw form. Note that commands and responses have overlapping commandCode space, so you'll need to keep track of whether the message was sent to the Tappy or received from it, and use the appropriate resolution function.