|
By Alka Gupta and Mayank Srivastava
|
|
|
Contents
Overview of the SampleRFID Application
This document introduces the audience to developing and deploying a Java technology-based RFID solution using the Sun Java System RFID Event Manager, Sun Java System Application Server, and the Solaris Operating System. It is accompanied by a sample application called SampleRFID, which represents a typical supply-chain management application that reads and processes RFID data from RFID readers in real-time. SampleRFID is a Java 2 Platform, Enterprise Edition (J2EE) application.
Requirements
- Software
- Sun Java System RFID Event Manager 1.0
- Sun Java System Application Server 7.x or 8.x
- JVM 1.4.2
- Oracle RDBMS
- Solaris 8 or Solaris 9 Operating System
- Hardware
- System running Solaris OS, SPARC or x86 platform
- RFID Reader
- RFID Tags
Architecture of the SampleRFID application
SampleRFID application consists of four components:
- RFID Reader, Tags and Antenna
- Sun Java System RFID Event Manager
- Sun Java System Application Server
- Oracle Database
As depicted in Figure 1, two antennae are located at two separate locations: Door1 and Door2. Both antennae are connected to the same Reader via a wired cable. RFID tags are read by the two antennae, and the information is communicated to the RFID reader. The Reader in turn sends the RFID events to the RFID Event Manager via cabled or wireless LAN. The Event Manager processes the events and sends PML messages to the Sun Java System Application Server via JMS, again via wired or wireless LAN. The PML messages are processed by the SampleRFID application running on the Application Server. SampleRFID communicates with Oracle database over Java DataBase Connectivity (JDBC) software, which serves as the repository of all the information on the tagged items scanned by the reader and by the RFID Event Manager. The SampleRFID application does not make use of the Sun Java System RFID Information Server.
Figure 1: Architecture of the SampleRFID Application
The above architecture is extensible to include multiple readers and antennae, as well as Sun Java System Event Manager instances. For example, there might be more than one reader in a big warehouse, communicating to multiple Execution Agents within a single instance of the Event Manager. Multiple Event Manager instances might be running on separate systems located in geographically different locations and sub-networks within a supply-chain.
Install and set up the platform for the SampleRFID application
Step 1: Download the SampleRFID application software called SampleRFID.zip
Extract the SampleRFID software from the archive
SampleRFID.zip contains the following files:
SQL scripts containing the schema and data for populating the database used by the SampleRFID application
The J2EE application module to be deployed on the Application Server. The war file contains the application source code as well.
Example RFID Event Manager configuration file, which may be used to configure multiple readers and antennae
This is a simulator application provided for sending PML messages to the SampleRFID application. Check the Appendix section for details on its description and use.
Step 2: Download and install the Oracle RDBMS
Download Oracle from http://www.oracle.com. Follow the associated instructions to install and run Oracle RDBMS. Use the script files provided with the SampleRFID.zip archive to create and populate the tables needed by the SampleRFID application. Oracle RDBMS can be run on a remote or a local machine. The database communicates with the Application Server through JDBC. Make sure that the Oracle JDBC driver classes are in the classpath of the Application Server.
Any other database that can communicate with Sun Java System Application Server over JDBC can be used as an alternate to Oracle RDBMS.
Step 3: Download and install Sun Java System Application Server
The Solaris OS, release 9 or higher, has the Sun Java System Application Server bundled into it. It is installed in the directory /usr/appserver. On Solaris 8 or other releases, download and install Sun Java System Application Server. Use the associated documentation for instructions on how to install and run the Application Server. In this document, it is assumed that the Sun Java System Application Server is installed in the directory /usr/appserver. To start the application server, run the following
command:
#/usr/appserver/bin/asadmin
asadmin> start-appserv
Go to the Application Server administration console at
http://hostname:4848 for further administration tasks.
Modify the server's server.policy configuration file to include only the following line:
grant{ permission java.security.AllPermission;};
Step 4: Download and set up the Sun Java System RFID Event
Download the Sun Java System RFID software. It includes the RFID Event Manager and the Information Server. SampleRFID makes use of only the RFID Event Manager.
unzip the software in the directory /tmp. Then cd to the /tmp/rfidem directory. Start the RFID Event Manager Install Wizard by running the ./setup executable from this location. An install GUI is presented. Follow the instructions. For details, readers are referred to product Installation and Administration guides.
By default, the software will be installed as follows:
/opt/SUNWrfid includes the software binaries, libraries and startup scripts.
/var/opt/SUNWrfid includes the log files for the Execution Agents and the Control Station.
/etc/opt/SUNWrfid includes the configuration files, including RfidConfig.xml, which describes the configuration of the Reader adapters, smoothers, filters and loggers.
Once the software is installed, go to /opt/SUNWrfid/bin and run the startall script to start the RFID Event Manager. At installation, the Sun Java RFID system is configured to run as follows.
The Event Manager software comes packaged with a simulator software reader called PMLReader, the adapter to which is called PMLAdapter. PMLReader is a software program that generates the emulated RFID events. It is installed in the directory /opt/SUNWrfid/bin. By default, RfidConfig.xml file is configured to communicate with the PMLReader. Hence, at installation, the Event Manager listens to the RFID events from the PMLReader simulator. The simulator can be used to test, debug and use the RFID system in the absence of RFID reader hardware. However, it should be used for demonstration purposes only. PMLReader uses the file /etc/opt/SUNWrfid/system/Simulators.properties to specify its runtime parameters, such as the number of EPCs to generate the actual EPC codes. The output from the RFID Event Manager is sent to a GUI screen called the EPC Viewer. When the Event Manager is run, EPC Viewer shows up on the terminal monitor.
To start the Event Manager, go to the directory /opt/SUNWrfid/bin.
Type ./startall.
To stop the Event Manager, go to the directory /opt/SUNWrfid/bin.
Type ./stopall.
The Event Manager must be executed as root. Also, root privileges must be given to the windowing system by running the command xhost +.
If the EPC Viewer does not appear on starting the Event Manager, refer to the system logs as described in the Troubleshooting section later in the document.
To start the PMLReader, go to the directory /opt/SUNWrfid/bin and type PMLReader. The EPC Viewer terminal window should display the tags information as described in Simulator.properties file. Also check out the PML output in the file /var/opt/SUNWrfid/RfidFileLogger.out. This is the file name where the PML messages generated by the Event Manager are logged as per the default configuration. The PMLReader can be run as any user.
One of the important properties for PMLReader configuration is the port number. For a given Reader name, the readerepc and port properties must match between the RfidConfig.xml and Simulators.properties files. The configuration information for the leading hardware Readers supported by the Event Manager is also provided in RfidConfig.xml, however, it is commented at installation.
The following snippet includes portions of the PMLAdapter configuration. For the complete configuration, refer to the RfidConfig.xml file included in the software.
<ems:adapter>
<!--Name of the PMLReader Adapter-->
<ems:name>PMLReader</ems:name>
<ems:classname>com.sun.autoid.adapter.pml.PMLAdapter</ems:classname>
<ems:properties>
<!--The IP address of the PMLReader-->
<ems:property>hostname</ems:property>
<ems:value>localhost</ems:value>
</ems:properties>
<ems:properties>
<!--The port number of the PMLReader
simulator-->
<ems:property>port</ems:property>
<ems:value>9092</ems:value>
</ems:properties>
<ems:properties>
<!--The EPC number of the Reader-->
<ems:property>readerepc</ems:property>
<ems:value>urn:epc:tag:gid-96:1.255.1</ems:value>
</ems:properties>
<ems:outputs>
<!--The name of the output filters-->
<ems:output>RfidSmoother</ems:output>
<ems:output>EpcGuiLogger</ems:output>
</ems:outputs>
</ems:adapter>
The following snippet shows the Simulator.properties
file included in the software:
readers=Reader1
#Port number of the PMLReader
Reader1.port=9092
#EPC number of the PMLReader
Reader1.readerepc=urn\:epc\:tag\:gid-96\:1.255.1
Reader1.epc=urn\:epc\:tag\:gid-96\:1.1.100
Reader1.setsize=1
Reader1.generator=sequential
Reader1.minCycleTime=9000
Reader1.maxCycleTime=11000
If PMLAdapter is not to be used, the PMLReader adapter may be removed from the RfidConfig.xml file.
Step 5: Set up the RFID Reader hardware
Sun Java System RFID Event Manager provides the adapters for the Readers from the following leading vendors:
- Matrics Reader
(com.sun.autoid.adapter.matrics.MatricsReaderAdapter) from Matrics
- Alien Reader
(com.sun.autoid.adapter.alien.NanoScannerAdapter) from Alien Technology
- ThingMagic Reader
(com.sun.autoid.adapter.tyco.Mercury3Adapter) from Sensormatic
- SAMSysMP9320 Reader
(com.sun.autoid.adapter.SAMSys.SAMSysAdapter) from SAMSys Technologies
For the latest on the supported Readers, please check the software documentation Release Notes.
The default configuration information for the above readers is available in the file RfidConfig.xml. This section describes how to set up a ThingMagic Reader. To set up any of the other supported readers, follow the instructions provided by the corresponding vendors.
Connect the ThingMagic reader to one or more antennae. Connect the power cord to the power supply. The Reader comes with a default IP address and port number as documented by the vendor. To change the IP address, port number or other configuration parameters, connect the reader to a computer via a cross over cable. Access the default IP address from a browser on port 80. A GUI is presented which enables the reconfiguration of the reader, including IP address and port number.
To configure the RFID Event Manager to connect and talk to the Reader, edit the configuration file RfidConfig.xml in the directory /etc/opt/SUNWrfid. By default, it is configured to run with the simulator called PMLAdapter as described in Step 4. Comment this adapter, and uncomment the adapter information corresponding to ThingMagic. Set the hostname element to the IP address of the Reader as set above. Stop and Start the Event Manager. The EPC Viewer screen should come up. Bring one or more EPC tags in view of the antenna. EPC Viewer displays the tags in view of the antenna and the count of the number of times each tag is read while it is in view.
Step 6: Configure the Event Manager to connect with the Sun Java System Application Server
The Event Manager can log the events to a variety of loggers including file, socket, http and JMS. The SampleRFID application demonstrates how to configure the Event Manager to log the events to a file and a JMS queue. To configure the Event Manager to log the events to a JMS queue, a JMS logger needs to be added to the RfidConfig.xml file. By default, at installation, only a file logger is provided. The following snippet shows the JMS logger configuration. Add this piece of code to the RfidConfig.xml file after the FileLogger.
<!--JMS Logger configuration-->
<ems:logger>
<!--Name of the JMS Logger, must be unique for a given Event Manager
instance, classname is the name of the class which implements the
logger-->
<ems:name>JMSLogger</ems:name>
<ems:classname>com.sun.autoid.logger.JMSLogger</ems:classname>
<ems:properties>
<!--Defines the detail of the logging information to be
generated by the logger-->
<ems:property>LogLevel</ems:property>
<ems:value>INFO</ems:value>
</ems:properties>
<ems:properties>
<!--Defines the JNDI binding Service Provider URL
-->
<ems:property>JndiProviderURL</ems:property>
<ems:value>file:///tmp1</ems:value>
</ems:properties>
<ems:properties>
<!--Defines the JNDI JMS Connection Factory name
-->
<ems:property>ConnectionFactory</ems:property>
<ems:value>sampleRFIDQCF</ems:value>
</ems:properties>
<ems:properties>
<!--Defines the JNDI JMS Destination resource name
-->
<ems:property>QueueName</ems:property>
<ems:value>sampleRFIDQ</ems:value>
</ems:properties>
<ems:properties>
<!--Defines the JNDI Context Factory -->
<ems:property>JndiContextFactory</ems:property>
<ems:value>com.sun.jndi.fscontext.RefFSContextFactory</ems:value>
</ems:properties>
</ems:logger>
The preceding configuration parameters do the following:
When the Event Manager is run, an instance of the class com.sun.autoid.logger.J, MSLogger is created, which binds a Connection Factory called sampleRFIDQCF, a queue called sampleRFIDQ using a local JMS binding file called /tmp1. The Event Manager posts the PML messages on this queue. SampleRFID application communicates with the RFID Event Manager on this JMS queue.
Also add the following line to the
<ems:outputs> element of the RfidDelta Filter
in the RfidConfig.xml file.
<ems:output>JMSLogger</ems:output>
This is in addition to the FileLogger already defined in this filter.
Step 7: Configure the Sun Java System Messaging and Application Server to receive messages on the JMS queue
Create a directory /tmp1 using the UNIX command mkdir /tmp1
Run the IMQ broker if it is not already running on the local machine
/usr/bin/imqbrokerd
Run the IMQ Admin utility to create the JMS bindings file, the Destination Queue and the Connection Factory as follows:
/usr/bin/imqadmin
Create a new objectStore by the name RFID
Right click on RFID
Connect to the new objectStore
Select properties
Configure the property java.naming.factory.initial as com.sun.jndi.fscontext.RefFSContextFactory
Configure the property java.naming.provider.uri as file:///tmp1
Add a destination Queue to this objectStore by the name sampleRFIDQ
Add a QueueConnectionFactory to this objectStore by the name sampleRFIDQCF
Exit from IMQ Admin utility
For more detailed information on this configuration, readers are referred to the product Administration Guide.
To use alternate names for the above IMQ parameters, the deployment descriptor file web.xml included in the SampleRfid.war module needs to be modified.
The SampleRFID application uses the PMLParser provided with the RFID Event Manager Software for unmarshaling and manipulating the PML messages. The PMLParser utility jar file called pml-util.jar is packaged in the directory /opt/SUNWrfid/lib of the RFID Event Manager software. SampleRFID application also requires the Java Architecture for XML Binding (JAXB) classes in the directory /opt/SUNWrfid/lib/utils. Include these jar files in the classpath of the Application Server by following the instructions below:
Go to the Application Server admin console at
http://<hostname>:4848
Select :
server1 -> JVM Settings -> Path Settings
In the Classpath suffix section, add
/opt/SUNWrfid/lib/ pml-util.jar
Select:
server1 -> JVM Settings -> JVM Options
Add
-Djava.endorsed.dirs=/opt/SUNWrfid/lib/utils
Apply changes and restart the application server.
Step 8: Configure the Sun Java System Application Server to communicate with Oracle RDBMS
To configure the Oracle Database to communicate with the Application Server, configure a JDBC Resource with Java Naming and Directory Interface (JNDI) name jdbc/SampleRfidDB using the Application Server administration console. Configure the associated JDBC Connection-Pool with Oracle 8i or Oracle 9i as the Database vendor. Configure the remaining properties as per the database settings of the Oracle installation and setup in Step 2.
To use an alternate JNDI name for the JDBC Resource, the web.xml and sun-web.xml deployment descriptor files included in the SampleRFID.war module would need to be modified.
Step 9: Deploy the SampleRFID.war module
Deploy SampleRFID.war module from the Sun Java System administration console or using the asadmin command line utility.
Step 10: Restart the Application Server and the RFID Event Manager
# cd /usr/appserv/bin
# asadmin
# appserv>stop-appserv
# appserv>start-appserv
# cd /opt/SUNWrfid/bin
# stopall
# startall
Watch for any exceptions in the following log files:
/var/opt/SUNWrfid/logs/agent_0.log
/var/opt/SUNWrfid/station_0.log
/var/appserver/domains/domain1/server1/logs
Step 11: Run the SampleRFID application
Point a browser to http://<hostname:port>/SampleRFID where hostname and port correspond to the Sun Java System Application Server hostname and port number. Click on "Real Time Query" link on the left navigation bar. Bring a tag in view of the Reader. The tag information should appear on the browser.
Using the SampleRFID Application
When a tag is brought in view or taken out of view of a reader, an event is sent by the Event Manager to the SampleRFID application as a PML message. SampleRFID application parses the message and stores the information corresponding to the tag in the database repository. SampleRFID "real-time" page also displays the information in the browser in real time. The following dynamic information corresponding to a tagged item is derived from the PML message and stored in the database:
- Tag EPC URI
- Tag Reader-antenna EPC
- Date and Time the tag was read
- Current status of the Tag (TagIn or TagOut) w.r.t to a Reader and Antenna
When an item with a new EPC whose information is not registered in the database is scanned by the reader, it gets stored as an un-registered item. An admin page is provided which can be used for registering and configuring new items.
Some of the static registration information besides the dynamic information derived from the PML message which can be stored in the database includes:
- Tag EPC URI
- Description of items for a given tag EPC. The item description includes:
- Image
- Item type
- Item Category
- Mapping of a Reader-Antenna EPC with a location for tracking the movement of items
All items in the database can be sorted or retrieved by choosing one of the following criteria:
- All: Displays all items in the database
- Category: Displays all items for the selected category
- EPC URI: Displays the item for the selected EPC
- Date-time: Data can be further sorted by choosing a date-time duration
A history of each item is maintained in the database as follows. Every time a given item is scanned by the reader, all of the information included in the PML message is logged in the repository by SampleRFID. This enables the history of the item with a unique EPC to be retrieved from the database. The history may include business-level information such as:
- Location and movement of an item over, say, the last 3 days
- Count or Number of items for a given category in store
- Out of stock information when item count goes to zero
- Number of days an item lives in a particular location before it is moved. For example, how long an item was on a shelf in a store before it was sold.
The source code for the SampleRFID application along with the database schema is included inside the SampleRfid.war module. It also includes a build.xml file for compiling the source code.
Configure the RFID Event Manager with multiple readers and antennae
A single instance of RFID Event Manager can read and manage events from multiple readers by defining multiple Execution Agents. To configure the Event Manager to communicate with more than one reader, an adapter for each of the readers must be present in sequence in the file RfidConfig.xml. Each Reader's IP address is assigned to the hostname property of the corresponding Reader adapter in the RfidConfig.xml file. To distinguish the tags being read from different readers, a unique Reader EPC must be assigned to each of the readers. Each adapter can be configured to send output to the same or different smoothers, filters and loggers. One such RfidConfig.xml file, provided as part of the archive SampleRFID.zip, is called MultiReaderConfig.xml.
If a reader can have multiple antennae attached to it, a unique EPC can be assigned to each of the antennae via additional property elements in the configuration file in order to discriminate the antennae. For instance, the two element names for the ThingMagic UHF antennae are readerepcUHF1 and readerepcUHF2. By assigning a unique EPC to each of them, the two antennae can be discriminated. When an item is scanned by each of the antennae, the EPC of the antenna is transferred by Event Manager as part of the PML message. This EPC overrides the EPC of the Reader. This discrimination can further help identify the location of the tagged item if the location of each antenna is known. For example, if Antenna1 with EPC1 is mapped to location dock door1 in the warehouse and Antenna2 with EPC2 is mapped to location dock door2 in a warehouse, when the tagged item moves from dock door1 to door2, two EPC events will be sent as PML messages to the Application Server by the RFID Event Manager. These messages will include the EPC of the antennae that read the tagged items. A TagOut command along with Antenna1 EPC will be sent when the item moves out of the view of door1 antenna. Similarly, a TagIn command will be sent when the item moves into the view of door2 antenna. The SampleRFID database schema tables are designed to include antenna EPCs and corresponding locations for tracking inventory movement.
To use the SampleRFID application with multiple readers and antennae, copy the MultiRfidConfig.xml provided with the SampleRFID.zip archive to the directory /etc/opt/SUNWrfid as RfidConfig.xml. Edit this file for configuration of adapters as needed depending on the readers and antennae being used. Assign appropriate IP addresses and EPC numbers to the property elements for each of the adapters. Restart the RFID Event Manager.
Configure the RFID Event Manager to communicate with multiple EIS applications
A single instance of the RFID Event Manager can be configured to communicate with more than one EIS application by one of the following methods:
- If there are multiple Readers, define multiple Execution Agents, one for each Reader. Associate a unique Logger with each Execution Agent. Each logger can be configured to communicate to a different application by defining different JMS queues for each Execution Agent-Application pair.
- Output from a single Reader can be sent to multiple applications by defining a single Execution Agent and associating multiple loggers to it. Each logger can be configured to communicate to a different application by defining different JMS queues for each Logger-Application pair.
Troubleshooting
Problem:
Solution:
The log files for the Control station and the Execution Agent are located in the
directories:
/var/opt/SUNWrfid/logs
All exceptions and error messages are located in the log files in these
directories and can be used for debugging purposes. By default, only
Severe problems, Warnings and Information messages are logged. The
above logging directory is the default one and is defined in the Log
Policy files: /etc/opt/SUNWrfid/system/logging-agent.properties
and /etc/opt/SUNWrfid/system/logging-station.properties
Problem:
Only one control station can run within a single
sub-network.
An attempt to run multiple control stations will result in an exception
and failure of the second control station to be launched. This is due
to the conflict between the Group IDs of the two instances within the
same subnet.
Solution:
Modify the following files:
File: /etc/opt/SUNWrfid/Rfid.xml
Change the Group AutoID to a different
AutoID group name.
<?xml version= 1.0 encoding= ISO-8859-1 standalone= no
?>
<!DOCTYPE opstring SYSTEM "java://com/sun/rio/dtd/rio_opstring.dtd" [
<!ENTITY Local.IP 10.6.165.65 >
<!ENTITY Local.Port 9000 >
<!ENTITY CodeServerURL http://&Local.IP;:&Local.Port;/
>
<!ENTITY Group AutoID >
]>
Files: /etc/opt/SUNWrfid/system/env.station and
/etc//opt/SUNWrfid/system/env.agent
Change RFIDEM_LUSGROUP=AutoID to a different group name.
If [ $RFIDEM_LUSGROUP = ]
then
RFIDEM_LUSGROUP=AutoID
export RFIDEM_LUSGROUP
fi
File: /etc//opt/SUNWrfid/infrastructure.xml
Change the Group AutoID to a different
AutoID group name.
<?xml version="1.0" encoding="ISO-8859-1"
standalone="no"?>
<!DOCTYPE opstring SYSTEM "java://com/sun/rio/dtd/rio_opstring.dtd"
[
<!ENTITY Local.IP SYSTEM
java://java.net.InetAddress.getLocalHost().getHostAddress()" >
<!ENTITY CodeServerURL "http://&Local.IP;:52493/"
>
<!ENTITY Group " AutoID" >
]>
Problem:
Change the IP address of the RFID Event
Manager
Solution:
Edit the following files:
/etc/opt/SUNWrfid/system/csenv.conf (RFIDEM_WEBSTER_HOST)
/etc/opt/SUNWrfid/system/agentenv.conf (RFIDEM_WEBSTER_HOST)
/etc/opt/SUNWrfid/Rfid.xml (Local.IP)
/etc/opt/SUNWrfid/infrastructure.xml (Local.IP)
Appendix
SampleRFID.zip includes an archive file called PMLSenderSimulator.zip. To test the J2EE side of the SampleRFID application without installing or configuring the RFID Event Manager, the PMLSenderSimulator.zip includes a PML Sender application called PMLSender.java, as well as a PML message file called
#unzip PMLSenderSimulator.zip
There are three files in this archive:
PMLMessage.xml
PMLSender.java
RunSend.sh
Edit the RunSend.sh appropriately to set the PATH and CLASSPATH appropriately. Then, run as follows:
#chmod +x RunSend.sh
#./RunSend.sh
This will compile and run PMLSender.java and post the PML message as included in the file PMLMessage.xml to the JMS queue sampleRFIDQ. This message should automatically appear at the URL http://<hostname>:<port>/SampleRfid.html where hostname and port correspond to the Sun Java System Application Server hostname and port number.
References
| 
Print-friendly Version
