Attachment_0008_DoD Active RFID Common Abstraction Interface Developers ....docx

Attachment 0008

**NOTE**: This attachment will be updated to include the functionality required by the intrusion detection and sensor transponders (as it is defined).

DoD Active RFID Common Abstraction Interface JAR description

The Common Abstraction Interface (CAI) provides software interfaces that standardize the way RFID software applications (both Government and vendor developed) communicate with vendor provided active RFID hardware. For more information see the DoD Active RFID Common Abstraction Interface Developers Guide below.

The JAR file will be made available upon request after proposal submittal.

DoD Active RFID Common Abstraction Interface Developer’s Guide Version 2.0

Introduction

This document covers the functionality provided by the DoD Active RFID Common Abstraction Interface (CAI). Its intended audience includes both RF-ITV software application developers and RF-ITV hardware providers planning to implement a CAI compliant driver for their active RFID products.

The intent of the CAI is to provide a well-defined set of software interfaces (written in Java) that standardizes the way RFID software applications (both Government and vendor developed) communicate with vendor provided active RFID hardware (transponders and interrogators).

Using the CAI, software developers can write a single application that works with any vendor supplied active RFID hardware (including the existing DoD Active RFID infrastructure). In addition, the CAI is an extendible framework that allows active RFID hardware vendors to provide additional functionality.

The CAI is primarily focused on supporting active RFID devices that adhere to the ISO/IEC 18000-7 Air Interface standard (in addition to the current DoD Active RFID infrastructure that is based primarily on ANSI INCITS).

A high-level diagram of the DoD Active RFID Architecture is shown in the figure below to help describe where the CAI fits in.

Edge Applications Gov. Furnished Info Vendor Provided Any Transponder Legacy

CAI Structure

The CAI is composed of classes and interfaces, some of which are implemented and some of which are required / optional for implementation by a vendor who is creating an active RFID driver for their hardware. Detailed descriptions of these classes and interfaces can be found in the JAR file, DoD Active RFID Common Abstraction Interface Developer’s JavaDoc. The lists below outline the different categories:

Implemented classes – These classes are implemented within the CAI and are used for (1) the registering and management of RFID drivers, and (2) handling exceptions from devices and transponders.

gov.pmjait.cai.RFIDManager gov.pmjait.cai.driverRegistration.RFIDDriverRegistrationUI gov.pmjait.cai.driverRegistration.RFIDDriverRegInfo gov.pmjait.cai.device.DeviceConnectionException gov.pmjait.cai.device.DeviceException gov.pmjait.cai.tag.TagException

Required interfaces – These interfaces must be implemented by a vendor in order to have a complete RFID driver. They define the minimum required functionality between the RFID software and hardware (interfaces with ** after the name are still in development and subject to change).

gov.pmjait.cai.RFIDDriver gov.pmjait.cai.DriverInfo gov.pmjait.cai.GPSLocation ** gov.pmjait.cai.device.DeviceConnection gov.pmjait.cai.device.DeviceConnectionFactory gov.pmjait.cai.device.DeviceFactory gov.pmjait.cai.device.ISO180007Reader gov.pmjait.cai.device.GPSISO180007Reader ** gov.pmjait.cai.device.HHISO180007Reader ** gov.pmjait.cai.device.ISO180007WriteDevice gov.pmjait.cai.tag.ISO180007Tag gov.pmjait.cai.tag.ISO180007TagEvent gov.pmjait.cai.tag.TagFactory gov.pmjait.cai.tag.table.TagTableProperties gov.pmjait.cai.tag.udbElements.ApplicationExtensionBlock gov.pmjait.cai.tag.udbElements.ApplicationExtensionElement gov.pmjait.cai.tag.udbElements.ApplicationIDTLDElement gov.pmjait.cai.tag.udbElements.ApplicationTLDElement gov.pmjait.cai.tag.udbElements.HardwareFaultStatusElement gov.pmjait.cai.tag.udbElements.MemorySizeElement gov.pmjait.cai.tag.udbElements.OptionalCommandListElement gov.pmjait.cai.tag.udbElements.RoutingCodeElement gov.pmjait.cai.tag.udbElements.SensorStatusElement gov.pmjait.cai.tag.udbElements.TableQueryResultsElement gov.pmjait.cai.tag.udbElements.UserIDElement

Optional interfaces – These interfaces can be optionally implemented by a vendor as part of an RFID driver implementation. They primarily define interfaces used for supporting the existing DoD Active RFID infrastructure (legacy support), transponders with sensors, and higher level interfaces (interfaces with ** after the name are still in development and subject to change).

gov.pmjait.cai.device.Device gov.pmjait.cai.device.Reader (required for legacy support) gov.pmjait.cai.device.TagConnectionListener gov.pmjait.cai.device.CollectEventListener gov.pmjait.cai.device.WriteDevice (required for legacy support) gov.pmjait.cai.tag.ActiveTag gov.pmjait.cai.tag.DatabaseTag (required for legacy support) gov.pmjait.cai.tag.ISO180007SensorTag ** gov.pmjait.cai.tag.SensorTag ** gov.pmjait.cai.tag.Tag gov.pmjait.cai.tag.TagEvent (required for legacy support) gov.pmjait.cai.tag.udbElements.UDBElement

Driver Registration

Active RFID products developed by vendors for the DoD will include an RFID driver that at a minimum implements the required interfaces listed above for their RFID hardware. In addition, PD AMIS will provide a reference transponder hardwire driver implementation that can communicate with any RFID III and RFID IV compliant transponders over a standardized USB connection, which vendors can use (either incorporating directly or as the foundation of their own implementation). So, at a minimum, a typical RFID workstation could have at least two RFID drivers installed (and possibly more). In order to facilitate the appropriate loading and initializing of multiple RFID drivers, an RFID driver registration process and utilities are provided as part of the CAI. The figure below depicts the driver registration and driver loading process:

As shown in the figure, the RFID driver registration information is stored in a properties file on the host system. The properties file has the structure provided in the Java java.util.Properties class (see http://java.sun.com/j2se/1.5.0/docs/api/java/util/Properties.html for more details) and can be stored either in the root directory of the hard drive that contains the user’s home directory (typically C: on a Windows system) with the name “RFIDDrivers.Properties” or in a file specified by the user in the execution command line as a system property called “PropLoc” (-DPropLoc=”C:\RFIDDrivers.Reader”). The contents of an example properties file is shown below:

#DOD RFID Driver Registration File #Thu Feb 28 15:52:28 PST 2008 driver.count=2 driver0.deviceconntype=RS-232 driver1.classname=gov.dod.rfid.driver.DODRFIDDriver driver1.deviceconntype=RS-232 driver1.deviceconnid=COM9,115200 driver0.devicedescription=ISO USB Cable on COM11 driver0.deviceconnid=COM11,38400 driver0.classname=gov.dod.rfid.driver.DODRFIDDriver driver1.devicedescription=DOD ISO Reader on COM9

The first two lines of the properties file are comments (denoted by a # symbol as the first character). The following lines are name-value pairs (name followed by an “=” sign followed by the value) that contain the following:

· A name-value pair named driver.count whose value indicates the number of drivers that are present in the properties file (in the example above there are 2)

· A set of name-value pairs for each driver that is registered in the file that contains the following (each name starts with the word driver followed by a number for the registration it is referring to (zero based)):

· A name-value pair named driver<<driver reg. number>>.classname whose value indicates the java class name of the class in the RFID Driver that implements the gov.pmjait.cai.RFIDDriver interface

· A name-value pair named driver<<driver reg. number>>.deviceconntype whose value indicates the type of physical connection to be used and should be one of the following values (defined as constants in the RFIDDriverManager class): “Ethernet”, “Generic”, “RS-232”, or “RS-485”.

· A name-value pair named driver<<driver reg. number>>.deviceconnid whose value provides any vendor specific parameters needed to initialize the driver for the specific connection type. In the example above the COM port and baud rate are included in this value.

· A name-value pair named driver<<driver reg. number>>.devicedescription whose value contains a string that describes the driver and devices for which it shall be used.

Notice from the example properties file that the ordering of the name-value pairs is not important. The CAI includes a simple RFID Driver Registration user interface (shown below) that can be used for generating the properties file described above.

The java main class to specify for executing the user interface is gov.pmjait.cai.driverRegistration.RFIDDriverRegistrationUI. The process of registering RFID Drivers on a given system is intended to be a one-time operation and can be done either by the vendor before shipment of a turnkey system, or by a Field Service Engineer (FSE) when the system is installed on site.

As part of the initialization process, an RFID software application must make the RFIDDriverManager.loadDrivers() method call, which will cause the RFIDDriverManager class to read the properties file and, for each registered RFID driver, make a Class.forName() call for the registered class name of the RFIDDriver interface implementation. Every RFIDDriver interface implementation class must have a static initializer block that does the following:

1. Request the list of driver registrations associated with this class name (there could be more than one) using the RFIDDriverManager.getDriverRegistrationInfo() method.

2. For each driver registration (returned from step 1), create a new instance of itself (the RFIDDriver implementation) and register it with the RFIDDriverManager using the RFIDDriverManager.registerDriver() method.

A sample static initializer block is demonstrated in the code fragment below:

public class DODRFIDDriver implements RFIDDriver {

// include a static initializer static { // first we need to request the registration information from the // driver manager List driverRegistrations = RFIDDriverManager.getDriverRegistrationInfo( "gov.dod.rfid.driver.DODRFIDDriver");

// next we need to go through the list and for each entry we need to // create a new driver instance for(int i=0;i<driverRegistrations.size();i++) { RFIDDriverRegInfo dri = (RFIDDriverRegInfo) driverRegistrations.get(i);

// next we need to construct an instance of the driver using the // registration info DODRFIDDriver curDriver = new DODRFIDDriver(dri);

// next we need to register the instance with the RFIDDriverManager RFIDDriverManager.registerDriver(curDriver,dri);

Basic Usage Tutorial

The CAI was designed to make performing RFID operations simple. This section will walk through examples of how to use the CAI to perform typical RFID operations.

The first example shows how to initialize the RFIDDriverManager and get a listing of all connected devices (interrogators or write cables):

// initialize all registered drivers RFIDDriverManager.loadDrivers();

// get a listing of all the connected devices List deviceList = RFIDDriverManager.getAllDevices();

// print out the types of devices Iterator deviceIter = deviceList.iterator();

int i=0;

while(deviceIter.hasNext()) { Device curDevice = (Device) deviceIter.next();

if(curDevice instanceof WriteDevice) {

} else { System.out.println("Device " + i + " is a WriteDevice");

} else if(curDevice instanceof Reader) { if(curDevice instanceof ISO180007Reader) { System.out.println("Device " + i + " is an ISO180007Reader");

} else { System.out.println("Device " + i + " is a Reader");

i++;

The next example shows how to perform a collect from an interrogator and for each tag collected, print out the tag ID and the Routing Code:

ISO180007Reader reader = (ISO180007Reader) curDevice;

List tagEventList = reader.collect(60);

System.out.println("Number of tags found was: " + tagEventList.size());

// loop through the tags events and see what we got in the UDBs for(int j=0;j<tagEventList.size();j++) { ISO180007TagEvent curTagEvent = (ISO180007TagEvent) tagEventList.get(j);

System.out.println("The tag id is: " + curTagEvent.getTagID());

RoutingCodeElement rce = (RoutingCodeElement) curTagEvent.getTagDataElement(UDBElement.ELEMENT_ROUTING_CODE);

if(rce != null) { System.out.println("\tThe routing code for tag " + curTagEvent.getTagID() + " is " + rce.getRoutingCode());

Notice that this example uses a synchronous collect with a 60 second timeout (meaning that the call is guaranteed to return after 60 seconds even if the collection is not completed). There is also an asynchronous collection method in which classes that implement the CollectEventListener interface and register with the reader will receive callbacks when collection events take place. This version of the collect call also assumes the default UDB type to be returned, which is the TRANSIT type (User ID, Routing Code, and Application UDB extension).

The next example shows how to connect to a tag using a write cable, read the User ID and Routing Code, and reset the User ID to ‘1234’:

// attempt to load the DODRFID driver RFIDDriverManager.loadDrivers();

// get the driver object reference (using the driver description) driver = RFIDDriverManager.getRFIDDriver("ISO USB Cable on COM11");

// next get the Device Connection Factory assoicated with this driver DeviceConnectionFactory dcf = this.driver.

getDeviceConnectionFactory();

// now attempt to create a Device Connection object DeviceConnection dCon = dcf.createDeviceConnection();

// next discover all devices on this connection--for this example // a write cable is the connected device Collection devices = dCon.discoverDevices();

if (devices.size() == 0) { System.out.println("No devices were detected on the connection.");

JOptionPane.showMessageDialog(null, "Please connect a device", "No devices present", JOptionPane.INFORMATION_MESSAGE);

devices = dCon.discoverDevices();

// here we will assume that device zero is the write cable Iterator deviceIter = devices.iterator();

Device deviceZero = null;

while (deviceIter.hasNext()) { Device curDevice = (Device) deviceIter.next();

deviceZero = curDevice;

break;

// check to make sure the device is a write cable if(deviceZero.getDeviceType().equals(Device.DEVICE_TYPE_WRITE_STATION)) { // here we can downcast to a write device ISO180007WriteDevice writeStation = (ISO180007WriteDevice) deviceZero;

// print out the id for the device System.out.println("The device ID is: " + writeStation.getID());

// now attempt to perform a collect--here we will expect the // default UDB (TRANSIT type) to be returned List tags = writeStation.collect(20);

System.out.println("Collected " + tags.size() + " tags");

// next read the User ID and Routing Code--there should be // only one tag event collected since this is a write cable TagEvent tagEvent = (TagEvent) tags.get(0);

// next we can convert the Tag Event object into a full- // blown tag object (so that we can write the User ID) TagFactory tagFactory = driver.getTagFactory();

Tag tag = tagFactory.createTag(tagEvent,writeStation);

// next we can cast the tag object down to an ISO tag // (if possible) if(tag instanceof ISO180007Tag) { ISO180007Tag isoTag = (ISO180007Tag) tag;

// next we can read the current Routing Code and User ID // values from the tag System.out.println("The Routing Code is: " + isoTag.getRoutingCode());

System.out.println("The User ID is: " + isoTag.getUserID());

// next set the user id to 1234 isoTag.setUserID("1234");

Device IDs

ID values returned from Devices (interrogators and write cables) will vary depending on (1) whether they are active or inactive, and (2) whether they are legacy (pre-RIFD III). An active device is one that is capable of reporting its ID through electronic means (an interrogator is an example). An inactive device is one that has no means of reporting its ID (a USB write cable is an example). Non-Legacy active devices will report an ID that is 48-bits in length consisting of the 16-bit manufacturer ID (as defined by ISO / IEC 18000-7 Section 6.2.6.3) followed by a 32-bit serial number managed and administered by each manufacturer. An example of how to convert the ID from the 48-bit binary value into a string can be found in DoD Transponder Barcode Labeling Guidelines. Legacy active devices (existing interrogators) will retain their original identifiers. For inactive devices, the ID value reported through the CAI will be the MAC address of the first network adapter in the host computer prefixed with a “T”. An example of how the value will be returned from the CAI is show below:

Routing Code

The Routing Code that is stored on the transponder as part of the UDB signifies ownership and, as such, must not be changed as part of an erase operation. As part of the implementation of the clearMemory() method within the ActiveTag interface or any of it sub-interfaces (ISO180007Tag, etc.), any existing Routing Code value must be persisted on the transponder as part of the operation (the Routing Code value should be read and stored from the transponder, and then written back to the transponder once the memory has been cleared).

Time Outs

It is assumed that an RFID application developer will implement some form of timeout mechanism when communicating with RFID hardware (transponders and interrogators). It can be assumed that all point-to-point commands (barring a wake-up) will complete within 5 seconds or the transponder will respond with a tag exception (error code = 3F / sub code = 81).

Extendibility

As mentioned before, the CAI is an extendible framework and, as such, vendors who create CAI hardware drivers can include additional functionality beyond what is defined within the CAI interfaces and classes. This functionality will only be accessible, though, when using that specific vendor’s products and, as such, will only be useful in a closed environment (until such a time when it is deemed useful to incorporate the new functionality into the CAI).

Appendix A – Exceptions

The CAI contains three Exception classes: DeviceException, DeviceConnectionException, and TagException. All exceptions are classified by error codes and sub codes. The error codes and sub codes are extendable by vendors, but the CAI contains definitions of the standard error codes / sub codes that all vendors will use (at a minimum). A listing of the standard error codes / sub codes and their descriptions for each of the Exception classes is provided below:

DeviceConnectionException Error Codes

DeviceException Error Codes

Tag Exception Error Codes

DoD Active RFID Common Abstraction Interface Developer’s Guide image2.emf image3.png image1.emf oleObject1.bin PC (Read or Write Station)

TIPS

CMOS

GATES

Other GOTS Software

DOD RFID Common Abstraction Interface

Vendor X DOD RFID CAI Driver

Vendor X Interrogator

Any Vendor’s ISO 18000-7 Compliant Transponder

DOD RFID Table Manager Module

DOD Transponder Hardwire Driver

Network Interface (RS-485 / Ethernet)

ISO RF

Commands

Standardized Connection (USB)

DOD Legacy RFID CAI Driver

ANSI / ISO

Dual Mode Interrogator

ISO RF Commands

Network Interface (RS-485 / Ethernet)

ANSI Legacy / Upgraded ISO Transponders

RS-232 Connection

ANSI / ISO RF Commands