Katherine Satellite

Name	Katherine
Description	Satellite to control the Timepix3 readout system Katherine
Category	Readout Systems
Language	C++
Website	constellation/satellites/katherine
Version	v1.2.0

Description

This satellite controls the Katherine readout system for Timepix3 detectors. The readout system is connected to the controlling computer via Gigabit Ethernet and consequently supports maximum hit rates of up to 16MHits/s.

The satellite allows to operate the Timepix3 detector in any of its matrix operation modes. i.e. the combined time-of-arrival and time-over-threshold mode (TOA_TOT), the time-of-arrival mode (TOA) or the counting mode with integrated TOT (EVT_ITOT). The detector can be operated either in data-driven mode (sequential_mode = false) or frame-based mode. In the latter case, the number of frames to acquire has to be configured via no_frames.

Building

The Katherine satellite requires the libkatherine library. For Meson versions starting with 1.3.0 it can be installed automatically, otherwise it can be installed via

git clone -b v1.1.0 https://github.com/petrmanek/libkatherine.git
cd libkatherine
mkdir build && cd build
cmake .. -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=/opt # Adjust install path if wanted
ninja install

The satellite requires Meson for building. It can be built and installed via:

meson setup build -Dbuildtype=debugoptimized -Dprefix=/opt # Adjust install path if wanted
meson compile -C build
meson install -C build

Pixel Configuration / Trim DACs

The individual per-pixel trimming DAC settings are read from a file. The BMC and BPC formats of Katherine as well as a simple ASCII text format are supported, the file type is inferred from the file extension (either .txt, .bmc or .bpc).

The ASCII text format expects the following layout:

<column> <row> <trim> <mask> <testpulse>

Where <trim> is a 4-bit trim DAC value, <mask> is a Boolean for masking the pixel, and <testpulse> a Boolean to enable sending test pulses to this pixel.

Data Format & Data Decoding

Timepix3 sends its data in individual packages, which are buffered by the Katherine readout system and then sent to the satellite as 6-byte data packets. The parameter decode_data controls whether the Katherine library decodes these words into pixel hits before sending them, or whether the raw Timepix3 data packets are sent.

Each data record sent by the satellite contains one data block per pixel hit or per data packet. The format of the data in a specific run can be inferred from the parameters op_mode, fast_vco and decode_data provided in the satellite configuration in the begin-of-run message. All multi-byte fields are stored little-endian and without padding.

Decoded Pixel Data

When decoding data, each data record contains the pixel hits of one flush of the pixel buffer. The buffer is flushed when it holds pixel_buffer pixel hits, when no data has arrived for 500 ms, and at the end of the run. Each block holds one pixel hit with the following layout:

op_mode	fast_vco	Block layout	Bytes
TOA_TOT	true	x:u8, y:u8, ftoa:u8, toa:u64, tot:u16	13
TOA_TOT	false	x:u8, y:u8, toa:u64, hit_count:u8, tot:u16	13
TOA	true	x:u8, y:u8, ftoa:u8, toa:u64	11
TOA	false	x:u8, y:u8, toa:u64, hit_count:u8	11
EVT_ITOT	true	x:u8, y:u8, hit_count:u8, event_count:u16, integral_tot:u16	7
EVT_ITOT	false	x:u8, y:u8, event_count:u16, integral_tot:u16	6

Both TOA_TOT layouts have the same size, the fast_vco parameter decides whether it contains ftoa or the hit count.

Raw Measurement Data

When data is sent without decoding, each data record holds the content of one data packet received from the Katherine readout system. Each block holds one 6-byte with the word type stored in the upper four bits. These data packets can be decoded e.g. with the decoding routines of libkatherine.

Parameters

The following parameters are read and interpreted by this satellite. Parameters without a default value are required unless noted otherwise.

Parameter	Description	Type	Default Value
ip_address	IP address of the Katherine system	String	-
chip_id	ID of the chip to be operated. Optional setting, this will only be checked when provided. If it does not match, an error is reported.	String	-
dacs	Configuration section with DAC settings, see below for details.	Section	-
px_config_file	Path to file with individual pixel trim settings, in TXT, BMC or BPC format.	String	-
positive_polarity	Threshold polarity switch	Bool	true
sequential_mode	Switch to enable/disable sequential mode	Bool	false
op_mode	Operation mode, can be TOA_TOT, TOA, EVT_ITOT or MASK	String	TOA_TOT
fast_vco	Enable the fast VCO for fine ToA measurements, at the cost of the hit counter in TOA and TOA_TOT modes.	Boolean	true
decode_data	Choose whether Katherine should already decode the pixel data or send the raw Timepix3 data out.	Boolean	true
shutter_mode	Shutter operation mode, can be POS_EXT, NEG_EXT, POS_EXT_TIMER, NEG_EXT_TIMER or AUTO	String	AUTO
shutter_width	Width of the shutter window, only relevant for shutter modes POS_EXT_TIMER and NEG_EXT_TIMER	Int
pixel_buffer	Depth of the pixel buffer. This many pixel hits are accumulate before sending. The default corresponds to one full Timepix3 frame	Int	65536
data_buffer	Depth of the data buffer in units of Timepix3 packets (6 bytes each). Data is either decoded or sent directly from this buffer. The default corresponds to 200 MB memory.	Int	34952533
no_frames	Number of frames to acquire. Needs to be set to 1 for data-driven mode (sequential_mode = false)	Int	1
bias_voltage	Bias voltage applied to the sensor, in volts	Float	0

DACs Section

The section dacs holds the DACs to be set for Timepix3, all configuration keys are interpreted case-insensitively. The following DAC settings are available:

Parameter	Description	Type	Default Value
IBIAS_PREAMP_ON		Int	128
IBIAS_PREAMP_OFF		Int	8
VPREAMP_NCAS		Int	128
IBIAS_IKRUM		Int	128
VFBK		Int	128
VTHRESH_FINE		Int	256
VTHRESH_COARSE		Int	8
IBIAS_DISCS1_ON		Int	128
IBIAS_DISCS1_OFF		Int	8
IBIAS_DISCS2_ON		Int	128
IBIAS_DISCS2_OFF		Int	8
IBIAS_PIXELDAC		Int	128
IBIAS_TPBUFIN		Int	128
IBIAS_TPBUFOUT		Int	128
VTP_COARSE		Int	128
VTP_FINE		Int	256
IBIAS_CP_PLL		Int	128
PLL_VCNTRL		Int	128

The fine (VTHRESH_FINE) and coarse (VTP_COARSE) threshold values can be converted to a linearized threshold value via:

threshold = coarse * 160 + (fine - 352)
# with: 352 <= fine < 511

coarse = floor(threshold / 160)
fine = (threshold % 160) + 352

Configuration Example

The following example configuration could be used to control a Katherine readout system satellite with a Timepix3 detector. The satellite is configured to connect to the system at 192.168.1.182 and to use the provided local file for the pixel matrix configuration. The pixel buffer is set to 300 pixel hits, two DACs are changed from their default values. All other settings are left at their defaults:

[Katherine.TPX3]
ip_address = "192.168.1.182"
px_config_file = "E2-W0005_trimdacs.txt"
pixel_buffer = 300
bias_voltage = 230.0

[Katherine.TPX3.dacs]
VTHRESH_FINE = 200
IBIAS_PIXELDAC = 127

Custom Commands

The following custom commands are exposed to the command interface by this satellite:

Command	Description	Arguments	Return Value	Allowed States
get_temperature_readout	Read the current temperature from the Katherine readout board	-	Temperature in degree Celsius, double	INIT, ORBIT, RUN
get_temperature_sensor	Read the current temperature from the temperature sensor	-	Temperature in degree Celsius, double	INIT, ORBIT, RUN
get_adc_voltage	Read the voltage from the ADC channel provided as parameter	channel number, int	channel reading, double	INIT, ORBIT, RUN
get_chip_id	Read the chip ID of the attached sensor	-	Chip ID, string	INIT, ORBIT, RUN
get_hw_info	Read hardware revision and other information from the device	-	List of strings with HW type, revision, serial number and firmware version	INIT, ORBIT, RUN
get_link_status	Read chip communication link status from the device	-	List of strings with line mask, data rate and chip presence flag	INIT, ORBIT, RUN

Miscellaneous Information

Timepix3 Packet Headers and Header Filters

Packets coming from the chip have a header identifying the type of information contained. The following table relates them:

packet               header           filter bit
AnalogPeriphery      0000 (0x0)       0
OutputBlockConfig    0001 (0x1)       1
PLLConfig            0010 (0x2)       2
GeneralConfig        0011 (0x3)       3
Timer                0100 (0x4)       4
                     0101 (0x5)       5
Trigger (SPIDR)      0110 (0x6)       6
ControlOperation     0111 (0x7)       7            <- Marks e.g. EndOfCommand
LoadConfigMatrix     1000 (0x8)       8
ReadConfigMatrix     1001 (0x9)       9
ReadMatrixSequential 1010 (0xA)       10           <- Pixel data
ReadMatrixDataDriven 1011 (0xB)       11           <- Pixel data
LoadCTPR             1100 (0xC)       12
ReadCTPR             1101 (0xD)       13
ResetSequential      1110 (0xE)       14
StopMatrixReadout    1111 (0xF)       15

Framework Parameters

This satellite interprets the following configuration parameter that are provided through the Constellation framework. Parameters have to be placed in their respective configuration section.

Data Transmission

The following parameters control the data transmission of this satellite and have to be provided in the _data section:

Parameter	Type	Description	Default Value
disable_transmission	Boolean	Disable data transmission. This parameter turns off transmission of data to receiver satellites and instead ignores and drops all data records.	false
bor_timeout	Unsigned integer	Timeout in seconds to send the BOR message. The satellite will attempt for this interval to send the message and goes into ERROR state if it fails to do so. A possible reason for failure is that no receiver satellite connected to this satellite and is receiving data.	10
eor_timeout	Unsigned integer	Timeout in seconds to send the EOR message. The satellite will attempt for this interval to send the message and goes into ERROR state if it fails to do so.	10
data_timeout	Unsigned integer	Timeout in seconds to send the data message. The satellite will attempt for this interval to send the message and goes into ERROR state if it fails to do so.	10
payload_threshold	Unsigned integer	Threshold for sending data messages in KiB. The satellite will only send queued data records after the combined payload size of the data records has reached this threshold.	128
queue_size	Unsigned integer	Size of the queue for the data records. Small values might lead to performance issues, large values lead to larger memory usage.	32768
license	String	License this data is recorded under. Defaults to the Open Data Commons Attribution License. This information will be added to the run metadata.	ODC-By-1.0

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 provides the following metrics that are defined by the Constellation framework.

Data Transmission

Metric	Description	Value Type	Interval
TX_BYTES	Amount of bytes transmitted during current run	Integer	5s
TX_BLOCKS	Number of data blocks transmitted during current run	Integer	5s
TX_RECORDS	Number of data records transmitted during current run	Integer	5s

Basic Satellite Metrics

Metric	Description	Value Type	Interval
RUN_ID	Current run identifier. Updated whenever it changes.	String	-
STATE	Current satellite state. Updated when changed.	String	-
CPU_LOAD_AVG	CPU load average over the past 1 minute, provided in percent.	Float	10s
MEM_AVAIL	Available memory in Megabytes.	Integer	10s