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 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.
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.
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.
The asynMotorController base class defines the following methods:
asynMotorController(const char *portName, int numAxes, int numParams, int
interfaceMask, int interruptMask, int asynFlags, int autoConnect, int priority,
int stackSize)
portName
numAxes
numParams
interfaceMask
interruptMask
asynFlags
autoConnect
priority
stackSize
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.
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:
|
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.
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 |
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.
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.