areaDetector Photon II driver

July 15, 2017

Mark Rivers

University of Chicago

Table of Contents


This is an EPICS areaDetector driver for the Photon II detector from Bruker.

The interface to the detector is via a TCP/IP socket interface to the p2util program that Bruker provides. p2util is a standard Linux command line program. In order to provide a socket interface it is run with the procServ program. The procServ program must be installed on the Linux computer that is running the detector. The following "start_p2util" script is useful for running p2util under procServ.

    /usr/local/bin/procServ --noautorestart --logstamp -n "p2util_procServ" -L /home/bruker/logs/p2util.log 20000 /home/bruker/p2util/p2util
    telnet localhost 20000 

This script assums that procServ was installed in /usr/local/bin, that a directory /home/bruker/logs has been created to store the procServ log file, and that the p2util program is in /home/bruker/p2util. It assigns TCP port 20000 to connect to the p2util program. Any number of simultaneous connections are allowed. Typically there is at least one local telnet connection to provide interactive control of p2util. The Photon II areaDetector driver also connects to port 20000 to issue commands and read responses from p2util.

The p2util program saves the data to disk as raw image files with no header. The areaDetector software reads these disk files in order to read the data, because p2util 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 Photon II detector. The Photon II class documentation describes this class in detail.

Implementation of standard driver parameters

The following table describes how the Photon II 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 Photon II are:
  • Normal (corrected for ADC0, dark, and flat field)
  • Dark (corrected for ADC0; NOT YET IMPLEMENTED)
  • ADC0 (uncorrected; NOT YET IMPLEMENTED)
NDFileFormat $(P)$(R)FileFormat Photon II only supports RAW files.

Photon II specific parameters

The Photon II driver implements the following parameters in addition to those in asynNDArrayDriver.h and ADDriver.h..

Parameter Definitions in PhotonII.cpp and EPICS Record Definitions in PhotonII.template
Parameter index variable asyn interface Access Description drvInfo string EPICS record name EPICS record type
PII_DRSumEnable asynInt32 r/w Flag to control whether the DR Summation mode is enabled. If it is enabled then p2util will change from NDR Integration mode to DR Summation mode when the AcquireTime is 1.0 seconds or less. PII_DRSUM_ENABLE $(P)$(R)DRSumEnable
PII_NumDarks asynInt32 r/w The number of dark frames to acquire when FrameType=Dark or ADC0. (NOT YET IMPLEMENTED) PII_NUM_DARKS $(P)$(R)NumDarks
PII_TriggerType asynInt32 r/w The trigger type. Choices are Step and Continuous. In Step mode each trigger results in a single frame. In Continuous mode trigger results in NumImages frames. PII_TRIGGER_TYPE $(P)$(R)TriggerType
PII_TriggerEdge asynInt32 r/w The trigger Edge. Choices are Rising and Falling, which controls which edge of the trigger pulse is used. PII_TRIGGER_EDGE $(P)$(R)TriggerEdge
PII_NumSubFrames asynInt32 r/w Number of sub-frames per frame. Increasing this number reduces the chance that a sub-frame will have saturated pixels. However, this comes at the expense of increased read noise. Thus it is generally best to set this number to the smallest value that will not result in any saturated pixels. In NDR mode each subframe requires a minimum of 1 non-destructive read and 1 destructive read per subframe. The minimum time per subframe is thus 1/(2*70)=28.5 ms. So if the exposure time is 1 second the maximum number of sub-frames/frame is 35, and if the exposure time is 2 seconds it is 70 sub-frames/frame. In practice we observe data read errors from p2util when these values are used, but 33 subframes in 1 second and 62 subframes in 2 seconds appears to work.
Note that this driver always runs p2util in auto mode, so the number of sub-sub-frames per sub-frame is set automatically by p2util.
N/A N/A N/A asyn record to control debugging communication with p2util program N/A $(P)$(R)PIIAsyn asyn

Unsupported standard driver parameters

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


Prior to starting the EPICS IOC the p2util program must be started under procServ as described above.

The Photon II driver is created with the PhotonIIConfig command, either from C/C++ or from the EPICS IOC shell.

int PhotonIIConfig(const char *portName, const char *commandPort,
                 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 PhotonIIConfig function in the PhotonII.cpp documentation and in the documentation for the constructor for the PhotonII class.

The Photon II driver defines an additional iocsh command which is used to pass p2util commands directly from the iocsh shell.

int p2util(const char *portName, const char *command)

The portName argument is the name of the PhotonII port created with the drvAsynIPPortConfigure command previously in the startup script. The command argument is the p2util command to execute. If the command contains any spaces, which it typically will, then the entire command must be enclosed in quotes. This command is typically used to send the command to load an initilization script (e.g. prep_collection.cmd) to p2util right after the PhotonIIConfig command. This ensures that p2util is in a known state before starting the IOC. This is an example:

p2util("PII", "load --commands --filename "/home/bruker/p2util/scripts/prep_collection.cmd")

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

MEDM screens

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

PhotonII.adl is the screen used to control the Photon II driver.




The following are some current restrictions of the Photon II driver: