This page describes how to develop a plugin using the Rifidi Edge Server Sensor API that connects to a sensor and collects information from it. For a more detailed description of the architecture of the sensor API, see this page. This HOWTO assumes that you know java, are relatively familiar with eclipse (or an equivalent IDE such as netbeans). It does not require that you know OSGi or spring dependency injection, but knowledge in these areas will help you understand why the steps are being taken and will help debugging.

Prerequisites

1. Follow the instructions on how to set up a Rifidi Edge Server development environment.
2. Use the Plug-in Project wizard in eclipse to create a new plugin-project. Make sure that the target platform is set to run with a standard OSGi framework. In the second page, uncheck the option to automatically generate an Activator. In the third page, do not use a template.
3. Open up the Manifest.MF file. Click on the dependencies tab. Add the following Plug-in dependencies:

   org.rifidi.edge.core

   org.rifidi.edge.core.services

   org.rifidi.edge.api

4. Add 'Import package' dependencies to the following pacakges:

   javax.jms

   org.apacahe.activemq.command

   org.apache.commons.logging

   org.osgi.framework

   org.springframework.core

   org.springframework.jms.core

   org.springframework.osgi.service.importer

5. Add a new folder called 'spring' into the META-INF folder
6. Add a new file called spring.xml in the spring folder
7. Add a new file called osgi.xml in the spring folder
8. Add a new package. Typically the package has the same name as your project (for example, if the project is called com.yourcompany.org.rifidi.edge.sensorplugin.yourreadertype, that is also the name of the top level package.

Short Introduction to the Sensor API

The sensor factory consists of three main components:

SensorFactory

The sensor factory creates new Sensors when the createInstance method is called. There is one instance of SensorFactory per sensor type. For example, in a running instance of the edge server, there is only one instance of an AlienSensorFactory which can create multiple instances of AlienSensor objects. The SensorFactory is normally created in the spring.xml of a sensor plugin and registered in the OSGi service registry in the osgi.xml.

Sensor

The Sensor object's main duty is to create SensoSession objects. There is normally one Sensor object for each physical sensor in the RFID system. For example, if your system has one Alien reader at a Dock Door and one at a weigh station, then there would be two instances of the AlienSensor object. Sensors also normally have getter-setter methods for setting properties of that sensor. For example, it is common for sensors to have methods to get and set the IP and port of the sensor to connect to. These properties are then used when creating new sessions. It is possible for a sensor to have more than one session (certain sensors (such as a database plugin) may support parallel sessions), but it is common for the sensor to allow only one session at a time.

SensorSession

The SensorSession has two main functions: 1) To connect to a sensor (over a network, serial, usb, etc) and to read data from it, and 2) To manage commands that have been submitted. Many sensors offer a networked TCP/IP interface. The Rifidi Sensor API offers abstract classes that other classes can extend which will take care of the TCP sockets and threads. If the manufacturer of the sensor makes a java API available to connect to the sensor, the Rifidi Sensor API allows you to use that instead.

This image shows the relationship between the three main classes needed to create a plugin for the Rifidi Sensor Abstraction Layer. Only a few important methods are shown in each class, just to give the reader an idea about what the class does

Creating the Classes

The Sensor API provides several base classes for you to extend when creating a new sensor plugin. Because the Sensor and SensorFactory classes use generics when referring to the classes that they can create, it is easiest to create the session first, then the Sensor, the the SensorFactory.

Session

As stated above, the session has two main functions: 1) to connect to a sensor and read data from it, and 2) To handle the submission and execution of commands. Every session must extend the SensorSession abstract class at some level. However, most SensorSession implementations won't extend the SensorSession abstract class directly and will instead take advantage of one of the other abstract classes that provide some basic functionality.

Avtive vs Passive Sessions

The first thing to figure out when creating the session class is whether the session is active or passive.

Active Sessions

An active session is one in which it is possible to send commands to the sensor. For example, the AlienSession is active because it is possible to send a command such as 'get taglist'. An LLRPSession is active because it can send GET_ROSPEC messages. A database session would probably be active since you would probably want to submit SQL queries to it. In fact, most sessions will probably be active ones.

Passive Sessions

Passive session simply listen for the sensors to push tag reads to them. They cannot send commands to the sensor. The only example of this kind of session at the moment is the AlienAutonomousSession. It simply opens up a port and listens for tag reads to be pushed to it by an Alien Reader operating in autonomous mode.

Please note that this active/passive terminology has nothing to do with active and passive RFID tag technology.

Communication Channel

The next thing to figure out about the sensor you are connecting to is the medium of communication. Many sensors are networked and use TCP/IP. However, the Sensor API is channel-agnostic, and it is possible to connect to sensors that use USB or serial, for example. Currently, the Sensor API only has base classes that handle the work of connecting to TCP/IP sensors. If the sensor is USB or serial, you will need to write this functionality yourself.

Tag Request Model

Active SensorSession normally operate in one of two ways when receiving tag data from a sensor

Poll

In this case the SensorSession will request that the Sensor send back its tag data immediately. An example of this is the Alien's 'get taglist' command.

Push

In this case, the SensorSession will configure the Sensor to send back tag data continuously until some stop trigger happens (e.g. sending a stop command)

Java API Availability

Sometimes the manufacturer of the sensor provides a java API that handles the connection to the sensor. If so, you can use this API. You will need to turn the supplied jar into an OSGi bundle if it is not one already. This can be accomplished by using the "new plug-in project from existing jar" wizard from eclipse.

SensorSession Hierarchy

There are several base classes you can extend in the Sensor API that provide useful SensorSession functionality.

• SensorSession - This is the class at the root of the hierarchy. It has many abstract methods for concrete classes implement.
  • AbstractSensorSession - This is an abstract class that extends SensorSession by adding functionality for submitting and killing commands. All concrete SensorSessions will probably at least want to extend this class. If your sensor has an API that manages the communication channel for you, or if your sensor does not use TCP/IP you will want to extend this class directly. For an example of a SensorSession that extends this class directly see the LLRPSession
    • AbstractIPSensorSession - This is a base class for a SensorSession that uses TCP/IP. It handles socket I/O and threads. This class will not normally be extended directly by concrete implementations. Instead, concrete implementations should extend one of the following two classes:
      • AbstractPollIPSensorSession - This class should be extended by sensor sessions that use TCP/IP communication and operate by periodically polling the sensor for tag data. See AlienSensorSession for an example
      • AbstractPubSubIPSensorSession - This class should be extended by sensor sessions that use TCP/IP communication and operate by configuring the sensors to push data back to them. See the AwidSensorSession as an example.
    • AbstractServerSocketSensorSession - This class should be used by passive sessions that use TCP/IP communication. See AlienAutonomousSensorSession for an example.

Sesnor

After creating your Session class, its time to create the sensor class. All sensor classes should extend the AbstractSensor class. There are two important pieces to the Sensor class.

Creating Session Objects

The sensor object's most important functionality is to create sessions. Most sensors will only have one session active at a time, however the API is designed to allow sensors to have multiple sessions. There are two methods for creating sensor sessions. The one that takes a SessionDTO is used to recreate persisted sessions.

Property Getters and Setters

The sensors expose getter and setters methods to allow users to configure the sensor. These getter and setter methods are also used to recreate sensors from persistence. Each getter and setter method pair has an @Property annotation over the getter method. This exposes the property to workbench via Mbeans objects.

One important thing to understand is that sessions are immutable; Once they are created, users cannot adjust properties on them. For example, suppose a sensor exposes a port property. A user can adjust this property using the getter/setter methods. Once the session is created however, changing the port property has no effect on the created session. To modify the port on the session, the user must destroy the session and create a new one.

SensorFactory

The SensorFactory is the class that creates the Sensor objects. All concrete implementations should extend the AbstractSensorFactory class. Most AbstractSensor factories will need to have two object injected by spring:

NotifierService

This service allows the sensor and sensorSession to notify clients (such as workbench) when an important event happens such as a session being created. For more information on this service see this page.

JMSTemplate

Tag events need to be placed on the internal JMS queue. The template is a helper object from spring that makes it easy to send JMS notification messages. For more information about JMS in the edge server see this page.

Short Introduction to the Command Framework

The SensorSession objects execute commands from the Command framework. The command framework enables commands to be created and configured. There are three main components to the command framwork:

CommandConfigurationFactory

A CommandConfigurationFactory produces CommandConfiguration objects. There is one instance of a CommandConfigurationFactory for every command type. For example, the Alien sensor plugin has three command types available to it: Alien-Poll, Alien-Push-Start, and Alien-Push-Stop. That means there are three factories instantiated when the plugin starts. The factories are created in the spring.xml and registered in the OSGi registry in the osgi.xml.

CommandConfiguration

A CommandConfiguration produces commands. Users can modify parameters of a Command by using the properties exposed through the @Property annotations and getter/setter methods.

Command

A command is a runnable that wraps some logical piece of communication with a sensor. For example, the LLRPConfigure command configures the LLRP command to send back tag reads. To do this, it sends several LLRP messages. Some commands should be scheduled for repeated execution, while others should only execute once. Regardless, the run() method inside a command should execute quickly (i.e. there should be no loops that wait on I/O or sleep).

Creating the Command Classes

Command

CommandConfiguration

CommandConfigurationFactory

Creating Factories and registering them with OSGi Service Registry

All factories (both SensorFactories and CommandConfigurationFactories) must be created and registered using spring.

Sensor Factories

The following is an example of a SensorFactory being created in the spring.xml

<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans 
	http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">

	<!--  Create Reader Configuration Factory -->
	<bean id="factory"
		class="org.rifidi.edge.readerplugin.thingmagic.ThingmagicReaderFactory">
		<property name="context" ref="bundleContext" />
		<property name="template" ref="internalMB" />
		<property name="notifierService" ref="JMSNotifierService" />
		<property name="commandConfigurations" ref="thingmagicCommands" />
	</bean>

</beans>

This code shows 1) How to register a sensor factory in the osgi registry and 2) How to get references to the notifier service and the jms template so that they can be injected into the factory in the above xml.

<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:osgi="http://www.springframework.org/schema/osgi"
	xsi:schemaLocation="http://www.springframework.org/schema/beans 
	http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
    http://www.springframework.org/schema/osgi 
    http://www.springframework.org/schema/osgi/spring-osgi.xsd">

	<!-- Put reader configuration service in OSGi Registry -->
	<osgi:service id="thingmagicConfigurationFactoryService" ref="factory">
		<osgi:interfaces>
			<value>org.rifidi.edge.core.configuration.ServiceFactory</value>
			<value>org.rifidi.edge.core.sensors.base.AbstractSensorFactory</value>
		</osgi:interfaces>
	</osgi:service>
	
	<!-- Create a set that listens for ThingMagic command configurations -->
	<osgi:set id="thingmagicCommands" interface="org.rifidi.edge.core.sensors.commands.AbstractCommandConfiguration"
		cardinality="0..N" filter="(reader=ThingMagic)">
		<osgi:listener ref="thingmagicConfigurationFactory" bind-method="bindCommandConfiguration" unbind-method="unbindCommandConfiguration"/>
	</osgi:set>
	
	<!-- Get a reference to the NotifierService -->
	<osgi:reference id="JMSNotifierService"
		interface="org.rifidi.edge.core.services.notification.NotifierService" />

	<!-- Get a reference to the JMS Queue -->
	<osgi:reference id="internalMB"
		interface="org.springframework.jms.core.JmsTemplate" bean-name="internalJMSTemplate" />
</beans>

Notice how these work together: each ref attribute references the ID attribute of another bean. For example, in the spring.xml a bean is crated with an id of "factory". The osgi:service tag references this ID in the osgi.xml.

Command Factories

The following show the CommandFactories being created for the Alien Sensor:

<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:osgi="http://www.springframework.org/schema/osgi"
	xsi:schemaLocation="http://www.springframework.org/schema/beans 
	http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
    http://www.springframework.org/schema/osgi 
    http://www.springframework.org/schema/osgi/spring-osgi.xsd">

	<bean id="alienGetTagListCommandConfigurationFactory"
		class="org.rifidi.edge.readerplugin.alien.commands.AlienGetTagListCommandConfigurationFactory">
		<property name="context" ref="bundleContext" />
	</bean>
	<bean id="alienAutonomousModeCommandConfigurationFactory"
		class="org.rifidi.edge.readerplugin.alien.commands.AlienAutonomousModeCommandConfigurationFactory">
		<property name="context" ref="bundleContext" />
	</bean>
	<bean id="alienAutonomousModeStopCommandConfigurationFactory"
		class="org.rifidi.edge.readerplugin.alien.commands.AlienAutonomousModeStopCommandConfigurationFactory">
		<property name="context" ref="bundleContext" />
	</bean>	
</beans>

Using @Property annotations