Chapter 1. Getting Started with NFC

In this chapter, we will cover the following topics:

Requesting NFC permissions
Indicating that your app uses NFC
Defining minimal requirements
Verifying whether the device has an NFC controller
Downloading Open NFC Android Edition
Downloading Open NFC SDK Edition
Configuring the Open NFC Android add-on into your Android SDK
Configuring an NFC-enabled testing AVD
Configuring the Connection Center tool
Testing your app all together

Introduction

We live in a world that is constantly changing, and every day, new and innovative technologies emerge which make daily life easier and more convenient. Near Field Communication (NFC) is one of these new technologies. It allows users to exchange digital content between devices with a simple touch. It is a short-range RFID technology that is currently being introduced in smartphones and used for mobile payments, mobile ticketing, marketing, identification mechanisms, and other such cool applications.

NFC is specified by the NFC Forum, http://nfc-forum.org/, which promotes the implementation and definition of the NFC standards for interoperability of devices and services. The biggest differences among the common RFID technologies are the communication distance, which is limited to about 10 centimeters, and the ability for bidirectional communication.

By now, you are probably thinking, why do I need another adapter on my smartphone? This will be another battery-draining feature that most probably will be disabled most of the time. Well, that's not exactly the case when we talk about NFC. It is specially designed to have a very small battery consumption footprint so that it can be enabled all the time, thus avoiding the annoying rituals of enabling and disabling the adapter when we need to use it.

However, you might think you can't send large amounts of data; that's true, but it doesn't matter! We already have other good and reliable alternatives such as Bluetooth or Wi-Fi Direct for that. So, why would we need another super-fast, battery-drainer adapter? With NFC, things are kept simple. There's no need to pair devices, it can be constantly turned on, and it takes less than one-tenth of a second to establish a connection between devices.

Then you may think that what you really want is to keep the battery consumption low and still be able to transfer bigger files. In cases like these, we can use the best of both worlds. For example, we can use NFC to transfer a small data block that contains the necessary information for a successful Bluetooth pair, then turn Bluetooth on, pair the devices, transfer the files, and turn it off again. All of this is done automatically and with a seamless user experience. That too with just one tap!

NFC communication can be established between two NFC-enabled devices or between a device and a tag. One of the entities in the communication process will act as active and will be responsible for sending, reading, or writing the data, and the other will act as passive. There are three main operation modes:

Reading and writing: In this mode, a device reads and writes data to/from a tag.
Peer to Peer (P2P): In this mode, a P2P connection is established between two devices.
Host Card Emulation (HCE): In this mode, a device emulates the behavior of a tag/card. For example, we can use our smartphone as if we are using several payment cards.

This book will focus only on the first two modes. HCE is available from Android 4.4 KitKat, onwards and you should have a look at this amazing feature at http://developer.android.com/guide/topics/connectivity/nfc/hce.html

In this first chapter, we will create a very simple application that will allow us to cover the first steps needed in all applications that use NFC, as well as cover how to set up a working virtual testing environment.

Requesting NFC permissions

As Android developers, we are accustomed to using the manifest file to request permission to use a specific device feature, and NFC is no exception to this.

Getting ready

Make sure you have an NFC-enabled Android device or a virtual test environment—refer to the Testing your app all together recipe.

How to do it…

We will start by creating an Android project where we will request the correct permissions, as shown in the following steps:

Open Eclipse and create a new Android application project named NfcBookCh1Example1 and a package named nfcbook.ch1.example1, as shown in the following screenshot:
Make sure you select API 10: Android 2.3.3 (GingerBread) in the Minimum Required SDK field.
When prompted to create an activity, select Blank Activity.
Open the AndroidManifest.xml file located in the project's root and add the following code just before the application node:
```
<uses-permission android:name="android.permission.NFC"/>
```

How it works…

Android requires every app to request permissions from the user to allow the application to perform restricted actions. Examples of restricted actions include access to users' current location, permission to send an SMS without user interaction permission to, read contacts, and many others. This is done in the AndroidManifest.xml file using the <uses-permission/> node. Permissions are granted by the user when the application is installed. Requesting unnecessary permissions may cause users to not trust the application and refrain from installation. If we do not request permissions in the manifest and try to do restricted actions, an exception is thrown and the application will not work correctly.

Indicating that your app uses NFC

This step isn't required, but it is always good practice to specify the features used in our app manifest file—if it is indeed a required feature for our application to work correctly. Google Play Store uses this information to filter the apps visible to users based on their device's specifications. Users with incompatible devices will be able to install the application if we don't specify this, and we don't want that. We don't want users to get frustrated with a non-working application and give us negative feedback.

How to do it…

We are going to continue adding functionality to the previously created project by declaring the features required by our application in the manifest as follows:

Open the NfcBookCh1Example1 project created in the previous recipe.
Open the AndroidManifest.xml file located in the project root and add the following code just before the application node. Since NFC is a required feature in our application, we should also set the required attribute to true, as shown in the following line of code:
```
<uses-feature android:name="android.hardware.nfc"  android:required="true" />
```

How it works…

The Android market uses this information in the manifest to filter the apps visible to the users. This way, if your device doesn't support a required feature of an app, there's no need for that app to appear listed; it will still be listed on the website but we cannot install it since it's incompatible. This application node is not required, but it's a good idea to place it. Otherwise, the user will be disappointed with the app—it will probably just crash or show an an error occurred! message. Users don't like that, and this results in a bad rating.

An alternative is to have multiple approaches for the same result. For example, if the user's device isn't NFC enabled, use a QR code instead (when applicable).

Defining minimal requirements

Defining minimal requirements is a very important step since only users with minimal requirements will be able to run our application properly.

NFC was introduced in Android Version 2.3, API level 9, although some very important features, such as being able to get an instance of the NFC Adapter, were only introduced in API level 10. This is the minimum API level we can work with. Users with previous versions of Android will not be able to use our NFC applications unless a fallback alternative is added.

How to do it…

We are going to define the minimum required version of Android to enable our application to use NFC features, as follows:

Open the previously created NfcBookCh1Example1 project.
Set the minimum SDK version to 10 with the following code:
```
<uses-sdk android:minSdkVersion="10" />
```

How it works…

When we add the previous line to the manifest file, Eclipse will automatically scan our code and warn us of incompatible pieces of code. This is also used in the market to filter searches for apps that our devices are able to run. NFC-related features are consistently being added and improved in the latest Android releases; so, depending on your application specifications, you may need to target a higher version.

Verifying whether the device has an NFC adapter

The very first lines of code we write in an app that uses NFC should be a simple validation that tests for the NFC adapter.

How to do it…

We'll create an application that shows a Toast saying whether the device has the NFC adapter, as follows:

Open the previously created NfcBookCh1Example1 project.

Open MainActivity located under nfcbook.ch1.example1 and place the following code inside the onCreate method:

NfcAdapter nfcAdapter = NfcAdapter.getDefaultAdapter(this);

if (nfcAdapter != null && nfcAdapter.isEnabled()) {
  Toast.makeText(this, "NFC is available.", Toast.LENGTH_LONG).show();
} else {
  Toast.makeText(this, "NFC is not available on this device. This application may not work correctly.", 
Toast.LENGTH_LONG).show();
}

Run the application and try enabling and disabling NFC and see the different results.

How it works…

Android provides a simple way to request the Adapter object by calling getDefaultAdapter([context]). If a valid NfcAdapter instance is returned, the NFC adapter is available; however, we still need to check if it is enabled by calling the isEnabled() method. Otherwise, we need to inform the user that the application may not function correctly as NFC is a required feature. Testing the result for a null value is the simplest way to know if NFC is available to us. However, we can also use the hasSystemFeature method from the PackageManager class to do this validation.

There's more…

Testing for NFC is an operation that we will probably do very often. So, we can create a simple method and call it every time we need to test for NFC, as shown in the following code:

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  setContentView(R.layout.activity_main);

  if (hasNfc()) {
    Toast.makeText(this, "NFC is available.", Toast.LENGTH_LONG).show();
  } else {
    Toast.makeText(this, "NFC is not available on this device. This application may not work correctly.", Toast.LENGTH_LONG).show();
  }
}

boolean hasNfc() {
  boolean hasFeature = getPackageManager().hasSystemFeature(PackageManager.FEATURE_NFC);
  boolean isEnabled = NfcAdapter.getDefaultAdapter(this).isEnabled();
  
  return hasFeature && isEnabled;
}

Downloading Open NFC Android Edition

Application development using a virtual device is very popular in Android. Using virtual devices lets you use adapters that you may not have in your real device and test your application in several Android versions. The NFC adapter is no exception; so, even if your smartphone isn't an NFC-enabled device, there is no excuse not to use this awesome technology.

Android SDK tools provide us with Android Virtual Devices (AVD), which are device emulator configurations that allow us to configure hardware and software options. Open NFC Android Edition allows us to create an NFC-enabled AVD since there is no native support for that. We can then simulate a tag tap or a P2P tap, and the correct intent is launched like it would be in a real device.

Getting ready

The following are the settings required for this recipe:

Make sure you have a working Android development environment. If you don't, ADT Bundle is a good start. You can download it from http://developer.android.com/sdk/index.html.
It is assumed that Eclipse is the development IDE for Android.

How to do it…

We are going to download, extract, and verify the Open NFC files that are needed to get our virtual test environment up and running, as shown in the following steps:

Open a new browser window and navigate to http://open-nfc.org.
On the left navigation menu, click on Downloads.
On the download list, select the 4.4.1 Open NFC for Android release. The download link's name should be Android Edition (SDK).
At the time of writing this book, the current Open NFC release is 4.5.2 for Android 4.2.1, Jelly Bean; however, since this version has been reported to be faulty several times, we will use an older but stable version.
Create a folder named NFCBook in your home directory and extract the downloaded archive.
There should be a folder named android_sdk and at least one folder named OpenNFC_AddOn in it, where we will find an Android image on which we will create our AVD.

Downloading Open NFC SDK Edition

Open NFC SDK Edition allows us to connect to the AVD, log in NFC communications, and simulate different tag taps and P2P taps.

How to do it…

We are going to download, extract, and verify the files used to connect the AVD to the NFC Simulator that allows us to test the NFC application without a physical NFC-enabled device with the following steps:

Open a new browser window and navigate to http://open-nfc.org.
On the left navigation menu, click on Downloads.
On the download list, select the 4.4.1 SDK release.
Extract the downloaded archive to the previously created NFCBook directory.
There should be a folder named core in it and at least two folders named connection_center and nfcc_simulator. The nfcc_simulator folder will allow us to simulate a tag tap or a P2P connection. The connection_center folder contains the software that allows the simulator to communicate with the AVD.

Configuring the Open NFC Android add-on into your Android SDK

In this recipe, we will see how to set up the Open NFC Android Edition add-on in our existing Android SDK installation.

Getting ready

The following are the settings required for this recipe:

Make sure that the Android SDK and the Open NFC add-on target Android version is installed. Since the Open NFC version used is targeting Android ICS 4.0.3, we need to have Android API level 15 installed. Navigate to https://developer.android.com/sdk/installing/adding-packages.html for instructions on how to install packages.
Make sure you have downloaded Open NFC Android Edition—refer to the Downloading Open NFC Android Edition recipe.
It's assumed that the Android SDK location is known and that Open NFC Android Edition was previously downloaded and extracted to the NFCBook folder in your home directory.

Note

Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.

How to do it…

We are going to configure the previously downloaded Open NFC plugin into our Android SKD installation as follows:

Open the NFCBook folder and navigate to the Open NFC for Android Edition folder.
Copy the add-ons folder located inside the OpenNFC_AddOn folder to your clipboard.
Navigate to the Android SDK installation folder.
Paste the add-ons folder from your clipboard (copied in step 2) to the Android SDK folder. If asked to merge the two folders, select yes.
Start Android SDK Manager by installing the SDK Manager.exe file on Windows. You should see the Open NFC add-on under the Android version item, as shown in the following screenshot:

How it works…

The add-ons folder in Open NFC Android Edition contains a modified image of the Android system. This modified image contains the simulator for the NFC controller.

Configuring an NFC-enabled testing AVD

We will create and configure an AVD based on the Open NFC Android Edition image. This virtual device will be able to exchange data between the NFC Simulator tool and therefore allows us to test our applications.

Getting ready

The following are the settings required for this recipe:

Make sure Open NFC Android Edition is properly configured in the Android SDK—refer to the Configuring the Open NFC Android add-on into your Android SDK recipe
Make sure you have downloaded Open NFC SDK Edition—refer to the Downloading Open NFC SDK Edition recipe
It's assumed that the Open NFC SDK Edition Core has been downloaded and extracted to the NFCBook folder in your home directory

How to do it…

We are going to use the Android Virtual Device Manager tool to create a device capable of simulating the NFC feature as follows:

Open the NFCBook folder and navigate to the Android SDK folder.
Start SDK Manager and navigate to Tools | Manage AVDs….
On the Android Virtual Device Manager window, click on New to open the creation wizard.
Configure the parameters as shown in the following screenshot. The Target parameter must be Open NFC Android Edition, and the RAM should be set to a maximum value of 768 to prevent the AVD from failing to start. Also, Device should be set to a standard device and not to Galaxy Nexus or other such specific devices.
Click on OK and start the AVD you created.
Once the AVD finishes booting, open the application drawer and open the Settings Open NFC application, as shown in the following screenshot:
Configure the parameters as shown in the following screenshot:
Shut down the AVD.

How it works…

When we created the AVD, its target was the modified Android system image; so, when the AVD starts, it also starts the NFC Controller Simulator.

By default, the AVD is configured for the MicroRead controller and NFC is not enabled. We needed to change the configuration to simulator. So, we set the 10.0.2.2 IP address, which is a special alias that represents our machine, and then finally enable NFC.

There's more…

If you have a slower/older PC, or don't like to wait an infinite amount of time for the AVD to start, or you simply do not like the native simulator, there is a pretty neat alternative. Open NFC provides a VirtualBox appliance, which allows us to run Android in a virtual machine. It's a much faster and smoother alternative, and no extra configuration is needed.

We need to download an open source virtualization software and create a working Android virtual machine as follows:

Download and install VirtualBox from https://www.virtualbox.org/.
Download the VirtualBox appliance from the Download section on the Open NFC website.
In VirtualBox, go to File-Import Appliance and import the downloaded one from Open NFC.
Start the virtual machine and go to View-Switch to Scale Mode to fit the window to your screen.

Configuring the Connection Center tool

The Connection Center tool is like a bridge for communication between our AVD and our NFC Simulator. It just needs some simple configuration to provide smooth communication.

Getting ready

The following are the settings required for this recipe:

Make sure you have downloaded Open NFC SDK Edition—refer to the Downloading Open NFC SDK Edition recipe.
It's assumed that the Open NFC SDK Edition Core is already downloaded and extracted to the NFCBook folder in your home directory.
The .NET framework 2.0 or later must be installed. It can be downloaded directly from Microsoft Download Center, that is, http://www.microsoft.com/download.

How to do it…

We are going to configure the Connection Center tool properly to recognize our virtual device as follows:

Open Explorer and go to the Open NFC SDK Edition folder.
Open the folder named connection_center.
Start Connection Center by right-clicking on Connection Center.exe and selecting Run as administrator.
The program automatically starts hidden in the taskbar. Right-click on the icon labeled Connection Center and select Show from the context menu.
Click on the Connection tab and configure it as shown in the following screenshot:
Restart the Connection Center tool.
Click on the Connection tab and verify whether the changes were saved.

How it works…

Since our AVD and our PC are two different machines even though the AVD is running on our PC, we need to "tell" the Connection Center tool to allow incoming and outgoing connections from other machines. This way, our AVD is able to connect to the Connection Center tool and vice versa.

Note

If the Windows firewall asks you to add an exception, please do so. The Connection Center tool needs to access the network.

Testing your app all together

So far, we have set up and configured several parts of the puzzle—from Open NFC Android Edition to the Simulator, passing through the AVD and the Connection Center tool.

While these puzzle pieces are very important, we can't do much with the individual pieces. So, it's time to bring them all together.

Getting ready

The following are the settings required for this recipe:

Make sure you have downloaded Open NFC SDK Edition—refer to the Downloading Open NFC SDK Edition recipe
Make sure you have properly configured the Connection Center tool—refer to the Configuring the Connection Center tool recipe
Make sure you have properly configured an AVD—refer to the Configuring an NFC-enabled testing AVD recipe
It's assumed that the Open NFC SDK Edition Core is located at the NFCBook folder in your home directory and that the Android SDK location is known

How to do it…

We'll run everything and perform a simple test to make sure everything works properly before we start our first application:

Start the Connection Center tool located in the Open NFC SDK Edition folder. You will receive a Waiting for a connection… message.
Start the NFC Simulator tool located in the Open NFC SDK Edition folder. In the previously started Connection Center tool, we should see a Connected! message as shown in the following screenshot:
The Trace Server should be automatically started as well. We should now have the Connection Center tool, the NFC Controller Simulator, and the Trace Server running.
Start the previously configured AVD by clicking on Start in the Android Virtual Device Manager located in the Android SDK folder.
Once the AVD has started, we should see the following (or similar) information in the previously started tools:
- In the Connection Center tool, we should start seeing the following NFC Controller-connected messages:
- In the Trace Server, we should start seeing a tree that shows the devices connected (on the left) and any activity in the log list, as shown in the following screenshot:
- In the NFC Controller Simulator, several orange lights should appear that indicate what communication standards the device supports, as shown in the following screenshot:
Now, we are going to do the final test. In the NFC Controller Simulator, double-click on [MIREFIRE_UL_TAG2_LOCKED] in the Object List panel.
In the NFC Device #1 Antenna panel, a green light should appear, which means the tag was successfully dispatched to the simulator. In the simulator, the browser should be started. Now navigate to http://www.google.com/indexToFillSomeC, as shown in the following screenshot:

How it works…

The Connection Center tool is the first to be started. It listens for connection requests; so, when the Simulator and the AVD start, they will try to connect to a listening server. If no listener is running, nothing happens.

In the Trace Server, we can see what's happening in the communication between the devices. The sent and received messages and communications errors can be found here.

In the Simulator, we can easily see when a device is connected by looking at the top-right box. Here, we find a lot of information such as the communication standard supported by the device, represented by the orange circles, and the standard used in the last communication, represented by the green circles. The Simulator tool provides many other features such as creating custom tags. There is a detailed manual on this in the Open NFC SDK Edition Core folder.