EPICS Motor Record Device and Driver Support

March 11, 2012

Mark Rivers

University of Chicago

Table of Contents

Introduction

This document describes the device and driver support for the EPICS motors. It briefly describes the older APIs for such support (referred to as Model 1 and Model 2), but focuses mainly on the newer Model 3 API, which is the API which should be used for new motor drivers.

The APIs described here are mainly intended to be used with the EPICS motor record. However the Model 2 and Model 3 drivers are actually independent of the motor record. They implement standard EPICS asyn interfaces, and can in principle be used with any EPICS records, and do not require the motor record. However, the motor record currently provides the only "state machine" logic that keeps track of backlash, enforcing soft limits, etc. Model 2 and 3 drivers to permit access to controller-specific features that the motor record does not support, and this is typicaly implemented using standard EPICS records (ao, ai, bo, bi, etc.)

Model 1 device and driver support

Model 1 is the API that was used for all motor drivers prior to 2006, when Model 2 was introduced. Model 1 drivers have the following characteristics:

Because this API was the only one supported prior to 2006, the majority of existing motor drivers are written using this Model 1 API.

Model 2 device and driver support

Because of the recognized deficiencies in the Model 1 API, in 2006 Diamond Light Source and APS collaborated in developing a new API, now called Model 2. The Model 2 API has the following characteristics:

There are Model 2 drivers in the motor module for the simulation motor, Newport MM4000, Newport XPS, Pro-Dex MAXnet, Attocube ANC150, and Aerotech Ensemble.

Model 3 device and driver support

In 2011 the Model 3 API was introduced. This API is based in part on the ideas and infrastructure that were developed for the areaDetector module. The Model 3 API has the following characteristics:

The Model 3 C++ API is based on the concept of two types of objects: a motor controller and one or motor motor axes. The controller object supports the functions that apply to the entire controller. The controller supports one or more axes. The axis objects support the functions for a specific axis. These objects are implemented in the device-dependent driver. There is a base class for each of these objects, asynMotorControlller and asynMotorAxis.

The asynMotorController base class has methods that handle much of the work in writing a driver, including implementing the asyn interfaces and calling the appropriate methods in the axis classes. A basic motor driver derived class will often only need to implement only the constructor for the controller class, and can just use the base class implementation of all other methods in the asynMotorController class.

The asynMotorAxis base class on the other hand mainly provides dummy methods (asynMotorAxis::move(), asynMotorAxis::stop(), etc.). The main work in writing a Model 3 driver consists of implementing these methods in the derived class.

There are Model 3 drivers in the motor module for the simulation motor, Hytec XXXX, Newport XPS, Parker ACR series controllers (e.g. Aires), and the ACS MCB-4B.

The ACS MCB-4B is the simplest Model 3 driver, consisting of only 336 lines of well-commented C++ code (ACSSrc/MCB4BDriver.h and MCB4BDriver.cpp). It does not implement any controller-specific features, it only implements support for standard motor record features. It is a very good starting point for writing a new driver with basic motor record support.

asynMotorController base class

The asynMotorController base class defines the following methods:

asynMotorAxis base class

The asynMotorAxis base class defines the following methods:

This driver inherits from ADDriver. It implements many of the parameters in asynNDArrayDriver.h and in ADArrayDriver.h. It also implements a number of parameters that are specific to the mar345 detector. The mar345 class documentation describes this class in detail.

Implementation of standard driver parameters

The following table describes how the mar345 driver implements some of the standard driver parameters.

Implementation of Parameters in asynNDArrayDriver.h and ADDriver.h, and EPICS Record Definitions in ADBase.template and NDFile.template
Parameter index variable EPICS record name Description
ADAcquire $(P)$(R)Acquire Setting this to 1 starts an acquisition sequence. If ADNumImages is greater than 1 then it acquires multiple frames. For each frame it does the following:
  1. Erases the detector if mar345EraseMode is "Before expose".
  2. Opens the shutter if either the mar345 shutter or EPICS shutter controls are enabled.
  3. Waits for the desired exposure time.
  4. Closes the shutter if either the mar345 shutter or EPICS shutter controls are enabled.
  5. Scans the detector and saves the file.
  6. Erases the detector if mar345EraseMode is "After scan".
If ADAcquire is set to 0 during exposure (step 3 above) then it proceeds immediately to step 4, finishes collecting the current frame and stops the acquisition sequence if ADNumImages is greater than 1. If mar345Abort is set to 0 then the acquisition is terminated as soon as possible without saving the data. Note however that commands to the mar345 server to erase, change mode, or scan cannot be aborted, so the driver must wait for these commands to complete.

It is useful to use NDPluginROI to define an ROI containing the entire mar345 detector. The MaxValue_RBV PV in this ROI can be monitored to make sure that the 16-bit limit of 65,535 is not being approached in any pixel.

mar345 specific parameters

The mar345 driver implements the following parameters in addition to those in asynNDArrayDriver.h and ADDriver.h. 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 mar345ScanSize.

Parameter Definitions in mar345.cpp and EPICS Record Definitions in mar345.template
Parameter index variable asyn interface Access Description drvInfo string EPICS record name EPICS record type
Readout parameters
mar345
ScanSize
asynInt32 r/w The detector diameter to read out. Choices are 180mm, 240mm, 300mm, and 345mm. MAR_SIZE $(P)$(R)ScanSize
$(P)$(R)ScanSize_RBV
mbbo
mbbi
mar345
ScanResolution
asynInt32 r/w The pixel size to use when reading the detector out. Choices are 0.10 and 0.15mm. MAR_RESOLUTION $(P)$(R)ScanResolution
$(P)$(R)ScanResolution_RBV
mbbo
mbbi

Configuration

The mar345 driver is created with the mar345Config command, either from C/C++ or from the EPICS IOC shell.

int mar345Config(const char *portName, const char *serverPort,
                 int maxBuffers, size_t maxMemory,
                 int priority, int stackSize)
  

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

There an example IOC boot directory and startup script (iocBoot/iocMAR345/st.cmd) provided with areaDetector.

MEDM screens

The following show the MEDM screens that are used to control the mar345 detector. Note that the general purpose screen ADBase.adl can be used, but it exposes many controls that are not applicable to the mar345, and lacks some fields that are important for the mar345.

mar345.adl is the main screen used to control the mar345 driver.

mar345.adl

mar345.png