Dectris MYTHEN User manual

DECTRIS Ltd.
5405 Baden- Daettwil
Switzerland
www.dectris.com
Socket Interface
Specification
MYTHEN Detector System
Version:
3.0.0
Document Version:
2

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 2/34

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 3/34
Table of Contents
1. Document History 5
1.1. Current document 5
1.2. Changes 5
2. How to use this guide 6
2.1. Address and Support 6
2.2. Explanation of Symbols 7
2.3. Explanation of Terms 7
2.4. Disclaimer 8
3. Warnings 9
4. Introduction 10
5. Operation 11
5.1. Connecting to the server 11
5.2. Initialization 11
5.3. Settings 12
5.3.1. Predefined Settings 12
5.3.2. Setting Threshold and Energy 12
5.3.3. High frame rates 12
5.4. Acquisition control 12
5.5. Data corrections 13
5.6. Triggering and gating 13
5.7. Debugging 13
6. Example Applications 14
7. Commands 15
7.1. Command list 15
7.1.1. General commands 16
7.1.2. Acquisition control 18
7.1.3. Detector settings 20
7.1.4. Data correction 22
7.1.5. Trigger / Gate 23
7.1.6. Debugging 25
7.1.7. Deprecated commands 26
7.2. Error Codes 28
7.3. Decoding the raw data 29
8. Release Notes 30
8.1. Version 3.0.0 30

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 4/34
8.1.1. Modifications 30
8.1.2. Migration notes 31
8.1.3. Legacy2 mode 31
8.2. Version 2.1.0 31
8.3. Version 2.0.5 31
8.4. Version 2.0.4 31
8.5. Version 2.0.3 32
8.6. Version 2.0.2 32
8.7. Version 2.0.1 32
8.8. Version 2.0.0 32
8.8.1. New Functionalities 33
8.8.2. Migration notes 33
8.8.3. Legacy Mode 33
9. Appendix 34
9.1. Table of Tables 34
9.2. Referenced Documents 34

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 5/34
1. Document History
1.1. Current document
Version
Date
status
prepared
checked
released
3.0.0 DV2
04.02.2016
ready for release
DJ
AM
PT
1.2. Changes
Version
Date
Changes
3.0.0 DV2
04.02.2016
New postal address
3.0.0 DV1.1
11.06.2013
Adapted CD
3.0.0 DV1.0
21.09.2012
Simplified operation of the detector system
Better data quality due to optimized calibration
Restricted threshold and energy ranges
By default all commands affect all active modules

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 6/34
2. How to use this guide
Before you start to operate the MYTHEN detector system please read the User Manual and the Technical
Documentation included in the documentation package carefully.
This document has been designed for the MYTHEN detector systems.
2.1. Address and Support
DECTRIS Ltd.
Taefernweg 1
5405 Baden-Daettwil
Switzerland
Phone: [phone]
Fax: + 41 56 500 21 01
Website:
www.dectris.com →support →Technical Notes →MYTHEN
www.dectris.com →support →FAQ
www.dectris.com →support →Problem Report
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!

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 7/34
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
Functional earth
2.3. Explanation of Terms
Term
Description
GUI
Graphical User Interface
DCS1
Detector Control System for 1detector module
DCS6
Detector Control System for up to 6detector modules
DCS24
Detector Control System for up to 24 detector modules
Detector module
The smallest fully functional unit of the detector (1280
channels).
MCB
Module Control Board
FIFO
Storage working according to the First In - First Out
principle
keV
Kilo electron Volt

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 8/34
2.4. Disclaimer
DECTRIS Ltd. 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 Ltd. bears no responsibility or liability for damage of any kind, also for indirect or consequential damage
resulting from the use of this system.
DECTRIS Ltd. 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 Ltd. 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 Ltd. 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.

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 9/34
3. Warnings
Please read these warnings before operating the detector system.
DO NOT TOUCH THE ENTRANCE WINDOW OF THE DETECTOR.
Place the protective cover on the entrance window of the detector when it is not in use.
The detector is not specified to withstand direct beam at a synchrotron. Such exposure will damage the
exposed channels.
The detector system should have enough space for proper ventilation. Operating the detector outside the
specified ambient conditions could damage the system.
The air inlets and outlets of the detector control system should not be blocked.
Power down the detector system before connecting or disconnecting any cable.
Before connecting the power supply to the mains-supply, check the supply voltage with the label on the
power supply. Using an improper main voltage will destroy the power supply and could damage the
detector.
Make sure the cables are connected and properly secured.
Avoid pressure or tension on the cables.
Opening the detector, the detector control system or the power supply housing without explicit instructions
from DECTRIS Ltd. will void the warranty.
The embedded Linux operating system on the detector control system has customized software for
controlling the MYTHEN detector system. Do not make any changes to the Linux operating system without
explicit instructions from DECTRIS Ltd.

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 10/34
4. Introduction
The detector control system (DCS) hosts an embedded Linux system, on which the MYTHEN Socket Server is
running. The DCS also stores the calibration files for the detector as well as some network settings. A client can
open a socket connection to the server and control the MYTHEN detector by sending the commands listed in
Chapter 7. Example applications in C++ for Linux and Windows are provided on the system memory stick. A spec
implementation based on this socket interface is available from http://www.certif.com.
To take advantage of new functionality and bug fixes, it is possible to update to a newer version of the MYTHEN
Socket Server within the same major release. The configuration files and the network settings stored on the DCS
will not be affected by the update. The required files can be downloaded from the DECTRIS Ltd. website
http://www.dectris.com.
An upgrade to a new major release usually requires a recalibration of the detector by DECTRIS Ltd. and is
therefore not possible to be performed by the customer. If you are interested in a major upgrade please contact
[email protected].

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 11/34
5. Operation
5.1. Connecting to the server
As a first step, the client has to open a socket connection to the server. The user can choose whether he wants to
use UDP or TCP as protocol. While TCP is more reliable, UDP is faster and allows for higher frame rates.
To open the connection, the user has to specify the IP of the DCS, which is by default 192.168.0.90. The port of
the socket server is 1030 for the UDP and 1031 for the TCP protocol.
The commands sent to the server are ASCII strings. The response is a byte array, which has to be interpreted as
string, integer array or float array, depending on the command. All commands return responses of well defined
lengths. Since the response might be fragmented on its way through the network, the client might have to read
several packages, until the expected response length is reached.
In case of an error, the server will respond with a negative number. The meaning of the error codes can be found
in section 7.2.
5.2. Initialization
First of all it should be checked, that the socket server has the expected version. This is done with help of the
command "-get version".
Afterwards the detector system should be initialized by invoking the "-reset" command, which takes up to two
seconds per module. This command loads settings for Cu X-rays and enables the flatfield correction and the
interpolation for bad channels (more details on the default values after initialization can be found in section 7).
For proper operation all delivered modules have to be connected to the DCS. Nonetheless it is possible to read
out only the first few modules. The number of active modules to be used can be specified using the “-nmodules”
command. The MYTHEN system can also be operated with more than the delivered modules if the corresponding
calibration files are available on the DCS. When increasing the number of active modules, all modules are set
back to default settings.

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 12/34
To check, whether the communication with all modules is working, the module serial numbers can be read out ("-
get modnum").
By default the commands affect all active modules. Some commands can be invoked on single modules. This can
be achieved by selecting a specific module with the “-module” command. The same command can also be used,
to restore the default behavior by selecting all active modules.
5.3. Settings
5.3.1. Predefined Settings
The simplest way to operate the detector is to load predefined settings for a copper or molybdenum tube with the
“-settings" command. Depending on the calibration of your system, predefined settings for chromium and silver X-
rays are also available.
5.3.2. Setting Threshold and Energy
The predefined settings can be customized by explicitly specifying the energy threshold and the X-ray energy with
the command “-kthreshenergy”. The allowed ranges for these parameters depend on the calibration of your
system.
5.3.3. High frame rates
To maximize the frame rate, the user should consider the following options:
1. Minimizing the number of bits which are read out with the "-nbits" command.
2. Disabling the server side rate correction with the command "-ratecorrection 0".
3. Disabling the server side flatfield correction with the command “-flatfieldcorrection 0".
4. Using a UDP connection instead of the slower TCP connection.
5. Using the “-readoutraw”command instead of the slower “-readout”command.
5.4. Acquisition control
Before starting an acquisition, the number of frames and the duration of the frames have to be programmed. The
former can be done with the "-frames" command, the latter with the "-time" command. Since the duration is
specified in units of 100ns, the argument can be a large number. Therefore the user should make sure to handle
these numbers correctly. For example in the C programming language, it will be necessary to use the data type
long long, which comprises 64 bits.
An acquisition is started with the "-start" command. Afterwards each frame is read out with a "-readout" command.
A readout command that is sent while the corresponding frame is still acquired will return when the data collection
for this frame has finished. Since the DCS can only buffer four frames, it is important to read out the frames as
soon as possible. An acquisition can be interrupted with the "-stop" command, which results in the loss of the
frames, which have not yet been read out.
The status of the acquisition can be checked with the "-status" command. Sending commands other than "-
readout", "-status" or "-stop" during an acquisition can result in misbehavior of the detector.

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 13/34
5.5. Data corrections
For channels marked as bad the server will replace the number of counts with the average number of counts of
the next lower and the next upper working channels. With the "-badchannelinterpolation" command the user can
turn off this correction. In this case the number of counts will equal to -2 for these channels.
The server automatically applies a flat-field correction to the data. This behavior can be disabled with the "-
flatfieldcorrection" command.
For high incoming X-ray fluxes, the rate correction can be turned on with the "-ratecorrection" command.
5.6. Triggering and gating
The standard and the continuous trigger modes can be enabled by the "-trigen" and "-conttrigen" commands. The
timing of the measurements can be adjusted with the "-delbef" and "-delafter" commands.
The gating mode is turned on by the "-gateen" command. The number of gates can be programmed with the "-
gates" command.
The polarity of the input and output signals can be defined with the help of the "-inpol" and "-outpol" commands.
5.7. Debugging
After sending the command "-log start" the socket server will log its activities into a file on the DCS until a "-log
stop" command is sent. The content of the file is sent to the user in response to the "-log read" command. Since
there is only limited disk and memory space on the DCS, the logging functionality should only be turned on for
short periods of time.
For debugging problems related to the transmission of the data packages over the socket, the freely available
network protocol analyzer WireShark can be used.

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 14/34
6. Example Applications
As a starting point a Unix and a Windows C application with some comments are provided on the system memory
stick. They set up a socket connection to the DCS and read back the module serial numbers. Afterwards a short
acquisition is performed, and the result is printed on the command prompt. The Windows version was developed
with the freely available Microsoft Visual C++ 2008 Express Edition.

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 15/34
7. Commands
7.1. Command list
Synopsis: Specifies the format of the command. Values in angle brackets have to be replaced by the user: bstands for a boolean (i.e. a 0 or 1), nfor an integer, ffor a
float, time for a 64-bit integer (long long or int64_t, used for the timing commands).
Arguments: Gives the meaning of the arguments. Default values after initialisation are set in italic type.
Description: Describes the effect of the command.
Return Type: Specifies the data type of the returned byte array. If no return type is indicated, the command returns an integer: a zero indicating successful execution of
the command or a negative number in case of an error (see section Error Codes). If the return value is of type float, the error code is returned as a float number, and as
an integer otherwise.
Return Size: Specifies the number of data elements in the returned byte array. For example a response of return type int and return size 1280 is 5120 bytes long (since
one integer uses 4 bytes). NMOD stands for the number of active modules (set by "-nmodules").

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 16/34
7.1.1. General commands
Table 1 General Commands.
Synopsis
Argument
Description
Return
Type
Return
Size
-get assemblydate
Returns the assembly date of the system as character array.
char
50
-get badchannels
Returns the status of each channel. A value of 0 means that the
channel is working, a value of 1 means that it is defective.
int
NMOD*1280
-get commandid
Returns the current command identifier. The command identifier
increases by one whenever a client sends a command to the server.
Can be used to make sure that no other clients changed the state of the
system.
int
1
-get modnum
Returns the serial numbers of the modules, which have to be
interpreted as hex-numbers.
int
NMOD*
-get module
Returns either the position of the selected module or 65535 when all
modules are selected.
int
1
-get nmaxmodules
Returns the maximal number of modules which can be connected to
this MYTHEN system.
int
1
-get nmodules
Returns the number of active modules.
int
1
-get sensormaterial
Returns an identifier for the sensor material.
0: Silicon
int
1
-get sensorthickness
Returns the nominal sensor thickness in µm.
int
1
-get systemnum
Returns the serial number of the MYTHEN system.
int
1
-get version
Returns the software version of the socket server, which is of the form
"M3.0.0". The returned string is terminated by a Null character.
char
7
-module ˂n˃
Module position
0 ≤ n < NMOD |
65535
Selects the module at the given position as the target of module
specific commands. An argument of 65535 selects all active modules.
After initialization all modules are selected.
-nmodules ˂n˃
Number of modules
Sets the number of active modules (NMOD). When the number of active
modules is increased, all modules are set back to default settings. After

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 17/34
initialization the number of active modules is set to the number of
delivered modules.
-reset
Sets the detector back to default settings. This command takes about
two seconds per module.

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 18/34
7.1.2. Acquisition control
Table 2 Acquisition control commands.
Synopsis
Argument
Description
Return
Type
Return Size
-delafter ˂time˃
Delay in units of 100 ns.
Default is 0 ns.
Sets the delay between two subsequent frames (“delay
after frame”).
-frames ˂n˃
Number of frames.
Default is 1.
Sets the number of frames within an acquisition.
-get delafter
Returns the delay between two subsequent frames.
long long
1
-get frames
Returns the number of frames.
int
1
-get nbits
Returns the number of bits to be read out.
int
1
-get status
Returns the status of the DCS as a bit pattern:
Bit 0: Acquisition running
Bit 3: Waiting for trigger
Bit 16: No data available for readout (empty buffer)
int
1
-get time
Returns the programmed exposure time of one frame in
units of 100ns.
long long
1
-nbits ˂n˃
n = 4 | 8 | 16 | 24
Sets the number of bits to be read out, thereby
determining the dynamic range and the maximum frame
rate. After initialization 24 bits are read out.
-readout
The DCS can internally buffer the last four acquired
frames. This command returns the data of the oldest frame
in the buffer (i.e. the frames are returned in the same order
as they were acquired). If the buffer is empty and there is
an ongoing measurement, the command returns the data
after the measurement has finished. If the readout fails for
some reason, all count values are set to -1.
int
NMOD*1280

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 19/34
-readoutraw
Returns the data of the oldest frame in the buffer in a raw,
compressed format. The DCS does not apply any
correction to the data, thereby allowing for maximal frame
rate. The example code in section 0 shows how to decode
the raw data.
int
NB*NMOD
NBITS
NB
24
1280
16
640
8
320
4
160
-start
Starts an acquisition with the programmed number of
frames or gates.
-stop
Stops the current acquisition. The data of the ongoing
frame is discarded.
-time ˂time˃
Exposure time in units of
100ns. Default is 1s.
Sets the exposure time of one frame.

Socket Interface Specification. MYTHEN Detector System. Version: 3.0.0, Document Version: 2 20/34
7.1.3. Detector settings
Table 3 Detector setting controlling commands.
Synopsis
Argument
Description
Return
Type
Return Size
-energy ˂f˃
Emin ≤f ≤Emax in units of
keV. Default is 8.05 keV.
Sets the X-ray energy for the selected modules while
keeping the current threshold energy. The energy is used
to provide an optimal flatfield correction. The supported
energy range depends on the calibration of the system.
This command takes about two seconds per module.
-get energy
Returns the X-ray energies of the selected modules.
float
NMOD*
-get energymax
Returns the maximal supported X-ray energy in units of
keV.
float
1
-get energymin
Returns the minimal supported X-ray energy in units of
keV.
float
1
-get kthresh
Returns the threshold of the modules in keV.
float
NMOD*
-get kthreshmax
Returns the maximal supported threshold energy in units
of keV.
float
1
-get kthreshmin
Returns the minimal supported threshold energy in units of
keV.
float
1
-kthresh ˂f˃
Thrmin ≤f ≤Thrmax in units
of keV. Default is 6.4 keV.
Sets the energy threshold for the selected modules while
keeping the current X-ray energy. The supported threshold
range depends on the calibration of the system. This
command takes about two seconds per module.
-kthreshenergy ˂f1˃ ˂f2˃
Thrmin ≤f1 ≤Thrmax, Emin≤
f2 ≤Emax in units of keV.
Defaults are f1 = 6.4 keV
and f2 = 8.05 keV.
Sets the energy threshold and the X-ray energy for the
selected modules. The supported ranges depend on the
calibration of the system. This command takes about two
seconds per module.