JSR-257 API Reference Implementation (RI) Users Guide .fr

... trademarks or registered trademarks of Sun. Microsystems, Inc. Other product and company names mentioned herein may be trademarks or trade names of.
102KB taille 19 téléchargements 369 vues
JSR-257 API Reference Implementation (RI)

Users Guide

Table of Contents 1.

INTRODUCTION ..........................................................................................................................................................4 1.1. 1.2.

2.

INSTALLATION............................................................................................................................................................4 2.1. 2.2.

3.

SUPPORTED DEVELOPMENT ENVIRONMENT AND SOFTWARE REQUIREMENTS .....................................................4 SUPPORTED APIS AND CONFIGURATIONS ............................................................................................................4

PACKAGE STRUCTURE ...........................................................................................................................................4 INSTALLING THE REFERENCE IMPLEMENTATION ...................................................................................................5

FEATURES ...................................................................................................................................................................5 3.1. USING THE SIMULATOR ..........................................................................................................................................5 3.1.1 Contactless Simulator Window .........................................................................................................................6 3.1.2 Card Properties Window ..................................................................................................................................6 3.1.3 Communicating with NFC Peers ......................................................................................................................7 3.2. USING REAL RFID HARDWARE ..............................................................................................................................8

4.

SAMPLE APPLICATIONS .........................................................................................................................................8 4.1. 4.2. 4.3. 4.4. 4.5. 4.6. 4.7.

DIRECTORY STRUCTURE .......................................................................................................................................8 BUILDING THE SAMPLE APPLICATIONS...................................................................................................................8 INSTALLING SAMPLE APPLICATIONS TO A MOBILE DEVICE .....................................................................................9 RUNNING SAMPLE APPLICATIONS ..........................................................................................................................9 THE ‘CONTACTLESS’ SAMPLE APPLICATION ..........................................................................................................9 THE ‘BARCODE’ SAMPLE APPLICATION ..................................................................................................................9 THE ‘NDEF’ SAMPLE APPLICATION .....................................................................................................................10

JSR-257 (Contactless Communication API) Reference Implementation Copyright © 2006 Nokia Corporation. All rights reserved. Nokia Prototype SDK: Copyright (c) 2001-2005 Nokia Corporation. All rights reserved. Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. Includes Java(TM) technology from Sun Microsystems, Inc. Portions of this software are Copyright by Sun Microsystems, Inc. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other product and company names mentioned herein may be trademarks or trade names of their respective owners.

1. INTRODUCTION The purpose of this document is to explain installation steps and usage of JSR-257 (Contactless Communication API) Reference Implementation. RI supports the mandatory features of the JSR-257 specification, and based on the Nokia Prototype SDK version 3.0. From the several MIDP device emulators in the original Nokia Prototype SDK, only one is supported, namely the Nokia Series 40 MIDP Emulator. The emulator uses CLDC version 1.1 and MIDP 2.0. This document is written for people, who might have downloaded the JSR-257 RI binaries and want to use it by writing applications themselves. It is recommended that reader of this document is familiar with the Contactless Communication API Specification and the Nokia Prototype SDK. Please note, that this package does not contain the complete Nokia Prototype SDK and is not supported by Forum Nokia.

1.1.

Supported development environment and software requirements

JSR-257 RI is run on Windows 2000 (SP3) and Windows XP. To compile the sample applications you need Apache Ant, and WTK 2.2. In order to run sample applications you need installed RI or a CLDC 1.1, MIDP 2.0 and JSR-257 enabled mobile device.

1.2.

Supported APIs and configurations

JSR-257 Reference Implementation is based on Nokia Prototype SDK 3.0, therefore it supports many other APIs in addition to the JSR-257. RI supports and uses the following APIs and configurations: • • • •

CLDC 1.1 MIDP 2.0 PDA Opt. Packages for the J2ME Platform (JSR-75, FileConnection Optional Package) JSR-257

2. INSTALLATION 2.1.

Package structure

The Contactless Communication API RI is delivered in zip file format. The installation package has the following structure:

JSR-257_Reference_Implementation_License_Agreement.pdf  JSR_257_RI_1_0 .......  docs ........ Prototype_3_0_S40_128x128_MIDP_Emulator ........ samples ........ReleaseNotes

2.2.

Installing the Reference Implementation

Unzip the contents of the ZIP file, retaining directories. The RI will be placed in a directory called 'JSR_257_RI_1_0', where 1_0 is the version of the RI.

3. FEATURES The following target types are supported by the reference implementation: • NFC_TAG • NFC_PEER • VISUAL_TAG For working with NFC tags, the RI provides two choices. Either it can working with commercial RFID hardware, or it can simulate one using a built-in simulator with a GUI interface. These features are described in the following sections. The user can choose which one is used by editing the RI configuration file which is Prototype_3_0_S40_128x128_MIDP_Emulator/bin/contactless_config.xml. The default is to use the simulator. The RI also has support for encoding/decoding visual tags. Encoding of EAN/UPC, and decoding of Code39 is supported. The encoder only supports the default image generation properties.

3.1.

Using the simulator

The simulator simulates a real RFID device attached to the emulator. It is started when a midlet registers a listener for NFC events using the DiscoveryManager class. The simulator has a GUI which consists of a number of windows.

3.1.1 Contactless Simulator Window

This window contains two lists. The list on the right side contains the available NFC cards. This list has a context menu accessible by pressing the right mouse button which enables the user to define new cards, delete old ones, and access the properties of each card. The list of the left side contains the cards which are in the 'RF field', i.e. which the application can work with. Cards can be moved between the two lists by selecting one or more card and pressing the arrow buttons between the two lists. When cards are added to the RF field, the RI will notify applications through the various listeners which can be registered using the DiscoveryManager class.

3.1.2 Card Properties Window

This window is displayed when the user selects a card and chooses 'Card properties' from the context menu. It displays the properties of the selected card. These are: • Name: Only used on the GUI, has no meaning to the RI • UID: The unique ID of the card. This is generated automatically by the RI. • Card Type: The type of the card can be viewed or changed using this listbox. • Raw contents: This tab shows the raw data on the card as a table of bytes. • Formatted contents: This tab shows the NFC formatted data on the card, if it has any. Clicking the left mouse button in this tab allows the user to define the data on the card. This is done by selecting a file from the file system whose contents is copied to the card. If the file contains an NDEF message, then the tab will display the contents of the message. Files containing example NDEF messages can be found in the samples/ndef subdirectory of the RI.

3.1.3 Communicating with NFC Peers If a card of type NFC_PEER is added to the RF field, it is possible to simulate the sending/receiving of NDEF messages between this card and the emulator. To ‘receive’ messages from the card, select ‘NFC Peer Receive Data’ from the context menu of the card in the RF field. A file selection dialog box is displayed where the data which will be received by the emulator can be selected. The J2ME application can read this data using the NFCConnection.receive () method. When the J2ME application sends an NDEF message to the card using the NFCConnection.send () method, the simulator will notify the user using the following dialog box:

3.2.

Using real RFID hardware

The RI has support for using commercially available RFID hardware, specially the Mifare Pegoda reader from Philips: http://www.semiconductors.philips.com/acrobat_download/other/identification/PE066010.pdf The RI needs various driver dlls to communicate with the Pegoda reader. These dlls are not part of the RI release; instead they can be obtained by installing the 'MifareWnd' application from the Pegoda Reader CDROM. After installation, the directory where MifareWnd is installed should be added to the PATH so the RI can find the necessary dlls: set PATH=%PATH%;c:\Program Files\Philips Semiconductors\MifareWnd The RI by default is configured to use the simulator. To use the Pegoda reader, some changes need to be made in the RI configuration file Prototype_3_0_S40_128x128_MIDP_Emulator/bin/contactless_config.xml:



4. SAMPLE APPLICATIONS The RI contains three small sample applications, one for RFID tags, one for visual tags (barcodes), and one for creating different types of NDEF records.

4.1.

Directory structure

Each sample application locates under JSR_257_RI_1_0/samples in separated folders as barcode, contactless and ndef. Once the JSR-257 RI is installed, the sample directories along with its subdirectories are also created. The contents of these directories are as follows (on Win32 platforms assume backslashes in directory paths, instead of forward slashes used here). File or Directory bin/ res/ src/

4.2.

Contents Sample application binaries, Ant build script and starting bat file. Resource files used by application. Source code of sample application.

Building the sample applications

Each sample can be built using the Ant build file build.xml in the bin subdirectory of the sample. The build process requires the Antenna Ant extension, available here: http://antenna.sourceforge.net/

Before building the application you have to edit the xml file and set the necessary locations: • wtk.home should be set to the to the installation location of the Sun Wireless Toolkit, e.g. c:\WTK2.2. • the ‘classpath’ attribute of the ‘taskdef’ element should be set to the location of the Antenna JAR file.

4.3.

Installing sample applications to a mobile device

If you want to try sample applications on a JSR-257 enabled device, sample MIDlets must be downloaded to a mobile device through the serial or USB cable, or using over-the-air protocol. The application binaries can be found under bin directories.

4.4.

Running sample applications

In case of emulator is used, each sample can be started by running the run.bat file in the bin subdirectory of the sample. If the sample application is installed on a JSR 257 enabled mobile phone, you can run it similar to other installed Java applications.

4.5.

The ‘Contactless’ sample application

This sample application consists of two midlets: •



the ‘Contactless’ midlet demonstrates reading from a tag. It waits for a tag to be inserted into the RF field, reads its contents, and displays it in the emulator window. Only a small amount of content types are supported, i.e. “text/x-uri”. the “ContactlessWrite” midlet demonstrates writing data to a tag.

This sample also demonstrates PushRegistry support. If a tag with an NDEF record of type ‘U’ is inserted into the RF field, the “Contactless” midlet is started automatically by the emulator.

4.6.

The ‘Barcode’ sample application

This sample demonstrates decoding barcodes. It reads an image containing a barcode from a resource, and decodes it into a string.

4.7.

The ‘NDEF’ sample application

This sample demonstrates creating different types of NDEF records and messages. It could also be run under J2SE by adding the contactless.jar file found under lib/ext to the CLASSPATH.