areaDetector ADSC driver

September 17, 2008

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 a 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

  1. Build the ADSC control library
  2. 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
  3. Add DIRS += adscSrc to ADApp/Makefile
  4. Set ADSC_HOME in ADApp/adscSrc/Makefile
  5. 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 and adsc.template databases should also be loaded for the driver instance.

An example IOC configuration for this driver is at iocBoot/iocAdsc/st.cmd.

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.

External

The External 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)ADSCOkToExpose to be Yes
  2. Set $(P)$(R)ADSCExTrCtl to Start to start the exposure
  3. Set $(P)$(R)ADSCExTrCtl to Stop to stop the exposure
  4. Wait for $(P)$(R)ADSCExTrCtl_RBV to be OK or Again
  5. If $(P)$(R)ADSCExTrCtl_RBV is Again, the exposure did not work and should be tried again

Note that care must be taken when waiting for $(P)$(R)ADSCExTrCtl_RBV 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 Trigger

OK to expose, $(P)$(R)ADSCOkToExpose
When in External trigger mode, indicates whether it is OK to start an image exposure.
Start, Stop, $(P)$(R)ADSCExTrCtl
When in External trigger mode, set to 1 to start an exposure and 0 to stop it.
$(P)$(R)ADSCExTrCtl_RBV
When in External 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