Welcome!

Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Java Development

NFC Developer FAQ

by BlackBerry Development Advisor (Retired) ‎03-23-2012 08:53 AM - edited ‎08-19-2013 10:39 AM (8,471 Views)

Introduction

This article is part of a series intended to help developers wishing to exploit NFC in their BlackBerry® smartphone applications. Here, we’ve collated known issues and tips in the form of an FAQ. We’ll maintain this article going forwards.

 

Readers of this article should have some pre-existing knowledge of the fundamental architecture of NFC systems and be familiar with Java®. It would be beneficial to have read the first article in this series entitled: "NFC  Primer for Developers".

 

The Authors

This article was co-authored by Martin Woolley and John Murray both of whom work in the RIM Developer Relations team. Both Martin and John specialize in NFC applications development (amongst other things).

  

The BlackBerry NFC Developer FAQ

Items are presented in no particular order.

 

#

Issue

Comment

1 What tags are supported by BlackBerry smartphones?  

The following types of tags have been tested by RIM and are known to work. This is not a full and exhaustive list however. Tags which comply with the appropriate NFC Forum standards should work in theory. If in doubt, test.

NFC Forum Type

Supported Tags

Type 1

  • Topaz 96
  • Topaz 512

Type 2

  • MiFare Ultra Light
  • MiFare Ultra Light C
  • Infineon my-D Move
  • Infineon my-D NFC
  • Kovio 2K

Type 3

  • FeliCa RC-S965
  • FeliCa RC-S888

Type 4

  • MiFare DESFire EV1 (2k, 4k, 8k)
  • MicroPass 4101-2K

Note that MiFare DESFire EV1 tags must be pre-formatted before they can be used with a BlackBerry smart phone.

 

See FAQ #17 for guidance on choosing tags.

2

Your application encounters the error “ControlledAccessException - Listener belongs to another application module” when attempting to use on of the NFC listener interfaces such as TransactionListener, NDEFMessageListener or DetectionListener.

This is a known issue with early releases of BlackBerry 7.0 software.

Workaround: Sometimes implementing the listener in the UiApplication sub-class will result in this issue being avoided. This does not always work however.

Solution: Affected devices must be upgraded to an OS version in which the problem has been rectified. Details for BlackBerry® Bold9900 and BlackBerry® Curve 9360 are as follows:

Bold 9900: fixed in OS version 7.0.0.337 (bundle 1603)

Curve 9360: fixed at 7.0.0.360 (bundle 1699).

Ref: MKS 1935744

3

You suspect NFC is simply not working on your device. You’ve checked that the NFC service is switched on in the Manage Connections screen tags and have tried testing with a contactless smart card reader. Your contactless card reader has an LED which would normally provide a visual indication of an NFC device in proximity but you see no indication that this is the case when you place your BlackBerry on or sufficiently near to it.

You will not see evidence of activity with a contactless card reader unless the device is in card emulation mode. Early releases of the BlackBerry 7.0 OS did not enable card emulation mode automatically and an application is required to do this by calling the SecureElement.setTechnologyTypes(...) method with suitable parameters. Later 7.0 releases put the device into card emulation mode with routing to the UICC automatically on device start-up (Ref: CL 4373804). It is recommended that you upgrade to the latest OS build available for your device and re-test before taking any other action.

4

You are developing a MIDlet that involves card emulation mode. This necessitates the use of both the TransactionListener interface and PushRegistry to enable the receipt of NFC HCI transactions. However when you try to register your TransactionListener implementation or register with the PushRegistry, you receive an Exception which indicates you have already registered.

This is a known issue which affected earlier releases of the BlackBerry 7.0 OS. The recommended course of action is to upgrade the affected devices.

 

The issue is resolved in:

Curve: bundle 2386 or higher.

Bold: bundle 2395 or higher.

Ref: MKS 2377983

5

Is it possible to read a MIFARE Classic tag from a BlackBerry application?

No. The MIFARE Classic does not fully comply with all the relevant NFC standards. It also uses a proprietory cryptographic system which is subject to licencing.

6

You’d like to utilise the BlackBerry embedded secure element for your application. How do you go about getting access?

Use of the BlackBerry embedded secure element is only granted by RIM in certain cases and is dependent on both business and technical criteria. Engage your RIM contact in discussion about this.

7

Your application uses Virtual Target Emulation to emulate an NFC tag of some sort. You want to be able to set the UID for your emulated tag so that it is presented to the reader like a real tag.

Unfortunately the BlackBerry NFC APIs do give the impression that this is possible:

 

public VirtualISO14443Part4TypeATarget(
    VirtualISO14443Part4TargetCallback callback,
    String identifier,
    byte[] historicalBytes
)

 

The intention had been that the value provided as the identifier parameter would be used as the UID of the emulated tag. However, we later decided to remove this capability due to security concerns. The API remains so as to not break older application code but the parameter has no effect and is ignored.

8

Where can I buy NFC tags?

We can’t recommend any particular store I’m afraid. The following URL may help however:

http://lmgtfy.com/?q=buy+nfc+tags

 

9

You’re seeing the error “Cannot wait for secure element 1 in PushRegistry - not present” in the event log.

This may appear in a stack trace generated by an IllegalArticleException such as the example below. It simply means that the UICC in the device does not have a secure element.

 

guid:0x9C3CD62E3320B498 time: Fri Jan 20 13:44:14 2012  severity:1 type:3 app:Java Exception data:

IllegalArgumentException

Cannot wait for secure element 1 in PushRegistry - not present

net_rim_nfc-2(4F06365E)                 SEPushRegistryManager$MyTransactionListener

                block

                0x5036

                net_rim_cldc-4(4F06321F)

                MIDletMain$MIDletPushRegistryWorkerThread

                run

                0x6A9E

10

You’re getting ‘Error: App will not start. "Error starting <app name>: Can't find entry point".’

There are various possible causes of this error but if you are using the TransactionListener interface it is possible you are running on an OS build which is too old for your code.

API changes which break binary compatibility are extremely rare on BlackBerry but we did have one relating to TransactionListener registration whereby the signature of SecureElement.addTransationListener was changed to require an array of applet AIDs to be included in the registration request. Consequently there’s a minimum OS version of 7.0.0.490 required to run applications which use TransactionListener. If you run such an application on an earlier OS version you will see this error. Your only recourse is to upgrade the device.

11

Whilst testing a card emulation application which works with the secure element on a UICC, you experience issues and are seeing a message similar to “JSR177 SecurityException: ACF bad signature -> disallow” in the event log. You have an ACF (Access Control File) governing applet access on your UICC.

This is a known issue affecting some early releases of the 7.0 OS. It’s a defect relating to the way that cod file signatures which have been applied using the CodTool tool are checked. The problem is that all certificates in the certificate chain are being checked to see if they are of the right usage to be used for verifying signatures on other certificates (keyUsage=KeyCertSign) but in fact only the root and intermediate certificates should be checked in this way. In the case where you experience this failure, your end entity certificate probably has a keyUsage field where KeyUsage=DigitalSignature is specified.  This means that the Key_CertSign usage is not allowed.

For a workaround, you have the choice of using a new certificate which has Key_CertSign in the keyUsage field or which does not have a keyUsage field at all.

Solution. upgrade to a minimum OS version of 7.0.0.573.

Ref: MKS 2424217

12

You’ve been issued with the RESE signing key to allow you to work with the BlackBerry embedded secure element but are having difficulty using it with Eclipse®.

The Eclipse eJDE cannot tell that RESE is required since essentially the same API is used for EMBEDDED vs SIM. Consequently after building your cod file you need to manually sign it by launching the SignatureTool.jar tool from within:

 <your eclipse folder>\ plugins\net.rim.ejde\vmTools

The signing tool "knows" what signatures to apply based on the contents of the .csl file in your \deliverables\standard\7.x.x directory

So before signing, you have to manually edit the file and add the following line:

 

52455345=RESE

 

Then try to sign the cod with the signing tool. Don't rebuild before signing and after editing the csl as the csl is generated by the build process and so your manually applied change will be lost.

13

Calls to secureElement.getUri(appletId) return a strange connection string.

This is a known issue.

With an appletId of say "A000000003000000" the URI value returned by the call may be something like "apdu:1;target=ffffffa0.0.0.0.3.0.0.0". It should actually be something like "apdu:1;target=a0.00.00.00.03.00.00.00"

A workaround is to hard code the connection string rather than obtain it from the SecureElement object.

14 How does NFC behave when the battery is low or dead?

Devices which support NFC will continue to be able to provide NFC card emulation functionality when in "low battery mode" or in some circumstances, even when the battery is completely dead. 

 

Let's explore what we mean by "low battery" vs "dead battery" before we move on.

 

Low battery mode starts when the device OS turns off the user interface due to the battery being deemed "low" so that the device appears to be off to the user but internally, the PMIC (Power Management Integrated Circuit) is still on. Dead battery mode by way of contrast, starts when the there is no longer enough power in the battery to keep even the PMIC on.

 

How long low battery mode will last before moving into the dead battery state varies from device to device but can be in the region of around 4 or 5 hours.
 
In low battery mode, all BlackBerry devices will continue to be able to provide NFC card emulation functionality.  Regarding dead battery mode however, whether NFC card emulation will continue to work or not depends on the device model:
  • Dead battery mode is not supported on the Bold 9900 and Curve 9360.  
  • The Curve 9380 and Bold 9790 do support this feature however.
The user has no way of knowing just from looking at their device, if they are in low battery mode or have a completely dead battery and so has no way of knowing whether or not NFC transactions in card emulation mode will work or not in a given instance since to the user, the device appears to be shut down in both the low battery and dead battery states.
 
Developers have an API function called SecureElementManager.getInstance().setCardEmulationWhenPoweredOff(true|false) which they can call to control whether or not card emulation will work or not when the battery is dead or has been removed by the way.

  

You may also have noticed that the Near Field Communication options screen has a setting in the section entitled "Allow NFC Card Transactions" labelled "When Powered Off".  This setting will also affect the behaviour of a device when in low battery or dead battery mode.

15 You'd like to be issued with the NFCR or RESE signing keys to allow NFC card emulation APIs to be used with either a UICC or the embedded secure element.

Since 25th April 2012 it has been possible to apply for NFC keys using the same form which is used for standard code signing keys. Just fill in the form at the following address and your application will be processed accordingly.

 

https://www.blackberry.com/SignedKeys/

 

 


16

 

BlackBerry 10

You have a BlackBerry 10 "Dev Alpha device" which you were given at one of the BlackBerry 10 Jam events. When you try to build a native application which uses the NFC APIs using the 10.0.4-beta version of the NDK you get compilation errors such as:

 

undefined reference to `nfc_request_events'

 

undefined reference to `nfc_unregister_tag_readerwriter'

 

and more.

By default, the library containing the NFC APIs is not on the LIBPATH with this version of the NDK. To solve this problem, look for a .pro file in your project's folder. If your app is called HelloWorld then you should find a file called HelloWorld.pro. Edit the file with a standard text editor and add the LIBS directive shown below:

 

TEMPLATE = app
TARGET = TagTool

CONFIG += qt warn_on debug_and_release cascades

INCLUDEPATH += ../src
SOURCES += ../src/*.cpp
HEADERS += ../src/*.hpp ../src/*.h
LIBS += -lnfcapi

 

..........

..........

 

Save the file and rebuild your application.

17 What tags should you use for your application?

What follows is an attempt to give some general guidance on this subject.

 

The answer depends what you want to use them for and what you want to do with them.

 

The key questions are how much space you need for data and whether you want them to be self-adhesive so you can stick them to surfaces or tough, robust plastic things for in your wallet. Or some other physical form.

 

But...

 

Always look for an indication of “NFC Forum Type n” in the description where for your purposes n will be 2 or 4. That tells you the tag is a standards based tag.

 

1. For general recording of simple, not too large URLs etc get an “NFC Forum Type 2” tag such as a Mifare Ultralight, Mifare Ultralight C or Kovio 2K.

 

e.g. http://www.nfcstuff.com/gbp/store/NFC_paper_ticket_144_byte_type_2_mifare_ultralight_c.html

 

Capacity varies from as little as 144 bytes to about 233 bytes. Check the tag details.

 

e.g. http://www.buynfctags.com/kovio-printed-nfc-sticker-kovio-2k-circle-35-mm.html

 

Watch out for apps that use very long URLs like Foursquare. If in doubt get 2K type 4 tags rather than the cheaper, smaller capacity ones.

 

2. For larger capacity needs (eg. 2K or more, up to 8K in fact) get a Mifare Desfire EV1. The “EV1” part is critical. They have a “Mifare Desfire” product (no “EV1”) which we do not support on BlackBerry (it's not one of the 4 NFC Forum standard types). Assuming you want to use them as tags e.g. to store large URLs that launch an app/browser then you need to ask the supplier to supply them “formatted for NDEF” otherwise they will not work. Suppliers generally do this and understand what you mean. Their web site should mention this. If not NDEF formatted, basically you would be using the “tag” more like a smart card.

 

e.g. http://www.buynfctags.com/nfc-card-desfire-ev1-2k.html

 

Avoid:

 

- Mifare Classic, Mifare 1K, Mifare DESFire. These are not compatible with BlackBerry smart phones. Note that Mifare DESfire EV1 on the other hand are compatible and good.

 

- “Anti-Metal” NFC tags. We’ve had problems reading them sometimes and in our lab testing have found that some of them fail the official "ISO tests".

 

Be careful with:

- the small round sticker variety unless you know for a fact they work with BlackBerry devices. Sometimes they’re OK and sometimes they’re not. No way to tell in advance without prior experience of a specific make with specific BlackBerry device models (performace varies due to different antenna size and other factors). Bigger tags will generally perform better, that’s all there is to it.

 

round_tags.png

Kovio 2K round sticker tags seem to work OK with BlackBerry devices as do some others. Here’s one stuck to a business card so you can see the size. 

 

kovio_2k.png

 

To be clear, there is no *general* problem with using the smaller, round tags.... we've just seen issues with a few of them so are flagging this. The best course of action would be to buy a small sample first, test with your target devices and application and then make your decision.

 

Contributors
Users Online
Currently online: 12 members 686 guests
Please welcome our newest community members: