Wiki source code of How to read Train IDs at FLASH

Last modified by sndueste on 2024/03/13 14:48
Show last authors
1 (% class="twikiTocTitle" %)Content
2
3
4
5 {{toc/}}
6
7 == Introduction ==
8
9 At FLASH photons are delivered with a special pulse structure:
10
11 * so-called //pulse trains// are delivered with 10 Hz repetition rate
12 * every //pulse train// can contain between 1 to 800 pulses separated by 1 to 20 µs
13 * the total length of the //pulse train// can not exceed 800 µs!
14
15 Each //pulse train// is identified by an **//Train ID//** (synonyms: **//bunch ID, timestamp//**).
16
17 Recording this Train ID on the user side allows the correlation of data acquired by the user with all the data saved at FLASH in the DOOCS system, especially with the photon intensity data measured by the GMD system.
18
19 Within DOOCS the Train ID is a 32-bit number. For the users it is transmitted via a socket connection over ethernet - TCP socket. The ID is set 20 ms before the train starts and stays 80 ms after the train. To read the Train ID by the user there are 2 options provided by FLASH:
20
21 * using a provided program (AdvancedIDServer.exe) running on the user's machine, that synchronizes with the Train ID sender and uses the local clock of the user computer to lower the jitter in reading the ID significantly. The user program connects then locally to the AdvancedIDServer program to get the ID ...
22 * direct reading of the ID via TCP socket
23
24 [[image:attach:aids_principle.png||height="400"]]
25
26
27 Basic pinciple of Train ID distribution at Flash1 with TIDS and AIDS
28
29 See also this [[sketch>>attach:timing.png]] of the sequence with miliseconds attached to it, to see when the ID updates relative to the beam.
30
31 Note: If the central Train ID server crashes it will not resume the ID numbers where it was. In most times it will restart with ID 0, sometimes it is set to some high number by hand. For this reason you will see Train IDs with some high bit not as often as expected.
32
33 [[Contents>>doc:||anchor="Contents"]]
34
35 == Train ID reading with local ID reader (Advanced ID Server) //recommended// ==
36
37 === What does //Advanced ID Server// do? ===
38
39 It connects to the TCP based TIDS server and continuously gets the Ethernet packets with the IDs. These packets are time stamped with microsecond resolution and stored. This runs all the time. Because we have a lot of data we can correlate the local time on that machine (that generated the local time stamps) and the IDs. If the Ethernet connection lags sometimes, chokes, hick ups and messes around with our packets, even drops some... Who cares. By closely monitoring all data we can define a function to calculate the Train ID from the local time on that machine.
40
41 [[image:attach:AIDS_running.png||height="189"]]
42
43
44 Here it is running on Windows, but of course you can also use it on your Linux machine (build it from the source).
45
46
47 The users can access this server via a socket. Use localhost:58051. Connect your program to that socket and you get immediately the actual Train ID for this very moment. (e.g. in the CMD window with {{code language="none"}}telnet localhost 58051{{/code}} ... note:telnet is usually deactivated in win10 and has to be activated) The packet you get looks like this:
48
49 {{code language="none"}}
50 3437004.37997 O 818 853
51 {{/code}}
52
53 You get a new calculated ID every time you send any data to the server. So normally your program looks like this and should not close and open the socket all the time:
54
55
56 * Connect to AdvancedIDServer.
57 * Check the state flag and jitter number in the first packet. Ignore the ID.
58 * loop:
59 ** do your measurement
60 ** get a trigger
61 ** send something to AIDS and get the Train ID
62 ** save your aquired data with that ID
63 * until shift finished or FLASH lost beam
64
65 {{code language="none"}}3437004.37997 O 818 853{{/code}}
66 {{code language="none"}}3437005.37997 O 851 889{{/code}}
67 {{code language="none"}}3437006.35997 O 885 925{{/code}}
68
69 About the format: More abstract you get a number, dot, a second number. A character. A third and fourth number.
70
71 The first number is the Train ID (decimal). The number after the dot is the fractional part of the Train ID. **The Train ID changes from "last ID" to "actual ID " 20 ms before the FEL pulse arrives at the experiment**. The fractional part tells you how far after the point in time did you query. It counts from 0.0 to 0.99999 in 100 ms. Thus you can estimate your timing. If you get xxx.20000 you asked for the Train ID 20 ms after it changed and thus at the time when the FEL hit the target. Accordingly xxx.60000 is 40 ms after the FEL. Make sure that you do not read too close to the change of the ID (not around x.0 and 0.9). So in short: you get the Train ID as **float**.
72
73 The char gives basic information about the state of the Advanced ID Server:
74
75 * O means Okay, all is well
76 * S means Stale, our database is quite old and if the state does not change to O soon something is wrong.
77 * D means Disconnected, we get no new information. Hopefully it will change to O in a moment.
78
79 So O means no worries. S and D are warnings, if they stay for more than some seconds your timing might run off.
80
81 The third number is the statistical quality of our calculation. Interpret it like something equal to timing jitter with the unit of microseconds. You can use it to monitor your Ethernet link quality. 10000 means 10 ms, everything below will not affect anyone I assume. The last number is also a statistical jitter value.
82
83 **//Hint: Do NOT enable "fast shutter eventIDs" in the Train ID sender program if you intend to use the Advanced ID Server! Or use a TIDY server.//**
84
85 === Addresses: ===
86
87 You need to specify a suitable TIDY server for your experimental location on invocation like so:
88
89 [[hasfcpuexp2.desy.de>>url:http://hasfcpuexp2.desy.de||shape="rect"]]{{code language="none"}}AdvancedIDServer.exe :58050{{/code}} //(for Flash1)// or [[flash2cpuxgmd2.desy.de>>url:http://flash2cpuxgmd2.desy.de||shape="rect"]]{{code language="none"}}AdvancedIDServer.exe :58050{{/code}} //(for Flash2)//
90
91
92 === Resources: ===
93
94 * [[attach:AdvancedIDServer.exe]]
95 * [[attach:AdvancedIDServer-inline.vi]]: Example how to use the Advanced ID Server with Labview (LV11)
96 * [[AdvancedIDServer on github>>url:https://github.com/Finii/AdvancedIDServer||shape="rect"]]
97
98
99 == Direct reading of Train ID ==
100
101 Receiving the Train ID via ethernet is rather simple. Just open a TCP socket to the one of the servers and read from it.
102 The returned string has the following format: YYMMDD HHMMSS.mmm EVENTID
103
104 The following machines can be used:
105
106 * [[hasfcpuexp2.desy.de>>url:http://hasfcpuexp2.desy.de||shape="rect"]]:58050 (TIDY (//for Flash1//))
107 * [[flash2cpuxgmd2.desy.de>>url:http://flash2cpuxgmd2.desy.de||shape="rect"]]:58050 (TIDY (//for Flash2//))
108
109 Please see also the sample code for [[C>>attach:bunch-id_readout.c]] and [[LabView 14>>attach:bunch-id_readout.vi]]. Example how to embed the ethernet Train ID code into your Labview project (LV 8.6): [[attach:BunchID-inline.vi]]. We have also [[C++ code>>attach:event-reader.hh]] which can be used to be integrate into existing projects.
110
111 The Train-ID for the train is set ~~ 20 ms (for TIDS) before the first photon pulse (at the same time as event 20 or E0) Note the timing differences between TIDS and TIDY in the following sections.
112
113 To validate the connection telnet can be used:
114
115 [[hasfcpuexp2.desy.de>>url:http://hasfcpuexp2.desy.de||shape="rect"]]{{code language="none"}}$ telnet 58050{{/code}}
116
117 You receive for example:
118
119 (% class="code" %)
120 (((
121 150929 180211.495 381469E
122 150929 180211.595 381469F
123 150929 180211.695 38146A0
124 150929 180211.795 38146A1
125 )))
126
127 This format probably is:
128
129 (% class="code" %)
130 (((
131 %y%m%d %H%M%S.%3N %X\r\n
132 )))
133
134 where {{code language="none"}}%y{{/code}} are the last two digits of the year, {{code language="none"}}%m{{/code}} month, {{code language="none"}}%d{{/code}} day number, {{code language="none"}}%H{{/code}} the hour of the day counting from 0 to 23, {{code language="none"}}%M{{/code}} minutes, {{code language="none"}}%S{{/code}} seconds, {{code language="none"}}%3N{{/code}} milliseconds, {{code language="none"}}%X{{/code}} the pulse ID in hexadecimal notation. So it is the last column which is the relevant Train ID.
135
136 The time and date have leading zeros as necessary to ensure a constant field width. The ID number is not zero padded and thus has a varying field width.
137
138
139
140 == Train ID Yelling server (TIDY) ==
141
142 As alternative to the Train ID sender you can use this server. These are the differences:
143
144 * **TIDS** versus **TIDY**
145 * Possible to restrict sending of ID only when the Flash1 fast shutter is open: TIDS
146 * Sends correct IDs independent of fast shutter: TIDY
147 * Sends new IDs (20 ms) before the light hits your experiment: TIDS
148 * Sends new IDs a (5 ms) after the light hits your experiment: TIDY
149
150 Note that the TIDY server is especially good for use together with AIDS, as there is no interaction with the fast shutter (which would break AIDS), and the rather late update to new IDs is of no consequence, as you get the IDs as floats anyhow. So the recommodation is to use TIDY together with AIDS and whenever you can, and use TIDS only if you need the fast shutter functionality.
151
152 Address:
153
154 * [[hasfcpuexp2.desy.de>>url:http://hasfcpuexp2.desy.de||shape="rect"]]:58050 //(for Flash1)//
155 * [[flash2cpuxgmd2.desy.de>>url:http://flash2cpuxgmd2.desy.de||shape="rect"]]:58050 //(for Flash2)//
156
157 === Known Issues ===
158
159 * If you write code to read the train-ID please make sure you close the socket properly. Otherwise it can happen that you eat up all available connections.
160 ** If you can not guaranty that the socket will be closed properly the best solution is to use always the same (client-)port number.
161 ** You can also change your system-settings to let the OS handle it (see tcp_keepalive_time).
162
163 * 20.9.18: The .exe always try [[hasfhvctrl.desy.de>>url:http://hasfhvctrl.desy.de||shape="rect"]] first. So start with additional parameter via the commandline.
164 [[attach:AdvancedIDServer.exe]] [[hasfcpuexp2.desy.de>>url:http://hasfcpuexp2.desy.de||shape="rect"]]
165
166
167 == Short presentation by Fini ==
168
169 * [[Here a short summary from Fini - held in the groupmeeting Nov 2014>>attach:eventid.pdf]]