areaDetector Plugins

October 1, 2012

Mark Rivers

University of Chicago

Contents

Overview

A powerful feature of the areaDetector module is the concept of plugins. A plugin is code that is called by a driver that passes NDArray data in a callback. Plugins can be used to process array data in real time. Existing plugins convert data to standard asyn arrays (NDPluginStdArrays), save data to disk (NDPluginFile), select regions-of-interest (NDPluginROI), and convert color modes (NDPluginColorConvert). New plugins could be written to perform functions like finding the centroid of a beam, etc. Once a plugin is written it will work with any areaDetector driver. Plugins have the the following properties:

NDPluginDriver

NDPluginDriver inherits from asynNDArrayDriver. NDPluginDriver is the class from which actual plugins are directly derived. The NDPluginDriver class handles most of the details of processing NDArray callbacks from the driver. Plugins derived from this class typically need to implement the processCallbacks method, and one or more of the write(Int32, Float64, Octet) methods. The NDPluginDriver class documentation describes this class in detail.

NDPluginDriver defines parameters that all plugin drivers should implement if possible. These parameters are defined by strings (drvInfo strings in asyn) with an associated asyn interface, and access (read-only or read-write). The EPICS database NDPluginBase.template provides access to these standard plugin parameters, listed in the following table. Note that to reduce the width of this table the parameter index variable names have been split into 2 lines, but these are just a single name, for example NDPluginDriverArrayPort.

Parameter Definitions in NDPluginDriver.h and EPICS Record Definitions in NDPluginBase.template
Parameter index variable asyn interface Access Description drvInfo string EPICS record name EPICS record type
Information about this plugin
NDPortNameSelf asynOctet r/o asyn port name PORT_NAME_SELF $(P)$(R)PortName_RBV stringin
NDPluginDriver
PluginType
asynOctet r/o A string describing the plugin type. PLUGIN_TYPE $(P)$(R)PluginType_RBV stringin
asyn NDArray driver doing callbacks
NDPluginDriver
ArrayPort
asynOctet r/w asyn port name for NDArray driver that will make callbacks to this plugin. This port can be changed at run time, connecting the plugin to a different NDArray driver. NDARRAY_PORT $(P)$(R)NDArrayPort
(P)$(R)NDArrayPort_RBV
stringout
stringin
NDPluginDriver
ArrayAddr
asynInt32 r/w asyn port address for NDArray driver that will make callbacks to this plugin. This address can be changed at run time, connecting the plugin to a different address in the NDArray driver. NDARRAY_ADDR $(P)$(R)NDArrayAddress
$(P)$(R)NDArrayAddress_RBV
longout
longin
Queue size and status
NDPluginDriver
QueueSize
asynInt32 r/o The total queue size for callbacks when BlockingCallbacks=0. QUEUE_SIZE $(P)$(R)QueueSize longin
NDPluginDriver
QueueFree
asynInt32 r/o The number of free queue elements. QUEUE_FREE $(P)$(R)QueueFree longin
NDPluginDriver
QueueUse
N/A r/o The number of used queue elements. N/A $(P)$(R)QueueUse calc
NDArray pool size and status (only for plugins that generate NDArrays for use by other plugins)
NDPool
MaxMemory
asynFloat64 r/o The maximum amount of NDArrayPool memory this plugin is allowed to allocate. POOL_MAX_MEMORY $(P)$(R)PoolMaxMem ai
NDPool
UsedMemory
asynFloat64 r/o The actual amount of NDArrayPool memory this plugin is currently using. POOL_USED_MEMORY $(P)$(R)PoolUsedMem ai
NDPool
MaxBuffers
asynInt32 r/o The maximum number of NDArrays this plugin is allowed to allocate. POOL_MAX_BUFFERS $(P)$(R)PoolMaxBuffers longin
NDPool
AllocBuffers
asynInt32 r/o The number of NDArrays this plugin has currently allocated. POOL_ALLOC_BUFFERS $(P)$(R)PoolAllocBuffers longin
NDPool
FreeBuffers
asynInt32 r/o The number of free NDArrays this plugin has in its NDArrayPool. POOL_FREE_BUFFERS $(P)$(R)PoolFreeBuffers longin
N/A N.A N/A The number of used NDArrays this plugin has in its NDArrayPool. Calculated from PoolAllocBuffers and PoolFreeBuffers. N/A $(P)$(R)PoolUsedBuffers calc
Callback enable, minimum time, and statistics
NDPluginDriver
EnableCallbacks
asynInt32 r/w Enable (1) or disable (0) callbacks from the driver to this plugin. If callbacks are disabled then the plugin will normally be idle and consume no CPU resources. ENABLE_CALLBACKS $(P)$(R)EnableCallbacks
$(P)$(R)EnableCallbacks_RBV
bo
bi
NDPluginDriver
BlockingCallbacks
asynInt32 r/w 0 = callbacks from the driver do not block; the NDArray data is put on a queue and the callback processes in its own thread.
1 = callbacks from the driver block; the callback processes in the driver callback thread.
BLOCKING_CALLBACKS $(P)$(R)BlockingCallbacks
$(P)$(R)BlockingCallbacks_RBV
bo
bi
NDPluginDriver
MinCallbackTime
asynFloat64 r/w The minimum time in seconds between calls to processCallbacks. Any callbacks occuring before this minimum time has elapsed will be ignored. 0 means no minimum time, i.e. process all callbacks. MIN_CALLBACK_TIME $(P)$(R)MinCallbackTime
$(P)$(R)MinCallbackTime_RBV
ao
ai
NDPluginDriver
ArrayCounter
asynInt32 r/w Counter that increments by 1 each time an NDArray callback is processed ARRAY_COUNTER $(P)$(R)ArrayCounter
$(P)$(R)ArrayCounter_RBV
longout
longin
N/A N/A r/o Rate (Hz) at which ArrayCounter is incrementing. Computed in database. N/A $(P)$(R)ArrayRate_RBV calc
NDPluginDriver
DroppedArrays
asynInt32 r/w Counter that increments by 1 each time an NDArray callback occurs when NDPluginDriverBlockingCallbacks=0 and the plugin driver queue is full, so the callback cannot be processed. DROPPED_ARRAYS $(P)$(R)DroppedArrays
$(P)$(R)DroppedArrays_RBV
longout
longin
Information about last NDArray callback data
NDPluginDriver
NDimensions
asynInt32 r/o Number of dimensions in last NDArray callback data ARRAY_NDIMENSIONS $(P)$(R)NDimensions_RBV longin
NDPluginDriver
Dimensions
asynInt32Array r/o Dimensions in last NDArray callback data ARRAY_DIMENSIONS $(P)$(R)Dimensions_RBV waveform
N/A N/A r/o First dimension of NDArray callback data N/A $(P)$(R)ArraySize0_RBV longin
N/A N/A r/o Second dimension of NDArray callback data N/A $(P)$(R)ArraySize1_RBV longin
N/A N/A r/o Third dimension of NDArray callback data N/A $(P)$(R)ArraySize2_RBV longin
NDPluginDriver
DataType
asynInt32 r/o Data type of last NDArray callback data (NDDataType_t). DATA_TYPE $(P)$(R)DataType_RBV mbbi
NDPluginDriver
ColorMode
asynInt32 r/o Color mode of last NDArray callback data (NDColorMode_t). COLOR_MODE $(P)$(R)ColorMode_RBV mbbi
NDPluginDriver
BayerPattern
asynInt32 r/o BayerPattern of last NDArray callback data (NDBayerPattern_t). BAYER_PATTERN $(P)$(R)BayerPattern_RBV mbbi
NDPluginDriver
UniqueId
asynInt32 r/o Unique ID number of last NDArray callback data UNIQUE_ID $(P)$(R)UniqueId_RBV longin
NDPluginDriver
TimeStamp
asynFloat64 r/o Time stamp number of last NDArray callback data TIME_STAMP $(P)$(R)TimeStamp_RBV ai
Array attributes
NDAttributesFile asynOctet r/w The name of an XML file defining the PVAttributes and paramAttributes to be added to each NDArray by this plugin. The format of the XML file is described in the documentation for asynNDArrayDriver::readNDAttributesFile(). ND_ATTRIBUTES_FILE $(P)$(R)NDAttributesFile waveform
Debugging control
N/A N/A N/A asyn record to control debugging (asynTrace) N/A $(P)$(R)AsynIO asyn

Guidelines and rules for plugins

The following are guidelines and rules for writing plugins

commonPlugins.cmd

The areaDetector iocBoot directory contains a file called commonPlugins.cmd. This file is loaded by all of the example driver IOC startup scripts. It loads a set of plugins which are typically useful for detectors IOCs. Each detector medm screen has links to related displays for each of the common plugins. While this set of plugins is often useful and sufficient, users are free to add or remove plugins from this set for their own IOCs. New medm displays will typically need to be created if that is done, to have the required links to related displays.

The following medm screen shows the status of all of the common plugins at a glance, with links to bring up the detailed screen for each.

commonPlugins.adl

commonPlugins.png