WebAPI/WebNFC: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
 
(314 intermediate revisions by 7 users not shown)
Line 1: Line 1:
= First iteration: NDEF =
= Introduction =
== Current Status (As to Firefox OS v2.2) ==
* Gecko b2g-nfc meta bug, {{bug|860906}}
* Gecko b2g-secure-element meta bug {{bug|1044428}}
* Gaia meta bug,  {{bug|933640}}
* nfcd meta bug, {{bug|1044425}}
* Gonk
** Use a native daemon nfcd which links to native NFC library. [https://github.com/mozilla-b2g/platform_system_nfcd nfcd github]
* Hardware
** Using Nexus-4/Nexus-5, which uses Broadcom NFC chipset with libnfc-nci library.
** Flame, NXP chipsets with libnfc-nci library.


== Scope ==
== Security Review (By Paul Theriault and Stephanie Ouillon) ==
* https://wiki.mozilla.org/Security/Reviews/B2G/WebNFC
* Security Review for WebNFC: {{bug|749325}}
* Security Review for NFC Payment: {{bug|948280}}
* Security Review for NFC privilege API: {{bug|1095417}}


== Contributors ==
* Gecko Engineers: Arno Puder, Garner Lee, Siddartha Pothapragada, Yoshi Huang, Dimi Lee
* Early Contributors: Markus Neubrand, Philipp von Weitershausen
= Roadmap =
== First iteration: NDEF (Firefox OS v1.3) ==
* meta bug, {{Bug|959692}} - (b2g-NFC-1.3) [meta] FxOS v1.3 NFC feature
* Technologies:
* Technologies:
** Focus on NDEF standard only for now
** Focus on NDEF standard only for now
Line 8: Line 29:
* Capabilities:
* Capabilities:
** Read/write NDEF records on tags
** Read/write NDEF records on tags
** P2P NDEF push/receive
** {{bug|933136}} - [Gecko] NFC onpeerready, onpeerlost callbacks
* Implementation:
* Implementation:
** NDEF-only API available on navigator.mozNfc object
** See {{bug|674741}}
** Discovered NDEF tags are automatically parsed and dispatched to content in the "ndefdiscovered" event on navigator.mozNfc
** NDEF-only API is available on MozNFCTag object.
** Discovered NDEF tags are automatically parsed and dispatched to content in the "nfc-manager-tech-discovered" system message.
** navigator.mozNfc only available to a specific privileged content page (cf. WebTelephony, WebSMS).
** navigator.mozNfc only available to a specific privileged content page (cf. WebTelephony, WebSMS).
** For now, content is expected to do filtering and dispatching to handlers e.g. via WebIntents/WebActions/postMessage
** For now, content is expected to do filtering and dispatching to handlers e.g. via WebActivity.
* Gonk
** {{bug|906579}} - B2G NFC: NFC Daemon for supporting libnfc-nci
* Hardware
** Using Nexus-4, which uses Broadcom NFC chipset with libnfc-nci library.
 
== Second iteration: Handover and other bug fixes (Firefox OS v1.4) ==
* meta bug : {{Bug|949293}} - (b2g-NFC-1.4) [meta] FxOS v1.4 NFC feature
* Capabilities:
** {{bug|933093}} NFC handover.
** {{bug|916863}} - [NFC] NFC support in emulator
** NFC Manager API
*** {{Bug|952217}} - [B2G][NFC] Have a separate NFC application API and NFC Manager API
*** {{Bug|959437}} - Refactor NfcManager APIs and implementation details to support sendFile , notifyUserAcceptedP2P and other privileged Nfc operations
 
== Third iteration: NFC Sharing feature, P2P, emulator support, test cases (Firefox OS v2.0) ==
* meta bug : {{Bug|949293}} - (b2g-NFC-2.0) [meta] FxOS v2.0 NFC feature
* NFC emulator: {{Bug|973133}}
* More Gaia unit tests for NFC in apps/system/test/unit/


== Proposed API ==
== Fourth iteration: HCI transaction event (Firefox OS v2.1) ==
* {{bug|979767}}


navigator.mozNfc has one event restricted to NDEF discovery. The "ndefdiscovered" NfcNdefEvent will be fired when a new NDEF message is discovered either via reading a tag or receiving it via P2P communication. The event will contain an array of the received NfcNdefRecords. There are two functions to write NDEF records either to a tag or push them as P2P message.
== Fifth iteration: Secure Element and NFC Privileged API (Firefox OS v2.2) ==
* {{bug|1044428}} b2g-secure-element
** {{Bug|879861}} - NFC Secure Element Support
* {{Bug|1042851}} - (b2g-nfc-privilege) (meta) [NFC] Make NFC APIs available to privileged webapps
** Slide: http://bit.ly/1x7nWp5


  interface Nfc
= Current API =
  {
Check DXR for latest NFC IDL
    [implicit_jscontext] attribute jsval onndefdiscovered;
    [implicit_jscontext] attribute jsval onndefdisconnected;
 
    nsIDOMDOMRequest writeNdefTag(in NfcNDefRecords[] records);
    nsIDOMDOMRequest ndefPush(in NfcNDefRecords[] records);
  };


  interface NfcNdefEvent : nsIDOMEvent
* [https://dxr.mozilla.org/mozilla-central/source/dom/webidl/MozNDEFRecord.webidl MozNDEFRecord.webidl]
  {
* [https://dxr.mozilla.org/mozilla-central/source/dom/webidl/MozNFC.webidl MozNFC.webidl]
    readonly attribute NfcNDefRecords[] ndefRecords; 
* [https://dxr.mozilla.org/mozilla-central/source/dom/webidl/MozNFCPeer.webidl MozNFCPeer.webidl]
  };
* [https://dxr.mozilla.org/mozilla-central/source/dom/webidl/MozNFCPeerEvent.webidl MozNFCPeerEvent.webidl]
* [https://dxr.mozilla.org/mozilla-central/source/dom/webidl/MozNFCTag.webidl MozNFCTag.webidl]
* [https://dxr.mozilla.org/mozilla-central/source/dom/webidl/MozNFCTagEvent.webidl MozNFCTagEvent.webidl]


NDEF records contain a bunch of metadata and a payload that is exposed as a string.
= Usage of APIs =


  interface NfcNdefRecord
https://developer.mozilla.org/en-US/docs/Web/API/NFC_API
  {
    readonly attribute octet tnf;
    readonly attribute DOMString type;
    readonly attribute DOMString id;
    readonly attribute DOMString payload;
  };


== NDEF Read Example ==
= Application Permissions =


  navigator.mozNfc.onndefdiscovered = function (event) {
NFC API has three permissions.
    console.log("Discovered an NDEF message with " + event.ndefRecords.length + " records.");
* '''nfc''', which will be used by privileged applications.
    event.ndefRecords.forEach(function (record) {
* '''nfc-share''', which will be used by ceritified(internal) applications.
      console.log("Found a " + record.tnf + " record" +
* '''nfc-manager', which will be used by System app.
                  " of type " + record.type +
                  " with ID " + record.id +
                  " and payload " + record.payload);
      // Could dispatch event.message here to other web apps based on MIME type, URI, etc.
    });
  };


== NDEF Write Tag Example ==
'''nfc''' permission could be used for  general tag reading/writing, or sending NDEF to NFC Peer.
'''nfc-share''' could be used to send large file (Blob) to another NFC peer.
'''nfc-manager''' is used to control the RF state of NFC hardware.


  navigator.mozNfc.onndefdiscovered = function (event) {
= Application Dispatch Order =
    var ndefRecords = [ new MozNdefRecord(1, "U", "", "\u0000http://mozilla.org") ];
1) Foreground App, if the callback ontagfound/onpeerfound is set.
    var domreq = navigator.mozNfc.writeNdefTag(ndefRecords);
2) If the foreground app doesn't register NFC callbacks or cannot process the event, the event will be redirected to System app, and System app will fire a nfc-ndef-discovered MozActivity.
    domreq.onsuccess = function(e) {
      console.log("Successfully wrote records to tag");
    }
    domreq.onerror = function(e) {
      console.log("Write failed!");
    }
  };


== NDEF P2P Push Example ==
= NFC on B2G emulator =
* See Kami's notes : https://bitbucket.org/kamituel/b2g-notepad/wiki/Using%20emulator


  var ndefRecords = [ new MozNdefRecord(1, "U", "", "\u0000http://mozilla.org") ];
= NFC Resources =
  var domreq = navigator.mozNfc.ndefPush = function (event) {
== Reference ==
  domreq.onsuccess = function(e) {
* Introduction to NFC: http://www.adafruit.com/datasheets/Introduction_to_NFC_v1_0_en.pdf
    console.log("Successfully pushed P2P message");
* NDEF specification: NFCForum-TS-NDEF_1.0.pdf
  }
* Understand NDEF messages : http://developer.nokia.com/Community/Wiki/Inside_NFC:_Understanding_NDEF_message
  domreq.onerror = function(e) {
* NFC forum specifications: http://members.nfc-forum.org/specs/
    console.log("P2P push failed!");
* Handover specification: NFCForum-TS-ConnectionHandover_1_2.pdf
  }


== Implementation ==
== Similar APIs ==
* W3C NFC API:  http://w3c.github.io/nfc/proposals/common/nfc.html
* Tizen NFC API: https://developer.tizen.org/dev-guide/2.2.0/org.tizen.web.device.apireference/tizen/nfc.html
* Android NFC API: http://developer.android.com/reference/android/nfc/package-summary.html


* See {{bug|674741}}
[[Category:Web APIs]]
* Engineers: Markus Neubrand, Arno Puder, Garner Lee, Siddartha Pothapragada, Philipp von Weitershausen

Latest revision as of 05:16, 16 March 2015

Introduction

Current Status (As to Firefox OS v2.2)

  • Gecko b2g-nfc meta bug, bug 860906
  • Gecko b2g-secure-element meta bug bug 1044428
  • Gaia meta bug, bug 933640
  • nfcd meta bug, bug 1044425
  • Gonk
    • Use a native daemon nfcd which links to native NFC library. nfcd github
  • Hardware
    • Using Nexus-4/Nexus-5, which uses Broadcom NFC chipset with libnfc-nci library.
    • Flame, NXP chipsets with libnfc-nci library.

Security Review (By Paul Theriault and Stephanie Ouillon)

Contributors

  • Gecko Engineers: Arno Puder, Garner Lee, Siddartha Pothapragada, Yoshi Huang, Dimi Lee
  • Early Contributors: Markus Neubrand, Philipp von Weitershausen

Roadmap

First iteration: NDEF (Firefox OS v1.3)

  • meta bug, bug 959692 - (b2g-NFC-1.3) [meta] FxOS v1.3 NFC feature
  • Technologies:
    • Focus on NDEF standard only for now
    • Others (e.g. proprietary MIFARE) to be investigated later.
  • Capabilities:
    • Read/write NDEF records on tags
    • bug 933136 - [Gecko] NFC onpeerready, onpeerlost callbacks
  • Implementation:
    • See bug 674741
    • NDEF-only API is available on MozNFCTag object.
    • Discovered NDEF tags are automatically parsed and dispatched to content in the "nfc-manager-tech-discovered" system message.
    • navigator.mozNfc only available to a specific privileged content page (cf. WebTelephony, WebSMS).
    • For now, content is expected to do filtering and dispatching to handlers e.g. via WebActivity.
  • Gonk
    • bug 906579 - B2G NFC: NFC Daemon for supporting libnfc-nci
  • Hardware
    • Using Nexus-4, which uses Broadcom NFC chipset with libnfc-nci library.

Second iteration: Handover and other bug fixes (Firefox OS v1.4)

  • meta bug : bug 949293 - (b2g-NFC-1.4) [meta] FxOS v1.4 NFC feature
  • Capabilities:
    • bug 933093 NFC handover.
    • bug 916863 - [NFC] NFC support in emulator
    • NFC Manager API
      • bug 952217 - [B2G][NFC] Have a separate NFC application API and NFC Manager API
      • bug 959437 - Refactor NfcManager APIs and implementation details to support sendFile , notifyUserAcceptedP2P and other privileged Nfc operations

Third iteration: NFC Sharing feature, P2P, emulator support, test cases (Firefox OS v2.0)

  • meta bug : bug 949293 - (b2g-NFC-2.0) [meta] FxOS v2.0 NFC feature
  • NFC emulator: bug 973133
  • More Gaia unit tests for NFC in apps/system/test/unit/

Fourth iteration: HCI transaction event (Firefox OS v2.1)

Fifth iteration: Secure Element and NFC Privileged API (Firefox OS v2.2)

Current API

Check DXR for latest NFC IDL

Usage of APIs

https://developer.mozilla.org/en-US/docs/Web/API/NFC_API

Application Permissions

NFC API has three permissions.

  • nfc, which will be used by privileged applications.
  • nfc-share, which will be used by ceritified(internal) applications.
  • nfc-manager', which will be used by System app.

nfc permission could be used for general tag reading/writing, or sending NDEF to NFC Peer. nfc-share could be used to send large file (Blob) to another NFC peer. nfc-manager is used to control the RF state of NFC hardware.

Application Dispatch Order

1) Foreground App, if the callback ontagfound/onpeerfound is set.
2) If the foreground app doesn't register NFC callbacks or cannot process the event, the event will be redirected to System app, and System app will fire a nfc-ndef-discovered MozActivity.

NFC on B2G emulator

NFC Resources

Reference

Similar APIs

Retrieved from "https://wiki.allizom.org/index.php?title=WebAPI/WebNFC&oldid=1062089"