September 17, 2012

Getting started with AppNearMe

In this post we will look at how to get started with the AppNearMe platform to develop your first NFC application.

Gather all the building blocks

To develop your NFC solution, you'll need:
  • A NFC Smartphone
  • A NFC device
  • A development PC

NFC Smartphone

The Smartphone must be NFC-enabled and run Android 4.0+. Compatible phones include the Google/Samsung Nexus S, Galaxy Nexus, Samsung Galaxy SIII, HTC One X. For a more extensive list see http://en.wikipedia.org/wiki/List_of_NFC-enabled_handsets#Android.

NFC Device

Your NFC object must use the µNFC stack. A good starting kit is Adafruit's NFC starting kit that contains a mbed (ARM development module) and a PN532 development board (NFC controller).
To get started with this kit look at the PN532 breakout board getting started page on the mbed website.

Developing the smartphone app

First of all, you need to register on the AppNearMe website. Once it is done, connect and go to your Dashboard. From there you can create your first app; if it is the first app you are creating on the platform, you will be asked to associate a Dropbox account. Your development directory will be created in this Dropbox under the /Applications/AppNearMe/[YourApp] path. It is worth noting that the platfom can only access the /Applications/AppNearMe/ scope of your Dropbox.

HTML5 & JavaScript API

In this directory you can create an index.html file which will be the entry point to your app. Feel free to add any needed image, JS, CSS file to this directory as well. 
Developing an app for the AppNearMe platform is actually like developing an HTML5 webapp, with extra possibilities.
For instance, you can use popular UI frameworks such as jQueryMobile to develop your app.
There are two functions that you can use from Javascript to communicate with the NFC device. To use them include the two following lines in your <head> section:
<script type="text/javascript" charset="utf-8" src="cordova.js"></script>
<script type="text/javascript" charset="utf-8" src="appnearme.js"></script>

Reading from the device

To read from a device, call window.AppNearMe.read(successCallback, errorCallback)

successCallback will be called if the transaction is successful and passed with an object (packet) containing the piece of data transmitted by the NFC device.

packet is an object containing data transmitted by the device; this packet will have the following structure:

{ "data" : [ [5, "hello", [1, 2, 3], 459241] ] }

packet["data"][0] contains a list of objects from the following: 8bit unsigned numbers, 32bit unsigned numbers, strings, byte arrays.

errorCallback will be called if there is an error during data transmission and is passed with a message describing the reason of the failure.

Here is an example of how to use the read method:

function onRead(packet)
{
  //Retrieve data packet 0
  var data = packet["data"][0];
  var number = data[0];
  var string = data[1];
  //Do something with that
  ...
  //Do not forget to register for the next read
   enableRead();
}

function enableRead()
{
  //On error, write the reason to the console and register for next callback
  window.AppNearMe.read( onRead, function(e){console.log(e); enableRead();}); 
}

//This event will be called when the app is ready
document.addEventListener('deviceready', function() {
  enableRead(); //Register for next read callback
}, true);


Writing to the device

To write to a device, use window.AppNearMe.write(packet, successCallback, errorCallback)

packet is an object containing data to transmit to the device; this packet must have the following structure:

{ "data" : [ [5, "hello", [1, 2, 3], 459241] ] }

packet["data"][0] must contain the list of objects from the following: 8bit unsigned numbers, 32bit unsigned numbers, strings, byte arrays.

successCallback will be called if the transaction is successful.

errorCallback will be called if there is an error during data transmission and is passed with a message describing the reason of the failure.

Example:

function writeOk(callback)
{
  //Tell user that write was successful
}

function writeFailed(e)
{
  console.log(e);
  //Tell user that write has failed
}

function write(data)
{
  var packet = {"data":[data]};
  window.AppNearMe.write(packet, writeOk, writeFailed);
  //Show the user that a write is pending
}


Embedded software

To get started with the µNFC stack you can follow this documentation: http://mbed.org/cookbook/munfc-stack

To communicate with your app you need to specify the "app hash". You can find the value for this parameter within your Dashboard.

Trying it out

Go back to your Dashboard, and click the "Edit" button for your app.

This page allows you to retrieve the development version of your app from your Dropbox. Click "Refresh" and you should see a list of the files used by your app. When you change something in your Dropbox, just click "Refresh" again and any changes of your app will be pulled.

You can download the AppNearMe Developer application on your Android device here: https://play.google.com/store/apps/details?id=com.appnearme.developer
Launch this app, type your email & password and you should see a list of your apps. Click on one element of the list to launch the corresponding app. From there you can test your app before making it available to users. If you want to pull the latest version of the app after some changes, open the Android context menu and click "Refresh".

Publishing the app

Once you are satisfied with the first version of your app, you can publish it to make it available from the AppNearMe application (with no authentication needed). Just go back to your Dashboard, click "Edit" and then "Publish".
Please note that the free version of the platform limits you with 5 simultaneous device installs of your app. If you need this limit increased, contact us.
At this point, a new development version is created: that way you can add features to your app without risking to break something in the published version!

More information

For more information, feel free to contact us.