diff --git a/documentation/adsc-screenshot.png b/documentation/adsc-screenshot.png new file mode 100644 index 0000000..4547cd2 Binary files /dev/null and b/documentation/adsc-screenshot.png differ diff --git a/documentation/adscDoc.html b/documentation/adscDoc.html new file mode 100644 index 0000000..3ba5cbb --- /dev/null +++ b/documentation/adscDoc.html @@ -0,0 +1,342 @@ + + + +areaDetector ADSC driver + + + + +

areaDetector ADSC driver

+ +

Table of Contents

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

Introduction

+ +

+This is a driver for ADSC detectors. +It has been tested with the ADSC Q210. While not yet tested with other +models, it should work with the ADSC Q4 (with the upgrade to four computers), +Q4r, Q210, Q210r, Q270, Q315, and Q315r. +

+ +

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. +
  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. +
  3. Add DIRS += adscSrc to ADApp/Makefile
    4. +
  4. Set ADSC_HOME in ADApp/adscSrc/Makefile
    5. +
  5. Rebuild the areaDetector module
    6. +
+ +

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

+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

+ + + + +