13 Oracle Sensor Edge Server

13.1.1.1 RFID Basics

RFID is the use of small transponders with embedded Electronic Serial Numbers (ESN) or memory, which transmit identifiers across one or more frequencies. A transponder can carry other information in its memory, and can be read or written to at a distance, without the need for line-of-sight contact.

Here are some useful terms for understanding the technology:

• Tag—a single unit that contains a chip, one or more antennae, and a power source. If the tag has its own power source (such as a battery or electrical connection), the tag is an Active Tag. If the power source is inductive-based, which means that it relies on photoelectric effect to generate power from remotely generated radio waves, the tag is a Passive Tag.

• Chip—a silicon chip, with embedded memory, is used in a tag. The chip is where the information is stored. It implements the wireless protocol and access functions to its embedded memory. Note that in active tags, this is not a single chip but a whole board.

• Antenna—there is one or more antennae on each tag. On the other side of the communication link, the reader must also have an antenna. Some readers can drive multiple antennae at the same time. Depending on the protocol, frequency and application, these antennae vary from thin strips of metal laid across a surface, to a portal doorway antenna that is meters tall.

• Reader—reads from, and writes to tags. Readers usually have serial interfaces used to communicate with a host computer. There is no widely-accepted standard for this protocol.

• Device—an end point of a sensor-based architecture. A device can be an RFID reader, a dry contact, a laser diode, carousel, robotic pickers, and so on.

• Oracle Sensor Edge Server—the middle tier that resides between all the readers and the applications. It is responsible for interfacing with all the readers and sending normalized data back to the application server.

13.1.2.1 Device Drivers

Device Drivers communicate with sensors, and normalize incoming data into standard format. Device Drivers can be customized or built to suit your needs.

13.1.2.2 Device Groups

Device Groups are used by administrators to group devices logically, and manage them more efficiently. An Oracle Sensor Edge Server can have one or many Device Groups instantiated. Each Device Group is responsible for the Device Drivers that it manages.

13.1.2.3 Filter Rules

Filter Rules remove unwanted or low-level events. Filter Rules can be used to sort incoming data. They can be applied to individual Devices, or to Device Groups.

13.1.2.4 Event Processor

Event Processor is the central processing engine for event delivery. It loads the rest of the components, which include the Driver Manager and (on start up) the Event Dispatcher. Internally, it reads the configuration to find out which Event Dispatcher to load. The process is started on startup.

13.1.2.5 Driver Manager

Driver Manager loads and manages the life cycle of the Device Groups and Device Drivers. There is only one instance of a Driver Manager for each Oracle Sensor Edge Server.Driver Manager provides an accessible context to device drivers so they can retrieve configuration information. It then loads the Device Groups, and binds them to the Device Drivers. The Driver Manager does not hold any thread internally, but an instance of it is held by the Event Processor instance as long as the server is up and running.

There is one Event Processor and one Driver Manager in each Oracle Sensor Edge Server. Each Driver Manager loads a number of Device Groups. In turn, each Device Group can have any number of Device Drivers. But, one Device Driver can only belong to one Device Group.

13.1.3.1 Streams/AQ

Oracle Sensor Edge Server supports forwarding data to Oracle Streams as the distribution mechanism to applications and agents. Dispatching through Streams provides the most robust and flexible method of forwarding data. This is the only dispatching method that fully supports rule-based processes and agents-based technologies.

Unlike other dispatcher methods mentioned (in which events are mostly transient and sent directly to an entry point), the Streams Dispatcher supports a much more sophisticated model in which arriving events are not directly mapped to event consumer entry points (that is, applications).

Events are data that is dropped into a Staging Area. The Oracle Sensor Edge Server defines various ways to aggregate data for different consumers. Interpretation of events is not done by either the Oracle Sensor Edge Server or the applications; it is done by the Sensor Data Hub in the database. This layer provides a rules-based process that defines the content and timing of notification.

Once events are staged, data can be archived, transformed and managed independently of the application and the Oracle Sensor Edge Server. This allows the Oracle Sensor Edge Server to be application and sensor neutral, providing far better quality and detail of data for goal-based and business intelligence models to process.

The Streams Dispatcher passes events to the staging area. Once data is in the staging area, the data can be processed in different ways.

The Rules Evaluation Job takes events from the staging area and runs them against the Oracle Sensor Edge Server ruleset. Each rule in the ruleset has an action, which is executed if the rule's predicate becomes relevant.

Actions defined can perform various operations, such as calling a PL/SQL callback, or propagating to other queues (which could then be consumed by other applications).

Applications needing to receive raw events before the rules evaluation phase can connect directly to the staging area by using AQ notification, AQ propagation, or JMS.

To summarize, the following are the ways an application can be invoked:

• PL/SQL Callback (rules-based)

• Queue propagation (rules-based)

• Mining the Sensor Data Hub

• Direct raw events by connecting to the staging area

begin
edg_utl.add_rule(     
    ruleName => 'my_callback',
    condition => 'tab.user_data.type = 0 AND tab.user_data.subtype = 2',
    param => 'my_schema.my_package.my_callback',
    command => 'call');
end;
/

begin
edg_utl.remove_rule(     
    ruleName => 'my_callback')
end;
/

PROCEDURE my_callback(ev IN EDGE.EDG_EVENT) IS
BEGIN

.... your code here ....

END my_callback;

begin
    edg_utl.route_map_fire_instruction(
device_name => 'device',
site_name => 'sitename',
cond => 'name of the condition');
end;
/ 

13.1.3.2 edg_utl Package

The edg_utl PL/SQL package contains utility functions that simplify common tasks required for accessing the Sensor Data Hub. The package is created under the EDGE user schema. The following table lists all the functions exposed in the edg_utl package.

For example, to send an event to a device called MyLight, with type 105, subtype 2, you could write:

SQL> edg_utl.sendToEdge( 105, 2, 'MySite', 'MyLight', 'dummyData', CURRENT_TIMESTAMP, '', '' );

To start a device called MyLight:

SQL> edg_utl.startDevice( 'MySite', 'MyLight' );

13.1.3.3 Java Messaging Services

The Java Messaging Services (JMS) is a standard messaging API that J2EE components use to communicate. The Oracle Sensor Edge Server provides a JMS Dispatcher to enable users to relay events to JMS topics.

13.1.3.4 Web Services

Another method supported by the Oracle Sensor Edge Server to distribute events is through Web Services, or more specifically SOAP calls.

A client can register a SOAP call which the server can invoke when a new message must be delivered. The following parameters must be provided by the client:

WebService EndPoint URL—this URL points to the WebService's EndPoint.

13.1.3.5 HTTP Interface

When HTTP client interface is chosen, the server uses standard HTTP 1.0 protocol to communicate with the client.

The client must provide a URL to which the Oracle Sensor Edge Server will post. When an event is received, the Oracle Sensor Edge Server initiates an HTTP Post command to the provided URL. The data is provided in the Post data. Note that each event is a separate post. All posts are performed sequentially, so if one post is blocked, other posts will not go through.

13.1.3.6 Custom Event Dispatcher

The Oracle Sensor Edge Server allows custom dispatchers to be loaded at runtime. The configurations for these dispatchers must be provided in an xml file and loaded into the Oracle Sensor Edge Server. The dispatcher must implement certain functions to provide the ability to send Events and also receive Instructions and other commands. To implement a dispatcher, see Oracle Application Server Administrator's Guide.

13.1.3.7 Sensor Data Hub

The term Sensor Data Hub (SDH) refers to a collection of standard out-of-the-box supported views and data objects. The constructs provide common functions used by most applications to shorten application development time.

13.1.3.8 Event

In all the client interfaces described, you will see the class or type Event being mentioned. This section describes the format and details usage of the fields in the Event type.

The Event type is a representation of a message that is sent from one component to another. An event is fixed-format but is extensible by mapping the existing fields to different meanings, depending on the type of event.

The following table shows the generic format of an Event:

The Event is split into the following sections:

Header—contains delivery information only. The header section contains these fields:

• correlationId—provided by the client; used for message responses to a particular client. It is up to the client to set it. Any message sent back in response to a client will have the same Id.sourceName—typically set to the name of the client for more efficient routing. The dispatch method may or may not use it to provide routing depending on this ID. It is up to the client to set it.

Type Info—information about how this Event's payload section is formatted. The type field of Event Type Info define the type of the message you are sending or receiving. The type field is assigned in a range depending of the type of the message:

• 0-99—System Messages

• 100-199—Instructions/Commands

• 200-299—Observations

More types can be defined, but currently the following types are available:

• 0: Unknown—If a event is set with type 0, it is either a bad event, or it is a system internal event. It should be ignored

• 1: Message Event—The message is a confirmation message, which is usually the return result code of a corresponding instruction requested

• 100: General Instructions—General instructions for controlling devices

• 101: RFID Instructions—Instructions to RFID devices

• 200: RFID Observation—The message is an RFID observation

• 201: RTLS

• 202: Physical Contact—(laser diode, dry contacts, and others)

• 203: Temperature

• 204: Humidity

• 205: Weight

• 206: Tampering

• 207: Audio

• 208: Message Board

EventPayload—Event-specific section with a specific data format (depending on the type of event or instruction).

• 102: Printer Instructions

• 103: Light Stack Instructions

13.2.1.1 Requirements

The following components are required before you can use this sample project:

• J2SE 1.4.x

• JDeveloper (10g)

• Oracle Sensor Edge Server

• Oracle Database 9.2 or later

13.2.2.1 What is Streams?

Oracle Streams enables the propagation and management of data, transactions and events in a data stream in one database, or across multiple databases. It enables you to manage and transform large amounts of data flowing through your Streams database. Sensor data is a data source that can be managed through Streams.

There are three stages to Streams:

• Capturing—taking in data from various sources to upload to a staging area for processing. The staging area is either an Advanced Queue or simply a table.

• Staging—once data and events are captured, events are placed in a staging area, this is the Staging Phase. Subscribers examine the contents of the staging area and then determine what to do with the events.

• Consumption—the events and data are applied to the database. You can build your own custom Streams for handling your data.

13.2.2.2 Oracle Sensor Edge Server and Streams

Oracle Sensor Edge Server supports using Streams as a distribution method; Streams is the recommended model because it provides the most flexibility, robustness and features.

When events are read in the devices, they are normalized by the drivers and sent out for filtering. After the data is cleansed and filtered, they are passed to the dispatchers to distribution.

Streams does not communicate directly with the application; it uses the Streams Dispatcher to hand off the events into a Streams Staging area (See the following diagram).

Figure 13-2 Architecture of Streams Dispatcher

Description of "Figure 13-2 Architecture of Streams Dispatcher"

Once the events are put into the Staging Area (which is an internal queue), the Oracle Sensor Edge Server's job is done. The rest of the process is handled by the database.

If you have installed the post installation scripts from the Oracle Sensor Edge Server for supporting Streams, you will gain extra functionality described below.

13.2.2.3 What Happens to the Events in the Database?

After events are deposited into the staging area, a background job picks them up and evaluates them against a set of rules. The rules are conditions that an event can either match or not. If the condition is satisfied for this event, an action will be taken. These actions, like the conditions, are user defined.

13.2.2.4 Rules and Actions

Each event that is staged is evaluated against the rules in the system. If any of them comes back positive, the action that is associated with the rule is executed. Rules are comprised of:

• Name

• Condition

• Command

• Parameter

Name is a unique rule name provided by the caller who created the rule. After creation, the rule name can be searched, changed, or deleted.

Condition is like a WHERE clause, but without the WHERE keyword. For example, if you want to match all tags with tag ID that starts with 159, you can use the condition tab.user_data.tagid LIKE '159%'. The prefix tab.user_data tells it to use the current event as the context.

Once the condition is met, the associated action is taken. Each action, is further broken down into:

• Command

• Parameter

Command gives the command (such as call to call a PL/SQL procedure, or queue to push the event to another queue).

Parameter is the parameter for the command. Call is the PL/SQL name; queue is the queue name.

13.2.4.1 Setting up the Database Instance

Set up a database instance. You can either use the Standard or Enterprise Edition of the Database, but it must be 9.0.2 or later. Once you have the instance, make sure you note the GDN (Global Data Name), and the administrator's user name and password.

If the database instance is on a separate machine (from Oracle Sensor Edge Server), you must edit ORACLE_HOME/network/admin/tnsnames.ora on the Oracle Sensor Edge Server machine to add the GDN to it.

13.2.4.2 Post-Installation

After setting up the database instance, set up the schema that the Streams Dispatcher will use. To do so, follow these steps (from the command line; all of the scripts mentioned here are in the \wireless\repository\sql directory.):

1. Go to ORACLE_HOME\wireless\repository\sql.

2. Start SQL*Plus, and use it to connect to your database instance as the administrator (user dba).

3. Run create_edg_user.sql to create the necessary user permision.This script will prompt your for the password for the user EDGE. Enter any password you like, but note it for your reference.

4. Log out of SQL*Plus.

5. Log in to SQL*Plus again, this time as the user EDGE. For example, if your GDN name is SDH, run sqlplus edge@sdh.

6. Run the script edg_create_streams.sql to create the internal queues, ruleset, and other streams-related data and schema.

7. Run the script edg_create_sdh.sql to create the Sensor Data Hub schema. If you do not need the Sensor Data Hub, omit this step.

Once you have executed the scripts, you will have a user in your database called EDGE. Under that user, all the necessary schemas and data will be created. The background jobs are also started automatically. For example, if your database is named mydb, your Sensor Edge Server is installed in C:/oracle/edge, and administrator password is manager, you can run the following commands to set up the database:

C:/> cd /oracle/edge
C:/oracle/edge> sqlplus system/manager@mydb @create_edg_usr.sql
SQL> password: edge <-- Enter your password, here we will use "edge"
SQL> exit
 
C:/oracle/edge> sqlplus edge/edge@mydb 
SQL> @edg_create_streams.sql
....
SQL> @edg_create_sdh.sql
....
SQL> exit
 
C:/oracle/edge>

Once you have done this, you are able to see the schema. Do a select * from sdh_events table to verify.

13.2.4.3 Configuring the Streams Dispatcher

Now that your database is prepared, you can begin sending it sensor observations.

To configure the Streams Dispatcher:

1. With a web browser, connect to the Sensor Services tab within the Wireless webtool.

2. Click Manage Edge Dispatchers.

3. From the drop-down list select StreamDispatcher.

4. Change the password for the edge user in the password parameter.

5. Change the parameter url to point to your database instance.

6. Click OK.

7. Restart the Sensor Edge Server. If the Sensor Edge Server is attached to simulators or real devices, you will begin to see the events coming into the database.

To verify that the dispatcher is connected properly, see wireless\logs\log.xml. You should see the following lines:

Tue Sep 14 19:06:15 PDT 2004: StreamsDispatcher: Attempting to create Q connectionsTue Sep 14 19:06:15 PDT 2004: StreamsDispatcher: Creating topic connectionTue Sep 14 19:06:21 PDT 2004: StreamsDispatcher: Creating topic sessionTue Sep 14 19:06:22 PDT 2004: StreamsDispatcher: Creating topic publisherTue Sep 14 19:06:22 PDT 2004: StreamsDispatcher: Creating topic subscriberTue Sep 14 19:06:26 PDT 2004: StreamsDispatcher: Finished initialization

If you see that initialization failed, your connection string or password is probably wrong, or the database is not seeded properly.

To test incoming events, from SQL*Plus, login as EDGE user, and execute: SELECT * FROM SDH_EVENTS. This is where all the observation events are archived. You should see it grow. If not, run the simulator and make sure the events are piping through.

Now that the Oracle Sensor Edge Server is ready, you can begin to code.

13.2.4.4 Adding Rules

To add Rules to the instance, follow these steps:

1. Connect to the database as user EDGE, for example: sqlplus edge/edge@mydb.

2. Run the following PL/SQL procedure: call edg_utl.add_rule( 'RuleName', 'Condition', NULL, NULL, 'Parameter', 'Command' );

   Where:

   'RuleName' is a unique name for the rule'Condition' is the rule condition'Parameters' is the parameter for the rule 'Command' is the command to invoke if the condition is satisfied

13.2.4.5 Testing Your Rules

You can test your Rules, even with the Sensor Edge Server running.

To test your Rule:

1. Connect to your database as user EDGE, for example: sqlplus edge/edge@sdh.

2. Call the utility function as follows: call edg_utl.sendToStage( type, subtype, id, siteName, deviceName, data, time, sourceName, correlId );

3. If the event matches one of your Rules, your callback will be called, or the event will be propagated to your queue (depending on the command you used).

4. To check for execution errors: select message from edg_log order by msg_time;

The utility function edg_util.sendToStage() sends an event directly to the staging area, which is evaluated by the Rules.

The EDG_LOG table stores any errors it encounters during execution.

13.2.4.6 Defining Conditions

A Rule's action is executed when the Condition clause is satisfied.

Condition is basically the WHERE clause of a SQL statement, with some distinctions. The event being evaluated is defined in the context tab.user_data (for details, see the DBMS Streams documentation for this construct). To see the fields in the event, execute desc edg_event, which will show you the definition of the EDG_EVENT ADT type. For example, if you want to look for any event that has a type value of 203, and an ID that begins with epc:, use the condition:

tab.user_data.type.type = 203 AND tab.user_data.id LIKE 'epc:%'

For more complex rules (such as joins with other lookup tables and so on), you can create PL/SQL functions, or better yet, use Streams context (see DBMS Streams documentation for more information).

13.2.4.7 Commands and Parameters

Once you have defined the condition, you must instruct the Oracle Sensor Edge Server as to what to do when the condition is met. This is specified in the command and parameters field.

There are two types of commands supported in this release:

'call' which calls a PL/SQL callback

'queue' which propagate the event to another queue

If the command is a 'call', the parameter field should be set to:

'schema.package.procedure'

For example, if a procedure is defined in the schema 'edge', in package name 'my_pkg', called 'testproc', then the parameter is:

'edge.my_pkg.testproc'

If the command is 'queue', then the parameter is set to the name of the queue you want to propagate to. Note that this queue must be created based on EDG_EVENT ADT type (future releases will support marshalling to different queue formats).

13.2.4.8 Creating Your Own Instances

If you want to clear out the instance and re-initialize it to start over, you can do so by dropping the edge user from the Oracle Sensor Edge Server. Note that all data and PL/SQL built in the edge user will also be cleared; back up any data you need before following these steps:

1. Log in, for example: sqlplus edge/edge@sdh.

2. Run exec edg_utl.deschedule_job.

3. Log out.

4. Connect to the database as administrator, for example: sqlplus edge/edge@sdh.

5. Run the SQL command to drop the user as follows: drop user edge cascade;

6. Exit from SQL*Plus.

Upon completion, you can re-initialize the instance.

13.3.1.1 Requirements

The following components are required before you can use this sample project:

• J2SE 1.4.x (downloadable from Sun's web site (http://www.javasoft.com)

• Oracle Sensor Edge Server

• Oracle Database 9.2 or later

13.4.1.1 Requirements

The following components are required before you can use this sample project:

• J2SE 1.4.x (J2DK is downloadable from Sun's web site (http://www.javasoft.com)

• Oracle Sensor Edge Server

• Oracle Database 9.2 or later