1 Configuring the Oracle Sensor Edge Server

1.1.1 Deploying Drivers, Filters and Dispatchers to the Oracle Sensor Edge Server

To receive and process event data from sensor devices, the Oracle Edge Sesor Server uses driver and filter objects to receive, read events and then process the event data. The Oracle Edge Sensor Server then sends the processed event data on to applications using a dispatcher. Depending on the configuration of the Oracle Sensor Edge Server's dispatcher, an Oracle Sensor Edge Server client application receives event messages through database streams, JMS (Java Message Service), Web Services (SOAP), or HTTP. The payload of the message is always an event. For more information on dispatching events, refer to Section 1.4.

The drivers provided out of the box support the 9RE-001 by Alien Technology, the Penn, Delaware, and PCMCIA readers manufactured by Intermec and the PHE-3FB PC-Controlled Light indicator manufactured by Patlite Corporation. For more information on drivers, refer to Chapter 2, "Managing Drivers". For filtering event data, the Oracle Sensor Edge Server provides filters that perform not only such functions as device monitoring, event tracking, and data cleansing by blocking redundant events, but can also send events that signal when new containers or pallets enter or exit the field or gateway of a device reader, or enable you to see all of the tag IDs of items held in a container or on a pallet. For more information on the filters provided by the Oracle Sensor Edge Server, refer to Chapter 3, "Managing Filters".

You can change or further enhance the capabilities of the Oracle Sensor Edge Server by adding extensions: custom-built drivers, filters and dispatchers. You add the drivers, filters and dispatchers by downloading an Extension Archive file (a JAR file containing all of the class files as well as other related files) to the repository. For more information, refer to Chapter 4, "Managing Extensions".

For the Oracle Sensor Server to use extensions, however, you must create instances of these objects. For example, for a sensor to use a driver, you must create an instance of the driver object called a device instance. Similarly, for device instance to utilize a filter, you must create a filter instance of the filter object. When you assign a dispatcher as the current dispatcher used by the Oracle Sensor Edge Server, you create an instance of a dispatcher. For more information on the components of the Oracle Sensor Edge Server, refer to the Oracle Application Server Wireless Developer's Guide

1.1.2 Overview of Events

The Event type represents a message sent from one component of the Oracle Sensor Edge Server to another. These event messages are specific to each type of driver or filter. The Event type is divided into the following sections:

• Header

• Type Info

• Payload

Header

The Header sections includes the routing headers and the message headers, which contain fields that designate the delivery of an event message. The routing fields include <sourceName> and <correlationID>. The message headers include the <siteName> and <deviceName> fields.

• <sourceName>

  This field identifies the originator of the event. This is an optional field, one set by the client.

• <correlationId>

  The client sets the value for this field, which is used for message responses to a particular client (such as checking if a device functions). Any message response sent back by the client will have the same ID. This is an optional field.

• <siteName>

  The site that originally generated the message.

• <deviceName>

  The name of the device or application that generates the event.

• <time>

  The date and time when the observation or message was created.

Type Info

The Type Info section contains the formatting information for the payload: the type and subtype of the event.

• <type>

  The number value that corresponds to the type of event. Table 1-1 describes the values of the <type> field. The Oracle Application Server Wireless Developer's Guide describes the values for the <type> field in further detail.

  Table 1-1 Value Ranges for the <type> Field

  Range	Message Type
  0-99	System messages. The range of values includes: 0 -- Unknown A value of 0 represents a bad event or a system internal event. 1 -- Message Event A confirmation message, usually the return result code of a corresponding instruction.
  100-199	Instructions or commands. The range of values includes: 100 -- General Instructions General Instructions for controlling devices. 101 -- RFID Instruction Instructions to RFID devices. 102 -- Printer Instructions to printers. 103 -- Lightstack
  200-299	Observations. The range of values includes: 200 -- RFID Observation The message is an RFID observation 201 -- RTLS 202 -- Physical Contact 203 -- Temperature 204 -- Humidity 205 -- Weight 206 -- Tampering 207 -- Audio 208 -- Message Board
  500-599	Custom messages

  
  

• <subtype>

  The number value for the subtype. For more information on Instruction Events, refer to the Oracle Application Server Wireless Developer's Guide

Payload

The Payload section, which is the event-specific section with the following fields:

• <id>

  The text value of this field identifies a tag (that is, a read or target) to an event instruction.

• <data>

  The tag data. This is an optional field.

1.2.1 The General Settings and Parameters for the Oracle Sensor Edge Server

The file's root element, <EdgeServer> encompasses high-level configurations (described in Table 1-2) and contains elements that enable you to configure not only the dispatchers, filters, and drivers available to the Oracle Sensor Edge Server, but the instances of these objects that enable the Oracle Sensor Edge Server to receive and process events.

1.2.2 Available Dispatchers, Filters, and Drivers

The <DispatcherList>, <DriverList> and <FilterList> elements comprise the template section of the configuration file, where you define the filters, dispatchers and drivers that are available to the Oracle Sensor Edge Server.

Dispatchers, filters and drivers are extensions, downloadable components that add functionality to the Oracle Sensor Edge Server. By themselves, these extensions are not active components; they are not executed. For the Oracle Sensor Edge Server to use these components, you must instantiate an extension by creating an instance of it. For example, to connect a driver to a reader, you must create a device instance of the driver extension. Table 1-3 describes the components for extensions that can be configured. The instances of these extensions (described in Section 1.2.4.1) are called devices and filter instances. The instance of a dispatcher is the current dispatcher.

Defining Parameters for Extensions and Instances

Both extensions and their instances contain dynamic lists of parameter settings which are defined within the <Parameters> elements of the configuration file. These parameters are specific to the type of extension and can be configured for each instance. For extensions, the <Parameters> elements and its child, <Parameter> tell the Oracle Sensor Edge Server the default values of the parameters and which parameters (if any) are exposed.

<Parameter> requires the following fields:

• id

  An attribute with a unique identifier. Some of the tags in edgeserver.xml (including <Parameters>) require a unique identifier so that they can be referenced by other tags. The identifier is defined in the id attribute and must be unique across the configuration file (although they do not have to be consecutive). When adding new elements that do not have references, you do not have to manually add the value of the reference id attribute; the Oracle Sensor Edge Server automatically assigns a value once it starts.

  
  

  Note: Entering an incorrect reference id might lead to incorrect behavior.

  
  

• name

  The name of the attribute, unique within the <Parameters> tag.

• defaultValue

  The default value for the parameter. This is used as the initial value in any UI or when first creating the object

• description

  Text that describes the value (mostly for the user interface).

• encrypted

  Indicates whether the value for the parameter should be encrypted so that the value does not have to be stored in clear-text format.

• isClearText

  Enables the default value (and the value for the parameter instance) to be reset to clear-text format. If the encrypted parameter is set to true, then the clear-text format is read and then set to encrypted format the next time the Oracle Sensor Edge Server starts.

• required

  Indicates whether the parameter value is required.

• valueType

  The type attribute specifics the type to use for the value. It could be

  • string for string values

  • int for integer values

  • boolean for true or false values

  • double for a double-precision number

1.2.3 The Current Dispatcher Method for the Oracle Sensor Edge Server

<CurrentDispatcher> defines which dispatcher the Oracle Sensor Edge Server uses as well as the dispatcher's parameters. This is the only instance object that is not defined in the <DeviceGroup> section (described in Section 1.2.4). An Oracle Sensor Edge Server can use only one dispatcher at a time. Even if you have only one dispatcher defined within <DispatcherList>, the Oracle Sensor Edge Server can use it only if it is defined within the <CurrentDispatcher> element. After you assign a dispatcher as current, you must stop and then start the Oracle Sensor Edge Server. For more information setting the current dispatcher method in edgeserver.xml, refer to Section 1.4.1. For information on starting and stopping the Oracle Sensor Edge Server, refer to Section 1.3.

1.2.4 Filters, Dispatchers and Devices Used by the Oracle Sensor Edge Server

Device groups are similar to the root or top-level directories of a file system. Because all devices (the instances of drivers) and filter instances must be part of a device group, you must create one or many device groups before you can connect devices and set up filters. You can group devices in terms of management if you want to treat them as a logical unit to manage, or you can group them by the type of filtering that they perform. For example, if you group devices by cross-reader filtering, then you create a group of related devices and then attach filters to that group.

The <DeviceGroups> section of the configuration file defines all the device groups in the system. All of the instances of devices and filters are defined within this element. The <DeviceGroups> element contains an array of <DeviceGroup> elements. Each <DeviceGroup> tag contains the following:

• <Device>

  One of many <Device> elements that can be defined in a device group. Each <Device> defines a device instance.

• <EventCollectWaitTime>

  The interval for the group to pull events out of the filtered window of events, in milliseconds.

• <FilterInsts>

  Defines the list of group filter instances

• <IsDefault>

  Set to false for all user groups

• <Name>

  The name of the device group

For more information on defining devices, refer to Section 1.5. For more information on creating filter instances, refer to Section 3.3.1.

<Name>Intermec Device</Name>
<DriverName>IntermecDevice</DriverName>   
<Extension Reference="35">/

1.3.1 Starting the Oracle Sensor Edge Server by Starting an OC4J Instance

To start the OC4J instance from a command line:

1. Start a command shell (on Windows, for example, use cmd.exe).

2. Navigate to ORACLE_HOME/j2ee/home.

3. Execute java -jar oc4j.jar to start the OC4J instance.

A message similar to the one illustrated in Example 1-4 displays if the Oracle Sensor Edge Server has been installed properly.

04/11/17 20:36:07 Extension upload monitoring is not enabled...
04/11/17 20:36:07 EdgeServer: finished initialization
04/11/17 20:36:07 Oracle Application Server Containers for J2EE 10g (10.1.2.0.0) initialized

1.3.2 Stopping Oracle Sensor Edge Server by Stopping the OC4J Instance

You can stop the Oracle Sensor Edge Server by using the OC4J administrative tools or you stop the OC4J instance itself from the command line. In either case, the Oracle Sensor Edge Server is notified and shuts down gracefully. To stop the OC4J instance from the command-line, send a kill signal to the OC4J instance. For example, on Windows, click Ctrl+C to kill the instance.

1.3.3 Starting the Oracle Edge Sensor Server From the Command Line

In addition to starting the Oracle Sensor Edge Server by starting an OC4J instance, you can also start the Oracle Sensor Edge Server by running the following:

On Windows:

ORACLE_HOME\edge\runSensorEdgeServer.bat

On UNIX:

ORACLE_HOME/edge/runSensorEdgeServer.sh

If you do not provide the argument specifying the ORACLE_HOME, then the system prompts you with the following message:

Must provide the for this Sensor Edge Server.Usage: runSensorEdgeServer.bat ORACLE_HOMEORACLE_HOME

If you provided the ORACLE_HOME argument, then a message simular to the one described in Example 1-5 appears.

04/11/17 20:36:07 Extension upload monitoring is not enabled...
04/11/17 20:36:07 EdgeServer: finished initialization
04/11/17 20:36:07 Oracle Application Server Containers for J2EE 10g (10.1.2.0.0) initialized

1.4.1 Setting the Current Dispatcher Used by the Oracle Sensor Edge Server

To set the current dispatcher for the Oracle Sensor Edge Server:

1. Select from among the dispatchers defined within <DispatcherList>.

2. In <CurrentDispatcher>, change the element content of <DispatcherName> to the name of the dispatcher, which could be any one of the following:

   • Streams Dispatcher (Section 1.4.1.1)

   • JMS Dispatcher (Section 1.4.1.2)

   • HTTP Dispatcher (Section 1.4.1.3.

   • Web Services (Section 1.4.1.4)

   • NullDispatcher (Section 1.4.1.5).

3. Compare the definition of <Dispatcher> within <DispatcherList> to ensure that each <ParameterInst> within <CurrentDispatcher> corresponds with each <Parameter> defined within <Dispatcher>.

4. Save edgeserver.xml and restart the Oracle Sensor Edge Server. The server then loads the selected dispatcher upon startup.

Example 1-6 illustrates configuring the <CurrentDispatcher> elements for the Streams dispatcher.

<CurrentDispatcher id="76">
   <DispatcherName>StreamsDispatcher</DispatcherName>
       <Extension class="Dispatcher" reference="5"/>
       <Name>StreamsDispatcher</Name>
       <NeedReload>false</NeedReload>
   <ParameterInsts id="77">
       <ParameterInst id="78">
          <Name>username</Name>
          <ParameterMetaData reference="7"/>
          <Value>edge</Value>
      </ParameterInst>
      <ParameterInst id="79">
         <Name>password</Name>
         <ParameterMetaData reference="8"/>
         <Value>oracle</Value>
      </ParameterInst>
      <ParameterInst id="80">
         <Name>url</Name>
         <ParameterMetaData reference="9"/>
         <Value>jdbc:oracle:thin:@(description=(address=(host=soclxs3db02)
                      (protocol=tcp)(port=9105))(connect_data=(sid=PRJ1)))</Value>
      </ParameterInst>
    </ParameterInsts>
 </CurrentDispatcher>

1.5.1 Creating a Device

To create a device:

1. Locate the <DeviceGroup> to which to add the device. If needed, add a new <DeviceGroup> element. For more information on the children of the <DeviceGroup>, refer to Section 1.2.4.

2. Add a new <Device> section. (You can copy a <Device> section from an existing device to use as a template.)

3. Set the name of the device within the <Name> tag.

4. Set the element definition in the <DriverName> tag to the name of a driver listed in the <DriverList> section.

5. Within the <Extension> element, set the value of the reference attribute to that of the driver.

6. Set the <ParameterInsts> to match the attribute values set for the driver's <Parameters> element.

7. If needed, add a filter instance to this device by defining the <FilterInsts> section.

8. Save edgeserver.xml and restart the Oracle Sensor Edge Server to instantiate the device.

Example 1-7 illustrates configuring the Oracle Edge Sensor Server to use a device called stack 1, an instance of a driver called Edge Device Driver.

<DeviceGroups>
    <DeviceGroup>
      <DeviceList>
        <Device>
          <Name>stack1</Name>
          <DriverName>Edge Device Driver</DriverName>
          <Extension reference="49"/>
          <ParameterInsts>
            <ParameterInst>
              <Name>PortNo</Name>
              <ParameterMetaData reference="51"/>
              <Value>7878</Value>
            </ParameterInst>
            <ParameterInst>
              <Name>IPAddress</Name>
              <ParameterMetaData reference="52"/>
              <Value>152.69.156.193</Value>
            </ParameterInst>
          </ParameterInsts>
          <FilterInsts/>
        </Device>
   </DeviceList>
      <EventCollectWaitTime>500</EventCollectWaitTime>
      <FilterInsts id="108"/>
      <IsDefault>true</IsDefault>
      <IsSystem>true</IsSystem>
      <Name>Unassigned</Name>
    </DeviceGroup>
  </DeviceGroups>

1.6.1 Creating a Filter Instance

To create a filter instance:

1. Within the <DeviceGroups>, locate the <Device> to which to add the filter instance.

2. Add a <FilterInst> element to the device's <FilterInsts> section.

3. For the <Extension> element, specify the name of the filter for the class attribute, and the id of the filter for the reference attribute.

4. Set the <ParameterInsts> to match the attribute values set for the filter's <Parameters> element.

5. Save edgeserver.xml and then restart the Oracle Sensor Edge Server.

   Example 1-8 illustrates configuring a device to use a filter instance by defining the <FilterInsts> element. In this example, the PalletPassFilter has a <Sequence> value set a 1. The number specified within the <Sequence> tag determines the order in which filter instances are applied. For more information or setting the order of the filter instances, refer to Section 3.3.1.1.

   Example 1-8 Configuring a Filter Instance for a Device

   <FilterInsts>
         <FilterInst>
             <Sequence>1</Sequence>
             <FilterName>PalletPassFilter</FilterName>
             <Extension class="Filter" reference="50"/>
             <ParameterInsts>
               <ParameterInst>
                 <ParameterMetaData reference="52"/>
                 <Value>11</Value>
                 <Name>ExitEventThresholdTime</Name>
               </ParameterInst>
               <ParameterInst>
                 <ParameterMetaData reference="53"/>
                 <Value>12</Value>
                 <Name>EventCollectControlTime</Name>
               </ParameterInst>
             </ParameterInsts>
             <NeedReload>false</NeedReload>
             <Name>PalletPassFilter</Name>
           </FilterInst>
    </FilterInsts>