areaDetector ADSC driver

August 9, 2011

Lewis Muir

University of Chicago

Table of Contents

  1. Introduction
  2. Dependencies
  3. Building
  4. Configuring
  5. Image Modes
  6. Trigger Modes
  7. Dark Images
  8. Driver Specific Values and Settings
  9. Screenshots
  10. Unsupported areaDetector base Features
  11. Limitations

Introduction

This is an EPICS areaDetector driver for ADSC detectors. Supported models are: Q4 (with the upgrade to four computers), Q4r, Q210, Q210r, Q270, Q315, and Q315r. This driver has been tested with the Q210 and Q210r. If you use this driver, please report your success, noting your detector model, to the author.

Dependencies

This driver controls the detector via the detcon_lib_th detector control library provided by ADSC. The detcon_lib_th library must date from 2008-06-30 or newer.

Building

By default, this driver is built against a simulated control library. To build against the ADSC detcon_lib_th control library to control a real detector, follow these steps:

  1. Build the ADSC auxlib library provided by ADSC
  2. Build the ADSC detcon_lib_th library provided by ADSC
  3. Copy and rename, or create a symlink to, the ADSC auxlib.a library so that it has the name libauxlib.a to satisfy the EPICS build facility's requirement that a library file name start with lib
  4. Set USE_SIMADSC to NO in ADApp/adscSrc/Makefile
  5. Set ADSC_HOME in ADApp/adscSrc/Makefile
  6. Rebuild the areaDetector module

Configuring

This driver is configured via the adscConfig() function. If this is to be used in an IOC, it must be called before iocInit(). It has the following signature:

int adscConfig(const char *portName, const char *modelName)
portName
ASYN port name for the driver instance
modelName
ADSC detector model name; must be one of Q4, Q4r, Q210, Q210r, Q270, Q315, Q315r

The underlying ADSC control library obtains its configuration from the environment. Therefore, the environment must be correctly configured (i.e. ADSC environment variables set) for the ADSC control library before calling adscConfig().

If being used in an IOC, and an EPICS PV interface with the driver is desired, the ADBase.template, NDFile.template, and adsc.template databases should also be loaded for the driver instance.

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

Image Modes

Single

The Single mode acquires just one image.

Multiple

The Multiple mode acquires the number of images specified in $(P)$(R)NumImages_RBV.

Continuous

The Continuous mode acquires images indefinitely until last image is set. In this mode, the last image of the acquisition must be signaled before exposing the last image by setting $(P)$(R)ADSCLastImage to 1. This requirement is due to how the underlying ADSC control library works.

Trigger Modes

Internal

The Internal mode will make the driver expose images on its own once the acquisition is started.

Ext. Software

The Ext. Software mode will make the driver expose images only when told to once the acquisition is started. A special protocol must be followed to trigger each image exposure. This would normally be very simple, but because the ADSC control library can report that an exposure did not work and should be retried after any exposure, a more complex protocol is required.

The protocol is described in terms of the EPICS PV driver interface, but the same rules apply if controlling the driver directly through ASYN. The protocol is as follows:

  1. Wait for $(P)$(R)ExSwTrOkToExp to be Yes
  2. Set $(P)$(R)ExSwTrCtl to Start to start the exposure
  3. Set $(P)$(R)ExSwTrCtl to Stop to stop the exposure
  4. Wait for $(P)$(R)ExSwTrCtlRsp to be OK or Again
  5. If $(P)$(R)ExSwTrCtlRsp is Again, the exposure did not work and should be tried again

Note that care must be taken when waiting for $(P)$(R)ExSwTrCtlRsp to be OK or Again to ensure the PV value is not stale (i.e. from the previous exposure). There are at least two methods to ensure this:

Dark Images

Dark images are acquired automatically at the beginning of a data acquisition. They are taken if any of the following conditions are true:

Driver Specific Values and Settings

This driver provides status values and settings in addition to what is provided by areaDetector base. They are listed here according to their label in the driver specific MEDM GUI and their EPICS PV name in the EPICS PV driver interface. A screenshot of the driver specific MEDM GUI can be seen in the Screenshots section.

Detector Condition

State, $(P)$(R)ADSCState
State of the detector reported by the ADSC control library.
Status, $(P)$(R)ADSCStatus
Status message reported by the ADSC control library.
Last error, $(P)$(R)ADSCLastError
Last error message reported by the ADSC control library.
Update rate for above properties, $(P)$(R)ADSCReadConditn.SCAN
How frequently to update the above properties.

Detector Error Recovery

Software Reset, $(P)$(R)ADSCSoftReset
Performs a software reset. Aborts any current operation, clears status and error messages, and sets detector state to Idle.

Detector Continuous Image Mode

Last Image, $(P)$(R)ADSCLastImage
Signals that the next exposure is the last image when in Continuous image mode.

Detector External Software Trigger

OK to expose, $(P)$(R)ExSwTrOkToExp
When in Ext. Software trigger mode, indicates whether it is OK to start an image exposure.
Start, Stop, $(P)$(R)ExSwTrCtl
When in Ext. Software trigger mode, set to 1 to start an exposure, and set to 0 to stop it.
$(P)$(R)ExSwTrCtlRsp
When in Ext. Software trigger mode, will be Start, Stop, OK, or Again. See Trigger Modes section for more about how this property will behave.

Driver Parameters

Reuse darks, $(P)$(R)ADSCReusDrk
Reuse dark images when possible. This is useful to avoid wasting time acquiring dark images when previously acquired dark images are available and can be reused.
Dezinger, $(P)$(R)ADSCDezingr
Acquire dezingered images.

Detector Hardware Parameters

ADC/Binning, $(P)$(R)ADSCAdc
For Q4 and Q4r detectors, controls whether to use Fast or Slow ADC. For all other detectors, controls whether to use Hardware or Software binning.
Raw images, $(P)$(R)ADSCRaw
Write raw images.
Image transforms, $(P)$(R)ADSCImXform
Perform image transformations.
Stored darks, $(P)$(R)ADSCStrDrks
Use stored dark images. If set to Yes, stored dark images are assumed to have been installed by ADSC and should be used.

Detector File Parameters

Beam center X, $(P)$(R)ADSCBeamX
Beam center in the X dimension.
Beam center Y, $(P)$(R)ADSCBeamY
Beam center in the Y dimension.
Distance, $(P)$(R)ADSCDistnce
Detector distance.
Two theta, $(P)$(R)ADSC2Theta
Detector 2θ angle.
Axis, $(P)$(R)ADSCAxis
Crystal rotation axis.
Wavelength, $(P)$(R)ADSCWavelen
X-ray wavelength.
Image width, $(P)$(R)ADSCImWidth
Crystal rotation during exposure.
Phi, $(P)$(R)ADSCPhi
Phi position at start of exposure.
Omega, $(P)$(R)ADSCOmega
Omega position at start of exposure.
Kappa, $(P)$(R)ADSCKappa
Kappa position at start of exposure.

Screenshots

Unsupported areaDetector base Features

Limitations