c53da15f54
git-svn-id: https://subversion.xor.aps.anl.gov/synApps/areaDetector/trunk@13406 dc6c5ff5-0b8b-c028-a01f-ffb33f00fc8b
337 lines
13 KiB
HTML
337 lines
13 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>areaDetector ADSC driver</title>
|
|
<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
|
|
</head>
|
|
<body>
|
|
<div style="text-align: center">
|
|
<h1>
|
|
areaDetector ADSC driver</h1>
|
|
<h2>
|
|
August 9, 2011</h2>
|
|
<h2>
|
|
Lewis Muir</h2>
|
|
<h2>
|
|
University of Chicago</h2>
|
|
</div>
|
|
<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. 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.
|
|
</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>
|
|
<p>
|
|
By default, this driver is built against a simulated control library. To build against
|
|
the ADSC <tt>detcon_lib_th</tt> control library to control a real detector, follow
|
|
these steps:
|
|
</p>
|
|
<ol>
|
|
<li>Build the ADSC <tt>auxlib</tt> library provided by ADSC</li>
|
|
<li>Build the ADSC <tt>detcon_lib_th</tt> library provided by ADSC</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>Set <tt>USE_SIMADSC</tt> to <tt>NO</tt> in <tt>ADApp/adscSrc/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>
|
|
</dd>
|
|
</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>, <tt>NDFile.template</tt>, and <tt>adsc.template</tt> databases
|
|
should also be loaded for the driver instance.
|
|
</p>
|
|
<p>
|
|
There an example IOC boot directory and startup script (<a href="adsc_st_cmd.html">iocBoot/iocAdsc/st.cmd)</a>
|
|
provided with areaDetector.
|
|
</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>Ext. Software</tt></h3>
|
|
<p>
|
|
The <tt>Ext. Software</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)ExSwTrOkToExp</tt> to be <tt>Yes</tt></li>
|
|
<li>Set <tt>$(P)$(R)ExSwTrCtl</tt> to <tt>Start</tt> to start the exposure</li>
|
|
<li>Set <tt>$(P)$(R)ExSwTrCtl</tt> to <tt>Stop</tt> to stop the exposure</li>
|
|
<li>Wait for <tt>$(P)$(R)ExSwTrCtlRsp</tt> to be <tt>OK</tt> or <tt>Again</tt></li>
|
|
<li>If <tt>$(P)$(R)ExSwTrCtlRsp</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)ExSwTrCtlRsp</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)ExSwTrCtlRsp</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)ExSwTrCtlRsp</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 Software Trigger</h3>
|
|
<dl>
|
|
<dt>OK to expose, <tt>$(P)$(R)ExSwTrOkToExp</tt></dt>
|
|
<dd>
|
|
When in <tt>Ext. Software</tt> trigger mode, indicates whether it is OK to start
|
|
an image exposure.</dd>
|
|
<dt>Start, Stop, <tt>$(P)$(R)ExSwTrCtl</tt></dt>
|
|
<dd>
|
|
When in <tt>Ext. Software</tt> trigger mode, set to <tt>1</tt> to start an exposure,
|
|
and set to <tt>0</tt> to stop it.</dd>
|
|
<dt><tt>$(P)$(R)ExSwTrCtlRsp</tt></dt>
|
|
<dd>
|
|
When in <tt>Ext. Software</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>
|