lin-epics-modules/ADAndor
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
2818d4e9fcb2da6ecc87f49758bd97bd5b658ac7
ADAndor/documentation/adscDoc.html
rivers 96e6b24271 Convert to Linux terminators 
git-svn-id: https://subversion.xor.aps.anl.gov/synApps/areaDetector/trunk@7708 dc6c5ff5-0b8b-c028-a01f-ffb33f00fc8b
2008-10-20 16:26:28 +00:00

330 lines
13 KiB
HTML
Raw Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html 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>
September 17, 2008</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. 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>
</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> 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&theta; 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>
Reference in New Issue View Git Blame Copy Permalink