Instrument Data Summaries and Telemetry Subsampling

SIAM instrument services acquire and log all raw data specified by their acquisition schedules. To aid management of limited telemetry bandwidth, an instrument service can be configured such that only every nth raw packet is returned in the telemetry stream; this feature is referred to as telemetry subsampling. The configurable defaultSkipInterval instrument service property specifies the number of "raw" SensorDataPackets to skip when telemetering data. A property value of 0 means to return all raw data for that instrument through the telemetry stream; a value of -1 means that no raw data for the instrument should be retrieved through the telemetry stream.

For example, the following invocation of the setProperty utility specifies that only every 10th raw sample from the instrument on port 3 of the local host should be retrieved via the shore-side portal; as usual, setProperty should always be followed by restartPort:

% setProperty localhost 3 defaultSkipInterval=10
% restartPort localhost 3

Note that defaultSkipInterval is applied only to the telemetry stream; the instrument service continues to save all raw samples to its device log. Telemetry filtering can be manipulated further with the getfilter, clearfilter, and setfilter utilities.

In addition, some services can be configured to "summarize" as well as log their raw data, and to return only these summaries in the telemetry stream. Summaries are "moving", in the sense that as a new raw data sample is acquired by a service and added to the data set used in computing the summary, the oldest sample is dropped from the data set Note that not all services can generate summaries, and you currently must have a priori knowledge of which services can summarize. Moreover each instrument service may implement a different summarization algorithm; "moving averaging" is common, but other techniques can be implemented by the service developer.

The following configurable service properties specify the frequency of summarization:

summaryTriggerCount Generate summary packet after this many raw samples are
                    acquired; width of the moving summary "window".

maxSummarySamples   Generate summary packet and initialize contents of the
                    moving summary "window" when this many raw samples
                    are acquired

Note that in almost all cases, NO raw instrument data should be retrieved through the service's telemetry stream when summarization is enabled; thus you must set the service's defaultSkipInterval property to -1.

For example, the following invocation of the setProperty utility specifies that for the service on port 3 of the local host, summary packets should be generated for every 36 samples, and that NO raw data should be retrieved by the shore-side portal:

% setProperty localhost 3 summaryTriggerCount=36 maxSummarySamples=36 defaultSkipInterval=-1

KNOWN BUGS

Setting summarization properties with the setProperty utility followed by restartPort does NOT currently work as expected, i.e. the new summarization properties do not take effect. For the new properties to take effect, you should use setProperty to set the values as in the above example, then invoke the cachePort utility, then terminate the service with the shutdownPort utility, and finally invoke scanPort to restart the service.

SEE ALSO

 Instrument Service Properties