areaDetector MarCCD driver

March 4, 2014

Mark Rivers

University of Chicago

Table of Contents


This is an EPICS areaDetector driver for the Rayonix (formerly MarCCD) detectors from Rayonix/MarUSA.

The interface to the detector is via a TCP/IP socket interface to the marccd_server_socket server that Rayonix provides. The marccd_server_socket program must be started before the areaDetector software is started, by running the marccd program and executing Acquire/Remote Control/Start.

marccd must be using Version 1 (for non-HS detectors) or 2 (for HS detectors) of the remote protocol. This is normally done done by editing the file marccd/configuration/marccd.conf and replacing the line

include marccd_server_v0.conf


include marccd_server_v1.conf

The file marccd_server_v1.conf should contain the lines:

remote_mode_server_command /home/marccd/contrib/marccd_server/marccd_server_socket
remote_mode_server_arguments 2222

The first line points to the location of the marccd_server_socket program that is used to implement remote control. In order to work with the areaDetector driver this must be a version of this program created after November 11, 2008 when support for the get_frameshift command was added. A recent version of this program can be downloaded from the Rayonix FTP site.

The marccd program saves the data to disk as TIFF files. The areaDetector software reads these disk files in order to read the data, because marccd does not provide another mechanism to access the data.

This driver inherits from ADDriver. It implements many of the parameters in asynNDArrayDriver.h and in ADArrayDriver.h. It also implements a number of parameters that are specific to the MarCCD detectors. The marCCD class documentation describes this class in detail.

Implementation of standard driver parameters

The following table describes how the MarCCD driver implements some of the standard driver parameters.

Implementation of Parameters in asynNDArrayDriver.h and ADDriver.h, and EPICS Record Definitions in ADBase.template and NDFile.template
Parameter index variable EPICS record name Description
ADFrameType $(P)$(R)FrameType The driver redefines the choices for the ADFrameType parameter (record $(P)$(R)FrameType) from ADDriver.h. The choices for the MarCCD are:
  • Normal (corrected data frame without double correlation)
  • Background (background frame with 0 exposure time, done with double correlation to remove zingers)
  • Raw (data frame without correction for background or spatial distortion)
  • DblCorrelation (two images each collected for half the nominal acquisition time, zingers removed by double correlation)
ADImageMode $(P)$(R)ImageMode The driver redefines the choices for the ADImageMode parameter (record $(P)$(R)ImageMode) from ADDriver.h.
  • "Single" (aingle frame acquisition)
  • "Multiple" (acquire ADNumImages images)
  • "Continuous" (acquire images continuously until ADAcquire is set to 0)
  • "Series triggered" (acquire a series of images using an external trigger signal)
  • "Series timed" (acquire a series of images using the internal clock)
"Series triggered" and "Series timed" are only supported for ServerMode=2 servers.
ADTriggerMode $(P)$(R)TriggerMode The driver redefines the choices for the ADTriggerMode parameter (record $(P)$(R)TriggerMode) from ADDriver.h.
  • Internal (Single frame acquisition)
  • Frame (rising edge causes frame transfer/readout and start of next acquisition)
  • Bulb (rising edge of trigger starts acquisition, falling edge causes frame transfer/readout)
  • Timed (rising edge of trigger causes frame transfer/readout and each exposure lasts for time ADAcquireTime)
ServerMode=1 servers only support "Internal", ServerMode=2 servers support all 4 modes.
ADNumImages $(P)$(R)NumImages Controls the number of images to acquire when ADImageMode is ADImageMultiple.
ADAcquirePeriod $(P)$(R)AcquirePeriod Controls the period between images when ADImageMode is ADImageMultiple or ADImageContinuous. If this is greater than the acquisition time plus readout overhead then the driver will wait until the period has elapsed before starting the next acquisition.
ADReadStatus $(P)$(R)ReadStatus Writing 1 to this parameter causes the status to be read from the marccd server. By processing or periodically scanning this record the status information can be refreshed. This is normally not necessary, but if ADArrayCallbacks is 0 and marCCDOverlap is 1 then the status will not indicate that the system is idle when acquisition is complete, because the driver polling stops before the file is written. This record can be used to eliminate the confusion that might cause.
NDFilePath $(P)$(R)FilePath Controls the path for saving images. It must be a valid path for marccd and for the areaDetector driver, which is normally running in an EPICS IOC. If marccd and the EPICS IOC are not running on the same machine then soft links will typically be used to make the paths look identical.
NDFileFormat $(P)$(R)FileFormat marccd only supports TIFF files.

It is useful to use an NDPluginStats plugin set to use the entire marCCD detector. The MaxValue_RBV PV can be monitored to make sure that the 16-bit limit of 65,535 is not being approached in any pixel.

MarCCD specific parameters

The MarCCD driver implements the following parameters in addition to those in asynNDArrayDriver.h and ADDriver.h. Note that to reduce the width of this table the parameter index variable names have been split into 2 lines, but these are just a single name, for example marCCDState.

Parameter Definitions in marccd.cpp and EPICS Record Definitions in marccd.template
Parameter index variable asyn interface Access Description drvInfo string EPICS record name EPICS record type
Status parameters
asynInt32 r/o The version number of the server software running on the detector. This is 1 for the servers running on non-HS detectors, and 2 for the servers running on HS detectors. MAR_SERVER_MODE $(P)$(R)ServerMode_RBV longin
asynInt32 r/o State word returned by marccd server. The low-order 4-bits of this word are the state of the marccd server, and will be Idle (0x0), Error (0x7), or Busy (0x8). The next 24 bits encode the state of the 6 server tasks (Acquire, Readout, Correct, Save, Dezinger, Series) with 4-bits per task. Each task can be in the state Idle (0x0), Queued (0x1), Executing (0x2), Error (0x4), or Reserved (0x8). MAR_STATE $(P)$(R)MarState_RBV longin
asynInt32 r/o Status of the marccd server task (Idle, Error, or Busy) MAR_STATUS $(P)$(R)MarStatus_RBV mbbi
asynInt32 r/o Status of the marccd server acquire task (Idle, Queued, Executing, Error, or Reserved) MAR_ACQUIRE_STATUS $(P)$(R)MarAcquireStatus_RBV mbbi
asynInt32 r/o Status of the marccd server readout task (Idle, Queued, Executing, Error, or Reserved) MAR_READOUT_STATUS $(P)$(R)MarReadoutStatus_RBV mbbi
asynInt32 r/o Status of the marccd server correct task (Idle, Queued, Executing, Error, or Reserved) MAR_CORRECT_STATUS $(P)$(R)MarCorrectStatus_RBV mbbi
asynInt32 r/o Status of the marccd server file writing task (Idle, Queued, Executing, Error, or Reserved) MAR_WRITING_STATUS $(P)$(R)MarWritingStatus_RBV mbbi
asynInt32 r/o Status of the marccd server dezinger task (Idle, Queued, Executing, Error, or Reserved) MAR_DEZINGER_STATUS $(P)$(R)MarDezingerStatus_RBV mbbi
asynInt32 r/o Status of the marccd server series acquisition task (Idle, Queued, Executing, Error, or Reserved). MAR_SERIES_STATUS $(P)$(R)MarSeriesStatus_RBV mbbi
Optimization parameters
asynInt32 r/w The marccd server has 5 tasks (Acquire, Readout, Correct, Write, Dezinger) that can overlap their operation. The areaDetector driver can exploit this to improve performance in some circumstances. If this parameter is set to 1 (Overlap) then the ADAcquire parameter will go to 0 (Done) when the Readout task is done executing, but before the Correct and Write tasks have finished correcting and saving the file to disk. This improves performance because the next image can begin as soon as ADAcquire goes to done, and hence before the previous image is written to disk. Note, however that this parameter must be set to 0 (Sequential) if callbacks are being used to compute statistics that are being used in data collection, e.g. in a scan. If this is not done then the statistics information will be grabbed before it is updated and incorrect scan data will result. MAR_OVERLAP $(P)$(R)OverlapMode
Frameshift parameters
asynInt32 r/w marccd can be used for time-resolved studies by collecting multiple data sets before reading out the detector. This is done by placing a mask in front of the detector that restricts the x-rays to horizontal stripe. An exposure is made, and then an external signal causes the detector to shift the image by the number of lines given by this parameter. A number of images separated by times of a few milliseconds can be collected, and then the detector is read out. Set this parameter to 0 to disable frameshift mode. MAR_FRAME_SHIFT $(P)$(R)FrameShift
Series acquisition parameters (ServerMode=2 only)
asynOctet r/w The template for the file names written in trigger or timed series acquisition modes. The FilePath, FileName and FileNumber are combined into a string using this C format string. This is used to construct a base file name. The actual file names in the series are constructed using this base file name plus the SeriesFileFirst and SeriesFileDigits records. Example: "%s%s_%3.3d" MAR_SERIES_FILE_TEMPLATE $(P)$(R)SeriesFileTemplate
asynInt32 r/w The number of the first file in a triggered or timed series acquisition. MAR_SERIES_FILE_FIRST $(P)$(R)SeriesFileFirst
asynInt32 r/w The number of digits to use for the file numbers in triggered or timed series acquisition. MAR_SERIES_FILE_DIGITS $(P)$(R)SeriesFileDigits
Gating and readout parameters (ServerMode=2 only)
asynInt32 r/w The gating mode for the detector. Choices are:
MAR_GATE_MODE $(P)$(R)GateMode
asynInt32 r/w The readout mode for the detector. Choices are:
"High gain"
"Low noise"
"HDR" (High Dynamic Range)
MAR_GATE_MODE $(P)$(R)GateMode
Baseline stabilization parameters
asynFloat64 r/w The following text is from a document describing baseline stabilization from Rayonix. "Baseline stabilization is an optional addition to the marccd data collection software. This software option stabilizes the baseline offset level of each CCD image to a more accurate value than only the analog electronics provide. This feature is important in any type of measurement that requires comparisons between successive data frames that include, for example, subtracting (or adding) two data frames, such as one often must do in small angle scattering experiments. Baseline instability can make it appear that there are slightly more or slightly less X-rays across the entire detector (or readout channel) in a data frame. That is different than the read noise, which has no net effect on the average. A stable baseline is less critical for data analysis in which a background value is calculated by measuring the background around each individual spot on the same data frame (typically done in single crystal crystallography experiments). The baseline level of a CCD is usually established by measuring an analog voltage of the readout amplifier, and the "zero" level can drift over time due to ambient temperature changes or other electronic instability. The time scale on which the drift occurs is usually greater than about 20 minutes or so; therefore, the marccd software default for recollecting background images is every 20 minutes or once every data segment in a dataset. Expected baseline stability improvement Whereas the older MarCCD detectors had a baseline stability that was only good to about ±1-2 ADU, the SX Series and MX Series detectors have improved electronic baseline stability, closer to ±0.5 ADU. When this Baseline Stabilization software option is used, the baseline can be improved much further, with baseline stability as low as about ±0.01 ADU. CCD overscan The method of improving the baseline is by an overscan technique. When this option is "on", extra blank pixels are read out from the CCD after each line of the CCD is read out from the serial register. In the marccd program memory, a temporary data frame which is larger than the normal data frame is recorded, and the pixels outside the imaging area are used to compute the baseline. These blank pixels do not correspond to any real region of the CCD; they are just a result of telling the readout electronics to readout with no charge present.
The user must also enter a target baseline stability value. This number represents the accuracy to which the program will try to stabilize the baseline, in ADU (analog-to-digital units). The resulting data frame will have a baseline value that is approximately the corrected_frame_bias, typically 10 or 100, plus or minus the target baseline stability value. For example, if the user enters 0.1, and the corrected_frame_bias is 10 (i.e. images with no X-rays normally have a baseline around 10 ADU), then a data frame with X-rays will result in a baseline value of approximately 10 ±0.1 ADU (and each individual pixel will also have contributions due to X-rays and read noise). The accuracy limit of this software feature is about 0.01 ADU, so any target value entered between 0 and 0.01 is automatically converted to the limit, 0.01 ADU. Entering a target value of 0 is equivalent to turning off the baseline stabilization."
MAR_STABILITY $(P)$(R)Stability
Timeout parameters
asynFloat64 r/w Timeout in seconds when reading a TIFF file. It should be set to several seconds, because there it can take some time for the marccd server to write the file. MAR_TIFF_TIMEOUT $(P)$(R)ReadTiffTimeout ao
Ancillary parameters. These parameters are written to the header of the marccd TIFF file.
asynFloat64 r/w Distance from the sample to the detector (mm) MAR_DETECTOR_DISTANCE $(P)$(R)DetectorDistance ao
asynFloat64 r/w X position of the direct beam on the detector (mm) MAR_BEAM_X $(P)$(R)BeamX ao
asynFloat64 r/w Y position of the direct beam on the detector (mm) MAR_BEAM_Y $(P)$(R)BeamY ao
asynFloat64 r/w Starting value of phi rotation (deg) MAR_START_PHI $(P)$(R)StartPhi ao
asynOctet r/w Rotation axis being used (phi, omega, etc.) MAR_ROTATION_AXIS $(P)$(R)RotationAxis stringout
asynFloat64 r/w Rotation range of the rotation axis. MAR_ROTATION_RANGE $(P)$(R)RotationRange ao
asynFloat64 r/w Detector two-theta angle (deg); requires theta axis definition with display name "TwoTheta" in a marccd configuration file (i.e. "theta_display_name TwoTheta"). This configuration file is typically goniostat_none.conf or goniostat_sw.conf, but any configuration file that gets loaded can be used. MAR_TWO_THETA $(P)$(R)TwoTheta ao
asynFloat64 r/w Wavelength in Angstroms. MAR_WAVELENGTH $(P)$(R)Wavelength ao
asynOctet r/w Comments for this file. MAR_FILE_COMMENTS $(P)$(R)FileComments waveform
asynOctet r/w Comments for this dataset. MAR_DATASET_COMMENTS $(P)$(R)DatasetComments waveform
N/A N/A N/A asyn record to control debugging communication with marccd_server_socket program N/A $(P)$(R)marSserverAsyn asyn

Unsupported standard driver parameters

The MarCCD driver does not support the following standard driver parameters because they are not supported in the marccd program:


The marCCD driver is created with the marCCDConfig command, either from C/C++ or from the EPICS IOC shell.

int marCCDConfig(const char *portName, const char *serverPort,
                 int maxBuffers, size_t maxMemory,
                 int priority, int stackSize)

For details on the meaning of the parameters to this function refer to the detailed documentation on the mar345Config function in the marCCD.cpp documentation and in the documentation for the constructor for the marCCD class.

There an example IOC boot directory and startup script (iocBoot/iocMARCCD/st.cmd) provided with areaDetector.

MEDM screens

The following show the MEDM screens that are used to control the MarCCD detector. Note that the general purpose screen ADBase.adl can be used, but it exposes many controls that are not applicable to the MarCCD, and lacks some fields that are important for the MarCCD.

marccd.adl is the main screen used to control the MarCCD driver.



marccdAncillary.adl is the screen used to input ancillary information that is written to the MarCCD TIFF files.



asynRecord.adl is used to control the debugging information printed by the asyn TCP/IP driver (asynTraceIODriver) and the EPICS device support (asynTraceIODevice).



asynOctet.adl can be used to send any command to the marccd remote server and display the response. It can be loaded from the More menu in asynRecord.adl above.



Performance measurements

The following measurements were done to demonstrate the performance that can be obtained with the areaDetector MarCCD driver. These measurements were made with a MAR-165 CCD. The EPICS IOC was running on the same Linux machine as the marccd program. The acquisition time was 1 second.

Binning Image size marCCDOverlap Time for 10 images Overhead per image Time per task
2x2 2048x2048 Sequential 50.0 4.00 Readout: 3.02
Correct: 0.56
Save: 0.20
2x2 2048x2048 Overlap 46.2 3.62 Same
4x4 1024x1024 Sequential 29.0 1.90 Readout: 1.30
Correct: 0.28
Save: 0.06
4x4 1024x1024 Overlap 28.7 1.87 Same
8x8 512x512 Sequential 24.0 1.40 Readout: 0.78
Correct: 0.29
Save: 0.06
8x8 512x512 Overlap 23.6 1.36 Same


The following are some current restrictions of the MarCCD driver: