Near Field Communications With Rhodes In-Depth Tutorial

This tutorial will guide you through running near field communications with Rhodes, both in the Android emulator and on an Android device. Near field communication is very similar to RFID, and you can even use near field communications to read RFID tags. It has features to have two devices communicate with each other, as well as act as mobile business cards.

• Source Code
• Webinar Video
• Pre-requisite Reading
• Setup
• Preparing the NFCDemo Project
• Getting the nfc-rhodes Application

Source Code

The source code for this example is located here.

• Rhodes Webinar Sample for nfc-rhodes

Webinar Video

Vimeo link

Pre-requisite Reading

• RhoStudio Tutorial
• RhoMobile Suite install
• Rhodes Installation from command line
• Rhodes NFC
• Android SDK

Setup

This tutorial assumes that you know how to edit a Rhodes application, and that you have Rhodes version 3.0.1 or higher. It assumes that you have installed Android SDK level 2.3.3, and set paths in your profile to your Android SDK and its tools folder. It also assumes that you have installed Google APIs:10 (which is based on Android 2.3.3), and that you created an AVD (Android Virtual Device) for the Google API. If you do not know how to do this, see Pre-requisite Reading.

If you have any Android SDK installed, you can check to see if it has Android 2.3.3 and Google APIs:10. Go to your tools folder in your Android SDK and run android. In the Android SDK and AVD Manager, click Installed packages. If you do not see SDK Platform Android SDK 2.3.3 and Google APIs by Google Inc., Android API 10 in the list of installed packages, click on Available Packages, find them, and install them. Also click Virtual Devices and check that you have an AVD (Android Virtual Device) set up for Google API level 10; create one if you do not.

The webinar and this tutorial show Android running from the command line, rather than an IDE such as Eclipse. You can also run from Eclipse.

In the Build for Android section of the Build Rhodes Application, you set a path to your Android SDK. Since you will run the adb command from the NFCDemo folder, you should set a path to adb in your profile. For example, on the Macintosh, in .bash_profile, you set a path to the Android SDK platform-tools folder.

Preparing the NFCDemo Project

You need to build the NFCDemo project and add a Java library to it.

Note: If you already built the NFCDemo app and added the Java library, but you added timer code and commented out some original code (as is done in one of the Rhodes webinar/tutorials for NFC), you should comment out the timer code and make sure the original code is uncommented, then build that and install it into the Android emulator. This tutorial assumes that you are using the original NFCDemo application as supplied in the Android SDK.

Building the NFCDemo Project

Navigate to the location of your Android SDK. For example, people who installed the SDK into their Eclipse on a Macintosh might navigate to /Applications/eclipse/android-sdk-mac_86.

Within your Android SDK folder, navigate to /samples/android-10/NFCDemo.

$ cd samples/android-10/NFCDemo

Check the lists of Android targets that you have.

$ android list targets

This will show you a list of all the Android versions you have. You want Google APIs:10 (which is based on Android 2.3.3). It will look like this:

id: 20 or "Google Inc.:Google APIs:10"
     Name: Google APIs
     Type: Add-On
     Vendor: Google Inc.
     Revision: 1
     Description: Android + Google APIs
     Based on Android 2.3.3 (API level 10)
     Libraries:
      * com.google.android.maps (maps.jar)
          API for Google Maps
     Skins: WVGA854, WQVGA400, HVGA, WQVGA432, WVGA800 (default), QVGA

Now run the Android command to generate the build scripts for the NFCDemo project. Set the -t parameter to the id number for your Android with Google APIs level 10 or higher; the id is 20 in the above example. Set the -p parameter to the path to your Android SDK, samples folder, Android Google APIs level 10 folder, NFCDemo project.

$ android update project -s -n "NFC Demo" -t 20 -p /Applications/eclipse/android-sdk-mac_86/samples/android-10/NFCDemo

Run ant debug to try to build the application. (It will fail, but run it anyway.)

$ ant debug

Installing the Java libraries into NFCDemo

You will get errors after you try ant debug because you also need some Java libraries for the NFCDemo project to work. Go to code.google.com/p/guava-libraries/downloads/list. Download the latest zip file, which is named something like guava-r09.zip. Unzip the file and copy the jar file (in this example, guava-r09.jar) into your libs folder in the NFCDemo project. (Since this libs folder is generated with the build command, you had to try to build and fail, then you have the libs folder into which you copy the guava jar file.)

Running the NFCDemo Project

Run ant debug to build the application.

$ ant debug

Running the Android Emulator

Run the Android SDK and AVD Manager: this is the app labeled “android” in your tools folder, which is within your Android SDK installation folder.

The Android SDK and AVD Manager should be set up to run an AVD for Android with Google APIs level 10 or above, which is the minimum required for near field communication. Highlight that AVD and click Start to start the Android emulator.

Installing NFCDemo into the Android Emulator

Now install your NFCDemo app into the Android emulator that you are running. From the command line, within your NFCDemo folder:

$ adb install bin/NFC\ Demo-debug.apk

In the Android emulator, the NFCDemo app should be running. The NFCDemo app lets you generate NFC tags that you can receive in a Rhodes Android application.

Getting the nfc-rhodes Application

You can go to the source code for the Rhodes Webinar Sample for nfc-rhodes, a Rhodes project which receives nfc tags, is stored. You can copy this project to your local computer.

Checking the Rhodes Application for NFC

Open the nfc-rhodes project in your text editor. In the build.yml file, make sure there is an android section which has the nfc extension, and a version of at least 2.3.3.

android:
  version: 2.3.3
  extensions:
  - nfc

Hooking and Processing the NFC Events from the nfc-rhodes app

Rhodes provides a hook called on_activate_app that is called every time an application using this hook launches, and when the application comes in from the background. The on_activate_app hook is used in the nfc-rhodes project, where it enables nfc and sets a couple of callbacks. When the nfc event occurs (set_nfc_callback), it will make a callback request to the controller action app/Nfc/nfc_callback. When the app receives a tech callback (set_nfc_tech_callback), it will make a callback request to the controller action app/Nfc/nfc_tech_callback. Also, perform_open_application_event processes the event in the callback (it says, okay, Rhodes, process the nfc event).

def on_activate_app
  Rho::NFCManager.enable

  Rho::NFCManager.set_nfc_callback("/app/Nfc/nfc_callback")
  Rho::NFCManager.set_nfc_tech_callback("/app/Nfc/nfc_tech_callback")

  Rho::NFCManager.perform_open_application_event
end

Controlling the NFC Event

In app/Nfc, a few files that were generated by Rhodes, and that were not needed for this nfc example, are deleted; such as edit.bb.erb, edit.erb, new.bb.erb, new.erb, show.bb.erb, and show.erb (we won’t be editing, creating, or showing models or their attributes). Also, the actions for these in app/Nfc/nfc_controller.rb are deleted also (show, new, edit, create, update, delete), leaving the index action.

The index action has been edited so when the page first launches, it displays the status of Nfc, to see if nfc is turned on or not.

Displaying the NFC Event in the View

We need to display information in the view for the nfc-rhodes application: app/Nfc/index.erb.

In app/Nfc/index.erb, the top toolbar that was generated by Rhodes \

<div class="content">
  <ul>
    <!-- show the nfc status -->
    <li>
    NFC Enabled: <span class="title"><%= @nfc_status %></span>
    </li>
    <!-- show the log information, content of nfc tag -->
    <li>Log:</li>
    <input type="text" style="font-style: bold" id="id_log" value="" />  
    <input type="button" value="Clear" onClick="onLogClear();"/>
  </ul>
</div>

<script type="text/javascript">
function setLog(log) {
  document.getElementById("id_log").value = log;
}

function onLogClear() {
  document.getElementById("id_log").value = "";
}
</script>

def nfc_callback
  @log = "TAG received: #{Time.now.strftime('%H:%M:%S')}"
  add_to_log(@log)
end

def add_to_log(msg)
  WebView.execute_js('setLog("'+msg+'");')
end

# startup page for your application
start_path = '/app/Nfc'

require 'nfc'

$ rake run:android

ant debug
adb install bin/NFC\ Demo-debug.apk

adb logcat

$ rake run:android:device

def nfc_tech_callback
  # assign message that nfc tag received, and update the view
  @msg = 'Tech received! Reading tag...'
  add_to_log(@msg)

  # get_current_tag from the [Rhodes NFC API](/rhodes/nfc)
  tag = Rho::NFCManager.get_current_Tag
  if tag != nil
    @msg = test_ndef_read(tag)
  else
    @msg = "Tag is nil!"
  end
  add_to_log(@msg)
end

def test_ndef_read(tag)
  result = "No records..."  # assign return in case processing does not work
  # get the tag technology to find out how to process it; it is an ndef tag
  ndef = tag.get_tech(Rho::NFCTagTechnology::NDEF)
  if ndef != nil
    # connect to the ndef tag
    ndef.connect
    # read the ndef tag message and get the records from it.
    msg = ndef.read_NdefMessage
    records = msg.get_records

    # for debugging, print out
    puts "msg: #{msg.inspect}"
    puts "records: #{records.inspect}"

    # iterate through the array of records and hash the record
    # we know we have only one tag, so the array has only one element
    r_a = []
    records.each do |record|
      r_a << record.make_hash
    end

    # assign to a variable and print it out
    msg_hash = { 'records' => r_a }
    puts "records after processing: #{msg_hash.inspect}"

    # Assign the string payload from the hash to the result
    # Return the result to nfc_tech_callback for display in add_to_log
    result = "Tag Result: " + msg_hash['records'][0]['payload_as_string'] if msg_hash['records'].size > 0
    # Close connection to the tag
    ndef.close
  end
  result
end