28 JSR 257: Contactless Communication API

The Contactless Communication API (http://jcp.org/en/jsr/detail?id=257) is a Java ME optional package that allows applications to access information on contactless targets, such as Radio Frequency Identification (RFID) tags and bar codes. RFID tags are often used in business for item identification, article surveillance, and inventory. Each RFID tag contains a unique identification number used to identify a tagged object.

Using the JSR 257 API, an RFID reader can be built into an Oracle Java Wireless Client software phone stack, allowing the handset to read data from a tagged target and write data back to it. RFID readers use the 13.56 MHz radio frequency and the communication distance is usually less than 10 centimeters.

The Near Field Communication (NFC) Forum defines the NFC Data Exchange Format (NDEF) data packaging format. NDEF facilitates communication with an RFID tag, or between one NFC device and another. The Contactless Communication API provides a connection to any physical target that supports the NDEF standard, allowing applications to exchange data with any target tagged with NDEF formatting, regardless of actual physical type.

28.1 Using ContactlessDemo

The Oracle Java ME SDK provides a way to test contactless communication. The MIDlet running on the emulator waits to detect an RFID tag. You can simulate the tag communication using the emulator's external events generator to detect and attach the tag. You can use one of the tags included in the sample, or create tag files of your own, as described in "Tag File Formats."

Launch the ContactlessDemo. The MIDlet registers the RFID tag listener, the NDEF tag listener and the NDEF record listener, then notifies you that it is waiting for a tag.
In the emulator, click the Tools menu and select External Events Generator. The Contactless Communication tab is automatically displayed. In the external events generator, the tag emulator supplies several tags by default: hello, nested, vcard, jdts, jdts2, and ndefEmpty.
To test the connection, select an available tag and press the Attach tag.

In the emulator, the MIDlet notifies you that the NDEF target is detected, displays the tag information, and prints the payload if it is a text record.

In the external events generator, press Detach tag to end the session.

Events are recorded in the log area. To clear the log, right-click and select Delete Text. To clear the emulator screen press Clear.
To create your own tag, create a tag file according to the NDEF standard. For a sample, see "Tag File Formats."

In the External Events Generator, press Create tag and browse to select your tag file, and press Open. If the file is properly formed, the new tag is added to the available tags list. To write protect the tag, select the tag and select the Locked option. When a tag is locked, no data can be written to the tag.

Click Remove tag to remove any tag from the list. If it is a tag you created, the original file on disk is not affected. If the default tags are removed, they reappear when you restart the demo.
Optional. Instead of performing interactive actions in the external events generator, you can use a script to do the same thing.

Create a file as directed in "Script Format." In the external events generator, click the Browse button to locate your script, then press Play.

28.2 Tag File Formats

Tags are created in XML format in accordance with the NFC and NDEF standards. To see how the sample files are formed, see: installdir\toolkit-lib\modules\emulator-ui-window-external-events\jsr257\conf\tags.

A sample file with several records might look like this:

Example 28-1 Tag File Format Example

<?xml version="1.0" encoding="UTF-8"?>
<jsr257client>
    <UID>12-CD-45-67-89-AB-CD</UID>

    <TargetProperties>
        <TargetProperty>NDEF</TargetProperty>
    </TargetProperties>

    <NDEFMessage>
        <NDEFRecord>
            <Format>MIME</Format>
            <Name>text/plain</Name>
            <Id>mimeid</Id>
            <Payload>Hello, MIME World!</Payload>
        </NDEFRecord>
        <NDEFRecord>
            <Format>MIME</Format>
            <Name>text/example</Name>
            <Id>urn:company:product:ndef:payload:2</Id>
            <Payload>payload2</Payload>
        </NDEFRecord>
        <NDEFRecord>
            <Format>EXTERNAL_RTD</Format>
            <Name>urn:nfc:ext:oracle.com:type1</Name>
            <Id></Id>
            <Payload>payload3</Payload>
        </NDEFRecord>
        <NDEFRecord>
            <Format>URI</Format>
            <Name>urn:company:product:test_uri</Name>
            <Id>urn:company:product:ndef:payload:4</Id>
            <Payload>payload4/<Payload>
        </NDEFRecord>
        <NDEFRecord>
            <Format>NFC_FORUM_RTD</Format>
            <Name>urn:nfc:wkt:Sp</Name>
            <Id></Id>
            <Payload>smart-poster</Payload>
        </NDEFRecord>
        <NDEFRecord>
            <Format>MIME</Format>
            <Name>text/x-vCard</Name>
            <Id>duke</Id>
            <Payload>BEGIN:VCARD VERSION:2.1 FN:Oracle TEL:+1-650-506-7000
                     ADR:500 Oracle Parkway City:Redwood Shores
                     State:CA;94065 END:VCARD
            </Payload>
        </NDEFRecord>
    </NDEFMessage>
</jsr257client>

28.3 Script Format

You can use the external events generator buttons to attach and detach a tag, or you can write a script to perform these actions. The script syntax is as follows:

Example 28-2 Tag Script File Format Example

# Comment:
  # this is a comment
# Tag definition:
    tag <tag name> <path to the tag xml file>
# Attach tag:
   attach <tag name>
# Delay. Ensures the tag is attached before other actions.
   wait <time in ms>
# Print tag information:
   print <tag name>
# Detach tag:
   detach <tag name>

This is a sample script:

Example 28-3 Tag Script Sample

   tag C D:\MyTags\ccomtag.xml
   attach C
   print C
   wait 10000
   detach C

In the external events generator, click Browse and select the script file, then press Play to run the script. The results are shown in the Log area. For example, if the sample script calls the sample tag file in "Tag File Formats," the log output is as follows:

[18:24:10]  Run Script: D:\JMESDKLocal\ccomtag.xml
[18:24:10]  Define tag 2058 (C)
[18:24:10]  Print 2058 (C)
[18:24:10]  Attached tag 2058 (C)
[18:24:10]  UID: 02-34-56-78-9A-BC-DE
Properties:  NDEF
NDEF message: 8 record(s)
#0: NDEF record:  format=MIME, name=text/plain, id.length=2, payload.length=18payload=Hello, MIME world!
#1: NDEF record:  format=MIME, name=text/example, id.length=34, payload.length=8payload=payload2
#2: NDEF record:  format=EXTERNAL_RTD, name=oracle.com:type1, payload.length=8payload=payload3
#3: NDEF record:  format=URI, name=urn:company:product:test_uri, id.length=34, payload.length=8
payload=payload4
#4: NDEF record:  format=EXTERNAL_RTD, name=company.com:type1, id.length=34, payload.length=8
payload=payload5
#5: NDEF record:  format=NFC_FORUM_RTD, name=Sp, payload.length=12
payload=smart-poster
#6: NDEF record:  format=URI, name=message/http, id.length=3, payload.length=56
payload=http://www.oracle.com/technetwork/java/javame/index.html
#7: NDEF record:  format=MIME, name=text/x-vCard, id.length=4, payload.length=122payload=BEGIN:VCARD VERSION:2.1 FN:Oracle TEL:+1-650-506-7000
ADR:500 Oracle Parkway; City:Redwood Shores;State:CA;94065 END:VCARD
[18:24:10]  Wait 10000ms
[18:24:20]  Detached tag 2058 (C)
[18:24:20]  Script finished.
[18:24:25]  Received data for unknown tag 2,058