NDPluginTimeSeries.adl
This plugin accepts 1-D arrays of dimension [NumSignals] or 2-D arrays of dimension [NumSignals, NewTimePoints]. The plugin creates NumSignals NDArrays of dimension [NumTimePoints], each of which is the time-series for one signal. It also creates an NDArray of dimension [NumTimePoints, NumSignals] containing the data for all of the signals. It also exports waveform records containing the time-series data for each signal, and a time-axis array containing the relative times of each point in the time-series. These waveform records are useful for plotting in OPI screens.
On each callback the new time points are appended to the existing time series arrays. The plugin can operate either two modes. In fixed time mode the time-series arrays are cleared when acquisition is started, and new time points are appended until NumTimePoints points have been received, at which point acquisition stops and further callbacks are ignored. In circular buffer mode once NumTimePoints samples are received then acquisition continues with the new time points replacing the oldest ones in the circular buffer.
The plugin requires knowing the time interval between samples from the driver (TimePerPoint). This information normally comes from a database link to a record in the detector driver, but it can be manually specified as well. The plugin exports a 1-D waveform record containing the relative time values of each sample, which can be used for the horizontal axis in an OPI display.
The plugin optionally does time averaging of the input signal. It can average any integer number of input samples(NumAverage), so that the time between points in the output waveforms is NumAverage*TimePerPoint = AveragingTime.
NDPluginTimeSeries inherits from NDPluginDriver. The NDPluginTimeSeries class documentation describes this class in detail.
Several database template files are provided:
| Template File Name | Description |
|---|---|
| NDTimeSeries.template | This needs to be instantiated once for each instance of the plugin. It provides records that apply to the entire plugin or to all signals. |
| NDTimeSeriesN.template | This needs to be instantiated once for each signal in the plugin (the number must equal the number of signals specified in the IOC shell function). The template provides records that apply to each signal. |
NDPluginTimeSeries inherits from NDPluginDriver.
NDPluginTimeSeries defines the following parameters. It also implements all of the standard plugin parameters from NDPluginDriver. The template files listed above provide access to these parameters, listed in the following tables.
|
Parameters for entire plugin.
Parameter Definitions in NDPluginTimeSeries.h and EPICS Record Definitions in NDTimeSeries.template |
||||||
| Parameter index variable | asyn interface | Access | Description | drvInfo string | EPICS record name | EPICS record type |
|---|---|---|---|---|---|---|
| TSAcquire | asynInt32 | r/w |
Starts and stops time-series data collection. Value are:
0: "Done": Stops times-series data collection. Performs callbacks on all time-series waveform records. The record automatically goes to Done when acquisition completes in Fixed Length acquire mode. 1: "Acquire": Clears all time-series arrays, sets TS_CURRENT_POINT=0, and starts time-series data collection. |
TS_ACQUIRE |
$(P)$(R)TSAcquire $(P)$(R)TSAcquiring |
busy bi |
| TSRead | asynInt32 | r/w | Forces the plugin to do callbacks with the time series NDArrays and waveform records. This record SCAN field can be set to periodically update the waveforms. The callbacks are automatically done when TSAcquire goes to done at the end of acquisition in Fixed Length mode. | TS_READ | $(P)$(R)TSRead | bo |
| TSNumPoints | asynInt32 | r/w | Controls the number of time-series points to collect. There is no maximum value, the time-series arrays in the plugin are freed and reallocated each time this value is changed. However, the size of the waveform records is fixed when the IOC is started, so NELM in those records must be large enough for the largest time-series needed. | TS_NUM_POINTS | $(P)$(R)TSNumPoints | longout |
| TSCurrentPoint | asynInt32 | r/o | The current time-series point. In Fixed Length mode when TSCurrentPoint reaches TSNumPoints then time-series acquisition is automatically stopped, and callbacks are done on all time-series NDArrays and waveform records, updating the values. This means that even if TSRead.SCAN is Passive that the NDArrays and waveform records will update when time-series acquisition is complete. | TS_CURRENT_POINT | $(P)$(R)TSCurrentPoint | longin |
| TSAcquireMode | asynInt32 | r/w |
The time series acquisition mode. Choices are: 0: "Fixed length" 1: "Circ. buffer" |
TS_ACQUIRE_MODE |
$(P)$(R)TSAcquireMode $(P)$(R)TSAcquireMode_RBV |
mbbo
mbbi |
| TSTimePerPoint | asynFloat64 | r/w | The time interval between samples in the waveforms from the driver. This value is normally updated automatically using the TSTimePerPointLink record described below. It can also be manually changed if there is no EPICS record available to provide this value automatically. This value is used to compute NumAverage, and to construct the TSTimeAxis array. | TS_TIME_PER_POINT |
$(P)$(R)TSTimePerPoint $(P)$(R)TSTimePerPoint_RBV |
ao ai |
| N.A | N.A. | r/w | This record has OMSL="closed_loop" and DOL set to a record that contains the time between points from the driver. The link will normally have the CP attribute, so this record processes whenever the input record changes. The OUT field of this record is TSTimePerPoint. | N.A. | $(P)$(R)TSTimePerPointLink | ao |
| TSAveragingTime | asynFloat64 | r/w | The requested value of the time interval over which input time-series points are averaged. If the TSAveragingTime is not an integer multiple of TSTimePerPoint then TSAveragingTime_RBV will be different from TSAveragingTime and will be the actual averaging time. | TS_AVERAGING_TIME |
$(P)$(R)TSAveragingTime $(P)$(R)TSAveragingTime_RBV |
ao ai |
| TSNumAverage | asynInt32 | r/o | The number of time points from the driver that will be averaged in the plugin. This is computed from TSAveragingTime/TSTimePerPoint. It is constrained to be the nearest positive integer to this ratio. | TS_NUM_AVERAGE | $(P)$(R)TSNumAverage | longin |
| TSElapsedTime | asynFloat64 | r/w | The elapsed time since TSAcquire was set to 1. Stops updating when TSAcquire goes to 0. | TS_ELAPSED_TIME | $(P)$(R)TSElapsedTime | ai |
| TSTimeAxis | asynFloat64ArrayIn | r/o |
A waveform record containing the time value of each point in the TimeSeries waveforms. When AcquireMode="Fixed length" then time=0 is the time when acquisition started and TSTimeAxis[i] = TSAveragingTime_RBV * i.
When AcquireMode="Circ. buffer" then time=0 is the most recent time and TSTimeAxis[i] = -TSAveragingTime_RBV * (NumTimePoints-1-i)so the oldest time point is the most negative. |
TS_TIME_AXIS | $(P)$(R)TSTimeAxis | waveform |
| TSTimeStamp | asynFloat64ArrayIn | r/o | A waveform record containing the NDArray timestamp for each sample from the input NDArray. Note that since multiple time points can be contained in a single NDArray there can be repeated values in this waveform. Assuming the driver provides a reliable value for TSTimePerPoint described above, then the TSTimeAxis waveform provides a more accurate relative time array to use in plotting. The values in this waveform are absolute timestamps which can also be useful. | TS_TIMESTAMP | $(P)$(R)TSTimestamp | waveform |
|
Parameters for each signal N.
Parameter Definitions in NDPluginTimeSeries.h and EPICS Record Definitions in NDTimeSeriesN.template |
||||||
| Parameter index variable | asyn interface | Access | Description | drvInfo string | EPICS record name | EPICS record type |
|---|---|---|---|---|---|---|
| TSSignalName | N.A. | r/w | The name for this signal. | N.A. | $(P)$(R)SignalName | stringout |
| TSTimeSeries | asynFloat64ArrayIn | r/o | The time series data arrays. | TS_TIME_SERIES | $(P)$(R)TimeSeries | waveform |
The NDPluginTimeSeries plugin is created with the NDTimeSeriesConfigure function, either from C/C++ or from the EPICS IOC shell.
NDTimeSeriesConfigure(const char *portName, int queueSize, int blockingCallbacks,
const char *NDArrayPort, int NDArrayAddr, int maxSignals,
int maxBuffers, size_t maxMemory, int priority, int stackSize)
All but the maxSignals parameter are common to all plugins.
maxSignals defines how many signals this plugin will deal with. Usually this will match the number of NDTimeSeriesN templates have been loaded.
For example:
NDTimeSeriesConfigure("TS1", 100, 0, "DET1", 0, 8, 0, 0, 0, 0)
The following MEDM screen provides access to the parameters in NDPluginDriver.h and NDPluginTimeSeries.h through records in NDPluginBase.template, and NDTimeSeries.template.
The following MEDM screen shows the time series plot for an array in NDPluginTimeSeriesN.template.
