# areaDetector Plugin NDPluginAttribute

## March 8, 2014

## Matt Pearson, Oak Ridge National Lab

## Mark Rivers, University of Chicago

## Contents

- Overview
- Configuration
- Screen shots

## Overview

This plugin provides the ability to extract an NDArray attributes and publish their values over channel access. It also publishes arrays of the attribute values, and the integrated values.

Each NDPluginAttribute plugin supports any number of attributes, each publishing the last attribute value, the sum of that attribute value since the last reset, and a time-series array of the attribute value. The number of attributes is defined when the NDPluginAttribute is created in the startup script. Each attribute is referenced by its asyn "addr" address field.

In addition to the actual NDAttributes attached to the NDArray this plugin supports 4 virtual attributes. These correspond to properties of all NDArray objects. These virtual attribute names can use used in the $(P)$(R)AttrName record to select that NDArray property.

Virtual attribute name | NDArray property
--- | ---
NDArrayUniqueId | NDArray.uniqueId
NDArrayTimeStamp | NDArray.timeStamp
NDArrayEpicsTSSec | NDArray.epicsTS.secPastEpoch
NDArrayEpicsTSnSec | NDArray.epicsTS.nsec

The time-series arrays use the same PVs to control acquisition as the NDPluginStats plugin. Acquisition of arrays for all attributes are started an stopped at the same time.

NDPluginAttribute inherits from NDPluginDriver. The NDPluginAttribute class documentation describes this class in detail.

NDPluginAttribute defines the following parameters. It also implements all of the standard plugin parameters from NDPluginDriver.

Parameter Definitions in NDPluginAttribute.h and EPICS Record Definitions in NDAttribute.template
Parameter index variable | asyn interface | Access | Description | drvInfo string | EPICS record name | EPICS record type
--- | --- | --- | --- | --- | --- | ---
NDPluginAttribute Reset | asynInt32 | r/w | Reset the plugin data. This zeros the array, and resets the value sum and value to zero. | ATTR_RESET | $(P)$(R)Reset | bo
NDPluginAttribute TSControl | asynInt32 | r/w | Controls time-series data collection. The enum choices are: Erase/Start: Clears all time-series arrays, sets TSCurrentPoint=0, and starts time-series data collection. Start: Starts time-series data collection without clearing arrays or modifying TSCurrentPoint. Used to restart collection after a Stop operation. Stop: Stops times-series data collection. Performs callbacks on all time-series waveform records. Read: Performs callbacks on all time-series waveform records, updating the values. | ATTR_TS_CONTROL | $(P)$(R)TSControl | mbbo
N.A. | N.A. | r/w | Sends the "Read" command to the TSControl record above. This record can be periodically processed to update the time-series waveform records. It is scan disabled if TSAcquiring=Done, so that updates are only performed when time-series acquisition is in progress. | N.A. | $(P)$(R)TSRead | longout
NDPluginAttribute 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. | ATTR_TS_NUM_POINTS | $(P)$(R)TSNumPoints | longout
NDPluginAttribute TSCurrentPoint | asynInt32 | r/o | The current time-series point. If TSCurrentPoint reaches TSNumPoints then time-series acquisition is automatically stopped, and callbacks are done on all time-series waveform records, updating the values. This means that even if TSRead has SCAN=Passive that the waveform records will update when time-series acquisition is complete. | ATTR_TS_CURRENT_POINT | $(P)$(R)TSCurrentPoint | longin
NDPluginAttribute TSAcquiring | asynInt32 | r/o | Indicates status of time-series data acquisition. Values are 0=Done and 1=Acquiring. | ATTR_TS_ACQUIRING | $(P)$(R)TSAcquiring | bi
Parameter Definitions in NDPluginAttribute.h and EPICS Record Definitions in NDAttributeN.template. There is one of these records for each attribute in the plugin.
Parameter index variable | asyn interface | Access | Description | drvInfo string | EPICS record name | EPICS record type
NDPluginAttributeAttrName | asynOctet | r/w | The name of the NDAttribute parameter that we want to publish. This can be modified at runtime. | ATTR_ATTRNAME | $(P)$(R)AttrName $(P)$(R)AttrName_RBV | waveform
NDPluginAttributeVal | asynFloat64 | r/o | Attribute value | ATTR_VAL | $(P)$(R)Value_RBV | ai
NDPluginAttributeValSum | asynFloat64 | r/o | Sum of the attribute value, since the last reset. | ATTR_VAL_SUM | $(P)$(R)ValueSum_RBV | ai
NDPluginAttributeTSArrayValue | asynFloat64Array | r/o | Attribute data as a 1-D array, possibly converted in data type from that in the NDArray attribute to epicsFloat64. | ATTR_TS_ARRAY_VALUE | $(P)$(R)TSArrayValue | waveform

If the array data contains more than 16K bytes then in order for EPICS clients to receive this data they must be built with EPICS R3.14 (not R3.13), and the environment variable EPICS_CA_MAX_ARRAY_BYTES on both the EPICS IOC computer and EPICS client computer must be set to a value at least as large as the array size in bytes.

## Configuration

The NDPluginAttribute plugin is created with the NDAttrConfigure command, either from C/C++ or from the EPICS IOC shell.

    NDAttrConfigure(const char *portName, int queueSize, int blockingCallbacks,
                          const char *NDArrayPort, int NDArrayAddr, int maxAttributes,
                          int maxBuffers, size_t maxMemory, int priority, int stackSize)

All arguments except maxAttributes are common to all plugins. maxAttributes defines the maximum number of attributes that this plugin will support.

For details on the meaning of the parameters to this function refer to the detailed documentation on the NDAttrConfigure function in the NDPluginAttribute.cpp documentation and in the documentation for the constructor for the NDPluginAttribute class.

## Screen shots

The following is the MEDM screen that provides access to the parameters in NDPluginDriver.h and NDPluginAttribute.h through records in NDPluginBase.template and NDAttribute.template.

### NDPluginAttribute.adl

The following is the MEDM screen that provides control and display of the parameters for 8 attributes.

### NDPluginAttribute8.adl

The following is the MEDM screen that displays the time-series data for each attribute. The first screen shows a plot of NDArrayUniqueID and the second shows NDArrayEpicsTSnSec.

### NDTimeSeries.adl

## Notes

- The plugin only supports epicsFloat64 type NDAttribute data at the moment. Any data of other numeric types will be converted. String attributes are not supported.