Name

filters

Synopsis

Utilities for managing instrument service "telemetry filters".

Description

The getfilter, setfilter, and clearfilter utilities are used to manage telemetry filters associated with an instrument service's data stream.

The filters are decimation filters, which allow you to send every nth packet of the data stream. They may be applied separately to different types of packets (data, metadata, message, summary) or to all packets in the data stream.

Filters are used when a telemetry retriever such as portal or getPackets requests packets from an instrument service. The service decimates (sub-samples) the number of packets returned, returning only every nth packet.

The filters are expressed as a skip interval, i.e., the number of packets to skip. For example, a filter value of 3 would indicate that every 4th sample should be sent.

Note that the filters displayed by getfilter will be applied by the service sequentially. E.g. in the above below, "filter 0" passes all packets of all types, but "filter 1" will subsequently remove all sensor data and message packets.

Note: there is currently no way to persist telemetry filter values across service restarts besides the defaultSkipInterval property.

Filter Utilities

There are a number of utilities for using telemetry filters:

The following table describes the utilities and their use. The options are described in greater detail in a separate table below.

Name Use Syntax Description
getfilter
getfilter nodeURL deviceID
Returns a listing of filters set for the specified deviceID
setfilter
setfilter nodeURL -types <types> -skip <interval> deviceID
Set filter values for an instrument service
clearfilter
Remove filters from the specified instrument service
Remove all filters from an instrument service's data stream.

Options

Option Description Values
nodeURL IP address or host name of SIAM node e.g. 134.89.88.1, mooring.moos.mbari.org
deviceID

long (64-bit) integer uniquely identifying the instrument service

filter utilities use deviceIDs instead of instrument ports to specify an instrument
14533,997,1003, etc.
-types

Indicates what types of packets to apply the filter to. Multiple values should be separated by spaces

Valid values are 'data', 'message', 'summary','metadata' or 'all'

-skip

Set skip interval (sub-sampling modulus) filter value.

valid values are integers greater than or equal to -1.

A value of -1 means skip all packets (don't return any packets of the specified type).

A value of 0 (zero) means skip no packets (return all packets of the specified type).

Example output:

					
					% clearfilter surface 1101
					% setfilter -types data message -skip -1 1101
					
					A subsequent invocation of getfilter shows:
					
					% getfilter localhost 1101
					SIAM version $Name:  $
					filter 0: types: SensorData Metadata DeviceMessage Summary : skip 0
					filter 1: types: SensorData DeviceMessage : skip -1
					
					Note that the filters displayed by getfilter will be applied by the service sequentially. 
					E.g. in the above example, "filter 0" passes all packets of all types, but "filter 1" will 
					subsequently remove all sensor data and message packets.
					

Environment

The following environment variables must be set:

Variable Description Example
JAVA_HOME location of Java installation
/j9, /opt/java/jdk1.3.1, etc.
JAVA Path to JVM command For MMC
$JAVA_HOME/bin/j9

For Sun JVM (e.g. linux, win32, mac OS)
$JAVA_HOME/bin/java
SIAM_HOME top of the SIAM directory tree -
SIAM_CLASSPATH Path including all SIAM and supporting classes For MMC
$JAVA_HOME/lib/jclMax/classes.zip:$JAVA_HOME/lib/prsnlmot.jar:$JAVA_HOME/lib/RXTXcomm.jar:$SIAM_HOME/classes

For linux/win32
$SIAM_HOME/classes

See Also

summaries and telemetry sub-sampling