PIRF Lite Version 2.0

User Manual

Introduction PIRF Lite (Platform Independent RFID middleware) is a limited version of PIRF. Its purpose is to demonstrate the basic capabilities of the product and to be used as a base for the development of small RFID applications. It is distributed not as a separate product, but rather as optional installation package along with some of our other software products. The difference between this version and the full version of PIRF is that it does not include advanced features such as data persistence layer, SOAP (Web Services) support, support for RCRFID, support for additional RFID devices, HTTP server, etc. (please, see below for more details). Nevertheless, it is fully functional platform and could be used in variety of solutions. PIRF was developed by DataBrokers, Inc. to help fellow software developers with the task of designing RFID related solutions. In essence, it is a middleware API that implements methods to control RFID equipment such as RFID interrogators (readers). It also provides support for additional equipment, such as RFID Multiplexer devices, etc. Highlights PIRF is written in Java. It works with a number of operating systems. DataBrokers, Inc. supports MS-Windows and SuSe Linux 9.1. PIRF is PC based. From architecture stand point it belongs either to the controller, (i.e. the PC that is attached to the RFID reader) or the J2EE application server. PIRF is not an SDK for development of embedded firmware. Having said that, we would like to point out that DataBrokers, Inc. provides the RCRFID module as a separate product. It can replace in function the more expensive PC and it is supported by PIRF. RCRFID contains separate microprocessor and is capable of executing business logic. It does not have moving parts and has small power requirements and dimensions. RCRFID could be much cheaper, more reliable, and scalable alternative to the standard PC configuration. In such case (with RCRFID replacing the controller PC) PIRF will reside on a central server, communicating to a number of RCRFID modules over TCP/IP. This approach is especially useful for building web-based applications. PIRF implements the host protocols for a variety of RFID equipment in a consistent manner. It does that with the use of modular software drivers that are provided or could be added to the list. Once the developer has the proper driver, it could be put to use with a simple configuration change, or detected and loaded automatically by the framework. The rest of the application remains intact. The software developer could focus on the business logic without the need to implement and support low-level interfaces. PIRF is not a set of DLLs. Visual Basic and other Microsoft specific applications can interoperate with Java through SOAP. PIRF provides support SOAP interfaces. PIRF Lite does not. The case for PIRF Every RFID implementation includes more then just RFID readers and antennas. In many cases it may include more then one type of reader, tag, or both. The state of the technology today is such (and most probably will remain in the future), that each manufacturer provides different host protocol(s) for their devices. Standards of course exist, but they cover mostly the air protocols, not the host protocol between the controller (PC) and the reader. These protocols most often are complex. The manufacturers may provide some software libraries to help with the development of applications, but they are almost certainly incompatible with the other devices in the system. Naturally, the developer is left with a large number of incompatible software modules that need to work together. Adding a new device, or replacing an existing one basically means to rewrite entire parts of the application. This approach does not scale well and needless to say costs a lot of money to support. Even more importantly, the simplest of all cases is never realistic. In large implementations it is critical for the software to be able to control more than just the reader. It is a fact that in order to create a robust system every module needs to work seamlessly with the rest, presenting the look and feel of one integral system. Therefore, RFID readers often need to be controlled in tight cooperation with digital and analog sensors (including optical), attenuators, conveyor motors, door locks, barcode scanners, printers, and many other devices. When everything comes together it becomes obvious that a new approach is needed. This is especially true when one realizes that the individual software libraries provided by the respective manufacturers are all written in different languages, or do not run at all on UNIX, Linux, etc. The issue usually arises gradually, when companies start using one technology and later want to add new components or replace the vendor. Very soon it becomes clear that the biggest investment is not the RFID hardware, but the software that works with it, and unfortunately exactly that part becomes obsolete first. DataBrokers, Inc. has experienced the problem first hand. In each case it was difficult to modify the system after changing the RFID vendor. Based on this experience we decided to spend the time and money to develop platform and vendor independent middleware. The Essence of PIRF While designing PIRF we had the following goals: To provide a single consistent interface to all RFID related hardware components in the system; To achieve it in a vendor-neutral manner. In other words, we should be able to replace one RFID reader with another one, made by different company without the need to change the code, or the business logic in the system; To be able to execute on as many different platforms (operating systems) as possible; To design it in the best possible way, so it could be easily used in distributed environments and with special attention to the needs of web-based applications; Where possible to achieve plug-and-play feel; To make it modular, scalable, and customizable. We were able to hit all of our goals because: We created a modular architecture, based on well-defined interfaces, which in turn allows us to provide a number of drivers all with the same API. We spent long hours analyzing and comparing different RFID devices until we completed a single list of methods (functions) that they all share. This is not the lowest common denominator, but rather what an application developer really needs from an RFID device. We provide control for RFID devices from different vendors, and one driver can be substituted with another with a mere change in the configuration file or less. The rest of the system continues to operate as before. When a new device comes to market we develop a driver for it and simply add it to the list. In addition to the low-level hardware support we analyzed how implementations can cope with different transponder (RFID tag) types. As it stands today, every manufacturer has different data layout for their tags. Even if the client has selected a single vendor, corporations must have a strategy to change the tag at some point or another if nothing else to upgrade their systems. To help with that we developed several software abstractions that shield the developer (and the business logic) from the details of how exactly the data is stored on the chip. The developer is free to work with software concepts and can be assured that his code will not have to change as soon as a new chip is introduced. In addition this simply saves a lot of development time, which is better spent coding the business logic then figuring out the hexadecimal layout, addressing scheme and block order of the individual transponder. At the end we added tools to configure the middleware and allow it to find automatically the correct driver, which gives it its plug-and-play feel. To be able to execute on many platforms we developed our product entirely in Java, which enabled us to run the same code base without modifications on Windows, Windows CE, Linux, UNIX, etc. The object-oriented design makes it easy for the developers to extend and customize the framework. Product Comparison PIRF and PIRF Lite contain the same core. However, they differ in the number of modules and supported hardware. Please, see Fig.1. for comparison. Features PIRF PIRF Lite Base API libraries Yes Yes Set of device drivers Extended Set Basic Set Sample applications Yes Limited User Manual Yes Yes Sample applications Yes Limited Database persistence layer Yes No SOAP support Yes No Production SOAP server Yes No Support for RCRFID Yes No Fig.1. PIRF Architecture Fig.2. Note: The layers marked with ‘*’ are not included or are with limited support in PIRF Lite. The Hardware Layer represents the functionality provided by the devices. Those could be any number and combinations of RFID integrators, Multiplexers, Sensors, Attenuators, Microprocessor Modules, etc. Each may come from a different manufacturer with specific proprietary features. The interfaces may vary between serial, parallel, Ethernet, etc. DataBrokers, Inc. does not provide hardware with PIRF. However, such could be purchased separately from us or from other companies. PIRF Lite could also be purchased as a part of evaluation kits, which do include RFID hardware and tags. PIRF stays between the Custom Application and the hardware. It resides on the controller PC. Its purpose is to provide consistent API (Application Programming Interface) written in Java that could be used by IT teams to develop custom applications. The core of the framework is the Driver API. It is a collection of driver implementations, all featuring consistent interface. Every driver is aware of the capabilities and limitations of the specific device it is designed to control. Since they implement the same API, the individual drivers are interchangeable. You could easily substitute one device with another with a mere change in the configuration. Your code remains unaffected. For convenience, we provide the DriverFactory. It handles the details of driver instantiation and initialization. In conjunction with the XML configuration utilities (included, but not shown here) it provides plug-and-play feel to the system. The DriverFactory will parse the configuration file and attempt to automatically locate the proper driver for the device attached. Developers could implement their own instantiation mechanisms that obtain configuration information from relational and other data sources. Different tag manufacturers implement different data formats for their products. The internal data location, capacity, and addressing of custom data blocks may differ between tags even if they all operate based on the same air protocol standard. The issue is even more profound when substituting one family of RFID equipment with another. The Data Layout Abstraction layer shields the developer of those details. Regardless of the technology used, she/he may count on consistent data representation. The driver will convert all data blocks in consistent sequential format. We have expanded on this concept and defined some more specific tag layouts for your convenience. For example, our DataBrokersRetailTag offers data fields for SKU, Expiration Date, Lot Number, Status, Description, etc. There are other data formats available for immediate use. The software team may develop their own layouts preserving and expanding the benefits. Initialized by one device a tag could be read properly by another. Most of our data layouts provide the added security of additional hardware-independent check sum verification. Larger applications require transactional data persistence. The usual approach is to store the information in a relational database. PIRF recognizes that by providing transparent mechanism for persisting tag, inventory, timestamp, and location information (including associations) to any RDBMS. We utilize JDBC. Our Database Layer is based on open standards and is compatible with most of the popular relational databases. To guarantee scalability, we provide SOAP interfaces. Those include generic SOAP driver, which allows you to control devices at remote locations. The SOAP protocol is firewall friendly because it is based on HTTP. In the full version of the product, we also provide a production server with HTTP(S) interface for remote administration. The server can work unattended and automatically update the database with inventory events and notifications. PIRF is a very flexible framework. There are many ways to use it. You could develop a simple desktop application with precise hardware control, or you could develop large-scale web-based application controlling a number of readers over the network. Please, see the description of sample application(s). We believe, those will give you a good initial understanding of the ways you could use PIRF. We think the best illustrations of the different approaches are sample application(s) we include. Please, refer to the detailed explanations for each of them (see below). Distribution Description PIRF Lite comes as an optional installation bundle included with some of DataBrokers, Inc. software products. Once installed, the examples can be executed directly, or modified and compiled by the developer. PIRF Lite ver.2.0 comes by default with RFID drivers for Texas Instruments, FEIG Electronics. Those are variations of some of the most popular drivers for control of multiplexer devices, smart shelves, RFID conveyor systems, POS, and RFID scanning tunnels. Installation To install PIRF Lite, simply select to include this installation package when installing the main software product and follow the instructions. Once, complete PIRF Lite directories will appear under the main installation directory. Those include the following: docs - contains the documentation files. Here you can find detailed description of the API in the form of Javadocs example - contains the source code for the sample application(s) bin - contains start script(s) to execute the sample application(s) Please, note that PIRF Lite requires you to install the main product distribution since it shares the software modules with it. Changes in the configuration files may affect the behavior of the main product, so it is advisable to secure back up copies before making changes in any of the files. Running the Sample Application(s) To execute the sample application(s) included with PIRF Lite, open a shell window (command line window) and navigate to the ‘pirf-lite/bin’ directory. Execute the start script that could be found in the ‘bin’ directory. For example, under MS Windows you may have the following: C:\>C: C:\>cd \Program Files\TagTracker\pirf-lite\bin C:\Program Files\TagTracker\pirf-lite\bin> startSimple This will launch the sample application. You can find the source code in the ‘examples’ directory and view it with your favorite text editor. The comments describe the logic. Together with the Javadocs, this should help you to develop your first application. Feel free to modify the startup script if you need to. Example Source Code Description(s) As we mentioned above, you can find the sample applications in the examples directory (under your installation directory). Below are detailed descriptions for each of the samples. Simple.java Simple.java is (as the name suggests) a very simple console-based application. This is our version of “Hello World” in the case of PIRF. It tries to automatically detect the RFID reader attached to your computer, loads the proper driver for it and executes tag initialization and read operation. To understand the logic better, open the source file Simple.java and take a look. It begins in the main method, where we get the command line arguments. We expect a single argument, which is the path to the configuration file. By default, the configuration file can be found in the config directory of the main product and is named rfid.xml. Feel free to name it any way you like; just do not forget to update your start script. Next, the main method calls run, which contains most of the logic. It begins by invoking the following method: driver = DriverFactory.getInstance(configFile).createDriver(); As you can see in the API documentation, DriverFactory is a utility class that helps with the initialization of drivers. It will parse the configuration file and try to load and initialize the drivers listed there one by one in the order they appear. The configuration file contains all driver specific parameters, which may differ depending on the hardware interface in use. For example, drivers operating with RS232C interfaces will contain parameters for the baud rate, COM port number, etc. TCP/IP parameters could be the host name, port number. For each driver, DriverFactory will attempt to load it, initialize it and test its operation in the order the driver descriptions are listed in the configuration. This is possible because, each driver implements method testDevice(), which allows it to determine if it can communicate with the attached device or not. In brief, this is the mechanism to detect if a driver is appropriate for your hardware. If the driver replies with success to the test call, it will be selected for use and the initialization completes. In other words, DriverFactory will either return a reference to fully initialized driver, or null. If it succeeds, you can use this driver to communicate with the reader. If you use the version of the method that does not take parameters, then DriverFactory will search the Java CLASSPATH for file named rfid.xml. Here is a simpler example: driver = DriverFactory.getInstance().createDriver(); PIRF provides more than just drivers. It also defines in an abstract way the logical structure of RFID transponders (tags). Different manufacturers use different layouts to store data blocks on the chip. PIRF shields you from these details. In the current example we decided to use our DataBrokersAsciiTag. This particular class contains simple ASCII text as a data field. On the next line, we create one ASCII tag to be initialized: DataBrokersAsciiTag tag = new DataBrokersAsciiTag(new BasicTransponderId(), "Hello There!"); Further on, we proceed to write the contents of this tag to all transponders that could be found in range of the reader: Warning! The following operation will re-initialize any custom data carried by ALL transponders in range of the reader. Please, remove tags that you do not want to be initialized. driver.initializeAllTransponders(tag); As you can see, all calls to the reader are done through the driver. If you have multiple tags in range, but wish to write to just one in particular (addressed write), then use initializeTransponderData instead. The transponder that will be initialized will be the one with UID (Unique Identifier) matching the one you set when initializing the transponder object. In contrast initializeAllTransponders will ignore the UID sending in effect a broadcast (unaddressed write). Some readers/tags do not allow you to write data. It is important to note that not all RFID devices are equal. Some support read/write operations, others do not. If your device does not allow certain function, then the driver will throw an RFID exception to that effect. In addition, some devices (most notably of the low-frequency family) do not support anti-collision. Anti-collision is the mechanism by which multiple tags could be detected. If not supported, the device can ‘talk’ to only one tag at any given time. This could manifest itself in multiple ways, but in general do not expect more then one tag to be accessible by the API. To read back the tags, we use: Vector tags = driver.getAllTransponders(); This method will return a vector of transponder objects, or an empty vector if none are found. These will include all data blocks as well. Much faster operation would be to simply get just the list of the UIDs of the tags present: Vector ids = driver.identifyTransponders(); The difference is that the vector returned this time will contain TransponderId objects, not Transponders. In some cases, this operation may require less RF power, providing better performance. Keep in mind that each driver utilizes some system resources. For example, it can reserve a serial port, so a second instance of the driver will not be able to work simultaneously. It is a good practice to make sure that the driver object is properly disposed when no longer needed: driver.close(); The API has other interesting features. You could implement listeners and get notifications for different events. Please, browse through the API documentation and try different approaches to find the one that works best for you. The framework is very flexible, extensible and could be used in more than one way. When writing your applications, you will need to make some decisions based on your preferences. For example, you could loop through and execute identifyTransponders at each cycle. This will provide a way to continuously scan for tags, or you could use combination of startScanning method and your own listener object(s). It all depends on the level of control you would like to achieve in your code. The first option will allow you to implement sophisticated caching mechanism and execute code within the cycle, while the second will make it easier to write thread-safe applications and help you focus on the business logic. Compiling the Sample Application(s) We provide a simple script that will help you compile Simple.java. However, you will have to install on your own Sun Microsystem’s JDK first and make sure that javac is in your path. You can download it from their web site (http://java.sun.com). Feel free to modify the script file, as you see fit. Under MS-Windows, navigate to the ‘bin’ directory, as shown in the previous example. There you can find compileSimpleDemo.bat. Executing it should produce Simple. class in the ‘example’ directory. Of course, you can use your favorite Java IDE to do this as well. Licensing DataBrokers, Inc. grants you the license to use PIRF Lite under the conditions listed in the Software License Agreement for the main software product with which PIRF Lite is distributed. You will be asked to agree to those conditions during installation. The License Agreement can also be found in the root directory on the installation CD-ROM disk. You are not authorized to distribute PIRF Lite separately. You need to purchase additional distribution licenses from DataBrokers, Inc. if you decide to distribute PIRF Lite as part of your own software products. Please, contact sales@databrokers.net for more information. Troubleshooting and Support PIRF Lite comes with limited support. We can assist you via e-mail or telephone with questions related to installation of the product for a period of 40 days after purchase. We can provide you with explanations of the sample source code (walk-through) as included, but cannot provide support regarding developing your own custom applications or issues resulting from post-installation modifications in the configuration and installation directories. If you have purchased PIRF Lite, you are entitled to patches, which you could download free of charge from http://www.databrokers.net The full distribution of PIRF comes with extended support package. For all inquiries regarding our products, please e-mail us at support@databrokers.net or visit our web site at http://www.databrokers.net Thank you for using the products of DataBrokers, Inc. The Development Team.