Since the source code for 2.3.4 has already been pushed to the Android Open Source Project (AOSP), we’ve been analyzing it and we found the some changes in the NFC Java Classes, mainly in card emulation features:

New NFC-EE (Nfc Execution Environment) API’s as shared library

There are two new classes, NfcAdapterExtras and NfcExecutionEnvironment, implemented as a shared library in frameworks/base/nfc-extras. The NfcAdapterExtras class provides additional methods on an NfcAdapter for Card Emulation and management of the Nfc Execution Environment (EE). But the access to this functionality is limited because it depends on the NfcAdapter.getNfcAdapterExtrasInterface() method that was hidden with the “@hide” tag.

New ApduList class in the android.nfc package to create an array of APDU commands and send them to the SE. This class is also hidden with the “@hide” tag.

No more NfcSecureElement class. This class was used in 2.3.3 version as the primary API for managing all aspects of the Secure Element (SE) like open/close the SE, get the SE unique identifier, and so on, but was deleted from this version, probably as result of this new “NFC-EE” paradigm. From now on,  you need to define a “route” (such as a UICC via SWP or the embedded secure chip) to the SE instead of open it directly.

So, what Google NFC software engineers said this past week at the company’s I/O developer conference about card emulation is true: there are no public APIs to card emulation. But definitely they are working on card emulation functionality and  it’s already part of the new Android 2.3.4

The four steps are based on the enable/disable foreground dispatch method and three intent actions:

Tag dispatch process

First step: The NfcAdapter.enableForegroundDispatch Method

This method will enable foreground dispatch to the given activity. This means, calling this method will give priority to the foreground activity when dispatching a discovered Tag to an application. You can provide any IntentFilters to this method and the are used to match dispatch Intents for both the ACTION_NDEF_DISCOVERED and ACTION_TAG_DISCOVERED. Remember that you must call disableForegroundDispatch(Activity) before the completion of their onPause() callback to disable foreground dispatch after it has been enabled.

The typical example of using this method is an application showing the screen “Waiting for tag…” for read or write. When the user taps a tag this activity has priority for the discovered tag so the activity chooser dialog will not shown.

Next steps: 3 Intent actions

If a tag is detected and there is no call to the enableForegroundDispatch method, then the system broadcasts three intent actions in this order, from specific (checking the content) to generic (just a tag):

1 – ACTION_NDEF_DISCOVERED

This intent is started when a tag with NDEF payload is discovered. The system inspects the first NdefRecord in the first NdefMessage and looks for a URI, SmartPoster, or MIME record. If a URI or SmartPoster record is found the intent will contain the URI in its data field. If a MIME record is found the intent will contain the MIME type in its type field. This allows activities to register IntentFilters targeting specific content on tags. Activities should register the most specific intent filters possible to avoid the activity chooser dialog, which can disrupt the interaction with the tag as the user interacts with the screen.

If any activities respond to this intent neither ACTION_TECH_DISCOVERED or ACTION_TAG_DISCOVERED will be started.

2 – ACTION_TECH_DISCOVERED

Intent to start an activity when a tag is discovered and activities are registered for the specific technologies on the tag. To receive this intent an activity must include an intent filter for this action and specify the desired tech types in a manifest meta-data entry. Here is an example manifest entry:

The meta-data XML file should contain one or more tech-list entries each consisting or one or more tech entries. The tech entries refer to the qualified class name implementing the technology, for example “android.nfc.tech.NfcA”.

A tag matches if any of the tech-list sets is a subset of Tag.getTechList(). For the current api version this could be:

NfcA (also known as ISO 14443-3A)
NfcB (also known as ISO 14443-3B)
NfcF (also known as JIS 6319-4)
NfcV (also known as ISO 15693)
IsoDep (ISO 14443-4)
Ndef on NFC Forum Type 1, Type 2, Type 3 or Type 4 compliant tags
MifareClassic
MifareUltralight
NdefFormatable

Each of the tech-lists is considered independently and the activity is considered a match is any single tech-list matches the tag that was discovered. This provides AND and OR semantics for filtering desired techs. Here is an example that will match any tag using NfcF or any tag using NfcA, MifareClassic, and Ndef:

If any activities respond to this intent ACTION_TAG_DISCOVERED will not be started.

3 – ACTION_TAG_DISCOVERED

This is the last step, more generic, if no activities respond to the previous intents, this one (as previous Android versions) will start an activity when a tag is discovered.

It only installs on devices with at least 2.3.3 version and NFC. Check it out https://market.android.com/details?id=com.nxp.nfc.tagwriter

• NFC-A (ISO 14443-3A)
• NFC-B (ISO 14443-3B)
• NFC-F (JIS 6319-4)
• NFC-V (ISO 15693)
• ISO-DEP (ISO 14443-4)
• Mifare Classic
• Mifare Ultralight
• NFC Forum NDEF tags

This release also provides a limited peer-to-peer communication protocol and API. As they say “advanced tag dispatching now gives applications more control over how and when they are launched, when an NFC tag is discovered. Previously, the platform used a single-step intent dispatch to notify interested applications that a tag was discovered. The platform now uses a four-step process that enables the foreground application to take control of a tag event before it is passed to any other applications (android.nfc.NfcAdapter.enableForegroundDispatch()). The new dispatch process also lets apps listen for specific tag content and tag technologies, based on two new intent actions — android.nfc.action.NDEF_DISCOVERED and android.nfc.action.TECH_DISCOVERED”.
We are going to test this new functionality, will be sharing our views about it and posting some new examples.

We’ve been analyzing the  Android kernel source code and we found a lot of ”@hide” tags in the NFC java classes. These are in:

frameworks/base/core/java/android/nfc
frameworks/base/core/java/com/android/internal/nfc
packages/apps/Nfc (the android service running in the background)
packages/apps/Tag (the application used to read and store tags)

And the hardware abstraction layer from NXP is in:

external/libnfc-nxp

Let’s see an example, the publised API for the class NCFAdapter has only two public methods:

getDefaultAdapter(): Get a handle to the default NFC Adapter on this Android device.
isEnabled(): Return true if this NFC Adapter has any features enabled.

But also has this public methods with the @hide tag:

enable(): Enable NFC hardware.
disable(): Disable NFC hardware.
createRawTagConnection(): Create a raw tag connection to the default Target.
createNdefTagConnection(): Create an NDEF tag connection to the default Target .

Interesting, isn’t it?

The “@hide” tag is used to mark public APIs that are not to be exported in the SDK. This is used by the Android team to have APIs accessible across packages without having them available to applications. APIs marked with @hide are considered private to the Android platform and can change at any time, so you cannot rely on them. So, with this in mind, we can confirm that there is some extended NFC functionality hidden in Android 2.3 that can be accessed, i.e. with reflection techniques. Let’s see how we can do this.

To write tags we’ll use the write() method from the INfcTag interface, so lets dive from NfcAdapter to the INfcTag. First we need a handle to the NFC adapter within the Nexus S:

NfcAdapter nfcAdapter = NfcAdapter.getDefaultAdapter();

Then we need a handle to the actually detected tag, this is done by getting the the data within the intent received when tag was discovered:

Parcelable nfcTag = intent.getParcelableExtra("android.nfc.extra.TAG");
Field f = nfcTag.getClass().getDeclaredField("mServiceHandle");
f.setAccessible(true);
Object mServiceHandle = f.get(nfcTag);

Now, we can create a raw connection to the tag, this is a low-level connection to a tag target. We’ll use this object to get later a handle to the INfcTag

Class tag = Class.forName("android.nfc.Tag");
Method createRawTagConnection = nfcAdapter.getClass().getMethod("createRawTagConnection", tag);
Object rawTagConnection = createRawTagConnection.invoke(nfcAdapter, nfcTag);

Now we can get the handle to the INfcTag interface (mTagService).

Field f = rawTagConnection.getClass().getDeclaredField("mTagService");
f.setAccessible(true);
Object mTagService = f.get(rawTagConnection);

Before we can write to the tag we connect our interface to it.

Method connect = mTagService.getClass().getMethod("connect", Integer.TYPE);
connect.invoke(mTagService, mServiceHandle.intValue());

Finally, we create the NdefTagRecord, this could be a smart poster, an uri, simple text or whatever record we want to write into the tag. This record will be encapsulated into an NdefMessage, so when we invoke the write() method we use this ndefMessage as parameter:

Method write = mTagService.getClass().getMethod("write", Integer.TYPE, NdefMessage.class);
write.invoke(mTagService, mServiceHandle, ndefMessage);

… and that’s it!
The write() method will work as long as you use a tag pre-formatted with any NFC Forum type tag with default public keys.
We developed an application using this code to write tags. Below you can see a demo of this app writing an URI type tag:

Well, today we finally got the Nexus S in our labs, so we are porting our software to the Android platform.

Google Nexus S

When you open Nexus S to put the battery in, you’ll see the 4 turns NFC antenna embedded in the back cover, it looks like a sticker. There are 2 gold contact points which connects this when you close. We also found an antenna jack so you can plug an external gsm antenna,  good for country drives to get much more constant reception. You can see a great full teardown of the handset at iFixit.

NFC Antenna detail on Nexus S

This phone comes with a PN544 standard NFC controller form NXP which can connect to a SIM using the standardized Single Wire Protocol (SWP). This chip can also do card emulation, read and write tags and exchange data in p2p mode, as far as the RF signals are concerned.

We’ll be posting more about our experience on this phone and the NFC feature over the next few days.

The Gibraltar SF Team is full of enthusiasm and really excited to dive into this New Year and wishes all of you a successful and happy 2011!!