1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
|
<html>
<body>
<p>Provides classes that manage the NFC functionality.</p>
<p>The NFC functionality is related to Near Field Communication.</p>
<p>The NFC APIs let applications:</p>
<ul>
<li>Scan for remote NFC targets (NFC Tag or NFC Peer)</li>
<li>Transfer raw data to and from remote NFC targets (NFC Tags or NFC Peer)</li>
<li>Read/Write NDEF data from/to remote NFC targets (NFC Tags)</li>
<li>Establish LLCP connection with a remote NFC target (NFC Peer with LLCP support)</li>
<li>Exchange data with a remote NFC target through LLCP services (NFC Peer with LLCP support)</li>
<li>Be notified of transactions on the local Secure Element by an external NFC reader</li>
</ul>
<h1>Setting Up NFC</h1>
<p>
Before an application can use the NFC feature, it needs to check if NFC is
supported on the device by getting an instance of the
{@link com.trustedlogic.trustednfc.android.NfcManager} class.
</p>
<pre>
NfcManager mNfcManager = (NfcManager) getSystemService(Context.NFC_SERVICE);
if (mNfcManager == null) {
// Device does not support NFC
}
</pre>
<p>
An application can ensure that NFC is enabled.
If not, an application with the needed permission can request that NFC be
enabled.
</p>
<pre>
if (!mNfcManager.isEnabled) {
// NFC is currently disabled.
// Enable NFC.
mNfcManager.enable();
}
</pre>
<p>
Before using the card emulation mode, an application can ensure that a secure
element is selected ({@link com.trustedlogic.trustednfc.android.NfcManager#getSelectedSecureElement}).
If not, an application with the needed permission can recover the list of
available secure elements on the device
({@link com.trustedlogic.trustednfc.android.NfcManager#getSecureElementList}) and select one
({@link com.trustedlogic.trustednfc.android.NfcManager#selectSecureElement}).
</p>
<p>
Before using the NFC feature, an application can configure the NFC device by
calling {@link com.trustedlogic.trustednfc.android.NfcManager#setProperties}. This function allows:
</p>
<ul>
<li>Enabling/disabling the NFC device capabilities (RF types, baudrates,
NFCIP-1 mode and role...)</li>
<li>Settings the NFCIP-1 general bytes and the LLCP link parameters</li>
</ul>
<p>
The setting properties can be customized according to the Device capabilities.
The next table give the minimal set of properties supported by the Device.
Depending on the implementation, the table may be completed.
</p>
<table>
<TR><TH> Property Name </TH><TH> Property Values </TH></TR>
<TR><TD> discovery.felica </TD><TD> <b>true</b>|false </TD></TR>
<TR><TD> discovery.iso14443A </TD><TD> <b>true</b>|false </TD></TR>
<TR><TD> discovery.iso14443B </TD><TD> <b>true</b>|false </TD></TR>
<TR><TD> discovery.iso15693 </TD><TD> <b>true</b>|false </TD></TR>
<TR><TD> discovery.nfcip </TD><TD> <b>true</b>|false </TD></TR>
<TR><TD> nfcip.baudrate </TD><TD> 106|212|424 </TD></TR>
<TR><TD> nfcip.generalbytes </TD><TD> </TD></TR>
<TR><TD> nfcip.mode </TD><TD> active|passive|<b>all</b> </TD></TR>
<TR><TD> nfcip.role </TD><TD> initiator|target|<b>both</b> </TD></TR>
<TR><TD> llcp.lto </TD><TD> <b>150</b> (0 to 255) </TD></TR>
<TR><TD> llcp.opt </TD><TD> <b>0</b> (0 to 3) </TD></TR>
<TR><TD> llcp.miu </TD><TD> <b>128</b> (128 to 2176) </TD></TR>
<TR><TD> llcp.wks </TD><TD> <b>1</b> (0 to 15) </TD></TR>
</table>
<p>(default values in bold)</p>
<h1>NFC Permissions</h1>
<p>
To change the NFC service settings such as enabling the NFC targets
discovery or activating the secure element, an application must declare the
NFC_ADMIN permission.
</p>
<p>
To perform NFC raw communication with a remote NFC target in
Reader/Write Mode or Peer-to-Peer Mode, an application must declare the NFC_RAW
permission.
</p>
<p>
To receive NDEF message or Secure Element intents, an application must declare
the NFC_NOTIFY permission.
</p>
<p>
To receive the LLCP link intent and perform an LLCP communication with a remote NFC target, an application must
declare the NFC_LLCP permission.
</p>
<h1>NFC Usage</h1>
<p>
The following code samples illustrate the APIs usage regarding the NFC service
use cases.
</p>
<h2>Reader/Writer Mode NDEF message notification</h2>
<p>
This code sample illustrates the NDEF message notification through an Intent declared in the manifest and a receiver implemented in the application.
</p>
<p>Main involved classes/methods:</p>
<p>Manifest Example:</p>
<pre>
<receiver android:name=".NfcReaderDemoReceiver">
<intent-filter>
<action android:name= "com.trustedlogic.trustednfc.android.action.NDEF_TAG_DISCOVERED"/>
</intent-filter>
</receiver>
</pre>
<p>Receiver Example:</p>
<ul>
<li>{@link com.trustedlogic.trustednfc.android.NdefMessage}</li>
<li>{@link com.trustedlogic.trustednfc.android.NfcManager#NDEF_TAG_DISCOVERED_ACTION}</li>
<li>{@link com.trustedlogic.trustednfc.android.NfcManager#NDEF_MESSAGE_EXTRA}</li>
</ul>
<pre>
public class NdefMessageReceiverSample extends BroadcastReceiver {
public void onReceive(Context context, Intent intent) {
if (intent.getAction().equals(NfcManager.NDEF_TAG_DISCOVERERD_ACTION)) {
NdefMessage msg = intent.getParcelableExtra(NfcManager.NDEF_MESSAGE_EXTRA);
/* Manage the NdefMessage received */
}
</pre>
<h2>Reader/Writer Mode raw exchange</h2>
<p>
This code sample illustrates raw exchanges with a NFC target in Reader/Writer
mode.
</p>
<p>Main involved classes/methods:</p>
<ul>
<li>{@link com.trustedlogic.trustednfc.android.NfcManager#openTagConnection}</li>
<li>{@link com.trustedlogic.trustednfc.android.NfcTag}</li>
</ul>
<pre>
public class TagReaderSample {
/** The NFC manager to access NFC features */
private NfcManager manager = (NfcManager) getSystemService(Context.NFC_SERVICE);
private void runTagReader() {
NfcTag tag = null;
String type;
byte[] cmd = { 0x01, 0x02, 0x03 };
byte[] res;
while (true) {
try {
Log.i("NFC example", "Please wave in front of the tag");
// Open a connection on next available tag
try {
tag = manager.openTagConnection();
} catch (NfcException e) {
// TODO: Handle open failure
}
// Look for a mifare 4k
type = tag.getType();
if (type.equals("Mifare4K")) {
Log.i("NFC example", "Tag detected");
tag.connect();
// Ready to communicate, we can send transceive !
res = tag.transceive(cmd);
} else {
Log.i("NFC example", "Unknown tag");
}
} catch (IOException e) {
// TODO: Handle broken connection
} finally {
if (tag != null) {
tag.close();
}
}
}
}
}
</pre>
<h2>Peer-to-Peer Mode raw exchange</h2>
<p>
This code sample illustrates raw exchanges with a NFC target in Peer-to-Peer
mode.
</p>
<p>Main involved classes/methods:</p>
<ul>
<li>{@link com.trustedlogic.trustednfc.android.NfcManager#openP2pConnection}</li>
<li>{@link com.trustedlogic.trustednfc.android.P2pDevice}</li>
<li>{@link com.trustedlogic.trustednfc.android.P2pInitiator}</li>
<li>{@link com.trustedlogic.trustednfc.android.P2pTarget}</li>
</ul>
<pre>
public class P2pSample {
/** The NFC manager to access NFC features */
private NfcManager manager = (NfcManager) getSystemService(Context.NFC_SERVICE);
private void runP2p() {
P2pDevice deviceP2p;
P2pInitiator initiator;
P2pTarget target;
byte[] data = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
byte[] echo = new byte[data.length * 10];
try {
deviceP2p = manager.openP2pConnection();
if (deviceP2p.getMode() == P2pDevice.MODE_P2P_INITIATOR) {
target = new P2pTarget(deviceP2p);
// Connect to the detected P2P target
target.connect();
// send data to the target
target.transceive(data);
// disconnect the connected target
target.disconnect();
} else if (deviceP2p.getMode() == P2pDevice.MODE_P2P_TARGET) {
initiator = new P2pInitiator(deviceP2p);
//target in receive state
echo = initiator.receive();
// send back the data received
initiator.send(echo);
}
} catch (IOException e0) {
} catch (NfcException e1) {
}
}
}
</pre>
<h2>Peer-to-Peer Mode LLCP exchange</h2>
<p>
This code sample illustrates how to get LLCP link state notification with the declaration of a Receiver in the manifest of the application and the implementation
of the receiver in the application.
</p>
<p>Manifest Example:</p>
<pre>
<receiver android:name=".LlcpModeReceiverSample">
<intent-filter>
<action android:name= "com.trustedlogic.trustednfc.android.action.LLCP_LINK_STATE_CHANGED"/>
</intent-filter>
</receiver>
</pre>
<p>Receiver Example:</p>
<ul>
<li>{@link com.trustedlogic.trustednfc.android.NfcManager#LLCP_LINK_STATE_CHANGED_ACTION}</li>
<li>{@link com.trustedlogic.trustednfc.android.NfcManager#LLCP_LINK_STATE_CHANGED_EXTRA}</li>
</ul>
<pre>
public class LlcpModeReceiverSample extends BroadcastReceiver {
public void onReceive(Context context, Intent intent) {
if (intent.getAction().equals(NfcManager.LLCP_LINK_STATE_CHANGED_ACTION)){
byte[] aid = intent.getByteArrayExtra(NfcManager.LLCP_LINK_STATE_CHANGED_EXTRA);
/* Create an LLCP service or client and start an LLCP communication */
}
}
</pre>
<p>
This code samples illustrate LLCP exchanges with a NFC Peer.
</p>
<p>Main involved classes/methods:</p>
<ul>
<li>{@link com.trustedlogic.trustednfc.android.NfcManager#createLlcpSocket}</li>
<li>{@link com.trustedlogic.trustednfc.android.NfcManager#createLlcpConnectionlessSocket}</li>
<li>{@link com.trustedlogic.trustednfc.android.NfcManager#createLlcpServiceSocket}</li>
<li>{@link com.trustedlogic.trustednfc.android.LlcpSocket}</li>
<li>{@link com.trustedlogic.trustednfc.android.LlcpConnectionlessSocket}</li>
<li>{@link com.trustedlogic.trustednfc.android.LlcpPacket}</li>
<li>{@link com.trustedlogic.trustednfc.android.LlcpServiceSocket}</li>
</ul>
<pre>
public class LlcpServerSample {
/** The NFC manager to access NFC features */
private NfcManager manager = (NfcManager) getSystemService(Context.NFC_SERVICE);
private void runLlcpClient() {
LlcpSocket sock;
byte[] data = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
byte[] echo = new byte[data.length * 10];
int length = 0;
sock = manager.createLlcpSocket((short) 128, (byte) 2, 1024);
// set a timeout in ms for connect request
sock.setConnectTimeout(10);
try {
// Connect to remote service
// NOTE: could be sock.connect("com.trusted-logic.tnfc.testapp");
sock.connect((byte) 0x10);
// Send data
for (int i = 0; i < 10; i++) {
sock.send(data);
}
// Receive echo
while (length < 10 * data.length) {
length += sock.receive(echo);
}
} catch (IOException e) {
// TODO: Handle broken connection broken (link down, remote closure
// or connect rejected) or Timeout expired
}
}
}
</pre>
<pre>
public class LlcpClientSample {
/** The NFC manager to access NFC features */
private NfcManager manager = (NfcManager) getSystemService(Context.NFC_SERVICE);
private void runLlcpClient() {
LlcpSocket sock;
byte[] data = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
byte[] echo = new byte[data.length * 10];
int length = 0;
sock = manager.createLlcpSocket((short) 128, (byte) 2, 1024);
try {
// Connect to remote service
// NOTE: could be sock.connect("com.trusted-logic.tnfc.testapp");
sock.connect((byte) 0x10);
// Send data
for (int i = 0; i < 10; i++) {
sock.send(data);
}
// Receive echo
while (length < 10 * data.length) {
length += sock.receive(echo);
}
} catch (IOException e) {
// TODO: Handle broken connection broken (link down, remote closure
// or connect rejected)
}
}
}
</pre>
<h2>Card Emulation Mode transaction notification</h2>
<p>
This code sample illustrates how to get the card emulation notification with the declaration of a Receiver in the manifest of the application and the implementation
of the receiver in the application.
</p>
<p>Manifest Example:</p>
<pre>
<receiver android:name=".NfcReaderDemoReceiver">
<intent-filter>
<action android:name= "com.trustedlogic.trustednfc.android.action.TRANSACTION_DETECTED"/>
</intent-filter>
</receiver>
</pre>
<p>Receiver Example:</p>
<ul>
<li>{@link com.trustedlogic.trustednfc.android.NfcManager#TRANSACTION_DETECTED_ACTION}</li>
<li>{@link com.trustedlogic.trustednfc.android.NfcManager#AID_EXTRA}</li>
</ul>
<pre>
public class CardEmulationReceiverSample extends BroadcastReceiver {
public void onReceive(Context context, Intent intent) {
if (intent.getAction().equals(NfcManager.TRANSACTION_DETECTED_ACTION)){
byte[] aid = intent.getByteArrayExtra(NfcManager.AID_EXTRA);
/* Manage the AID: */
/* For example start an activity related to this AID value or display a popup with the AID */
}
}
</pre>
<h1>Multiple Applications rules</h1>
<p>
Several LLCP sockets can be created by a single application or by multiple
applications by calling {@link com.trustedlogic.trustednfc.android.NfcManager#createLlcpSocket},
{@link com.trustedlogic.trustednfc.android.NfcManager#createLlcpConnectionlessSocket} or
{@link com.trustedlogic.trustednfc.android.NfcManager#createLlcpServiceSocket}, provided the local SAP
numbers are differents.
</p>
<p>
Only one application can open a raw connection by calling
{@link com.trustedlogic.trustednfc.android.NfcManager#openTagConnection} or
{@link com.trustedlogic.trustednfc.android.NfcManager#openP2pConnection}.
While this application has not closed or cancelled its connection, any other
application that attempts to open another raw connection will raise an
exception.
During an open connnection, the card emulation mode is always enabled and
applications are able to receive card emulation intents.
</p>
<p>
When an application opens a tag connection by calling
{@link com.trustedlogic.trustednfc.android.NfcManager#openTagConnection}, this operation is exclusive, no NDEF message intent are
broadcast while the connection is not closed or canceled.
</p>
<p>
When an application opens a peer-to-peer connection by calling
{@link com.trustedlogic.trustednfc.android.NfcManager#openP2pConnection}, this operation is exclusive, no LLCP intent are broadcast and LLCP sockets are
disabled while the connection is not closed or canceled.
</p>
<h1>NFC Tag types</h1>
<p>
The {@link com.trustedlogic.trustednfc.android.NfcTag} type returned by
{@link com.trustedlogic.trustednfc.android.NfcTag#getType} indicates the set of
commands supported by the tag. These commands can be used in
{@link com.trustedlogic.trustednfc.android.NfcTag#transceive}.
</p>
<TABLE BORDER="1">
<TR><TH> Tag Type </TH><TH> Returned string </TH></TR>
<TR><TD> Jewel/Topaz </TD><TD> Jewel </TD></TR>
<TR><TD> Mifare UltraLight </TD><TD> MifareUL </TD></TR>
<TR><TD> Mifare Standard 1K </TD><TD> Mifare1K </TD></TR>
<TR><TD> Mifare Standard 4K </TD><TD> Mifare4K </TD></TR>
<TR><TD> Mifare DESFIRE </TD><TD> MifareDESFIRE </TD></TR>
<TR><TD> Felica </TD><TD> Felica </TD></TR>
<TR><TD> ISO14443-4 A or B </TD><TD> Iso14443 </TD></TR>
<TR><TD> ISO15693 </TD><TD> Iso15693 </TD></TR>
</TABLE>
</body>
</html>
|
