EudaqNativeWriter Satellite#

Name	EudaqNativeWriter
Description	Satellite receiving data and writing it to EUDAQ2 native binary formatted files
Category	Data Receivers
Language	C++

Description#

This satellite receives data from other satellites and encodes them in the EUDAQ2 native binary file format. The satellite can be used for compatibility when using analysis software that interfaces EUDAQ2 for decoding data.

Since Constellation and EUDAQ2 data transmission formats are slightly different, there are two BOR tags which sending satellites should set in order to ensure the data can be correctly decoded:

The sending satellite should set the eudaq_event BOR tag to a string describing the EUDAQ2 event type to be used for encoding, for example TluRawDataEvent for data sent by the AIDA TLU. If this tag is not set, the satellite falls back to using the name portion of the canonical name of the sender. This can be used to improve interoperability of satellites which do not set these tags explicitly.
EUDAQ2 knows data blocks per event as well as sub-events, while Constellation data records always consist of a dictionary and any number of data blocks. In order to encode this data correctly to EUDAQ2 native binary format, the sending satellite should specify if the Constellation data blocks should be interpreted as as individual data blocks or as sub-events in the resulting EUDAQ2 native binary event by setting the BOR tag write_as_blocks to either true or false, respectively. If the tag is not provided, this satellite defaults to interpreting them as sub-events, repeating the dictionary for all of the attached blocks.

BOR and EOR messages which arrive before the start of a run and after its end are treated differently from regular data messages. The corresponding EUDAQ events are marked as BORE and EORE, respectively. The header of the EUDAQ event will contain all information from the corresponding Constellation data records. For the BOR, this is the user-provided tags as well as the additional EUDAQ_CONFIG key containing a string representation of the satellite configuration. For the EOR, the user-provided tags and the framework-provided metadata are merged into a single dictionary.

The data events can contain the following header flags which will be interpreted and translated to the corresponding EUDAQ flags or event configurations:

flag_trigger (boolean): if this flag is set to true, the corresponding EUDAQ FLAG_TRIG is set on the event. This will cause analysis software to treat the information as trigger information, i.e. use the trigger number and timestamp as compound information. This flag is necessary e.g. for the AIDA TLU.
trigger_number (integer): If set, the trigger number of the current EUDAQ event will be set from this, if not set the Constellation message sequence is used instead.
timestamp_begin (integer): Timestamp of the event start in units of picoseconds. If the tag is available from the Constellation message header, the value will be translated to nanoseconds and stored as EUDAQ event timestamp. If the tag is not set, 0 will be set as timestamp. This prompts analysis software to use the trigger number instead.
timestamp_end (integer): Timestamp of the event end in units of picoseconds. If the tag is available from the Constellation message header, the value will be translated to nanoseconds and stored as EUDAQ event timestamp. If the tag is not set, 0 will be set as timestamp. This prompts analysis software to use the trigger number instead.
device_number (integer): If set, the device number of the current EUDAQ event will be set from this, if not set the device number is set to 0.

Messages from all sending satellites are written into the output file sequentially in the order in which they arrive. Output files are stored under the path provided via the output_path parameter and are named data_<run_identifier>.raw where <run_identifier> is the identifier of the corresponding run.

Building#

This satellite does not have any external dependencies and is therefore built by default. Should this not be desired can the build be deactivated via

meson configure build -Dsatellite_eudaq_native_writer=false

Parameters#

Parameter	Type	Description	Default Value
`output_directory`	String	Base path to which to write output files to	-
`buffer_size`	Unsigned Integer	Size of file buffer before flushing takes place in KiB	`128`
`flush_interval`	Integer	Longest interval in seconds after which data in the file buffer will be written to disk	3

Framework Parameters#

This satellite inherits the following framework parameters from its base classes:

Parameters inherited from `ReceiverSatellite`#

Parameters to control data transmission in the _data section:

Parameter	Type	Description	Default Value
`allow_overwriting`	Bool	Switch whether overwriting files is allowed or not. If set to `false` and a file exists already, this satellite will go into `ERROR` state.	`false`
`receive_from`	List of strings	List of canonical names of transmitter satellites this receiver should connect to and receive data messages from. If empty, this receiver will connect to all transmitters.	`[]`
`eor_timeout`	Unsigned integer	Timeout waiting for the reception of the end-of-run message. The receiver satellite will wait this number of seconds for receiving the EOR message from each connected transmitter satellite, and will go into error state if the message has not been received within this period. The timeout will only be started after the pending data messages have been read from the queue.	`10`

Parameters inherited from `Satellite`#

Autonomous Operation#

Parameters to control autonomy in the _autonomy section:

Parameter	Type	Description	Default Value
`role`	Role name	Role this satellite should take in the Constellation. Accepted values are `ESSENTIAL`, `DYNAMIC`, `TRANSIENT` and `NONE`.	`DYNAMIC`
`max_heartbeat_interval`	Unsigned integer	Maximum interval in seconds between heartbeats to be sent to other Constellation components. The time between heartbeat is adjusted automatically according to the number of nodes in the Constellation but will never exceed this value.	`30`

Conditional Transitions#

Parameters to control conditional transitions in the _conditions section:

Parameter	Type	Description	Default Value
`require_initializing_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `initializing` state	-
`require_launching_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `launching` state	-
`require_landing_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `landing` state	-
`require_starting_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `starting` state	-
`require_stopping_after`	List of strings	List of canonical names of remote satellites for conditional transitioning in `stopping` state	-
`transition_timeout`	Unsigned integer	Timeout in seconds to wait for all conditions to be satisfied for conditional transitioning	`30`

Framework Metrics#

This satellite inherits the following framework metrics from its base classes:

Metrics inherited from `ReceiverSatellite`#

Metric	Description	Value Type	Interval
`RX_BYTES`	Amount of bytes received from all transmitters during current run	Integer	10s
`DISKSPACE_FREE`	Amount of megabytes available on the file system the current output file is located	Integer	10s
`OUTPUT_FILE`	Path of the currently used output file for this satellite. Updated whenever it changes.	String	-

Metrics inherited from `Satellite`#

Metric	Description	Value Type	Interval
`RUN_ID`	Current run identifier. Updated whenever it changes.	String	-