Dectris PILATUS 300K-W User manual

USER MANUAL
PILATUS Detector Systems
Version 1.4

Table of Contents
1 Document History .........................................................................................3
1.1 Changes.................................................................................................3
2 How to use this Manual.................................................................................4
2.1 Address and support ..............................................................................4
2.2 Explanation of Symbols..........................................................................4
2.3 Convention for Commands.....................................................................5
2.4 Disclaimer...............................................................................................5
3 Warnings.......................................................................................................6
4 System Description.......................................................................................7
4.1 Overview ................................................................................................7
4.2 Hardware................................................................................................7
4.3 Software...............................................................................................11
4.3.1 Overview of TVX ........................................................................12
4.3.2 Overview of Camserver..............................................................12
4.3.3 Description of the File Structure and Configuration Files on the
Pilatus Detector Server...........................................................................13
5 Quick Start Guide........................................................................................14
6 Control the Detector....................................................................................16
6.1 From the Detector Server.....................................................................16
6.2 From a Specific Environment ...............................................................16
6.2.1 Steps to Bring Up a PILATUS Detector in a New Environment..17
6.2.2 Testclients..................................................................................18
7 How to use the Pilatus Detector through Camserver..................................19
7.1 Main Commands ..................................................................................19
7.1.1 Variables....................................................................................20
7.2 Image formats ......................................................................................20
7.3 External Triggering...............................................................................22
7.3.1 Necessary Camserver Time Settings.........................................22
7.3.2 External Trigger Mode................................................................23
7.3.3 External Multi Trigger Mode.......................................................25
7.3.4 External Enable Mode................................................................26
7.3.5 Multiple Exposure Mode.............................................................28
8 Trimming the Detector ................................................................................29
8.1 Principle................................................................................................29
8.2 Simple Trimming Method......................................................................29
8.3 Set the Threshold with more Control....................................................30
9 Bad Pixel Mask and Module Gaps..............................................................32
9.1 Using the Bad Pixel Mask.....................................................................32
9.1.1 Adding new Bad Pixels to the Mask...........................................32
9.1.2 Make a new Bad Pixel Mask from an Uniform Illumination.........33
9.2 Flag the Module Gaps (Only for Multi Module Detectors).....................33
10 Adjust Crystallography Parameters...........................................................34
11 Flat Field Image........................................................................................35
11.1 Using the Flat Field Correction Image in Camserver..........................35
11.2 Creating a new Flat Field Image.........................................................36
11.3 Using the Flat Field Correction Image in TVX ....................................36

12 How to Use the Pilatus Detector through TVX..........................................37
12.1 Description of the Image Display........................................................40
12.2 Analysis commands ...........................................................................44
12.3 Mask files ...........................................................................................45
12.4 User defined commands.....................................................................47
12.5 Glossary files......................................................................................48
12.6 Example .............................................................................................48
13 Factory Calibration and Correction ...........................................................49
14 Camserver Commands.............................................................................51
15 Camserver Test Client..............................................................................62

3
1 Document History
Actual document
Version
Date
status
prepared
checked
released
1.4
01.05.2013
released
PS, BS
MS
SB
1.1 Changes
Version
Date
Changes
1.1
31.08.2007
Various improvements
1.2
06.02.2009
Various improvements
1.2.1
28.09.2010
Various improvements
1.3
23.08.2011
Major revision
1.4
01.05.2013
Various improvements

4
2 How to use this Manual
Before you start to operate the PILATUS detector system please read this
manual thoroughly.
The user manual and the technical specification together form the user
documentation.
2.1 Address and support
DECTRIS Ltd.
Neuenhoferstrasse 107
5400 Baden
Switzerland
Phone: [phone]
Fax: + 41 56 500 21 01
Email: [email protected]
Should you have questions concerning the system or its use, please contact
us via phone, mail or fax.
Do not ship the system Back before you receive the necessary
transport and shipping information!
2.2 Explanation of Symbols
Symbol
Description
Important or helpful notice
Caution. Please follow the instructions carefully to prevent
equipment damage or personal injury.
DC-current
AC-current
Ground

5
2.3 Convention for Commands
Example
Description
cd ..
Shell commands are written in blue and italic
ExpTime
Camserver commands are written italic
disp
TVX commands are written in bold italic
exposem
TVX macros are written in underlined, bold, italic
2.4 Disclaimer
DECTRIS has carefully compiled the contents on this manual according to the
current state of knowledge. Damage and warranty claims arising from missing
or incorrect data are excluded.
DECTRIS bears no responsibility or liability for damage of any kind, also for
indirect or consequential damage resulting from the use of this system.
DECTRIS is the sole owner of all user rights related to the contents of the
manual (in particular information, images or materials), unless otherwise
indicated. Without the written permission of Dectris it is prohibited to integrate
the protected contents published in these applications into other programs or
other Web sites or to use them by any other means.
DECTRIS reserves the right, at its own discretion and without liability or prior
notice, to modify and/or discontinue this application in whole or in part at any
time, and is not obliged to update the contents of the manual.

6
3 Warnings
Please read these warnings before operating the detector
Before turning the power supply on, check the supply voltage against
the label on the power supply. Using an improper main voltage will
destroy the power supply and damage the detector.
Power down the detector system before connecting or disconnecting
any cable.
Make sure the cables are connected and properly secured.
Avoid pressure or tension on the cables.
The air inlets and outlets for the detector fan should not be blocked.
The detector system should have enough space for proper ventilation.
Operating the detector outside the specified ambient conditions could
damage the system.
The detector is not specified to withstand direct beam at a synchrotron.
Such exposure will damage the exposed pixels.
Place the protective cover on the detector when it is not in use.
Opening the detector or the power supply housing without explicit
instructions from DECTRIS will void the warranty.
The Linux operating system, on the DETECTOR SERVER has a
customized Kernel to improve data throughput.
DO NOT UPDATE THE OPERATING SYSTEM OR THE KERNEL
DO NOT TOUCH THE ENTRANCE WINDOW OF THE DETECTOR

7
4 System Description
4.1 Overview
A PILATUS detector system consists of the following components (see also
Figure 1):
Detector
Detector server with a customized Linux operating system, the data
acquisition tool Camserver and the data analysis tool TVX
Power supply (where applicable)
Connecting cables
Figure 1. Overview of the PILATUS detector system setup (Monitor or laptop are not
included).
4.2 Hardware
DECTRIS X-ray detector systems operate in "single photon counting" mode
and are based on the newly developed CMOS hybrid pixel technology. The
main difference with respect to existing detectors is that the X-rays are directly

8
transformed into electric charge (Figure 2) and processed in the CMOS
readout chips. This new design has no dark current or readout noise, a high
dynamic range of 1'048'576 (20 bits), a read-out time of less than 3 ms, a
frame rate of over 300 images/s
*
and an excellent point spread function of 1
pixel. The quantum efficiency of the 0.32 mm thick silicon sensor is optimal for
experiments in the energy range from 3-12 keV; however the detectors can be
used for energies of up to 30 keV or more. The counting rate is greater than
2x106/s/pixel, enough to perform many experiments using the high flux of
modern synchrotron light sources. However, the detector cannot withstand a
direct synchrotron beam.
Figure 2. Principle of direct detection.
A DECTRIS hybrid pixel detector is composed of a silicon sensor, which is a
two-dimensional array of pn-diodes processed in high-resistivity silicon,
connected to an array of readout channels designed with advanced CMOS
technology (Figure 3). Each readout channel is connected to its corresponding
detecting element through a microscopic indium ball, with a typical diameter of
18 m. This connection process is called ‘bump-bonding’.
*
This maximum frame rate is only valid for 100k and 300k systems.

9
Figure 3. The detector module, the basic element of all DECTRIS area detector systems
The great advantage of this approach is that standard technologies are used
for both the silicon sensor and the CMOS readout chips, which guarantees
highest quality. Both processes are optimized separately, as the best silicon
substrates for X-ray detection and for high-speed/high-quality electronics are
very different. Moreover, the small size of the pixel and the interconnection
results in a very low capacitance, which has the beneficial effect of reducing
the noise and power consumption of the pixel readout electronics.
X-ray data collection can be improved with detectors operating in single
photon counting mode. A hybrid pixel which features single photon counting
comprises a charge-sensitive preamplifier (CSA), which amplifies the signal
generated in the sensor by the incoming X-ray, and a comparator (Comp),
which produces a digital signal if the incoming charge exceeds a pre-defined
threshold. The comparator feeds a 20 bit counter, which then leads to
completely digital storage and noiseless readout of the number of detected
X-rays in each pixel (Figure 4).
Figure 4. Design of each pixel. See text for details.

10
The fundamental unit of the DECTRIS detectors, the module, consists of a
single fully depleted monolithic silicon sensor with an 8 x 2 array of CMOS
readout chips bump-bonded to it. Each sensor is a continuous array of 487 x
197 = 94965 pixels without dead areas and covers an active area of 83.8 x
33.5 mm2. The readout chips are wire-bonded to the underlying print which is
glued to the mounting bracket. Together with its readout control electronics
the sensor with readout chips forms the complete module (Figure 3).

11
4.3 Software
The operating software for the PILATUS detector system consists of two
components:
TVX
Data analysis software and control program
Camserver
Operating software for the detector hardware
These two software packages are normally installed on one detector server
and communicate with each other through an internal socket connection.
Data
TVX Camserver Pilatus 100K
PILATUS
TCP/IP
Figure 5. Normal operation with TVX and Camserver on one computer.
It is also possible to operate the detector without TVX and access Camserver
directly via a socket connection from another PC.
Camserver
Data
Pilatus 100K
PILATUS
Interface TCP/IP
Figure 6. Operation with TVX and Camserver on separate computers.
Socket interface

12
4.3.1 Overview of TVX
TVX is a free, open source, data acquisition and control software suite tailored
to X-ray science. TVX is an attempt to provide a flexible user interface that is
easily adapted to control a broad range of 2-D X-ray detectors as well as a
powerful collection of analysis tools.
The suite operates by distributing the tasks of data analysis and hardware
control between two separate programs. The first program, which is referred
to as TVX, contains the user interface and analysis tool suite. The other,
which is referred to as the Camserver, is responsible for controlling the
hardware of the specific data acquisition system. These two programs
communicate over a TCP/IP connection, as shown in Figure 5, and thus do
not need to run on the same machine; see Figure 6.
An added benefit of this model is that it allows the experimenters to do their
analysis wherever and whenever it is most convenient for them, be it at the
beam line while the data are being taken or back at their home institution or
corporation. TVX compiles and operates on Linux. Camserver requires
specific camera hardware for operation.
4.3.2 Overview of Camserver
Camserver is a freestanding program that controls the Pilatus detector and
provides a simple user interface for "atomic" (single function) commands. It is
intended to provide a minimal, but fully functional, low level interface to
camera hardware.
On invocation, Camserver takes a single command-line argument, the path to
its resource file, by default called 'camrc'. Camserver will also use the same
path to open its debugging file, 'camdbg.out'.
A major function of Camserver is to accept socket connections from a high
level controller (e.g., 'TVX'), which can provide high level services to this or
other cameras. The interface is a simple text-based message passing system.
Images - the ultimate product of a working area X-ray detector - do not pass
thruogh the socket interface, but are written to a configurable location (e.g., a
NFS mount) where any program can access them.

13
4.3.3 Description of the File Structure and Configuration Files
on the Pilatus Detector Server
In the default setup, all data necessary for the use of the PILATUS detector
system is in the directory /home/det/p2_det.
Directory
Sub Directory
Description
config
Configuration Data
cam_data
Definitions of the camera / calibrations
calibration
All calibration details including Mask files
camstat
Status of the detector
images
Default image directory
programs
Program code for TVX and Camserver
graphs
Default directory for TVX graphs
correct
Masks for statistical analysis in TVX
docs
Documentation of TVX and Camserver
Important configuration files are listed in the followings table. The directory is
given relative to the default path ~/p2_det/.
File
Directory
Description
camrc
./
configuration file for Camserver
tvxrc
./
configuration file for TVX
camdbg.out
./
Debug file for Camserver
p2det.set
config/cam_data
Startup file for Camserver
default.gl
config
Startup glossary of TVX
det_spec.gl
config
Detector specific parameters for TVX
user.gl
config
User shortcuts for TVX
startup.gl
config
Final startup glossary executing detector self-tests

14
5 Quick Start Guide
Before you turn on the system, make sure you have read this manual, the
technical specification, and set up the detector accordingly.
● Turn on the detector server.
● Log in procedure:
User and password: see additional sheet in your user
documentation
● Open a shell.
● Change to the p2_det directory. All following paths are given relative to this!
cd ~/p2_det 
● Run TVX by typing
./runtvx 
After the initialization (up to 30s) you should get the following screen:
Figure 7. Startup screen after executing runtvx (example for a 100k detector)

15
●The command runtvx is a shell script which starts the programs Camserver
(yellow window on the left side of figure 9) and TVX (yellow window on the
right side of figure 9) as well as manages all log files.
●During startup the detector sets several parameters in the startup scripts
(details in 6.1).
Once two images (green and blue) appear on the screen the detector is ready
to operate. In Figure 7 only one (blue) is visible since it is above the other
(green) one. Both terminals (TVX and Camserver) have their prompt,
indicated by an asterisk symbol (*).
●To operate the detector correctly you
MUST TRIM THE DETECTOR
according to the incoming X-ray radiation. We refer to trimming as the process
of adjusting the settings (voltages and trimbits) of each pixel to the specified
gain and energy (for details see 8). This trimming can be done by the
SetEnergy or the SetThreshold command. These commands trim the detector
to a uniform threshold across the detector surface. The threshold should
generally be set to 50% of the incoming X-ray energy (more details can be
found in section 4.2 and 6.1). If you operate the detector every time at the
same energy (e.g. an X-ray tube with Cu-anode) you can add such a
command at the end of the startup glossary which gets executed during each
start up sequence (for details see 6.1).
For example, if you have a 8.048keV incoming beam, type in the TVX window
(yellow window on the right side in Figure 7) the following command:
cam SetEnergy 8048 
Details on this command can be found in section 8. For a finer control you can
use the SetThreshold command (see section 8.3). For more specific questions
and detailed advice, please contact DECTRIS Ltd. for support. Note that the
SetEnergy command takes a relatively long time. On a large multi module
system it can take up to 2 minutes.
●The detector is now ready for operation.
● To take an image you can type:
expose 10 
in the TVX window, where 10 is the exposure time in seconds.
● Further information:
Details on how to control the detector from a specific environment (e.g. at
a synchrotron) can be found in section 6.2.
Details on how to trigger the detector with an external signal can be found
in section 7.3.
For information concerning the dead pixels and gaps please see section 9.
For image manipulation with TVX please see section 12.

16
6 Control the Detector
6.1 From the Detector Server
The Pilatus detector can be controlled from the delivered detector server. Just
follow the instructions in the Quick Start Guide (Section 5) to start up the
detector.
The runtvx command is a shell script which starts the actual programs:
Camserver and TVX. It also handles the log-files which can be found in the
p2_det directory
During the Camserver startup a connection to the detector is established and
verified.
The TVX startup is carried out via the file called default.gl. This is a so called
glossary file (*.gl), which is a convention used for files which are processed by
TVX.
This default.gl file (stored in "$HOME/p2_det/config) makes several definitions
(short-cuts) which can be used further on in TVX.
For example the exposem command makes an endless loop and writes
images in a temporary file (see also section 12). This is a simple live-view tool
of TVX.
At the end of the startup glossary three more glossaries are called. The first
one (det_spec.gl) loads detector specific parameters such as camera size and
number of modules. The second one (user.gl) is used to enter user short-cuts
once you start to define your own ones. The last one (startup.gl) sets voltages
on the actual X-ray sensitive elements and carries out a test of the digital part
and the analog part of each pixel. The last two tests are done with the TVX
definitions rbd (read back detector) and calibdet, respectively. The results
are shown in a green (digital test with 1000 counts loaded into the counter of
each pixel) and a blue (analog test with 100 simulated pulses fed into each
pixel) image. These two images show up automatically at the end of the
startup procedure and verify the full functionality of the detector.
6.2 From a Specific Environment
In the previous section the stand alone operation is shown. However, often
there is a need to integrate the detector in an existing environment.
The Pilatus detector can be easily integrated into any system. To do this, one
has to send commands through a socket connection to Camserver. Any client
can connect to Camserver via a socket connection, and issue plain text
commands. However, only the first connection will get full control and can
execute commands. All following connections will only have read access. The
command syntax (see section 7) over the socket is identical to the syntax to

17
be typed directly in the Camserver window. Thus, direct typing is helpful for
testing.
The reply from Camserver (acknowledgement) consists of a command index
number, followed by a space and either "OK" or "ERR", followed by another
space and possibly a message. The acknowledgement arrives after the
requested action is completed, typically in 1-2 ms; some commands, such as
SetThreshold, take longer, especially for a big detector. All
acknowledgements end in 0x18 (ASCII 'CAN') without a newline; there may
be internal newlines in long messages. (Since there is no terminating linefeed,
MS Windows sockets must be opened in binary mode; this is not a
consideration for UNIX-like systems.)
Because of the socket connection protocol, the camera hardware and server
can reside on a different machine from the high level controller.
Camserver implements a token mechanism to prevent more than one outside
process from having control over the hardware. The Camserver window has
full control at all times.
There is a debug facility to help with setting up the interface. If you type
"dbglvl 5", the file 'camdbg.out' will contain many messages, including the
exact contents of socket messages. Be sure to set "dbglvl 1" (the default)
before doing real work, else 'camdbg.out' can grow without limit. If there are
difficult problems with the detector, a run with "dbglvl 6" reproducing the error
can be helpful for diagnosis. Simply capture 'camdbg.out' and send it to
DECTRIS.
The Camserver program of the PILATUS detector provides a simple to use
interface for either EPICS or SPEC. Several clients for these protocols have
been written at the Swiss Light Source (SLS) at the Paul Scherrer Institut
(PSI) and by Mark Rivers of the University of Chicago:
http://cars9.uchicago.edu/software/epics/pilatusROIDoc.html
6.2.1 Steps to Bring Up a PILATUS Detector in a New
Environment
1) If needed, change the hostname to be compatible with the local network.
This can be done conveniently in SuSE linux with YAST2, or directly with vi.
2) Set up the detector on the network, if needed. Note that the detector does
not require an external network.
3) Configure Camserver, and the client TVX, as needed. Probably the defaults
will be adequate, but many parameters can be adjusted in "camrc", and
"tvxrc", both of which reside in the $HOME/p2_det directory.
4) Start the detector by runtvx in the $HOME/p2_det directory.

18
5) If you are using your own client (see section 6.2.2) for Camserver (e.g.,
SPEC or EPICS) disconnect TVX (type “disconnect” in TVX). This can be
done automatically in the startup script after the test images are shown.
Connect your client and begin issuing commands (see section 1).
Further sources of information can be found in
$HOME/p2_det/programs/tvx/docs/.
To see the details of the current configuration of Camserver check the
hardware version file in $HOME/p2_det/config/camstat/HWVersions.
6.2.2 Testclients
The detector can be controlled from any client which opens a socket
connection to Camserver.
Make sure TVX is disconnected (type “disconnect” in TVX) before
you connect your own client.
The most simple client perhaps is telnet. It is possible to test it on the detector
server itself by executing “telnet localhost 41234”. Here localhost is the “IP” of
the detector and 41234 the port where Camserver is listening to.
A basic test client written in C can be found under section15.
Another test client, called "camclientt" in "p2_det/programs/tvx/camera" can
also be used to issue commands to Camserver.
For more information please contact Dectris at [email protected].

19
7 How to use the Pilatus Detector
through Camserver
Camserver is a completely freestanding program that controls the detector
and provides a simple user interface for "atomic" (single function) commands.
It is intended to provide a minimal, but fully functional, low level interface to
camera hardware.
To get help on the Camserver commands use the help facility of TVX (see
section12).
All commands in Camserver (unlike TVX) can be abbreviated to the minimum
number of letters that make the command unambiguous; below we use only
the full names for clarity. As in TVX, commands are case-insensitive, but
pathnames are case-sensitive. A full list of commands can be found in
section 1.
We recommend that full command names are used for clarity.
7.1 Main Commands
Command
Description
ExpTime
Set the exposure time (10-6 to 106sec).
Exposure [filename]
Make an exposure with the exposure time and exposure
period predefined with the command ExpTime and
ExpPeriod respectively. The format of the file is
determined from the supplied extension.
The file is stored relative to the path defined by the
imgpath unless an absolute path is given.
ExtTrigger [fname]
Start exposure with defined variables after receiving an
external trigger and store images [fname].
ExtMTrigger [fname]
Start multiple exposures with defined variables after
receiving multiple external triggers and store images
[fname] (see section 7.3.3).
ExtEnable [fname]
Start exposure defined by external signal and store
images in [fname].
help
exposurenaming
Type this in the TVX window for a discussion of how
exposure series are named.
dcb_init
Re-initialize the detector control board.