Webinos Logo

NFC API

Webinos API Specifications

27 Aug 2012

Authors


Abstract

Near Field Communication (NFC) support.

Table of Contents

  1. Introduction
  2. Interfaces and Dictionaries
    1. Webinos
    2. NFC
    3. NfcNdefEvent
    4. NfcTag
    5. NfcNdefRecord
  3. Callbacks
    1. NfcEventCallBack
    2. SuccessCallBack
    3. FailCallBack
    4. LLCPCallBack
    5. CloseCallBack
  4. Enums
    1. NfCTagTech
  5. Features
  6. Full WebIDL

Summary of Methods

Interface Method
Webinos
NFC void addListener(NfcEventCallBack listener, SuccessCallBack success, FailCallBack fail)
void addTextTypeListener(NfcEventCallBack listener, SuccessCallBack success, FailCallBack fail)
void addUriTypeListener(NfcEventCallBack listener, SuccessCallBack success, FailCallBack fail)
void addMimeTypeListener(DOMString mimeType, NfcEventCallBack listener, SuccessCallBack success, FailCallBack fail)
void shareTag(NfcNdefRecord[] message, SuccessCallBack success, FailCallBack fail)
void unshareTag(SuccessCallBack success, FailCallBack fail)
void peer(LLCPCallBack success, FailCallBack fail)
NfcNdefRecord textRecord(DOMString text)
NfcNdefRecord uriRecord(DOMString uri)
NfcNdefRecord mimeRecord(DOMString mimeType, byte[] data)
byte[] stringToBytes(DOMString string)
DOMString bytesToString(byte[] data)
NfcNdefEvent
NfcTag void write(NfcNdefRecord[] ndefMessage, SuccessCallBack success, FailCallBack fail)
void makeReadOnly(SuccessCallBack success, FailCallBack fail)
NfcNdefRecord

Introduction

Near Field Communication (NFC) is an international standard (ISO/IEC 18092) that specifies an interface and protocol for simple wireless interconnection of closely coupled devices operating at 13.56 MHz. (http://www.nfc-forum.org/specs/spec_list/). There are three groups of application scenarios for NFC: The first one is to hold a device close to a wireless tag to exchange some digital information or data. The second is to hold two devices close to each other in order to exchange some information or data between them. The third one is to make payments by holding mobile phones close to point of sales terminals instead of swiping smart cards.

Interfaces and Dictionaries

Interface Webinos (partial interface)

Creates the webinos.nfc namespace.

WebIDL
partial interface Webinos  {
  readonly attribute NFC nfc;
};

Interface NFC

The NFCinterface

WebIDL
interface NFC {


  void addListener(NfcEventCallBack listener,
      SuccessCallBack success, FailCallBack fail);


  void addTextTypeListener(NfcEventCallBack listener,
      SuccessCallBack success, FailCallBack fail);


  void addUriTypeListener(NfcEventCallBack listener,
      SuccessCallBack success, FailCallBack fail);


  void addMimeTypeListener(DOMString mimeType,
      NfcEventCallBack listener, SuccessCallBack success, FailCallBack fail);


  void shareTag(NfcNdefRecord[] message, SuccessCallBack success, FailCallBack fail);


  void unshareTag(SuccessCallBack success, FailCallBack fail);



  void peer(LLCPCallBack success, FailCallBack fail);




  NfcNdefRecord textRecord(DOMString text);

  NfcNdefRecord uriRecord(DOMString uri);

  NfcNdefRecord mimeRecord(DOMString mimeType, byte[] data);


  byte[] stringToBytes(DOMString string);


  DOMString bytesToString(byte[] data);
};

This interface provides a variety of means for adding listeners for NFC tags, setting the device into a sharing mode, and helper methods for dealing with NDEF records.

Introduction

It is becoming increasingly common for smart phones and other devices to include support for NFC. NFC Tags are inexpensive and widely used. There are many potential applications, e.g. here are just a few:

  • Electronic payments (tap to pay)
  • Exchange of contact details (an electronic business card)
  • Exchange of security credentials e.g. for a WiFi network
  • Credentials for induction of a new device into a user's Personal Zone
  • Tap to play - automatic induction into a multiplayer game

The phase 2 NFC API provides for a range of capabilities.

  • The means to register listeners for the presence of NFC Tags
  • The means to read and write NDEF records to NFC Tags
  • The means to set Tags to prevent further write operations
  • The means to configure a NFC device to push NDEF messages to other such devices
  • The means to establish a temporary bidirectional asynchronous message channel

This specification starts with some informative examples for how the API can be used. The next section deals with the normative definition of the API and is followed by the full WebIDL definition of API. The specification closes with acknowledgements and references.

Listen

To set up an event listener for an NFC Tag:

Webinos.nfc.addListener(listener, success, fail);

Code example
 function listener (event)
 {
   var tag = event.tag;  // object proxying the NFC Tag
   console.log("tag technology: " + tag.tech);
   tag.close = function () {
     console.log("lost contact with the Tag");
   };
 }
 
 function success ()
 {
   console.log("successfully registered NFC event listener");
 }
 
 function fail ()
 {
   console.log("failed to register NFC event listener");
 }
 

The tag.tech field is a string identifying the kind of NFC Tag:

  • OTHERS
  • NFCA
  • NFCB
  • NFCF
  • NFCV
  • ISODEP
  • NDEF

If the Tag is an NDEF Tag, the ndefMessage property can be used to access the NDEF records:

Code example
   var records = tag.ndefMessage || [];
 
   for (var i = 0; i  records.length; ++i
   {
     var record = records[i];
     console.log("Record: " + i);
     console.log("type: " + record.type);
     console.log("id: " + record.id);
     console.log("payload: " + Webinos.nfc.bytesToString(record.payload));
     console.log("");
   }
 

As a convenience to developers, you can also register for events for Tags with specific NDEF record types:

Code example
   // register for Tags with VCARD data
   Webinos.nfc.addMimeTypeListener("text/vcard", listener, success, fail);
 
   // register for Tags with URIs, e.g. for pointers to websites
   Webinos.nfc.addURITypeListener(listener, success, fail);
 

Writing

To write to a tag having discovered one:

Code example
 // called when the Tag is discovered
 function listener (event)
 {
   var nfc = Webinos.nfc;
 
   // read the tag here if you want ...
 
   // prepare an NDEF message
   var message = [
     nfc.textRecord("Have a nice day!");
   ];
 
   // and write it back to the Tag
   event.tag.write(message, success, fail);
 }
 
 function success ()
 {
   console.log("successfully wrote message to Tag");
 }
 
 function fail ()
 {
   console.log("failed to write message to Tag");
 }
 

There could be more than one Tag in range, e.g. you might have several in your wallet. This approach allows you to write back to the same Tag that you just read.

Set Read Only

To prevent further modifications to a Tag you can do the following:

Code example
   tag.makeReadOnly(success, fail);
 
 ...
 
 function success ()
 {
   console.log("successfully make Tag read-only");
 }
 
 function fail ()
 {
   console.log("failed to make Tag read-only");
 }
 

Push

How to determine when it is reasonable to exit sharing mode? Is there a way to determine that the other device has moved out of range? Or perhaps an acknowledgement that it read the shared data?

You can set your NFC device, e.g. a smart phone to push an NDEF message to another such device. The first step is to prepare the message. You then call the shareTag method to enter the sharing mode:

Code example
 // called when the Tag is discovered
 function listener (event)
 {
   var nfc = Webinos.nfc;
 
   // prepare an NDEF message
   var message = [
     nfc.uriRecord("http://www.example.com/");
   ];
 
   // and write it back to the Tag
   nfc.shareTag(message, success, fail);
 }
 
 function success ()
 {
   console.log("entered NFC sharing mode");
 }
 
 function fail ()
 {
   console.log("failed to enter NFC sharing mode");
 }
 

Some time later, you call the unshareTag method to restore your device to normal mode of operation where it is listening for NFC Tags that come in range:

Code example
   nfc.unshareTag(success, fail);
 
 ...
 
 function success ()
 {
   console.log("exited NFC sharing mode");
 }
 
 function fail ()
 {
   console.log("error on exiting NFC sharing mode");
 }
 

Peer to Peer Communications with LLCP

The Link Logical Control Protocol (LLCP) can be used to set up an HTML Message Channel for a temporary bidirectional aysnchronous connection. Message Channels are part of HTML5

HTML5 MessageChannel

Here is a simple example:

Code example
   // first set phone into peering mode
   Webinos.nfc.peer(success, fail);
 
 function success (channel)
 {
   console.log("successfully initiated peering mode");
 
   // to send a message to the other device
   channel.port1.postMessage('hello');
 
   // to receive a message from the other device
   // first you set a message handler
   channel.port1.onmessage = handleMessage;
 
   // you next instruct the channel to dispatch events
   // you can later close the port with the stop() method
   // your device then reverts to its normal mode
   channel.port1.start();
 }
 
 function handleMessage(event)
 {
   // message is in event.data
   // ...
 }
 
 // after a time out when peering couldn't be established
 function fail ()
 {
   console.log("failed to initiate peering mode");
 }
 

Methods

addListener

This is a method for registering a call back for all NFC tag technologies.

Signature
void addListener(NfcEventCallBack listener, SuccessCallBack success, FailCallBack fail);

It makes use of the success and failure call back pattern. These call backs are defined in a subsequent section.

Parameters
  • listener
    • Optional: No.
    • Nullable: No
    • Type: NfcEventCallBack
    • Description: Callback issued when an update occurs
  • success
    • Optional: No.
    • Nullable: No
    • Type: SuccessCallBack
    • Description: Callback issued when listener has been successfully added
  • fail
    • Optional: No.
    • Nullable: No
    • Type: FailCallBack
    • Description: Callback issued if an error occurs
Return value
void
addTextTypeListener

This is a method for registering a call back for NFC tags with NDEF text records.

Signature
void addTextTypeListener(NfcEventCallBack listener, SuccessCallBack success, FailCallBack fail);

It makes use of the success and failure call back pattern. These call backs are defined in a subsequent section.

Parameters
  • listener
    • Optional: No.
    • Nullable: No
    • Type: NfcEventCallBack
    • Description: Callback issued when an update occurs
  • success
    • Optional: No.
    • Nullable: No
    • Type: SuccessCallBack
    • Description: Callback issued when listener has been successfully added
  • fail
    • Optional: No.
    • Nullable: No
    • Type: FailCallBack
    • Description: Callback issued if an error occurs
Return value
void
addUriTypeListener

This is a method for registering a call back for NFC tags with NDEF URI records.

Signature
void addUriTypeListener(NfcEventCallBack listener, SuccessCallBack success, FailCallBack fail);

It makes use of the success and failure call back pattern. These call backs are defined in a subsequent section.

Parameters
  • listener
    • Optional: No.
    • Nullable: No
    • Type: NfcEventCallBack
    • Description: Callback issued when an update occurs
  • success
    • Optional: No.
    • Nullable: No
    • Type: SuccessCallBack
    • Description: Callback issued when listener has been successfully added
  • fail
    • Optional: No.
    • Nullable: No
    • Type: FailCallBack
    • Description: Callback issued if an error occurs
Return value
void
addMimeTypeListener

This is a method for registering a call back for NFC tags with NDEF MIME content records with a specific MIME type, e.g. "text/vcard", which is used for an electronic equivalent of a business card.This is a method for registering a call back for NFC tags with NDEF URI records.

Signature
void addMimeTypeListener(DOMString mimeType, NfcEventCallBack listener, SuccessCallBack success, FailCallBack fail);

It makes use of the success and failure call back pattern. These call backs are defined in a subsequent section.

Parameters
  • mimeType
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: Specific MIME type to listen for
  • listener
    • Optional: No.
    • Nullable: No
    • Type: NfcEventCallBack
    • Description: Callback issued when an update occurs
  • success
    • Optional: No.
    • Nullable: No
    • Type: SuccessCallBack
    • Description: Callback issued when listener has been successfully added
  • fail
    • Optional: No.
    • Nullable: No
    • Type: FailCallBack
    • Description: Callback issued if an error occurs
Return value
void
shareTag

This is a method for setting a device into a sharing mode for pushing an NDEF message to another NDEF device.

Signature
void shareTag(NfcNdefRecord[] message, SuccessCallBack success, FailCallBack fail);

It makes use of the success and failure call back pattern. These call backs are defined in a subsequent section.

Parameters
  • message
    • Optional: No.
    • Nullable: No
    • Type: array
    • Description: NDEF message to push
  • success
    • Optional: No.
    • Nullable: No
    • Type: SuccessCallBack
    • Description: Callback issued when message has been successfully pushed
  • fail
    • Optional: No.
    • Nullable: No
    • Type: FailCallBack
    • Description: Callback issued if an error occurs
Return value
void
unshareTag

This method is used after the shareTag method, and sets the device back to the default mode in which it listens for the presence of NFC tags.

Signature
void unshareTag(SuccessCallBack success, FailCallBack fail);

It makes use of the success and failure call back pattern. These call backs are defined in a subsequent section.

Parameters
  • success
    • Optional: No.
    • Nullable: No
    • Type: SuccessCallBack
    • Description: Callback issued when mode has been set back to default
  • fail
    • Optional: No.
    • Nullable: No
    • Type: FailCallBack
    • Description: Callback issued if an error occurs
Return value
void
peer

This method is used to establish a bidirectional channel with another NFC device for asynchronous exchange of data.

Signature
void peer(LLCPCallBack success, FailCallBack fail);

It makes use of the success and failure call back pattern. These call backs are defined in a subsequent section.

This method is used to establish a bidirectional channel with another NFC device for asynchronous exchange of data. It makes use of the Link Logical Control Protocol and exposes it as an HTML MessageChannel, see:

http://www.w3.org/TR/html5/comms.html

Each message channel exposes a pair of ports. The first port represents the local end of the channel, and the second port represents the remote end of the channel. Messages are posted between ports using the postMessage method. Messages can be strings or other kinds of JavaScript objects, and are serialized and reassembled automatically as structured clones, see:

http://www.w3.org/TR/html5/common-dom-interfaces.html#structured-clone

You can register a listener for notifications of incoming data. The channel is closed by calling the close method on the ports exposed by the message channel. For more details see the above link to the specification of the HTML MessageChannel.

Parameters
  • success
    • Optional: No.
    • Nullable: No
    • Type: LLCPCallBack
    • Description: Callback issued when message channel has been established
  • fail
    • Optional: No.
    • Nullable: No
    • Type: FailCallBack
    • Description: Callback issued if an error occurs
Return value
void
textRecord

This method creates an NDEF record from a string

Signature
NfcNdefRecord textRecord(DOMString text);
Parameters
  • text
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: Text used for creating the NDEF
Return value
NfcNdefRecord The created NDEF record
uriRecord

This method creates an NDEF record from a URI

Signature
NfcNdefRecord uriRecord(DOMString uri);
Parameters
  • uri
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: URI used for creating the NDEF
Return value
NfcNdefRecord The created NDEF record
mimeRecord

This method creates an NDEF record from a MIME type and a byte array representing data of that tyoe

Signature
NfcNdefRecord mimeRecord(DOMString mimeType, byte[] data);
Parameters
  • mimeType
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: MIME type the data is in
  • data
    • Optional: No.
    • Nullable: No
    • Type: array
    • Description: Data in the format indicated by the MIME type
Return value
NfcNdefRecord The created NDEF record
stringToBytes

This is a helper method for converting strings to byte arrays for use in NDEF messages.

Signature
byte[] stringToBytes(DOMString string);

This is a helper method for converting strings to byte arrays for use in NDEF messages. It maps 16 bit Unicode characters into a byte array in the big-endian manner with the most significant byte appearing first.

Parameters
  • string
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: String to convert
Return value
byte[] Resulting byte array for NDEF message use
bytesToString

This is a helper method for converting byte arrays from NDEF messages into strings.

Signature
DOMString bytesToString(byte[] data);

This is a helper method for converting byte arrays from NDEF messages into strings. This performs the inverse mapping from stringToBytes, and maps a big-endian byte array into a JavaScript string consisting of 16 bit unicode characters.

Parameters
  • data
    • Optional: No.
    • Nullable: No
    • Type: array
    • Description: NDEF style byte array
Return value
DOMString Converted NDEF data in text

Interface NfcNdefEvent

The NFC event has a single property -- the NFC Tag

WebIDL
interface NfcNdefEvent : DOMEvent {
  readonly attribute NfcTag tag; 
};

Interface NfcTag

he NFCTag interface defines properties and methods for NFC tags.

WebIDL
interface NfcTag {
  readonly attribute NfCTagTech tech;  
  readonly attribute NfcNdefRecord[] ndefMessage;

  attribute CloseCallBack close;



  void write(NfcNdefRecord[] ndefMessage,
             SuccessCallBack success, FailCallBack fail);


  void makeReadOnly(SuccessCallBack success, FailCallBack fail);
};

Methods

write

This method can be called on an open NFC tag to write an NDEF message. It will fail if the tag is read-only.

Signature
void write(NfcNdefRecord[] ndefMessage, SuccessCallBack success, FailCallBack fail);
Parameters
  • ndefMessage
    • Optional: No.
    • Nullable: No
    • Type: array
    • Description: Message to write to the NFC tag
  • success
    • Optional: No.
    • Nullable: No
    • Type: SuccessCallBack
    • Description: Callback issued when message has been written
  • fail
    • Optional: No.
    • Nullable: No
    • Type: FailCallBack
    • Description: Callback issued if an error occurs
Return value
void
makeReadOnly

This method can be called on an open NFC tag to set it to read-only.

Signature
void makeReadOnly(SuccessCallBack success, FailCallBack fail);
Parameters
  • success
    • Optional: No.
    • Nullable: No
    • Type: SuccessCallBack
    • Description: Callback issued when NFC tag has been set to read-only.
  • fail
    • Optional: No.
    • Nullable: No
    • Type: FailCallBack
    • Description: Callback issued if an error occurs
Return value
void

Interface NfcNdefRecord

An NDEF message is an array of records as defined above.

WebIDL
interface NfcNdefRecord {
  readonly attribute DOMString tnf;
  readonly attribute DOMString type;
  readonly attribute DOMString id;
  readonly attribute byte[] payload;
};

Callbacks

NfcEventCallBack

This is a call back for notifying the presence of NFC tags.

WebIDL
callback NfcEventCallBack = void (NfcNdefEvent event);
Signature
void NfcEventCallBack(NfcNdefEvent event);
Parameters
  • event
    • Optional: No.
    • Nullable: No
    • Type: NfcNdefEvent
    • Description:

SuccessCallBack

This is a call back for notifying the success of an operation such as registering a listener for the presence of NFC tags.

WebIDL
callback SuccessCallBack = void ();
Signature
void SuccessCallBack();

FailCallBack

This is a call back for notifying the failure of an operation such as registering a listener for the presence of NFC tags.

WebIDL
callback FailCallBack = void ();
Signature
void FailCallBack();

LLCPCallBack

This is a call back for notifying when a message channel has been established with another NFC device via the Link Logical Control Protocol.

WebIDL
callback LLCPCallBack = void (MessageChannel channel);
Signature
void LLCPCallBack(MessageChannel channel);
Parameters
  • channel
    • Optional: No.
    • Nullable: No
    • Type: MessageChannel
    • Description:

CloseCallBack

This is a call back that indicates that a NFC tag is no longer accessible, e.g. because the user has pulled the tag away from the reader.

WebIDL
callback CloseCallBack = void ();
Signature
void CloseCallBack();

Enums

NfCTagTech

This is an enumeration of string constants for the various kinds of NFC technologies that are generally supported by NFC devices.

WebIDL
          enum NfCTagTech {"OTHERS", "NFCA", "NFCB", "NFCF", "NFCV", "ISODEP", "NDEF"};

Values

OTHERS
NFCA
NFCB
NFCF
NFCV
ISODEP
NDEF

Features

This is the list of URIs used to declare this API's features, for use in the widget config.xml and as identifier for service type in service discovery functionality. For each URI, the list of functions covered is provided.

http://webinos.org/api/nfc

Acccess to all the module. This feature provides access to the whole API.

http://webinos.org/api/nfc.read

Acccess to all the module except write operations.

Full WebIDL

WebIDL
partial interface Webinos  {
  readonly attribute NFC nfc;
};




interface NFC {


  void addListener(NfcEventCallBack listener,
      SuccessCallBack success, FailCallBack fail);


  void addTextTypeListener(NfcEventCallBack listener,
      SuccessCallBack success, FailCallBack fail);


  void addUriTypeListener(NfcEventCallBack listener,
      SuccessCallBack success, FailCallBack fail);


  void addMimeTypeListener(DOMString mimeType,
      NfcEventCallBack listener, SuccessCallBack success, FailCallBack fail);


  void shareTag(NfcNdefRecord[] message, SuccessCallBack success, FailCallBack fail);


  void unshareTag(SuccessCallBack success, FailCallBack fail);



  void peer(LLCPCallBack success, FailCallBack fail);




  NfcNdefRecord textRecord(DOMString text);

  NfcNdefRecord uriRecord(DOMString uri);

  NfcNdefRecord mimeRecord(DOMString mimeType, byte[] data);


  byte[] stringToBytes(DOMString string);


  DOMString bytesToString(byte[] data);
};



callback NfcEventCallBack = void (NfcNdefEvent event);


callback SuccessCallBack = void ();


callback FailCallBack = void ();


callback LLCPCallBack = void (MessageChannel channel);



interface NfcNdefEvent : DOMEvent {
  readonly attribute NfcTag tag; 
};



interface NfcTag {
  readonly attribute NfCTagTech tech;  
  readonly attribute NfcNdefRecord[] ndefMessage;

  attribute CloseCallBack close;



  void write(NfcNdefRecord[] ndefMessage,
             SuccessCallBack success, FailCallBack fail);


  void makeReadOnly(SuccessCallBack success, FailCallBack fail);
};



callback CloseCallBack = void ();




          enum NfCTagTech {"OTHERS", "NFCA", "NFCB", "NFCF", "NFCV", "ISODEP", "NDEF"};



interface NfcNdefRecord {
  readonly attribute DOMString tnf;
  readonly attribute DOMString type;
  readonly attribute DOMString id;
  readonly attribute byte[] payload;
};