You are on page 1of 25

Rifidi Edge Server Developer’s Guide

Version 1.0 (Rifidi Edge Server version 1.2) September 2010

2

Table of Contents
Overview ....................................................................................................................................................... 4 Getting Started with the SDK ........................................................................................................................ 4 Overview of SDK........................................................................................................................................ 4 Documentation ......................................................................................................................................... 4 Setting up a Development Environment .................................................................................................. 4 Importing a Project Template ................................................................................................................... 4 Running the project .................................................................................................................................. 5 Setting up Configuration Files ................................................................................................................... 5 Viewing and Modifying the Rifidi Source Code......................................................................................... 5 Rifid Edge Server Architecture ...................................................................................................................... 6 Sensor Abstraction Layer .......................................................................................................................... 6 Application Engine Layer........................................................................................................................... 6 Communication Layer ............................................................................................................................... 7 Sensor Layer .................................................................................................................................................. 7 Creating a New Sensor Adapter ................................................................................................................ 8 Anatomy of a Sensor Plugin ...................................................................................................................... 8 Sensor Sessions ......................................................................................................................................... 9 AbstractSensorSession ........................................................................................................................ 10 AbstractIPSensorSession ..................................................................................................................... 10 AbstractServerSocketSensorSession ................................................................................................... 10 AbstractSerialSensorSession ............................................................................................................... 11 Sensors .................................................................................................................................................... 11 Sensor Factories ...................................................................................................................................... 11 Persistence .............................................................................................................................................. 11 General Purpose I/O ............................................................................................................................... 11 Tag Writing .............................................................................................................................................. 12 Application Layer ........................................................................................................................................ 12 Rifidi Application API ............................................................................................................................... 12 Lifecycle Management ........................................................................................................................ 14 Configuration Management................................................................................................................ 14 Esper Management ............................................................................................................................. 16

................................................................................................................. 25 ................................. 23 Northwind Business Rules........................................................................... 20 Integration Layer ......... 21 JMS ................................................................................................................................................................. 19 Diagnostic Applications ................................................................... 23 Setting up and running the Northwind Example ........................ 21 Databases .....................................3 Plugging into the OSGi console .................................................................... 18 Stable Set Service ................................................................................................................................. 18 Unique Tag Batch Interval Service ................................................................................................................................................................................................................................................................................................................................................................... 17 Rifidi Services ....................... 20 Tags ................................. 18 Unique Tag Interval Service ............................................................................................................................................................................................................................................ 19 Serial................................................................................................................... 19 Sensor Status Monitoring Service ......................................................................................................................................................................... 22 Exporting and Deploying ................................................................................... 17 Read Zone Monitoring Service ....................................................................................................................................................... 22 Webservice ..... 19 GPIO ........................................................................................................................................................................................................................................................................................................................................................................................... 22 RMI .. 24 Northwind Application Architecture..................................................................... 22 Example: Northwind ............................................................................................................................................................................................................................................ 20 Tag Generator .......................................................................................................................................................................................................................

org/javadoc/edge1.rifidi. It can be found at http://wiki. To do this. Please follow the instructions on this wiki page to import the SDK into your eclipse workspace: http://wiki. how to set up a development environment.4 Overview The Rifidi Edge Server is an application platform that provides developers with a way to quickly develop and deploy RFID applications. and how to create your first Rifidi application project.rifidi. . you will want to create a Rifidi application project.0 The wiki has some helpful pages to answer some common questions that users and developers have.rifidi. It can be found online at http://forums.php/Edge_Server_Development_Environment Importing a Project Template Now that you’ve set up your development environment. This document describes the features and tools available to application developers in the Rifidi Edge Server Standard Development Kit (SDK). Instead of following step by step instructions on how to set up an application. it is recommended that you import a project template from the examples directory in the SDK. It describes the structure of the SDK.org Setting up a Development Environment In order to develop a Rifidi application. Getting Started with the SDK This chapter will help you get started using the Rifidi Edge Server SDK.org/index.rifidi. docs – Contains all the documentation launch file – The default run configuration to run the edge server from within eclipse target file – The file that tells eclipse where to find the necessary dependencies to run the edge server Documentation There are several places to look for specific documentation needs      The User Documentation is a PDF that explains how to run and control the Rifidi Edge Server The Developer Documentation (this document) explains how to develop reader adapters and plugins for our Edge Server The Javadoc for the Rifidi API can be found online at http://www. Overview of SDK The SDK contains the following files and folders:      examples – Contains example Rifidi applications including a template to help you get started lib – Contains all the code necessary to run the Rifidi Edge Server.2. you will need to use Eclipse.org The forums provide a way for users and developers to ask questions.

4.app. you can simply right click on the class in the source code and select “Open Declaration”. You can set the path to these configuration folders using the ‘org. There are two main ways to view the source code. Now right-click on the plugin that you want to view and select import as->Source Project.properties – a file that controls the logging output of the edge server applications folder – contains properties for each application that starts up. 7. Click Apply and Run At this point you should see log output in your console to indicate that the Edge Server has been launched. Viewing and Modifying the Rifidi Source Code Because the Rifidi source code is included in the SDK as source plugins. open the plugins view in eclipse (Window->Show View>Other->Plugins). put the system properties in the run configuration. For more information see the section in this document on properties for applications When running the edge server from within eclipse. Now you can run the edge server from within eclipse.5 1.rifidi. 6. it prints a line that says “All Rifidi configuration paths relative to <path>”. 3.     sensorconfig/rifidi.rifidi. Notice that when the edge server starts up. 1.ini file for system properties. Select the ‘org. you do not need to download the source code separately to view or modify it.rifidi. 5.home’ system property.template’ project in the run configuration 3.xml – a file to save reader adapter configurations logging. This will allow you to not only view the source for the entire plugin. Open the run configuration (Run->Run Configurations) 2. but also allow you to make . you do not use a edgeserver. File->Import Choose General->Existing Projects into Workspace Click the Browse button next to “Select root directory” Browse to the SDK directory in the workspace folder Select ‘org. At some point you should also see the debug output that you added to the template. it is configured to point to the Rifidi-SDK/RifidiHome directory. Instead. Setting up Configuration Files The Rifidi Edge Server can make use of several configuration files when it starts up if they are available on the system.app. modify it by putting a print line in the start method so that you will see that the project is running and started. By default. This will let you view the source code for the class.template’ Select ‘Copy projects into workspace’ Click Finish Running the project Once you’ve imported the template. This is where the Rifidi edge server is looking for the properties listed above. If you want to see an entire source code plugin. 2. If your application is using a class or interface from the SDK.

Many sensors can send 1. To run the edge server with your new changes. RFID readers.000 of events a second. Application Engine Layer For most applications it is not desirable to save every event that the sensors produce. etc) from many kinds of devices. passive. and collecting EPC information. this consists of connecting to a Gen2 fixed reader (such as Alien 9800. The Sensor Abstraction Layer provides a common API to integrate with sensors to collect various kinds of data from them. open up the run configuration. The Edge Server is broken up into three conceptual layers. In many scenarios. Barcode readers. select the plugin from the workspace and deselect it from the target platform. the edge server is designed in a way so that so that it can collect many kinds of data (active. This layer allows users to connect to devices in a sensor-agnostic way to collect the kind of data required for the application. a large number of which might be duplicates.g. The Communication layer (sometimes referred to as the integration layer) provides a means to integrate the business events collected in the Application layer with other systems (such as databases or ERP systems). Rifid Edge Server Architecture This chapter explains the architecture of the Rifidi Edge Server at a high level. Mobile Devices) and collect information from them. The Application Engine Layer performs custom business processing rules on the data. However.6 changes to the source. Sensor Abstraction Layer The purpose of the edge server is to connect to any kind of sensors (e. Motorolla LLRP. Most applications are . etc).

The applications in this layer can perform custom business logic based on the tags that are seen. For the vast majority of the cases. For the most part. Complex Event Processing (CEP) is a paradigm of viewing data as ephemeral events (i. once a sensor had been configured. The edge server has several built in connectors to use. it will not change much. business) events from the stream using rules. Rifidi Edge Server uses a Complex Event Processor called Esper. The level of configuration depends on the capabilities of the sensor and how much works has been put into the adapter. such as barcodes and GPIO events. others might want it to be pushed into an ERP system like SAP or handed to a Rich User Interface of some sort. Another application might correlate barcode reads with RFID tags and write the association to a database. some users might want the data to be stored in a database. however. This section describes the main components of a sensor adapter for the Rifidi Edge Server.e. a stream consisting of non-persisted events) and identifying meaningful (i. it is possible to write your own connector (such as a TCP/IP socket connection) if the application needs it. Communication Layer After data has been processed. It allows you to write queries using an SQL-like syntax. In addition. from network-enabled Gen2 RFID readers to barcode scanners to JMS queues of events. since the easiest way to learn this is by looking at the source code for adapters that ship with the Edge Server. For example. an ERP system is probably interested in the event of a box arriving in area 1. it probably needs to be handed up to some kind of applicationdependent system. namely JMS and Web Services (via Spring's remoting framework). one application might alert a warehouse manager via an email if a tag that matches a certain pattern is seen in a particular area. it is easiest in most cases to configure the sensor using a tool provided by the sensor’s manufacturer.e. as this is application dependant. The sensor is either then configured to send events back to the edge server or the edge server will poll the sensor for events. sensor configuration is normally handled by a technician when first setting up the sensor. aggregate and process events produced by the Sensor. An example query to get tags from a particular reader might look something like this: select * from ReadCycle where ReaderID='gate_1' The application layer lets developers write custom business logic that uses Esper to filter. It does not give a step-by-step walkthrough on how to build an adapter. The kinds of sensors can be wide ranging. but other event types can be collected as well. the events can be of various types. the sensor layer allows some level of sensor configuration. Sensor Layer The sensor layer allows the edge server to connect to various kinds of sensors and collect data from them. The most common events are Gen2 RFID. In addition to collecting events. Thus. For example.7 interested in events that are one-level higher than the raw events produced by sensors. In addition the sensor API’s . and it is not desirable for the ERP system to do the work of filtering and processing all of duplicate reads the sensor produces. However. For examples.

you may need to develop some classes to represent that data.8 source code is well documented. For example. Repeated commands are intended to be scheduled for repeated execution. you will need to write this code yourself Will you need to poll the sensor for data. there is one SensorFactory for an Alien plugin. Creating a New Sensor Adapter The Rifidi Edge Server ships with adapters for several popular RFID readers out of the box. For example. Commands interact with a sensor. Single-Shot (or one-time) commands are intended to be executed only once. so it is recommended to look into that. There are three classes every command will need . Once a SensorSession is created. There is typically one SensorSession per Sensor object. There is typically one Sensor object for every physical sensor. Does the manufacturer provide a java API? Some sensor manufactures provide a java library that will parse and encode messages. The SensorFactory. If you have two Alien readers in your infrastructure. A SensorFactory class that creates Sensors. For example. it cannot be changed. if you have two Alien readers. all but the most basic of sensors will have Commands. A sensor exposes connection properties (such as an IP and Port) to use when it creates a new session. A sensor also has an ID to identify it from the OSGi command line. the sensor API has classes that you can extend. If you need to create a new sensor adapter. This chapter serves as a guide on how the various pieces of the sensor API work together. Many sensors fall into this category. you might have two Reader IDs called Alien_1 and Alien_2. A Sensor class that creates and maintains SensorSessions. Anatomy of a Sensor Plugin All sensors consist of three main classes:  A SensorSession class that creates a connection to the sensor and collects data from it. There is one SensorFactory per Sensor type. you will create two Sensors. A SensorFactory has an ID to identify it from the OSGi command line. If they do not. a poll command might ask a sensor for the tags that it can currently see. or will the sensor be configured to automatically send back data? Will you need GPIO support? Will you need tag writing support? What kind of data will the sensor send back? The Edge Server has support for Gen2 tags and some barcodes. you will use the AlienSensorFactory to create both AlienSensors. but if you are working with a special kind of data. there are a couple of things to consider:       What is the communication channel that the sensor uses? If it is TCP/IP or serial. if you have two Alien readers.   In addition. There are two types of commands. For example.

Connection Logic – The sensor session contains the logic for connecting to and maintaining a connection with a sensor.9  Command – The command class is a runnable which is executed by a session. The end goal of a sensor session is to parse events that comes back from a sensor and put them into the Esper event engine. 3. most of the work will typically go in to protocol parsing. Protocol Parsing – It is the responsibility of the sensor session to parse incoming messages according to the protocol that the sensor uses. The Sensor API in the Rifidi Edge Server provides several base classes that implementations can extend which handle common cases. Like the Sensor. it can expose properties which it uses when creating the Command. For example. When developing a sensor adapter. Once a command is created. 2. because TCP/IP is a typical protocol used for connecting to readers. That is. some sensors require a command to tell sensor to start sending back tag reads. This service allows application-level access to querying GPI state and setting GPO state. Most barcode readers will send back the barcode that they read. For example. For example. Sensor Sessions The Sensor Session is the most important part of a sensor adapter. CommandConfigurationFactory – A factory that produces CommandConfigurations. The Alien reader sends back clear-text strings.   Finally. Command Execution – The sensor sessions have to ensure that commands issued to sensors are carried out in a thread-safe way. the API supplies an abstract class that handles TCP/IP connections robustly (it can detect if the socket is closed and attempts to reconnect). CommandConfigurations have IDs used for controlling them from the OSGi command line. There is one factory per CommandConfiguration type. From there. it cannot be changed. It is the job of the sensor session to ensure that only one command is issued at a time and to allow commands to be scheduled for repeated execution if necessary. It is intended that the command should execute quickly. the Application Event Layer can process the events. the Rifidi API provides a . Some kinds of command messages are often necessary to control the sensor. it is necessary to poll the sensor to ask if it has seen any new data. sensors that need to allow applications to access their GPIO capabilities can implement the GPIOService. For others. the LLRP sensor sends back byte messages that are encoded according the LLRP specification. since this is what varies widely from sensor to sensor. Well written sensors sessions should normally detect when a sensor has been disconnected and attempt to reconnect if possible. It has three main roles: 1. several other classes are provided that handle various kinds of connections. Since many applications built on top of the Rifidi Edge Server use Gen2 RFID readers. In addition. it should avoid sleeping or long running loops. CommandConfiguration – The CommandConfiguration creates Commands.

You should only have to subclass AbstractSensorSession directly if you need your sensor communicates via some other kind of protocol.php/ReadCycle_Class_Hierarchy One last note on sensor session development: It is common for network-enabled readers to have one channel that is intended for interactive communication in a request-response mode. please see http://wiki. . For more information on this. If this API contains connection logic. Many sensor adapters will be able to make use of a subclass of AbstractSensorSession that already handles connection logic. You can then configure the reader to send back tag data and GPIO data to different ports. subclass either the AbstractPollIPSensorSession or the AbstractPubSubIPSensorSession class. This master-slave pattern is common and typically works out well. and one or more passive channels which the reader uses to send events on. the Alien reader has an interactive channel on port 23. In addition. However.rifidi. AbstractServerSocketSensorSession Use this class for passive TCP/IP sessions. It will open up a socket and passively listen for a sensor to send data to it. AbstractSensorSession The AbstractSensorSession contains logic for executing commands. use the PubSub session. It cannot reply back to the sensor. The difference between these two classes is the way in which messages from the sensor are delivered.org/index. This logic should work for every SensorSession. A handheld reader that is connected to a wifi network could just send data to the port for example. then use the Poll session. It does not contain any logic for connecting to readers. Instead. It uses A ScheduledThreadPoolExecutor to schedule commands. and one for passively receiving GPIO data). It is often uses for “slave” sessions such as the GPIO session for an Alien reader. you should most likely not subclass this class directly. AbstractIPSensorSession This class handles the connection logic for a sensor which communicates via TCP/IP. You can connect to this port and send commands and receive responses. If messages are delivered asynchronously (that is for each command you send to the reader. If messages from the reader are delivered synchronously (that is that you expect a response for every command that you send). For example. readers that connect via TCP/IP or Serial can most likely inhert from a subclass. It can also be used to integrate hand held readers into the edge server.10 common structure for Gen2 tag data. you can inherit from AbstractSensorSession directly and rely on the manufacturer’s API to do connection logic. For example. It is used for interactive sessions (it can both send and receive messages). some sensor manufactures will provide a java jar which contains and API for connecting to their reader. the reader might send back multiple responses or none at all). The following sections describe abstract classes that can be used when developing a Sensor Session class. The Alien reader adapter in the edge server has one master sensor session (the interactive session ) and has two “slave” sessions (one for passively receiving tag data.

A user can then change the port with the ‘setproperties’ OSGi console command. For example. and the session will resume their saved state. the property must be changed on the sensor. This allows the readers to interact with other devices. there is one AlienSensorFactory and one LLRPSensorFactory available when the edge server starts up. Once the session is created. These factories can create multiple instances of Sensors. Each sensor factory has an ID that is used when creating new Sensors. Sensors contain connection properties (such as hostname. the session must be destroyed.11 AbstractSerialSensorSession This sensor session uses the RXTX library to connect to a serial port. When the edge server restarts these sensors and session will be recreated. If something needs to change on the session (such as the port that the session is connected to). Using a photo eye as input is an example of GPI. There is normally one Sensor instance per physical sensor device. a reader might want to send some output to another device based on some logic. a reader might be configured to start reading when a photo eye detects a forklift in the near vicinity. For example. There is one instance of the SensorFactory per sensor adapter type. Sensor Factories A Sensor Factory creates instances of Sensors. and the session must be created again. a sensor might have a method with this signature Public void setPort(Integer port) This sensor exposes the port property to the OSGi command line. Other times. etc). Subclasses should extend AbstractSensorFactory. Typically. a reader . General Purpose I/O Many popular RFID readers offer General Purpose I/O capabilities. Subclasses should extend AbstractSensor. If you type in ‘readers’ you will get a list of the sensors that have been created. it should not be changed. a sensor will have only one session. Persistence Sensors and Sessions are persisted to an XML file when the ‘save’ OSGi command is issued. These properties are exposed to the OSGi command line via getter and setter methods. port. Each sensor has an ID that is used to identify it on the OSGi command line. For example. Sensors The purpose of the Sensor class is to create and maintain an immutable instance of a sensor session. For example. With a serial connection it is not possible to detect if a connection has been broken or not.

please see the AlienGPIOService or AwidGPIOService classes. Often. like turning on a GPO light. In the previously mentioned green light/red light example. This means the application must tell the sensor to turn on a green light or a red light. needs to happen in application logic. This is an example of GPO. Tag Writing Tag writing is not currently supported by any reader. GPIO data needs to be used in the application layer. These services allow you to create applications without have to write Esper statements. The sensor can then put this service into the OSGi registry. these classes are used to add custom Esper statements to look for events. The sensor adapter and physical reader are just reporting back tags. and integrate with existing infrastructure such as databases and JMS queues. It then details the Rifid Services. This section starts out by taking an in-depth look at the Rifidi Application API and how to use it. suppose different business logic should be executed depending on which photo eye saw a forklift. Thus an interface could be developed (similar to the AbstractGPIOService) which would allow an application to control the reader to write tags. GPO differs from GPI in that it necessitates that the application actively controls the reader rather than passively listen for events from the reader. the reader should be configured to send back GPI events. Tag writing. In this case. To meet this need a sensor adapter can implement the AbstractGPIOService. Application Layer The purpose of the Sensor Layer is to collect data from sensors and put them into Esper. subscribe to Rifidi services. and the application can look it up and use it as it needs to. The application layer is intended to be general enough to support a wide variety of applications. but provide some tools that are common to many applications. For more information about how to implement this. only the application knows if a box belongs in a certain area or not (presumably from a database look up). Finally it describes some of the application that ship with the Edge Server which are useful for testing and debugging applications and sensor plugins. and the sensor session can put the GPI events into the Esper engine. Then.12 might want to light up a green light if a box belongs in a certain area and a red light if the box does not belong there. For example. Rifidi Application API Rifid Applications are at the heart of the Application Layer. the application can execute the proper logic based on the events that it saw in Esper. The purpose of the application layer is to perform business logic on the data that the sensors collect. which capture common patterns seen across many RFID applications. . which has a few abstract methods in it that allows control over the GPIO capabilities of the reader.

core. <!-. “app”). all applications should extend AbstractRifidiApp. deployment. etc) and registers the application in the OSGi service registry. This class provides a base set of services to Rifidi Applications. The first is the Application class itself. and management of Rifidi Applications.mycompany.13 In order to provide consistent development.rifidi. In addition.RifidiApp”/> The best way to get started with your own application is to import the Template application from the SDK and begin modifying it. } @Override public void _start(){ //insert code here to create esper statements or subscribe // to rifidi services } @Override public void _stop(){ //insert any clean up code here } } The second part is the Spring XML which creates the application.app. This xml file goes in the “META-INF/spring” folder in the bundle. Exploring those examples are the best way to get a feel for how to code using the API. including:     Life cycle management (starting and stopping the application) Configuration management (Using property files to provide input parameters to the application) Esper management (Ensuring that Esper is used correctly) Plugging into the OSGi console (Allowing your application to be controlled by the OSGi command line) There are two pieces to every application. Public class MyApp extends AbstractRifidiApp{ Public MyApp(){ super(“group”.edge. . there are several well-documented example applications in the SDK which demonstrate many of the features of the Application API. The required XML namespaces have been removed from the following example for the sake of brevity.api.register the app in the OSGi service registry --> <osgi:service ref=”app1” interface=”org.Create the application object --> <bean id=”app1” class=”com. injects the application with any dependencies it requires (such as rifidi services or database connections.MyApp”/> <!-.

add custom Esper event types. you can stop a started application using the stopapp command. When a bundle that contains one or more applications starts up. It is used to add Esper statements and listeners.14 You can start. Each line contains     The application ID (a numeric ID) The application group The application name The state of the application (started or stopped) You can start a stopped application using the startapp command. Likewise. Configuration Management One common need of many applications is to be able to externalize configuration properties to files so that they can be changed easily. The AppManager automatically keeps track of any object in the OSGi registry that is exported under the RifidiApp interface. There are three main types of configuration files that the Application API makes available to Rifidi Apps . Groups are logical sets of applications. such as unsubscribing from Rifidi Services. The main reason for using a group is that applications within a group can share configuration files. The rest of this section goes into more depth about the services offered by the AbstractRifidiApp abstract class. The _stop() method is used to do any cleanup work necessary. At this point it is important to note that each Rifidi App must provide in its constructor a ‘group name’ and an ‘app name’. The AbstractRifidiApp class provides two methods for developers to override. The _start()method is where most of the application code belongs. and monitor applications using the RifidiAppManager. Open up the OSGi console and type >apps You will see a list of applications printed out. Lifecycle Management Applications can be in one of two states: started or stopped. it should register its application(s) with the AppManager. For example. subscribe to Rifidi Services. It assigns this application and ID and automatically starts it if lazyStart() returns false. The might have another group of applications called ‘exporting’ which handle out-bound packages. or do any other work that needs to be done when starting the application. the Acme Corporation might have one group of applications called ‘receiving’ which handle in-bound packages. stop. The AppManager allows users to start and stop the applications. It does this by exporting the application into the OSGi registry under the RifidiApp interface in the spring XML. The Rifidi Application API gives you an easy way to do this using a standard directory structure and file-naming convention.

They share properties that are in the Receiving. If this property is set to true.properties  App2.properties  App3. For example. you will notice some property files. In addition.properties  App1. If the LazyStart variable is not defined in a property file. there can be one property file per application.  RifidiHome o applications  Receiving  Receiving. If it is set to false. the application will not be started automatically. Properties in this file will be shared with all applications in the group.properties In this example.  Properties If you open up the ‘applications’ directory in the ‘RifidiHome’ directory of the SDK. then it will be started automatically. App1 and App2 are both in the Receiving group. These files can contain any data the application needs. The directories at this level are so-called group directories. and App3). the Acme Corporation might use the following directory structure for their receiving and exporting applications. Applications can should access properties by calling the getProperty() method . you will notice several sub directories. it defaults to false. Data files are stored in the data directory. If you open up a group directory. They are read in when the application starts and are made available in the initialize() method. Each one describes a different logical readzone. App2. Each of these property files will share their name with the ‘app name’ of their corresponding application.15   Property Files follow the conventional name=value format. If a property is both in the group property file and the application property file. These are useful with Rifidi Services to determine which logical read zones a particular application is interested in. the Acme Corporation has two groups (Receiving and Exporting) and three applications (App1. Each group directory can contain one property file whose name is the ‘group name’ string that the applications use in their constructor. . Folders are in bold and property files are in italics. The names of these directories correspond to the group names that applications provide in their constructor. the value in the application property file will be used. This method should be called in the initialize()method of the Rifidi App. All Rifid applications use a property called LazyStart to determine if the application should be started as soon as it is loaded. App3 is in the Exporting group.properties  Exporting  Exporting. Applications can both read and write these files.properties file. Read zone files are stored in the readzones directory in a group directory.

tagPattern – an optional regular expression defining a pattern which can be used to filter tags based on their IDs matchPattern – an optional boolean used with the tagPattern. which returns a HashMap where the keys are the readzone IDs and the values are ReadZone objects. It allows users to insert events in the form of java objects into the engine and look for patterns in this data using queries. It is a powerful tool for building RFID applications because it allows Sensors to push events into the engine and applications to state the . it is useful for applications to read and write files. When this method is called all data files with the given prefix are read in. filter out tags that match the pattern The names of the readzone files follow a naming convention: readzone-[ID]. Esper Management Esper is a complex event processing engine. Readzones are read in when the application starts.[suffix] They can be accessed using the getDataFiles() method .’ characters is the ID of the readzone. This ID corresponds to the Sensor ID used in the Sensor layer antennas – an optional comma-delimitated list of integers which correspond to the antennas which should be used. The App API provides a mechanism to make it easy for applications to do this. The readzone files contain the following properties:     readerID – the internal ID used to identify this reader. Data Files Many times. Data files reside in the ‘data’ directory. This method takes in a String which is the prefix. turned into byte arrays and made available as a hashmap. They can be accessed using the getReadZones() method in the AbstractRifidiApp class. The word in between the ‘-‘ and the ‘. If set to true accept only the tags that match the pattern. a particular application might only be interested in tags from antennas 1 and 2 of a certain reader. For example. These files will be read in and ReadZone objects will be automatically created. They start with the word ‘readzone’. This method will write a new file when it is called. and they share a naming convention that is similar to the readzones: [prefix]-[id]. To this end.properties. For convenience. Files can also be written to the data directory using the writeData() method. In addition. If set to false. A particular file is located from within that hashmap using its ID. you can use the buildInsertStatement() in the EsperUtil class to build an esper statement that will insert tags into a given window that match some supplied readzones. most of the Rifidi Services use ReadZone objects to define their data windows.16 Read Zones One common requirement for RFID applications is to define logical read zones for applications. you can create readzone property files in the readzones directory of a group.

they can define listeners to certain statements. In addition. TagReadEvent. such as ReadCycle. there is no need to remove the statements when your application stops. For these scenarios. Custom Event Types The Esper runtime must know ahead of time what kind of events will be put into it. Please see the Esper documentation about how to access properties from these events in statements. It is often useful for administration and testing purposes. it can do so using any of the addEventType() methods. Each application can contribute to the console by overriding the getCommandProvider() method. and GPOEvent. Then applications are notified when an event happens that match the pattern. Using these methods will ensure that the Event Types are properly removed from the runtime when your application stops. Contributing an object that implements the CommandProvider interface will allow the application to expose its own commands on the OSGi command line. the Abstract Rifidi App provides two methods that should be used when adding statements and listeners. The Rifidi Edge Server has several kinds of events already defined in the Esper runtime that every application can make use of. By using these methods to add statements. The updateListener will allow you to handle any events which trigger the statement. Because it is important to keep up with which statements have been added and to make sure statements are removed when the application starts up. Please consult the Esper documentation online for information about esper syntax and semantics. Because events are filtered in memory. it allows RFID applications not to rely on databases and enables an event-driven architecture. However. Plugging into the OSGi console The OSGi console allows users to access their application via a command line. There are two types of events: Java objects and Map events. Rifidi Services Esper is a powerful tool for building RFID applications. Statements Esper’s query syntax is much like SQL. If your application needs to add its own custom event type.   addStatement(String) is used to add a single statement to the esper runtime addStatement(String. This is handled automatically for you. GPIEvent. many RFID applications have common needs.StatementAwareUpdateListener) is used to add a statement and a listener to that statement.17 patterns they are looking for. the Rifidi Edge Server offers ‘Rifidi Services’ which capture a few common . Applications can add these Esper ‘statements’ to the Esper runtime. The Application API helps developers keep up with two aspects of esper: statements and custom event types.

Read Zone Monitoring Service The Read Zone Monitoring service notifies subscribers when a tag enters a particular readzone and when it leaves a read zone.app. Inject it into your application 2.StableSetService”/> You should implement the StableSetSubscriber interface. To subscribe to this service. unsubscribe from the service. implement the appropriate subscriber interface 3. 4. which gives you two methods: tagArrived(TagReadEvent tag) tagDeparted(TagReadEvent tag) Stable Set Service The Stable Set Service notifies subscribers when a given amount of time has passed without any new tags having arrived.xml file: <osgi:reference id=”ReadZoneService” interface=”org. imagine that you want to group items to a container. In general.tagmonitor.rifidi.xml file <osgi:reference id=”StableSetService” interface=”org. put the following in your spring.rifidi. This pattern is often useful when there is a concept of children tags and a parent tag.core. In the spring xml for the application. to subscribe to a service you need to follow these steps: 1. and you want to be able to process all the tags seen as a group. You put all the tags in the field of view of an antenna.core.app.api. . To subscribe to this service. which gives you the following method: stableSetReached(Set<TagReadEvent> stableSet) Unique Tag Batch Interval Service The Unique Tag Batch Interval Service periodically notifies subscribers of unique tags that have been seen in the read zone since the last notification. It then passes all the tags seen in that interval to the listener.edge.service.service. put the following in your spring. get a hold of the service that you want to subscribe to.api.ReadZoneMonitoringService”/> You should implement the ReadZoneSubscriber interface.tagmonitor. In the _stop() method for your application. subscribe to the service passing in the subscriber and any parameters needed. In your application. In the _start() for your application.edge.18 RFID use cases and allow your application to subscribe to these patterns without the need to write custom Esper statements. For example.

19 To subscribe to this service.rifidi. To subscribe to this service. put the following in your spring.UniqueTagBatchIntervalService”/> You should implement the UniqueTagBatchIntervalSubscriber interface. which gives you the following method: tagBatchSeen(Set<TagReadEvent> tags) Unique Tag Interval Service The Unique Tag Interval Service notifies you the first time a unique tags is seen at a read zone and periodically after that if the tag is still in the read zone.app.edge.xml file <osgi:reference id=”UniqueTagBatchIntervalService” interface=”org. Instead of notifying subscribers about Tag events that happen.service.rifidi. See the help menu on the OSGi console for correct usage of these commands. put the following in your spring.api.UniqueTagIntervalService”/> You should implement the UniqueTagIntervalSubscriber interface.sensormonitor.tagmonitor.edge. .core. To subscribe to this service.app. which gives you the following method: tagSeen(TagReadEvent tags) Sensor Status Monitoring Service This service is slightly different from the others mentioned so far. it notifies subscribers about changes to the sensor layer.service. GPIO The GPIO application allows users to interact with GPIO devices (as long as the reader and Rifidi Edge Server reader adapter support GPIO).SensorStatusMonitoringService”/> You should implement the SensorStatusSubcriber interface.api.rifidi.service. which gives you the following method: handleSensorStatusEvent(SensorStatusEvent event) Diagnostic Applications The Rifidi Edge Server platform ships with several applications designed to help gather information some diagnostic information and to help developers and administrators troubleshoot common problems.edge.core.tagmonitor.api. It’s useful for giving your application access to when Sensor connect or disconnect.xml file <osgi:reference id=”UniqueTagIntervalService” interface=”org.app.core.xml file <osgi:reference id=”SensorSubscriberService” interface=”org. put the following in your spring.

For example.Returns the current GPI state on a reader setGPO – Sets a GPO state on a reader flashGPO – Changes a GPO state on a reader for a certain amount of time In addition. This is often useful when configuring a reader adapter which uses a serial protocol.    currenttags – lists the tags that the edge server can currently see recenttags . both located in the RifidiHome/applications/Diagnostic/data directory.    connectSerial – connect to a certain serial port disconnectSerial – disconnect from a certain serial port listSerial – List all serial ports available on your machine Tags The tags application allows developers and to gather some information about the tags that the edge server is gathering. This is useful for testing and troubleshooting applications which rely on GPI events from a reader to operate without having to actually have the hardware hooked up.     simGPIHigh – sends a GPI High event into Esper simGPILow – sends a GPI Low event into Esper simGPIFlashHigh – sends a GPI high event and then a GPI low event into Esper simGPIFlashLow – sends a GPI Low event and then a GPI High event into esper Serial The serial application exposes several commands that help you determine which serial ports are available on your machine.20    testGPI . use this command: > startTagRunner <tagFileID> <exposureFileID> .properties – this file controls how the tags will be exposed to Esper. it controls the rate at which tags are exposed and triggers to stop exposing them tags-<ID>.lists the number of tags per second that the edge server is current seeing Tag Generator This utility allows developers to send ‘fake’ tag events into Esper.txt – This file contains the tags to expose along with which reader and antenna In order to initiate the fake tag reads. It is useful when developing and testing applications so that you don’t have to have real hardware hooked up to your system to send tags events into the reader. there are a few commands which “simulate” GPI events by inserting fake GPI events into the esper runtime. It works using a set of two property files.lists the tags that the edge server has seen recently tagrate .   exposure-<ID>.

xml file. Indicates how many tags per second we should expose to esper groupSize: Used with ‘delay’ exposureType. Indicates number of milliseconds to pause in between exposing a group. The exposure will stop running after the defined number of tags have been exposed. JMS The Rifidi Edge Server runs an embedded ActiveMQ broker.springframework.count: A count-based stop trigger.JmsTempalte” beanname=”externalJMSTemplate”/> .21 Exposures Files There are several properties in an exposure file that control how tags are exposed  exposureType: There are two basic types of exposures: ‘rate’ and ‘delay’. The Rifidi Edge Server provides several methods of integration out of the box. and the antenna ID. Each line has three commaseparated fields: the tagID. the readerID. delay: Used with ‘delay’ exposureType.jms. The exposure will stop running after the defined number of milliseconds random: If true. they will want to integrate with existing systems.core. You can get a hold of it in spring with the following code: <osgi:reference id=”externalJMSTemplate” interface=”org. A ‘rate’ type means that the exposure will attempt to put tags into esper according to a given rate. You can change the ActiveMQ’s settings in by editing the config/rifidi-amq. Indicates how many tags should be exposed at once. A ‘delay’ means that the exposure will expose a defined number of tags with a given delay in between each cycle. Each tag is on a new line. you can use many spring technologies inside of the Rifidi Edge Server.       Tag Files Tag files simply contain the data to expose. the exposure will pick tags from the tag file at random tagRate: Used with ‘rate’ exposureType. stop. The integration layer is heavily spring based. there is already a preconfigured spring JMSTemplate that you can use to send out messages. Integration Layer Once applications have identified the business events they are interested in. and in general. In addition. stop. The following section lists a few of many possible integration technologies.time: A time-based stop trigger.

apache. add the name of the group folder to the default.core. Webservice If you have a service that you want to expose as a WebService.edge. This is an example of the directory structure for an application whose group is ‘Acme’ and whose application name is ‘Shipping’  RifidiHome .create=true In addition. 4. One way to access it is using Spring’s JDBCTemplate.rifidi.utilities.EmbeddedDriver url=jdbc:derby:DB_NAME. you will want to export it so that it can run on an instance of the edge server.22 Databases Out of the box. you can useRifidi’s JaxWsServiceExporter.jdbc. the Rifidi Edge Server ships with Derby – an embeddable database . <bean id="LRWebServiceDeployer" class="org. Please see spring’s documentation on how to use the JDBCTempalte. The following shows how to use the service in spring. In order deploy the application there are a few steps you need to follow: 1.xml file that is used when dynamically loading your bundle. Please note that the ‘service’ property refers to a bean that has the @WebService annotation.JaxWsServiceExporter" init-method="start" destroy-method="stop"> <property name="port" value="8080/> <property name="host" value="http://localhost" /> <property name="deploy" value="true" /> <property name="service" ref="beanID" /> </bean> Exporting and Deploying Once your application is built and tested. Place the jar and xml file into the application’s group folder. RMI You can use Spring’s RMIServiceExporter to expose an interface over RMI.derby. The database starts up when the edge server starts. Export the projects as OSGi bundles out of eclipse 2. Please refer to Spring’s JaxWsServiceExporter for details on how to use this.ini file in the applications directory. Please see Spring’s documentation for details. If you want the application to start immediately. The connection properties you need are driverClassName=org. Run the bindex utility on them in order to generate a repository. you can extend Rifidi’s AbstractDBDAO class which might provide a useful interface for some use cases. 3.

which are transported via forklift (also outfitted with RFID tags) to a dock door.jar  Acme. 3.php/How_to_export_your_custom_Rifidi_application Example: Northwind Congratulations! You are the proud new founder of Northwind Shipping Inc. You have decided to use the Rifidi Edge Server to run the RFID applications you will need in your distribution center.properties  Shipping. RFID can add value to this workflow by monitoring whenever a tag enters or leaves an area (either the dock door or the weigh station). something can go wrong and an item will do something unexpected.Pony Express Shipping Inc. . A message should be printed when. a tag enters or leaves an area. Northwind Business Rules The Northwind distribution center's current process looks like this: 1.. Error messages should be printed if.23 o applications  Acme  plugins o acme. an inventory is taken.. 1. After the weigh station. state-of-the-art distribution center. a tag moves from the dock door to the weigh station. You have heard all the hype about RFID and want to employ in it your new.rifidi. From the dock door. Occasionally.xml You can find more information about this topic on our wiki http://wiki.. tags are seen with their forklift tag. the packages would be sent out for shipping. One of your core business strategies is to out perform your competitor -.org/index. and do extra processing based on what happens when it enters and leaves an area. 3. The forklift will then take the packages to a weigh station. where the packages would be weighed.by capitalizing on increased efficiencies gained by your innovative use of technology."delivering packages faster than a caffeinated lightning bug"™.. -.properties  repository. 2. This tutorial will show you how to set up an application and use all the various features provided by the Rifidi Edge application API. -. 2. Boxes (fitted with RFID tags) are loaded onto a pallet.

as well as 3 events telling you that the tags have moved from the dock door . 2. You should get 3 “tag departed” messages for the dock door. plus a message telling you that a forklift was seen with the other tags.northwind plugin. Now either close and run the “Edge Server” launch framework or just press “run”. Go to Run > Run Configurations and click on “Edge Server” under “OSGi Framework” on the left. 3. you will have to manually start it. The properties files for both the dock door and weigh station ReadZones are also in this folder.24 1. Create 1 GID tag and 2 SSCC tags (this assumes that the “ForkliftPrefix” property is set to the default “35”). If you like. Press “Apply”. Select the package “org. 3. stop the edge server and open the org. Copy the “Northwind” folder and paste it into the “Rifidi-SDK/RifidiHome/applications” folder. You should see 3 “tag arrived” messages for the dock door. Type in “apps” and make sure the Northwind Application has started. and an already set up weigh station reader (127. You should see 3 “tag arrived” events for the weigh station. After the properties files are set up correctly. run the program and create the readers you want to use.properties” file. If you don't see the Northwind app at all. This shows all of the properties that can be adjusted for this application (see the application documentation for more on the properties files). Delete all the tags from the field of view. 2. 4. depending on what the names of the readers are in Rifidi Edge. Move the same 3 tags onto the weigh station reader. If you want. Check the Applications section of the documentation for more help debugging problems starting applications.rifidi. as well as the Setting up and running the Northwind Example 1.0. 4.1:30000).1:20000). 2.edge.0. Item tags are seen without an accompanying forklift tag. 3. After you have connected to the readers set in the Northwind properties file. and open the “Northwind. If you see it but it is stopped. A more thorough explanation of each of the properties is in the file itself. Tags move from the weigh station to the dock door.0. stating that the tag moved backwards. More documentation on how this was accomplished is given in the Esper documentation. move all 3 tags into the field of view of the Dock Door reader. Import the plugin from the “examples” directory in the SDK plugin. you can use any physical readers you have access to.edge. or you can use Emulator to create the readers of your choice and then use edge to connect to them. You might need to adjust the names of the readers for the dock door and weigh station.northwind” in the “bundles” tab. make sure the plugin is set to Auto-Start in the run configuration. you can begin adding and removing tags from the field of view of the readers. Here is a sample of what you can do: 1.rifidi. Tags are seen on the weigh station which was not seen at the dock door. 5. you can use the included Prototyper file with an already set up dock door reader (127.0. As a group. Then open the folder. Set up the eclipse workspace and import the SDK. After you know the application is working. 4.

org/viewforum. The event classes: These are simply shell classes that are created to be passed into Esper. but any events you make can contain any information. For more information on how these classes work. and should help you get a better understanding of how applications are built and run.php?f=35 . Invoking the rules given above on your own. Subscribers. as well as studying the Esper used to create these rules will help you greatly when you are writing your own application. The subscriber classes: These classes represent two different kinds of subscriber: one is a regular ReadZoneSubscriber. should you need more examples. Check out the file itself for a more detailed explanation of how the application works.rifidi. if you need any more help with your application. Setting up the ReadZones. Other application plugins.edge. which will subscribe to ReadZones that we create and fire events based on certain criteria. This is only one example of what you can do. Northwind Application Architecture The Northwind application contains three parts: 1. properties. only some of the rules were used for it. and Esper all happens in this class.diag) should give you more examples of what you can do with applications. such as the diagnostic tools (org. You should also get output telling you that a forklift was seen. The application class: NorthwindApp. check their respective files. 2. The other is a StableSetSubscriber that will look for forklift tags and print output depending if a forklift is present when tags are read. go to our forums: http://forums.app. They contain no information except for the ID of the tag that they represent.rifidi. The Northwind files themselves are well-commented. 3.java is where the program is set up. and all of the logic is implemented.25 to the weigh station. Finally.