First you need to download the Android SDK from the Android Developer site. Android recommends that you download the Android Developers Toolkit (ADT) bundle, which includes a bundled version of the Eclipse development environment. We’re not using Eclipse for this book, however, so you can just download the SDK tools for your platform, which should take less time to download. To do that, click “Use an Existing IDE” at the bottom of the “Download” page and you’ll get a link to download just the SDK tools without Eclipse.

export ANDROID_HOME=/Applications/android-sdk-macosx
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

;%ANDROID_HOME%	ools
;%ANDROID_HOME%platform-tools
;%JAVA_HOME%in
;C:Antin

export PATH=/usr/local/share/npm/bin:$PATH

$ npm install -g cordova

> npm install -g cordova

cordova create project-location package-name app-name

cd /path/to/project-location
cordova platform add android

Change directories to whatever directory you like to keep projects in (perhaps your Documents directory) and use the cordova create command to create a project:

$ cordova create ~/Hello com.example.hello Hello

There is no output from create if it succeeds, but it will create a new directory. This command will create a directory in your working directory called Hello. Change directories to it and list the files:

$ cd ~/Hello
$ cordova platform add android
$ ls

On Windows, the commands will be a little different. Open a Command Prompt (by default, it will place you in your home directory, usually C:Usersusername), but to be sure, you might want to change directory to it first with cd /D %userprofile% (in most configurations, the %USERPROFILE% environment variable contains your home directory). You can, of course, run these commands in another working directory:

> cd /D %userprofile%
> cordova create Hello com.example.hello Hello
> cd Hello
> cordova platform add android
> dir

On all three platforms, the directory will contain the following structure:

The platforms/android directory contains the following:

On Windows, you may need to install a USB driver for your device. When you updated the SDK earlier, you got USB drivers for many devices. However, even flagship devices like the Nexus 7 may require a separate driver installation. For example, you can download the Nexus 7 driver from ASUS. See Android’s USB Drivers page for instructions on installing drivers that are included with the Android SDK.

You’ve got everything you need here to run a very basic app that does nothing but display a splash screen. To compile and install it on your device, connect the device over USB and run the following command if you are on OS X or Linux:

$ cordova run

If you’re on Windows, run this command:

> cordova run

When everything’s ready, you’ll be running your app directly on your Android phone or tablet.

Finally, open the phone and launch the Hello Application. You should see a screen like that in Figure 3-1. Once you’ve got the basic “Hello, World!” application running, try modifying the index.html to make it more fancy. It lives in the www directory. Add buttons, images, and all the other things you’d add to an HTML page. Then save your files, run it again, and see how it changes on your phone.

Figure 3-1. The PhoneGap HelloWorld app

There are two files you’ll work with frequently in your PhoneGap projects: the index.html in the www directory, and the index.js file in the www/js directory. You can add other HTML and JavaScript files, but by convention, these will be the root of your application. These are the files you’ll modify to make your app do what you want.

The index.html page will include the graphic layout of your application, just as it would for any website. The index.js contains event handlers, like onDeviceReady(), initialize(), and so forth. Later on you’ll add some functions to it, like onNfc() for when a tag is read.

You can always get an unmodified version of the default file structure by creating a new project.

There are a few other JavaScript files that affect your application that you’ll likely never see: the cordova.js file, the cordova_plugins.js file, and its companion, the cordova_plugins.json file. The cordova.js file is the main PhoneGap library. The cordova_plugins.js and cordova_plugins.json files initialize the plug-ins you install, giving you access to the PhoneGap-NFC library and the NFC hardware. These show up in platforms/android/assets/www when you install plug-ins and run your app.

function toggleCompass() {

}
function init() {

}

toggleCompass()

var app = {
   initialize: function() {

   },

   bindEvents: function() {

   },

   onDeviceReady: function() {

   }
}

app.initialize();
app.bindEvents();
app.onDeviceReady();

There are a number of changes needed to add NFC support to your project. These are all automated by the command:

$ cordova plugin add /path/to/plugin

The one you’ll use commonly throughout the book is:

$ cordova plugin add https://github.com/chariotsolutions/phonegap-nfc.git

So you understand what’s going on under the hood, here’s what’s installed:

Since that’s a lot to remember, it’s nice that the one-line plug-in add command does it all for you.

You’ve already created your project using the create command, as directed earlier. Next, change directories to the root of your project and add the plug-in as described at the beginning of this section like so:

$ cd ~/NfcReader
$ cordova plugin add https://github.com/chariotsolutions/phonegap-nfc.git

> cd /d %userprofile%NfcReader
> cordova plugin add https://github.com/chariotsolutions/phonegap-nfc.git

This installs the NFC plug-in from its online repository in the current working directory.

Now that you’ve got all the assets in place, it’s time to make the application itself. You’ll have two files you need to edit for this project:

This app will listen for NFC-compatible RFID tags and print their IDs on the screen.

Start with index.html as before. Here’s a bare-bones page, much like the Locator app’s index page. The changes are that you’re adding a call to the Cordova script at the end of the body and you’re changing the elements of the app div in the body. The latter is where tag IDs will be displayed.

Open index.html and replace it with the following code, then save the changes:

<!DOCTYPE html>

<html>
   <head>
      <title>NFC tag ID reader</title>
   </head>
   <body style="font-size: 1.5em">
      <div class="app">
         <div id="messageDiv"></div>
      </div>
      <script type="text/javascript" src="cordova.js"></script>
      <script type="text/javascript" src="js/index.js"></script>
      <script type="text/javascript">
       app.initialize();
     </script>
   </body>
</html>

The index.js file will have an event handler to listen for NFC tags and rewrite the message div when it gets a tag. As before, start by initializing the app variable, and adding an initialize() function and a bindEvents() function:

var app = {
/*
   Application constructor
*/
   initialize: function() {
      this.bindEvents();
      console.log("Starting NFC Reader app");
   },

/*
   bind any events that are required on startup to listeners:
*/
   bindEvents: function() {
      document.addEventListener('deviceready', this.onDeviceReady, false);
   },

The onDeviceReady() function is a bit more complex this time. You need to add a listener for when tags are discovered by the NFC reader. The nfc.addTagDiscoveredListener() function tells the NFC plug-in to notify your app when any NFC tag is read. The first argument is the event handler that is called when a tag is scanned. The second and third arguments are the success and failure callbacks for the plug-in initialization. When it succeeds, it will call the onNfc() function. When the listener is initialized, it’ll let you know, and when it fails, it’ll give you failure messages as well.

The addTagDiscoveredListener() handler is one of a few different listeners you can use from the NFC library. It’s the most generic. It doesn’t care what’s on the tag, it just responds whenever it sees a compatible tag:

/*
   this runs when the device is ready for user interaction:
*/
   onDeviceReady: function() {

      nfc.addTagDiscoveredListener(
         app.onNfc,             // tag successfully scanned
         function (status) {    // listener successfully initialized
            app.display("Tap a tag to read its id number.");
         },
         function (error) {     // listener fails to initialize
            app.display("NFC reader failed to initialize " +
               JSON.stringify(error));
         }
      );
   },

The onNfc() function takes the tag read in an NFC event and prints it to the screen using display(), just as you saw in the Locator app. These are the last functions in the app:

/*
   displays tag ID from @nfcEvent in message div:
*/
   onNfc: function(nfcEvent) {
      var tag = nfcEvent.tag;
      app.display("Read tag: " + nfc.bytesToHexString(tag.id));
   },

/*
   appends @message to the message div:
*/
   display: function(message) {
      var label = document.createTextNode(message),
         lineBreak = document.createElement("br");
      messageDiv.appendChild(lineBreak);         // add a line break
      messageDiv.appendChild(label);             // add the text
   },
/*
   clears the message div:
*/
   clear: function() {
       messageDiv.innerHTML = "";
   }
};     // end of app

The full source listing for this application can be found on GitHub.

That’s all the changes. Save both files, then change directories to the root of the project if you’re not already there, and compile and install the application:

$ cd NfcReader
$ cordova run

> cd /d %userprofile%NfcReader
> cordova run

This launches the NFC Reader application. When it’s up and running, bring a tag close to the phone, and you should get a message saying “Read tag” followed by the UID, in hexadecimal notation, as shown in Figure 3-4. Try with another tag and you’ll see another UID.

$ cd projectDirectory
$ android update project -p platforms/android/

platforms/android/local.properties
platforms/android/bin
platforms/android/gen
platforms/android/assets/www

Figure 3-4. The NFC Reader app reading a tag

This will work with any RFID tag that’s compatible with your NFC reader. That includes all tags compatible with the ISO-14443A format, including Philips and NXP Mifare tags, Sony FeliCa tags, NXP DESFire. You’re not yet reading or writing data to the tag; you’re just reading the tag’s unique ID. For this application, compatible tags are not as much of an issue as when you start to write NDEF records to the tags. You’ll find that this app can read Mifare Classic tag IDs even on those devices that are supposedly incompatible with Mifare Classic.

You’ve proven that your device’s reader works, and can be programmed to read tags. In the next chapter, you’ll learn how to read from and write to tags using the NFC Data Exchange Format, NDEF.

If your app doesn’t read any of your tags, here are a few things to check: