291dd4a8f4
git-svn-id: https://subversion.xor.aps.anl.gov/synApps/areaDetector/trunk@7492 dc6c5ff5-0b8b-c028-a01f-ffb33f00fc8b
343 lines
11 KiB
HTML
343 lines
11 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
<html lang="en-us">
|
|
<head>
|
|
<title>areaDetector ADSC driver</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
</head>
|
|
<body>
|
|
|
|
<h1>areaDetector ADSC driver</h1>
|
|
|
|
<h2>Table of Contents</h2>
|
|
<ol>
|
|
<li><a href="#Introduction">Introduction</a></li>
|
|
<li><a href="#Dependencies">Dependencies</a></li>
|
|
<li><a href="#Building">Building</a></li>
|
|
<li><a href="#Configuring">Configuring</a></li>
|
|
<li><a href="#ImageModes">Image Modes</a></li>
|
|
<li><a href="#TriggerModes">Trigger Modes</a></li>
|
|
<li><a href="#DarkImages">Dark Images</a></li>
|
|
<li><a href="#ValuesAndSettings">Driver Specific Values and Settings</a></li>
|
|
<li><a href="#Screenshots">Screenshots</a></li>
|
|
<li><a href="#Unsupported">Unsupported <tt>areaDetector</tt> <q>base</q>
|
|
Features</a></li>
|
|
<li><a href="#Limitations">Limitations</a></li>
|
|
</ol>
|
|
|
|
<h2 id="Introduction">Introduction</h2>
|
|
|
|
<p>
|
|
This is a driver for <a href="http://www.adsc-xray.com/">ADSC</a> 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.
|
|
</p>
|
|
|
|
<h2 id="Dependencies">Dependencies</h2>
|
|
|
|
<p>
|
|
This driver controls the detector via the <tt>detcon_lib_th</tt> detector
|
|
control library provided by ADSC. The <tt>detcon_lib_th</tt> library must
|
|
date from 2008-06-30 or newer.
|
|
</p>
|
|
|
|
<h2 id="Building">Building</h2>
|
|
|
|
<ol>
|
|
<li>Build the ADSC control library</li>
|
|
<li>Copy and rename, or create a symlink to, the ADSC <tt>auxlib.a</tt>
|
|
library so that it has the name <tt>libauxlib.a</tt> to satisfy the EPICS
|
|
build facility's requirement that a library file name start with
|
|
<q><tt>lib</tt></q></li>
|
|
<li>Add <q><tt>DIRS += adscSrc</tt></q> to <tt>ADApp/Makefile</tt></li>
|
|
<li>Set <tt>ADSC_HOME</tt> in <tt>ADApp/adscSrc/Makefile</tt></li>
|
|
<li>Rebuild the <tt>areaDetector</tt> module</li>
|
|
</ol>
|
|
|
|
<h2 id="Configuring">Configuring</h2>
|
|
|
|
<p>
|
|
This driver is configured via the <tt>adscConfig()</tt> function. If this is
|
|
to be used in an IOC, it must be called before <tt>iocInit()</tt>. It has the
|
|
following signature:
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><tt>int adscConfig(const char *portName, const char *modelName)</tt></dt>
|
|
<dd>
|
|
<dl>
|
|
<dt><tt>portName</tt></dt>
|
|
<dd>ASYN port name for the driver instance</dd>
|
|
<dt><tt>modelName</tt></dt>
|
|
<dd>ADSC detector model name; must be one of <tt>Q4</tt>, <tt>Q4r</tt>,
|
|
<tt>Q210</tt>, <tt>Q210r</tt>, <tt>Q270</tt>, <tt>Q315</tt>,
|
|
<tt>Q315r</tt></dd>
|
|
</dl>
|
|
</dl>
|
|
|
|
<p>
|
|
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
|
|
<tt>adscConfig()</tt>.
|
|
</p>
|
|
|
|
<p>
|
|
If being used in an IOC, and an EPICS PV interface with the driver is desired,
|
|
the <tt>ADBase.template</tt> and <tt>adsc.template</tt> databases should also
|
|
be loaded for the driver instance.
|
|
</p>
|
|
|
|
<p>
|
|
An example IOC configuration for this driver is at
|
|
<tt>iocBoot/iocAdsc/st.cmd</tt>.
|
|
</p>
|
|
|
|
<h2 id="ImageModes">Image Modes</h2>
|
|
|
|
<h3><tt>Single</tt></h3>
|
|
|
|
<p>
|
|
The <tt>Single</tt> mode acquires just one image.
|
|
</p>
|
|
|
|
<h3><tt>Multiple</tt></h3>
|
|
|
|
<p>
|
|
The <tt>Multiple</tt> mode acquires the number of images specified in
|
|
<tt>$(P)$(R)NumImages_RBV</tt>.
|
|
</p>
|
|
|
|
<h3><tt>Continuous</tt></h3>
|
|
|
|
<p>
|
|
The <tt>Continuous</tt> mode acquires images indefinitely until <em>last
|
|
image</em> is set. In this mode, the last image of the acquisition must be
|
|
signaled before exposing the last image by setting
|
|
<tt>$(P)$(R)ADSCLastImage</tt> to <tt>1</tt>. This requirement is due to how
|
|
the underlying ADSC control library works.
|
|
</p>
|
|
|
|
<h2 id="TriggerModes">Trigger Modes</h2>
|
|
|
|
<h3><tt>Internal</tt></h3>
|
|
|
|
<p>
|
|
The <tt>Internal</tt> mode will make the driver expose images on its own once
|
|
the acquisition is started.
|
|
</p>
|
|
|
|
<h3><tt>External</tt></h3>
|
|
|
|
<p>
|
|
The <tt>External</tt> 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.
|
|
</p>
|
|
|
|
<p>
|
|
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:
|
|
</p>
|
|
|
|
<ol>
|
|
<li>Wait for <tt>$(P)$(R)ADSCOkToExpose</tt> to be <tt>Yes</tt></li>
|
|
<li>Set <tt>$(P)$(R)ADSCExTrCtl</tt> to <tt>Start</tt> to start the
|
|
exposure</li>
|
|
<li>Set <tt>$(P)$(R)ADSCExTrCtl</tt> to <tt>Stop</tt> to stop the
|
|
exposure</li>
|
|
<li>Wait for <tt>$(P)$(R)ADSCExTrCtl_RBV</tt> to be <tt>OK</tt> or
|
|
<tt>Again</tt></li>
|
|
<li>If <tt>$(P)$(R)ADSCExTrCtl_RBV</tt> is <tt>Again</tt>, the exposure did
|
|
not work and should be tried again</li>
|
|
</ol>
|
|
|
|
<p>
|
|
Note that care must be taken when waiting for <tt>$(P)$(R)ADSCExTrCtl_RBV</tt>
|
|
to be <tt>OK</tt> or <tt>Again</tt> to ensure the PV value is not stale (i.e.
|
|
from the previous exposure). There are at least two methods to ensure this:
|
|
</p>
|
|
|
|
<ul>
|
|
<li>Use a CA monitor on <tt>$(P)$(R)ADSCExTrCtl_RBV</tt>; before waiting for
|
|
the <tt>OK</tt> or <tt>Again</tt> values, wait for the <tt>Stop</tt> value; a
|
|
CA monitor is used to receive the value changes since the PV will have the
|
|
<tt>Stop</tt> value for just a short time</li>
|
|
<li>After starting the exposure, wait for <tt>$(P)$(R)ADSCExTrCtl_RBV</tt> to
|
|
be <tt>Start</tt></li>
|
|
</ul>
|
|
|
|
<h2 id="DarkImages">Dark Images</h2>
|
|
|
|
<p>
|
|
Dark images are acquired automatically at the beginning of a data acquisition.
|
|
They are taken if any of the following conditions are true:
|
|
</p>
|
|
|
|
<ul>
|
|
<li><em>Reuse darks</em> is <tt>No</tt></li>
|
|
<li><em>Exposure time</em> is different from that of the previous
|
|
acquisition</li>
|
|
<li><em>ADC/binning</em> is different from that of the previous
|
|
acquisition</li>
|
|
<li><em>Binning</em> is different from that of the previous acquisition</li>
|
|
<li>The acquisition is the first after <em>stored darks</em> was changed from
|
|
<tt>Yes</tt> to <tt>No</tt></li>
|
|
</ul>
|
|
|
|
<h2 id="ValuesAndSettings">Driver Specific Values and Settings</h2>
|
|
|
|
<p>
|
|
This driver provides status values and settings in addition to what is
|
|
provided by <tt>areaDetector</tt> <q>base</q>. 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 <a href="#Screenshots">Screenshots</a> section.
|
|
</p>
|
|
|
|
<h3>Detector Condition</h3>
|
|
|
|
<dl>
|
|
<dt>State, <tt>$(P)$(R)ADSCState</tt></dt>
|
|
<dd>State of the detector reported by the ADSC control library.</dd>
|
|
<dt>Status, <tt>$(P)$(R)ADSCStatus</tt></dt>
|
|
<dd>Status message reported by the ADSC control library.</dd>
|
|
<dt>Last error, <tt>$(P)$(R)ADSCLastError</tt></dt>
|
|
<dd>Last error message reported by the ADSC control library.</dd>
|
|
<dt>Update rate for above properties,
|
|
<tt>$(P)$(R)ADSCReadConditn.SCAN</tt></dt>
|
|
<dd>How frequently to update the above properties.</dd>
|
|
</dl>
|
|
|
|
<h3>Detector Error Recovery</h3>
|
|
|
|
<dl>
|
|
<dt>Software Reset, <tt>$(P)$(R)ADSCSoftReset</tt></dt>
|
|
<dd>Performs a software reset. Aborts any current operation, clears status
|
|
and error messages, and sets <em>detector state</em> to <tt>Idle</tt>.</dd>
|
|
</dl>
|
|
|
|
<h3>Detector Continuous Image Mode</h3>
|
|
|
|
<dl>
|
|
<dt>Last Image, <tt>$(P)$(R)ADSCLastImage</tt></dt>
|
|
<dd>Signals that the next exposure is the last image when in
|
|
<tt>Continuous</tt> image mode.</dd>
|
|
</dl>
|
|
|
|
<h3>Detector External Trigger</h3>
|
|
|
|
<dl>
|
|
<dt>OK to expose, <tt>$(P)$(R)ADSCOkToExpose</tt></dt>
|
|
<dd>When in <tt>External</tt> trigger mode, indicates whether it is OK to
|
|
start an image exposure.</dd>
|
|
<dt>Start, Stop, <tt>$(P)$(R)ADSCExTrCtl</tt></dt>
|
|
<dd>When in <tt>External</tt> trigger mode, set to <tt>1</tt> to start an
|
|
exposure and <tt>0</tt> to stop it.</dd>
|
|
<dt><tt>$(P)$(R)ADSCExTrCtl_RBV</tt></dt>
|
|
<dd>When in <tt>External</tt> trigger mode, will be <tt>Start</tt>,
|
|
<tt>Stop</tt>, <tt>OK</tt>, or <tt>Again</tt>. See <a
|
|
href="#TriggerModes">Trigger Modes</a> section for more about how this
|
|
property will behave.</dd>
|
|
</dl>
|
|
|
|
<h3>Driver Parameters</h3>
|
|
|
|
<dl>
|
|
<dt>Reuse darks, <tt>$(P)$(R)ADSCReusDrk</tt></dt>
|
|
<dd>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.</dd>
|
|
<dt>Dezinger, <tt>$(P)$(R)ADSCDezingr</tt></dt>
|
|
<dd>Acquire <q>dezingered</q> images.</dd>
|
|
</dl>
|
|
|
|
<h3>Detector Hardware Parameters</h3>
|
|
|
|
<dl>
|
|
<dt>ADC/Binning, <tt>$(P)$(R)ADSCAdc</tt></dt>
|
|
<dd>For Q4 and Q4r detectors, controls whether to use <tt>Fast</tt> or
|
|
<tt>Slow</tt> ADC. For all other detectors, controls whether to use
|
|
<tt>Hardware</tt> or <tt>Software</tt> binning.</dd>
|
|
<dt>Raw images, <tt>$(P)$(R)ADSCRaw</tt></dt>
|
|
<dd>Write raw images.</dd>
|
|
<dt>Image transforms, <tt>$(P)$(R)ADSCImXform</tt></dt>
|
|
<dd>Perform image transformations.</dd>
|
|
<dt>Stored darks, <tt>$(P)$(R)ADSCStrDrks</tt></dt>
|
|
<dd>Use stored dark images. If set to <tt>Yes</tt>, stored dark images are
|
|
assumed to have been installed by ADSC and should be used.</dd>
|
|
</dl>
|
|
|
|
<h3>Detector File Parameters</h3>
|
|
|
|
<dl>
|
|
<dt>Beam center X, <tt>$(P)$(R)ADSCBeamX</tt></dt>
|
|
<dd>Beam center in the X dimension.</dd>
|
|
<dt>Beam center Y, <tt>$(P)$(R)ADSCBeamY</tt></dt>
|
|
<dd>Beam center in the Y dimension.</dd>
|
|
<dt>Distance, <tt>$(P)$(R)ADSCDistnce</tt></dt>
|
|
<dd>Detector distance.</dd>
|
|
<dt>Two theta, <tt>$(P)$(R)ADSC2Theta</tt></dt>
|
|
<dd>Detector 2θ angle.</dd>
|
|
<dt>Axis, <tt>$(P)$(R)ADSCAxis</tt></dt>
|
|
<dd>Crystal rotation axis.</dd>
|
|
<dt>Wavelength, <tt>$(P)$(R)ADSCWavelen</tt></dt>
|
|
<dd>X-ray wavelength.</dd>
|
|
<dt>Image width, <tt>$(P)$(R)ADSCImWidth</tt></dt>
|
|
<dd>Crystal rotation during exposure.</dd>
|
|
<dt>Phi, <tt>$(P)$(R)ADSCPhi</tt></dt>
|
|
<dd>Phi position at start of exposure.</dd>
|
|
<dt>Omega, <tt>$(P)$(R)ADSCOmega</tt></dt>
|
|
<dd>Omega position at start of exposure.</dd>
|
|
<dt>Kappa, <tt>$(P)$(R)ADSCKappa</tt></dt>
|
|
<dd>Kappa position at start of exposure.</dd>
|
|
</dl>
|
|
|
|
<h2 id="Screenshots">Screenshots</h2>
|
|
|
|
<ul>
|
|
<li><a href="adsc-screenshot.png">ADSC Specific MEDM GUI</a></li>
|
|
</ul>
|
|
|
|
<h2 id="Unsupported">Unsupported <tt>areaDetector</tt> <q>base</q>
|
|
Features</h2>
|
|
|
|
<ul>
|
|
<li>Shutter control</li>
|
|
<li>Collect: number of exposures per image</li>
|
|
<li>File: save file</li>
|
|
<li>File: read file</li>
|
|
<li>File: format</li>
|
|
<li>File: auto save (always <tt>Yes</tt>)</li>
|
|
<li>Readout: image region of interest</li>
|
|
<li>Readout: reverse image</li>
|
|
<li>Readout: gain</li>
|
|
<li>Readout: data type (always <tt>UInt16</tt>)</li>
|
|
<li>Image frame callbacks</li>
|
|
</ul>
|
|
|
|
<h2 id="Limitations">Limitations</h2>
|
|
|
|
<ul>
|
|
<li>Only one ADSC detector may be controlled with this driver per OS process.
|
|
If this driver is being used in an IOC, this means only one ADSC detector may
|
|
be controlled with this driver per IOC. This is a limitation of the
|
|
underlying ADSC control library which does not support more than one detector
|
|
per OS process.</li>
|
|
<li>Acquiring <q>dezingered</q> images is not supported. This is a limitation
|
|
of the underlying ADSC control library which has a bug preventing it from
|
|
working correctly.</li>
|
|
<li><em>Software reset</em> does not work. This is a limitation of the
|
|
underlying ADSC control library which has a bug preventing it from working
|
|
correctly. It would be great if, after an error, performing a software reset
|
|
would allow a new acquisition to proceed normally. Currently, the recovery
|
|
solution often is to restart the control software.</li>
|
|
</ul>
|
|
|
|
</body>
|
|
</html>
|