|
Oracle® Sensor Edge Server Administrator's Guide
10g Release 2 (10.1.2) B14455-02 |
|
 Previous |
 Next |
|
Oracle® Sensor Edge Server Administrator's Guide
10g Release 2 (10.1.2) B14455-02 |
|
|
Previous |
Next |
This chapter, through the following sections, describes how to manage and configure the filters for the Oracle Sensor Edge Server.
Section 3.2, "Defining the Parameters of the Pre-Seeded Filters"
Section 3.3, "Enabling Event Filtering for Devices or Device Groups"
A filter is a class that strains out unwanted events or translates higher-level events from groups or events or specific conditions. An event is a message that is sent from either a sensor device or an application that signals that a state has changed. The Oracle Sensor Edge Server, which receives the data from these sensor devices or applications, normalizes the contents of these event messages by putting them in a common data format and then applies filters to strip them of extraneous information or unwanted events.
The <FilterList> element (Example 3-1) of edgeserver.xml defines the filters that are available to the Oracle Sensor Edge Server.
Example 3-1 The <FilterList> Element of edgeserver.xml
<FilterList id="51">
<Filter id="52">
<ClassName>oracle.edge.impl.filter.PassFilter</ClassName>
<Description>Filter redundant in range tag ids from a single
reader.</Description>
<Name>PassRedundantFilter</Name>
<Parameters id="53">
<Parameter id="54" name="ExitEventThresholdTime" defaultValue="800"
description="Time elapsed in
milliseconds since a tag has been seen last time"
encrypted="false">
<valueType type="int"/>
</Parameter>
</Parameters>
<Version>1.0</Version>
</Filter>
<Filter id="55">
<ClassName>oracle.edge.impl.filter.PalletPassFilter</ClassName>
<Description>Filter redundant in range tag ids from a single reader.</Description>
<Name>PalletPassFilter</Name>
<Parameters id="56">
<Parameter id="57" name="ExitEventThresholdTime" defaultValue="800"
description="Time elapsed in milliseconds since a tag
has been seen last time"
encrypted="false">
<valueType type="int"/>
</Parameter>
<Parameter id="58" name="EventCollectControlTime" defaultValue="1500"
description="Time elapsed in milliseconds since a
new tag has been detected last time"
encrypted="false">
<valueType type="int"/>
</Parameter>
</Parameters>
<Version>1.0</Version>
</Filter>
<Filter id="59">
<ClassName>oracle.edge.impl.filter.PalletShelfFilter</ClassName>
<Description>Filter redundant in range tag ids from a single reader.
</Description>
<Name>PalletShelfFilter</Name>
<Parameters id="60">
<Parameter id="61" name="ExitEventThresholdTime" defaultValue="800"
description="Time elapsed in milliseconds since a tag
has been seen last time"
encrypted="false">
<valueType type="int"/>
</Parameter>
<Parameter id="62" name="EventCollectControlTime" defaultValue="1500"
description="Time elapsed in milliseconds since a new
tag has been detected last time"
encrypted="false">
<valueType type="int"/>
</Parameter>
</Parameters>
<Version>1.0</Version>
</Filter>
<Filter id="63">
<ClassName>oracle.edge.impl.filter.ShelfFilter</ClassName>
<Description>Filter redundant in range tag ids from a single reader.
</Description>
<Name>ShelfRedundantFilter</Name>
<Parameters id="64">
<Parameter id="65" name="ExitEventThresholdTime" defaultValue="800"
description="Time elapsed in milliseconds since a tag
has been seen last time"
encrypted="false">
<valueType type="int"/>
</Parameter>
</Parameters>
<Version>1.0</Version>
</Filter>
<Filter id="66">
<ClassName>oracle.edge.impl.filter.CrossReaderRedundantFilter</ClassName>
<Description>Filter redundant tag ids from multiple readers.</Description>
<Name>CrossReaderRedundantFilter</Name>
<Parameters id="67"/>
<Version>1.0</Version>
</Filter>
<Filter id="68">
<ClassName>oracle.edge.impl.filter.CheckTagFilter</ClassName>
<Description>Check Tag Filter</Description>
<Name>Check Tag Filter</Name>
<Parameters id="69">
<Parameter id="70" name="CheckTagId" defaultValue=""
description="Tag id to be checked" displayName="Check
Tag Id"
encrypted="false">
<valueType type="string"/>
</Parameter>
<Parameter id="71" name="TagCheckInterval" defaultValue="60000"
description="Time interval in milliseconds between two
tag-checking window"
displayName="Tag Check Interval" encrypted="false">
<valueType type="int"/>
</Parameter>
<Parameter id="72" name="TagCheckTimeWindow" defaultValue="60000"
description="Time window in milliseconds for each
tag-checking"
displayName="Tag Check Time Window"
encrypted="false">
<valueType type="int"/>
</Parameter>
</Parameters>
<Version>1.0</Version>
</Filter>
<Filter id="73">
<ClassName>oracle.edge.impl.filter.DebugFilter</ClassName>
<Description>Debug Filter</Description>
<Name>Debug Filter</Name>
<Parameters id="74">
<Parameter id="75" name="EventOutputFile" defaultValue=""
description="Output file for dumping events"
displayName="Debug Output File"
encrypted="false">
<valueType type="string"/>
</Parameter>
</Parameters>
<Version>1.0</Version>
</Filter>
</FilterList>
Because a filter object is not executed and therefore cannot be used by a device, you must a create an instance of the filter (a filter instance) to enable a device to use the filter.
Filters can be attached to either a specific device or to a device group. Some filters are written as group-level filters and can only be attached to a device group. Likewise, some filters are written only for device-level filtering and only function if they are attached to a specific device. The filter object implements three levels of filtering:
Pre-Device Filtering
Pre-device filtering provides filtering against a batch of pass-in events before they are routed to the Oracle Sensor Edge Server device.
Post-Device Filtering
Post-device filtering provides any filtering against the events before they are merged up to a device group.
Device Group Filtering
Device group filtering provides filtering against events before they are delivered to an edge client.
|
Note: Pre- and post-device filters apply only to devices; device group filtering applies only to device groups. |
The Oracle Sensor Edge Server enables you to add filters that provide pre-device and post-device filtering. For more information on device group- and device-level filtering, refer to Section 3.3.1.
|
Note: Only the filters that you create enable pre- and post-device filtering. For more information on developing filters, refer to the Oracle Application Server Wireless Developer's Guide. |
The Oracle Sensor Edge Server provides a set of pre-seeded filters (described in Table 3-1). If needed, you can develop your own filter extensions and then upload them. For more information on uploading extensions, refer to Chapter 4.
Table 3-1 The Pre-Seeded Filters of the Oracle Sensor Edge Server
| Filter Name | Function | Applied to Device Group? (Supports Group-Level Filtering) | Applied to Devices? (Supports Device-Level Filtering) |
|---|---|---|---|
|
Check Tag ID Filter |
A diagnostic tool that checks if a device is reading tags during a specified interval. See Section 3.2.1 |
No |
Yes |
|
Cross-Reader Redundant Filter |
Blocks redundant events that are sent from the devices of a device group. See Section 3.2.2 |
Yes |
No |
|
Debug Filter |
Tracks events passing through the system and then writes these events to a log file. See Section 3.2.3 |
No |
Yes |
|
Pass Filter |
Notifies applications that a tag has passed through a device's field. This filter also blocks events, so that only one event, rather than duplicate events, is generated when a tag is detected by a device. See Section 3.2.4 |
No |
Yes |
|
Shelf Filter |
Signals that an item has entered, or exited the field or gateway of a device reader. See Section 3.2.5 |
No |
Yes |
|
Pallet Pass-Thru Filter |
Enables you to see all of the tag IDs for items held in a container or on a pallet. See Section 3.2.6 |
No |
Yes |
|
Pallet Shelf Filter |
Sends events that signal new containers or pallets entering or exiting the field or gateway of a device reader See Section 3.2.7 |
No |
Yes |
The following sections describe how the pre-seeded filters generate events and their configuration parameters:
A Check Tag is any normal tag used to test if the device (in this case, a reader) is reading tags. Because the Check Tag itself should be physically located within the field of the reader, it should always be read; when other tags move through the field of the reader, the device also reads the Check Tag in conjunction with them.
The Check Tag ID Filter ensures that the device reads a Check Tag periodically. Using this filter enables you to check the status of a driver, its corresponding reader, and attached antennae. Because the Check Tag ID Filter is used solely for diagnostic purposes, it does not provide any events for dispatching to client devices. Instead, this filter generates an event if it does not detect that the device has read a Check Tag for a specified period of time.
|
Note: You can apply the Check Tag ID Filter only to devices. |
Table 3-2 describes the parameters (and associated values) of the Check Tag ID filter.
Table 3-2 Parameters of the Check Tag ID Filter
| Name | Value Type | Description |
|---|---|---|
|
CheckTagId |
A |
The tag ID of the Check Tag, which is the ID that the filter searches for to see if the tag is being read. |
|
TagCheckTimeWindow |
An |
The period of time, in milliseconds, after which an event is generated if the filter has not seen the specified Check Tag. |
To define the parameters for the Check Tag ID Filter, you must note the ID of the Check Tag itself (which must be placed within the field of the reading device). Enter this ID as the String value of <CheckTagId>. If the filter does not detect that a device has read a Check Tag bearing the specified ID for the period defined in the <TagCheckTimeWindow> parameter, it generates an event. Table 3-3 describes the signature of the generated event. Refer to Section 1.1.2 for more information on the Event type.
The Cross-Reader Redundant Filter blocks redundant events that are sent from the devices of a device group and does not generate any events. This filter considers events redundant if it finds they have the same tag ID.
The Cross-Reader Redundant Filter is for group-level filtering only; it performs no functions if applied to a device. This filter has no parameters to configure.
The Debug Filter traces events passing through the system. Upon receiving events from its associated device, this filter writes events to a log file. This filter has a single parameter called <EventOutputFile>. To define this parameter, enter the full path of the log file to which the Debug Filter writes events. (The server must make this file writable.) The format of the Debug Filter's output is:
"Devicename: <devicename> Type: <type> Subtype: <subtype> EventTime: <time>TagIds:<tagid(,tagid)*>Data:<dat(,data)*>\n"
Each event is on a separate line; each line is separated by a newline character (LF or CRLF, depending on the operating system). The <time> value is a long as returned by the time(2) call.
This filter can only be attached to a device, not to a device group.
When a tag passes through the range of transmission, or through the gateway of a device reader, it generates a series of "tag is seen" events. The device reports these events periodically, starting when the tag enters the transmission field. The reporting stops when the tag moves out of the reader field.
Applications often do not require the series of events that a device reader generates; instead, these applications only need to know that a tag has passed through a device's gateway or range of transmission. The Pass Filter applies to such situations, as it reduces all of the "tag is seen" events into single events for each unique tag that passes through the field of a reader device.
The Pass Filter has one parameter, <ExitEventThresholdTime>. To define this parameter, enter the time (an int value), in milliseconds, since the device last read the tag before it is considered to have moved out of the device's transmission field. The parameter settings, which range from 50 milliseconds to under two seconds, dictate the frequency (that is, the reader cycle) in which the device reports these "tag is seen" events. If you set this frequency too high, such as to two seconds, then the device may miss the tag altogether.
When the device first reads a tag, the Pass Filter caches the tag's ID (tagid), notes the time that the tagid was read into the cache, and then immediately sends the pass-through event. The filter blocks subsequent reads for this cached tagid. Each time the filter receives a new read from the device, it updates the time that it read the tagid into the cache. If the sum of the caching time and the value set for <ExitEventThresholdTime> is less than the current time, then the Pass Filter clears the tagid from the cache. The next time the device reads this tag, the filter considers it a new event, caches its tagid and sends out a new pass-through event. Refer to Section 1.1.2 for more information on the Event type.
Table 3-3 describes the signature of the pass-through event.
Table 3-3 Signature of the Pass-Through Event
| Event Field | Value |
|---|---|
|
sourceName |
This field identifies the originator of the event. This is an optional field. |
|
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 sent back by the client has the same ID. This is an optional field. |
|
siteName |
The name of the site that generated this event. |
|
deviceName |
The name of the device that generated this event. |
|
time |
The time that the event was generated. |
|
type |
Event.OBSERVATION |
|
subtype |
Event.PASS |
|
id |
The ID of the tag. |
|
data |
The data payload of the tag. |
The Shelf Filter is a device-level filter that generates events when a tag is detected within the field of a reader or when the tag has left the field. Like the Pass Filter, the Shelf Filter has a single parameter, <ExitEventThresholdTime>. To define this parameter, enter the time (an int value), in milliseconds, since the device last read the tag before it is considered to have moved out of the device's transmission field. Unlike the Pass Filter, however, the Shelf Filter silently clears its cache once the interval defined for the <ExitEventThresholdTime> parameter elapses and does not generate an event.
The Shelf Filter generates two events:
IN FIELD Event
The Shelf Filter generates this event when the device first detects the tag. Table 3-4 describes the signature for this event. Refer to Section 1.1.2 for more information on the Event type.
Table 3-4 Signature of the IN FIELD Event
| Event Field | Value |
|---|---|
|
sourceName |
This field identifies the originator of the event. This is an optional field. |
|
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 sent back by the client has the same ID. This is an optional field. |
|
siteName |
The name of the site that generated this event. |
|
deviceName |
The name of the device that generated this event. |
|
time |
The time that the Shelf Filter generated this event. |
|
type |
Event.OBSERVATION |
|
subtype |
Event.INFIELD |
|
id |
The ID of the tag. |
|
data |
The data payload of the tag. |
OUT FIELD Event
The Shelf Filter generates this event when the interval defined for the Exit Event Threshold Time parameter elapses. Table 3-5 describes the signature for this event. Refer to Section 1.1.2 for more information on the Event type.
Table 3-5 Signature of the OUT FIELD Event
| Event Field | Value |
|---|---|
|
sourceName |
This field identifies the originator of the event. This is an optional field. |
|
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 sent back by the client has the same ID. This is an optional field. |
|
siteName |
The name of the site that generated this event. |
|
deviceName |
The name of the device that generated this event. |
|
time |
The time that the Shelf Filter generated this event. |
|
type |
Event.OBSERVATION |
|
subtype |
Event.OUTFIELD |
|
id |
The ID of the tag. |
|
data |
The data payload of the tag. |
When a device first detects the tag, the Shelf Filter caches the ID of the tag and then generates an IN FIELD event. At this point, the tag is read during every reader cycle. While the tag may not be read during some of these cycles, it is read during others. When the device does not read the tag consistently for a period longer than that designated for the <EventExitThresholdTime> parameter, then the filter removes the tag's ID from the cache and generates an OUT FIELD event. The devices stops reading the tag once it passes from the field of the device.
The Pallet Pass Thru Filter collects all of the events received during a specified period and sends them out as a single event. When a pallet or container passes through a gateway or through the field of transmission of a reader device, this filter generates a single event for all of these tags. This filter enables you to see what items a container or pallet may hold.
The Pallet Pass Thru Filter includes the following parameters:
<ExitEventThresholdTime>
To define this parameter, enter the time (an int value), in milliseconds, since the device last read a tag before it is considered to have moved out of the device's transmission field. The parameter settings, which range from 50 milliseconds to under two seconds, dictate the frequency (that is, the reader cycle) in which the device reports these "tag is seen" events. If you set this frequency too high, such as to two seconds, then the device may miss the tag altogether.
<EventCollectControlTime>
To define this parameter, enter the time (an int value), in milliseconds, for a device to complete a reading cycle of the tags included in a pallet or container before starting a new reading cycle. When this time elapses, the reading cycle concludes (that is, the device has read all of the new tags) and the Pallet Pass Thru Filter then generates an event with the following signature (described in Table 3-6). Refer to Section 1.1.2 for more information on the Event type.
Table 3-6 Signature of the Pallet Pass Thru Event
| Event Field | Value |
|---|---|
|
sourceName |
This field identifies the originator of the event. This is an optional field. |
|
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 sent back by the client has the same ID. This is an optional field. |
|
siteName |
The name of the site that generated this event. |
|
deviceName |
The name of the device that generated this event. |
|
time |
The time that the event was generated. |
|
type |
Event.OBSERVATION |
|
subtype |
Event.MULTIPLE_PASS |
|
id |
A comma-separated list of tag IDs. |
|
data |
A comma-separated list of datum. |
The Pallet Shelf Filter collects all of the events received during a set interval and then sends them as a single event. This filter enables you to identify when new containers or pallets holding many items enters an area, or exits the field or gateway of a device reader.
The Pallet Shelf Filter has the following parameters:
<ExitEventThresholdTime>
To define <ExitEventThresholdTime>, enter the time (an int value), in milliseconds, from the last time that the device read the tag before it is considered to have moved out of the device's transmission field. The Pallet Shelf Filter silently clears its cache once the interval defined for the <ExitEventThresholdTime> parameter elapses and does not generate an event.
<EventCollectControlTime>
To define <EventCollectControlTime>, enter the time (an int value), in milliseconds, for a device to complete a reading cycle for the tags of a pallet or container before starting a new reading cycle. When this time elapses, the reading cycle concludes (that is, the device has read all of the new tags) and the Pallet Shelf Filter then generates an event.
The Pallet Shelf Filter generates two events:
MULTIPLE IN FIELD Event
The Pallet Shelf Filter generates the MULTIPLE IN FIELD event when the device first detects the tags. This event has the following signature (described in Table 3-7).
Table 3-7 Signature of the MULTIPLE IN FIELD Event
| Event Field | Value |
|---|---|
|
sourceName |
This field identifies the originator of the event. This is an optional field. |
|
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 sent back by the client has the same ID. This is an optional field. |
|
siteName |
The name of the site that generated this event. |
|
deviceName |
The name of the device reading the pallet or container that generated this event. |
|
time |
The time that the Pallet Shelf Filter generated this event. |
|
type |
Event.OBSERVATION |
|
subtype |
Event.MULTIPLE_INFIELD |
|
id |
A comma-separated list of tag IDs. |
|
data |
A comma-separated list of datum. |
MULTIPLE OUT FIELD Event
The Pallet Shelf Filter generates the MULTIPLE OUT FIELD event when the interval defined for the <ExitEventThresholdTime> parameter elapses. This event has the following signature (described in Table 3-8):
Table 3-8 Signature of the MULTIPLE OUT FIELD Event
| Event Field | Value |
|---|---|
|
sourceName |
This field identifies the originator of the event. This is an optional field. |
|
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 sent back by the client has the same ID. This is an optional field. |
|
siteName |
The name of the site generating this event. |
|
deviceName |
The name of the device reading the pallet or container that generated this event. |
|
time |
The time that the Pallet Shelf Filter generated this event. |
|
type |
Event.OBSERVATION |
|
subtype |
Event.MULTIPLE_OUTFIELD |
|
id |
A comma-separated list of Tag IDs. |
|
data |
A comma-separated list of datum. |
Filter instances enable events to be filtered for both devices and device groups. To enable filtering, you create a filter instance from a filter object defined in the edgeserver.xml file's <FilterList> element (Example 3-1). You define these filter instances (that is, the <FilterInsts> tags) within the <DeviceGroups> elements of edgeserver.xml (illustrated in Example 3-2).
To create a filter instance:
Within the <DeviceGroups>, locate the <Device> to which to add the filter instance.
Add a <FilterInst> element to the device's <FilterInsts> section.
For the <Extension> element, specify the name of the filter for the class attribute, and the id of the filter for the reference attribute.
Set the <ParameterInsts> to match the attribute values set for the filter's <Parameters> element.
Save edgeserver.xml and then restart the Oracle Sensor Edge Server. For more information on starting and stopping the Oracle Sensor Edge Server, refer to Section 1.3.
|
Note: You define device-level filters using the<FilterInsts> tag of the <Device> element. You define device group-level filters using the <Filterinsts> tag of the <DeviceGroup> element.
|
You can stack filters together. For example, you can configure a device to first filter out redundant events and then aggregate them with another custom filter. While you can stack both of these filters on top of the same device, you must prioritize these filters, as the order in which the device's filters process events is crucial; the proper filter sequence for the aforementioned device would not first aggregate events and then filter for the redundant events.
The <Sequence> tag within the <FilterInsts> element for a device sets the order in which filters are invoked when a device reads an event. This sequence ranges from 0 to 65535. The filter assigned the lowest value in the sequence is placed closest to the data source (a device or a device group). The filters process the events according to the numbers that you assign to them. After a device reads an event, the filter with the lowest number first processes the event and then passes the output onto the filter assigned to the next number in the sequence.
If two or more filters have the same sequence number, then the order in which the filters process events is random. For example, there are five filters with sequence numbers of 0, 1, 2, 3, 3, 4 set for a device. When the device receives an event, it first passes it to the filter assigned with 0 (Filter 0). Filter 0 processes the event and then passes the output to the next filter, Filter 1, which in turn processes the output from Filter 0 and passes its own output on to Filter 2, which continues the filtering cycle and passes its output to Filter 3. Because the device has two filters that are assigned the same value in the sequence, The Oracle Edge Sensor Server selects one of these filters at random to first process the output generated by Filter 2. When the next Filter 3 completes its task, it passes its output to Filter 4.
Example 3-2 illustrates configuring a device to use a filter instance by defining the <FilterInsts> element. In this example, the PalletPassFilter has a <Sequence> value set at 1.
Example 3-2 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>
