API Reference

Table of Contents

common.proto

Messages

BoolValue

Boolean wrapper.

Field Type Description
value bool Boolean value

BytesValue

Field Type Description
value bytes Blob value

ChipBoolValue

A boolean value bound to a specific chip.

Field Type Description
idx uint32 none
value bool none

ChipIndex

ChipIndex wrapper.

Field Type Description
idx uint32 Chip index

ChipIntValue

A int value bound to a specific chip.

Field Type Description
idx uint32 none
value int32 none

ChipSintValue

A signed int value bound to a specific chip.

Field Type Description
idx uint32 none
value sint32 none

ChipStringValue

A string value bound to a specific chip.

Field Type Description
idx uint32 none
value string none

ChipUintValue

A unsigned int value bound to a specific chip.

Field Type Description
idx uint32 none
value uint32 none

Date

A date.

Field Type Description
year uint32 Year, complete, e.g. 2019
month uint32 Month 1-12
day uint32 Day 1-31

Empty

Empty message.

FloatValue

Field Type Description
value float Floating point value

InetAddress

Abstraction of an internet address.

Field Type Description
host string none
port uint32 none

Int32Value

Int32 wrapper.

Field Type Description
value int32 Integer value

Int64Value

Int64 wrapper.

Field Type Description
value int64 Integer value, 64 bits

LogLine

A single line of logging.

Field Type Description
text string none

SInt32Value

Signed int32 wrapper.

Field Type Description
value sint32 Signed Integer value

SInt64Value

Signed int64 wrapper.

Field Type Description
value sint64 Signed Integer value, 64 bits

StringList

A list of strings.

Field Type Description
items repeated string String items

StringValue

A String wrapper.

Field Type Description
value string String value

UInt32Value

Unsigned int32 wrapper.

Field Type Description
value uint32 Unsigned integer value

UInt64Value

Unsigned int64 wrapper.

Field Type Description
value uint64 Unsigned integer value, 64 bits

Version

Version message for querying service versions.

Field Type Description
product string Product name
majr int32 Major version number
minr int32 Minor version number
patch int32 Patch number
build_date string Build date (converted to string)
commit_info string Commit information string (usually GIT information)

control.proto

Services

ControlInfo

High level control and info service for SPIDR4.

Methods 
GetVersion(Empty) Version
Request version of the SPIDR4 control software.
Note that this is different from the firmware version. 

GetFirmwareVersion(Empty) Version
Returns the base firmware version. 

GetSerial(Empty) Int64Value
Request the serial number of this SPIDR4 module. 

Shutdown(ShutdownRequest) Empty
Shutdown the service or device. 

SysConfig(StringValue) StringValue
System configuration task. Expert call! 

SysUpdate(UpdateCall) UpdateResponse
System update task. Expert call! 

PowerDisable(Empty) Empty
Panic power disable for the chip.
Call this if things go horribly wrong. This state is unrecoverable, and the control must be restarted in order to restore the state. 

GetPixelChipInfo(Empty) PixelChipList
Request information about the chips connected to this SPIDR4 board. 

GetChipBoardInfo(Empty) ChipBoardInfo
Request information about the board. 

ResetPixelChips(Empty) Empty
Reset all pixel chips and run initialization scripts.
This will interfere with any ongoing on-chip operations.
TODO: move this to the pixelchip service? 

RegMapAccess(RegMapActionList) RegMapValueList
Low level access to the register map.

RegMap access allows multiple operations to be executed on the registers at once, therefore the RegMapRequests consists of multiple RegMapAction objects.
Each action can be either read, write or modify (=masked write).
Bulk reading / writing is possible by creating a multiple RegMapAction items in the RegMapRequest's actions list.

All addresses are physical addresses, as provided in the reference documentation and thus must be located at multiples of four. Trying to access registers outside of the SPIDR4 firmware register map or at an illegal offset will cause an error response. 

FpgaRegWrite(FpgaRegWriteReq) FpgaRegRpl
Writes a register in the FPGA fabric from an offset.
See register map documentation for exact offsets.
Low level FPGA command, using this could cause undefined behavior and in extreme cases malfunction. Use with care. 

FpgaRegRead(FpgaRegReadReq) FpgaRegRpl
Reads a register in the FPGA fabric from an offset.
See register map documentation for exact offsets.
Low level FPGA command, using this could cause undefined behavior and in extreme cases malfunction. Use with care. 

GetLogging(Empty) LogLine
Returns console logging as a stream.

DataStream

DataStream is a high-level control interface for configuring the path of the output of the pixelchip.

There are 3 major paths which have all a separate configuration command:

  • Slow control (Use ConfigSlowControl)
  • 10 Gigabit Ethernet (Use ConfigXGbe)
  • Optical links (Use ConfigOptical)
Each specific method will configure all elements in the output chain such that the PixelChip is able to send data through the configured data path. This includes enabling the channels on the pixel chip itself, but also includes configuring the IP settings when 10GbE is selected.

Once configured a final Enable command must be given to enable the last elements in the chain.

Note: For Timepix4 only the optical datapath allows for full-speed readout.

Methods 
ConfigXGbe(XGbeConfig) Empty
Configures the 10GbE Ethernet.
Can only be called if not enabled. 

ConfigOptical(OpticalLinkConfig) Empty
Configures direct optical links.
Can only be called if not enabled. 

ConfigSlowControl(ChipIndex) Empty
Configures the DAQ over slow-control.
(For the future, for now it does not do anything) 

ConfigNone(ChipIndex) Empty
De-configure the given chip. 

GetChipCapabilities(ChipIndex) DataStreamPathList
Returns the capabilities for the given chip. 

GetConfig(Empty) LinkConfigList
Returns the current configuration.

Trigger

Shutter configuration and control service.

Note*: This is the SPIDR4 shutter system!

To propagate this to the pixelchip you must enable external input on the chip itself.
For example, for the shutter on a Timepix4 you must set:
Tpx4ShutterConfig.mode = TPX4_SHUTTER_MODE_MANUAL
Tpx4ShutterConfig.input = TPX4_SHUTTER_INPUT_PAD

Methods 
Enable(Empty) Empty
Enable the trigger circuit.

Without this call the SPIDR4 will not generate shutter or T0 Syncs. 

Disable(Empty) Empty
Disable the trigger circuit. 

GetStatus(Empty) TriggerStatus
Return shutter information. 

SetConfig(TriggerConfig) Empty
Configure the shutter. 

StartAutoShutter(Empty) Empty
Start the auto-shutter
(when TriggerConfig.shutter_input == SHUTTER_IN_AUTO_GEN). 

StopAutoShutter(Empty) Empty
Stop the auto-shutter
(when TriggerConfig.shutter_input == SHUTTER_IN_AUTO_GEN). 

ShutterOpen(Empty) Empty
Open the shutter
(when TriggerConfig.shutter_input == SHUTTER_IN_SOFTWARE). 

ShutterClose(Empty) Empty
Close the shutter
(when TriggerConfig.shutter_input == SHUTTER_IN_SOFTWARE). 

ResetShutterCounter(Empty) Empty
Reset the shutter counter. 

T0Sync(Empty) Empty
Generate a 100 us T0 Sync pulse
(when TriggerConfig.t0sync_input == T0SYNC_IN_SOFTWARE). 

ResetT0Counter(Empty) Empty
Reset the T0 Sync counter

Messages

ChipBoardInfo

Information about the connected chip-board.

Field Type Description
type string Type of the board, configuration file specified type name
serial string Serial of the board, confguration file specified

DataStreamPathList

List of DataStreamPath items.

Field Type Description
items repeated DataStreamPath none

FpgaRegReadReq

FPGA register read request.

Field Type Description
offset uint32 Register offset from base address

FpgaRegRpl

Field Type Description
offset uint32 Register offset from base address
value uint32 Read-back value

FpgaRegWriteReq

FPGA register write request.

Field Type Description
offset uint32 Register offset from base address
value uint32 Value to write
mask uint32 Mask, is optional.
When used, bits are changed only where mask bits are set. Otherwise the entire value is written to the register.

LinkConfig

Field Type Description
path DataStreamPath The stream path for this link config.
Also defines which entry of link will be filled.
oneof link.xgbe XGbeConfig Set for DataStreamPath = DSPATH_XGBE or DSPATH_2XGBE
oneof link.optical OpticalLinkConfig Set for DataStreamPath = DSPATH_OPTICAL
oneof link.sc ChipIndex Set for DataStreamPath = DSPATH_SLOW_CONTROL

LinkConfigList

List of Link configurations.

Field Type Description
items repeated LinkConfig For each item, a link configuration

OpticalLinkConfig

Configures the optical path.

Field Type Description
idx uint32 Chip index to configure
channels uint32 The channels you wish to enable on the chip.
Bit 0 - First channel
Bit 1 - Second channel, etc...
For TPX4:
  • Bit 0 = top0
  • Bit 7 = top7
  • Bit 8 = bot0
  • Bit 15 = bot7
  • Bit >15 = not valid
Leave empty for 'all available'.
To disable from outputting data chip, use configNone() grpc call.
link_speed float Set the link-speed for all selected channels, in MHz.
If the link_speed is not possible an error will be returned.
Depends on the specific chip.
For Timepix4:
  • 10240 MHz (uses 320 MHz mode)
  • 5120 MHz
  • 2560 MHz
  • 1280 MHz
  • 640 MHz
  • 320 MHz
  • 160 MHz
  • 80 MHz
  • 40 MHz

PixelChipInfo

Generic pixelchip information.

Field Type Description
type PixelChipType The type of the pixel chip
chip_id uint32 The ID of the chip
idx uint32 Chip index on the board, used as primary identifier
revision int32 Chip revision

PixelChipList

List of pixelchips information.

Field Type Description
items repeated PixelChipInfo A list of PixelChipInfo elements

RegMapAction

Register map operation.

Field Type Description
oper RegMapOp Operation to perform
addr uint32 Physical address on the bus
value uint32 Value to write (not used with READ)
mask uint32 Mask to apply (only used with MODIFY and MODIFY_READ)

RegMapActionList

Request a number of regmap register operations.

Field Type Description
items repeated RegMapAction Register map action items

RegMapValue

SPIDR4 register map value reading.

Field Type Description
addr uint32 Register address
value uint32 Register value

RegMapValueList

A reply with zero or more register map value readings.

Field Type Description
items repeated RegMapValue none

ShutdownRequest

Shutdown request

Field Type Description
action ShutdownAction Specific shutdown action to execute

TriggerConfig

Trigger block configuration.

Field Type Description
shutter_input ShutterIn Define the shutter input
t0_input T0SyncIn Define the T0 input.
busy_output BusyOut What signal to put on the busy out.
auto_shutter_open_us float Set shutter open duration in microseconds. Granularity is 25 ns.
Choose either auto_shutter_open_us or auto_shutter_open.
Only when useful when using AUTO_GEN or AUTO_GEN_EXT_START.
auto_shutter_close_us float Shutter close duration in microseconds. Granularity is 25 ns.
Choose either auto_shutter_close_us or auto_shutter_close
Only when useful when using AUTO_GEN or AUTO_GEN_EXT_START.
shutter_count uint32 Number of shutters to generate. Don't set or set to 0 for infinite.
auto_shutter_open uint32 Set shutter open duration in 25 ns clocks.
Choose either auto_shutter_open_us or auto_shutter_open.
Only when useful when using AUTO_GEN or AUTO_GEN_EXT_START.
auto_shutter_close uint32 Shutter close duration in in 25 ns clocks..
Choose either auto_shutter_close_us or auto_shutter_close
Only when useful when using AUTO_GEN or AUTO_GEN_EXT_START.

TriggerStatus

Returns the shutter status.

Field Type Description
enabled bool Whether or not the trigger circuit is enabled.
config TriggerConfig Current trigger config.
auto_shutter_busy bool Whether or not the auto-shutter is busy
software_shutter_open bool Whether or not the software shutter is open
shutter_counter uint32 Number of shutters output
t0sync_counter uint32 Number of T0 Syncs output

UpdateCall

Expert function, do not use!

Field Type Description
action UpdateAction none
sequence uint32 none
details string none
data bytes none

UpdateResponse

Expert function, do not use!

Field Type Description
result UpdateResult none
sequence uint32 none
details string none

XGbeConfig

Configure data stream Via 10 Gbe Ethernet

Field Type Description
idx uint32 Chip index
primary XGbeLinkConfig Primary link configuration
secondary XGbeLinkConfig Secondary link configuration. Don't set if you do not want to use a secondary link. Make sure the primary.port != secondary.port
ignoreLockState bool For diagnostics only! Don't set!

XGbeLinkConfig

10GbE link configuration.
IP addresses are strings formatted as #.#.#.#, e.g. 192.168.1.1
MAC addresses are strings formatted as xx:xx:xx:xx:xx, e.g 00:02:FF:EE:00:11

Field Type Description
source_ip string source IP address
dest_ip string destination IP address
dest_mac string destination MAC address (default = ff:ff:ff:ff:ff:ff)
port uint32 Base port, default: 43210 for primary and 43211 for secondary.
For single 10GbE link configurations the source and destination port will be 'port' for top and 'port+1' for bottom, unless a second port number is provided in the most-significant 2 bytes of 'port', which will be used for bottom (e.g. set both port numbers to the same value if top and bottom data is to be received on one port).
For dual 10GbE link the primary port will be used for top and the secondary port for bottom.

Enums

BusyOut

The busy-out can be routed to the external IO to indicate the state of the trigger logic.

Name Number Description
BUSY_OUT_NONE 0 No busy output (output will be low)
BUSY_OUT_AUTO_SHUTTER_BUSY 1 The auto_shutter_busy signal.
BUSY_OUT_T0_SYNC 2 Direct copy the T0Sync signal
BUSY_OUT_SHUTTER 3 Direct copy the SHUTTER signal

DataStreamPath

DataStreamPath defines the way a link is configured.

Name Number Description
_DSPATH_NONE 0 Don't use
DSPATH_SLOW_CONTROL 1 none
DSPATH_XGBE 2 10GbE data path
DSPATH_2XGBE 4 2x 10GbE data path
DSPATH_OPTICAL 8 Optical connection data path (FireFly devices)

PixelChipType

Pixelchip type identifier.

Name Number Description
UNKNOWN 0 Unknown chip type
TIMEPIX4 1 Chip is a Timepix4 chip.
Use of Timepix4 service is possible with this chip type only.
MEDIPIX4 2 Chip is a Medipix4 chip.
Use of Medipix4 service is possible with this chip type only.

RegMapOp

Type of operation to execute on the register map.

Name Number Description
READ 0 Read a value from a register
WRITE 1 Write a value to a register
WRITE_READ 2 Write a value to a register, and read it back
MODIFY 3 Modify the register using the mask:
(*addr) = ((*addr) & ~mask) | (value & mask)
MODIFY_READ 4 Same as MODIFY, but also reads back the result

ShutdownAction

Allowed shutdown actions

Name Number Description
STOP_SERVICE 0 Stop RPC service
RESTART_SERVICE 1 Restart RPC service
SHUTDOWN 2 Power off SPIDR4 control board
REBOOT 3 Reboot the SPIDR4 board

ShutterIn

Shutter Input

Name Number Description
SHUTTER_IN_SOFTWARE 0 Through software (use Trigger::ShutterOpen() and Trigger::ShutterClose())
SHUTTER_IN_AUTO_GEN 1 Using the auto-generator (use Trigger:StartAutoShutter() )
SHUTTER_IN_EXTERNAL 2 Using the external input (high->open, lo->close)
SHUTTER_IN_AUTO_GEN_EXT_START 3 Using the auto-generator.
Started on the rising edge of the external input.

T0SyncIn

Name Number Description
T0SYNC_IN_SOFTWARE 0 Through software, use Trigger::T0Sync()
T0SYNC_IN_EXTERNAL 1 Using external input.

UpdateAction

Expert function, do not use!

Name Number Description
RESET 0 none
TRANSFER 1 none
RESULT 2 none

UpdateResult

Expert function, do not use!

Name Number Description
SUCCESS 0 none
ERROR_SEQUENCE 10 none
ERROR_WRITING 11 none

pixelchip.proto

Services

Medipix4

Medipix4 chip controls.

Methods 
ReadReg(ReadRegRequest) ReadRegReply
Read register request. 

WriteReg(WriteRegRequest) WriteRegReply
Write register request. 

SimpleRead(SimpleReadRequest) SimpleReadReply
Simple register read, for registers up to 32 bit.
Converts the entire register value to a integer.

For example, getting the chip ID:
print( "ChipId: %08x" % tpx4stub.SimpleRead(SimpleReadRequest(idx=0, addr=0x9000)).val ) 

SimpleWrite(SimpleWriteRequest) Empty
Simple register write, for registers up to 32 bit.

For example, setting a the DAC_VbiasADC:
tpx4stub.SimpleWrite( SimpleWriteRequest(idx=0, addr=0xA000, val=128) )

Timepix4

Timepix chip controls.

Methods 
Reset(Empty) Empty
Resets the Pixel matrix. 

ReadReg(ReadRegRequest) ReadRegReply
Read register request. 

WriteReg(WriteRegRequest) WriteRegReply
Write register request. 

SimpleRead(SimpleReadRequest) SimpleReadReply
Simple register read, for registers up to 32 bit.
Converts the entire register value to a integer.

For example, getting the chip ID:
print( "ChipId: %08x" % tpx4stub.SimpleRead(SimpleReadRequest(idx=0, addr=0x9000)).val ) 

SimpleWrite(SimpleWriteRequest) Empty
Simple register write, for registers up to 32 bit.

For example, setting a the DAC_VbiasADC:
tpx4stub.SimpleWrite( SimpleWriteRequest(idx=0, addr=0xA000, val=128) ) 

RunScript(ChipStringValue) Empty
Runs a configuration script (.adat).
All scripts must be located in the default script directory on the control SD-card, most likely this is /etc/control/scripts.
The string value must be the filename without extension, or directory. e.g. the file it will try to find is:
/etc/control/scripts/.adat 

SetDacs(DacValueList) Empty
Set one or more DACs.
If a DAC value is out of range an error will be returned. 

GetDacs(ChipIndex) DacValueList
Get all DAC values for specified chip. 

ConfigAdc(Tpx4AdcConfig) Empty
Configure the ADC. 

AdcRead(Tpx4AdcRequest) FloatValue
Starts and returns an ADC conversion.
Note that the ADC is connected to the DAC_OUT. As such any signal selected on this line will be sampled. 

PixelMatrixReset(ChipIndex) Empty
Resets the entire pixel matrix to its defaults. 

ConfigPixels(Tpx4PixelConfig) Empty
Sets the pixel configuration of the entire chip. 
 Expects 512 x 448 8-bit pixel configurations, order:
 For each Half(top, bottom) 
 For each colum (0..223) 
 For each SPGroup (0..15) 
 For each SuperPixel (0..3) 
 Write 8 x Pixel config (8 bits)
 See: https://timepix4.web.cern.ch/timepix4/timepix4/ChipOperation/configuration_and_accessing_the_matrix.html#id1
The first pixel written is the pixel 0 of superpixel 0, of SPgroup 0 of column 0, of the bottom half.
The last pixel written is pixel 7 of superpixel 3 of SPgroup 15 of column 223 of the top half. 

ConfigGetPixels(ChipIndex) Tpx4PixelConfig
Reads out the pixel configuration. Order is same as ConfigPixels. 

ConfigPixelsPartial(Tpx4PartialPixelConfig) Empty
Partially configures the pixel matrix. Either using columns or superpixel addressing.

TODO 

ConfigPixelsBroadcast(Tpx4BroadcastPixelConfig) Empty
Broadcast the pixel configuration per column.
When no specific columns are provided the column configuration will be set to all column top and bottom.
Note that the broadcast only consists of pixel configurations for one SPGroup. It will be applied to ALL SPGroups in that column!
Expects 32 bytes in 'pixels'.
Order:
For each SuperPixel (0..3)
Write 8 x Pixel config (8 bits) 

ConfigSPGroups(Tpx4SPGroupConfig) Empty
Configures all SPGroups. 
 Expects 32 x 224 24-bit SPGroup configurations, ingroups of 3 bytes per configuration. 
 Big-endian encoded. Order: 
 For each half (top, bottom): 
 For each column (0..223): 
 For each SPGroup (0..15): 
 Write SPGroup config (24 bits) 
 See: https://timepix4.web.cern.ch/timepix4/timepix4/ChipOperation/configuration_and_accessing_the_matrix.html#id2 


ConfigGetSPGroups(ChipIndex) Tpx4SPGroupConfig
Reads out the pixel group configuration.
Order is the same as ConfigSPGRoups. 

ConfigSPGroupsBroadcast(Tpx4BroadcastSPGroupConfig) Empty
Broadcast SPGroup config to to all or selected columns.
When no spefic columns are provided the column configuration will be set to all column top and bottom.

Expects 16 SPGroup configurations (384 bits) 

ConfigSPGroupsPartial(Tpx4PartialSPGroupConfig) Empty
Set SPGroup config to selected SPGroups.
For each item you must specify the half (top/bottom), the column (0..223) and the SPGroup (0..15)

TODO 

PacketReadout(ChipIndex) Tpx4Packets
Reads out the TPX4 packets through the SlowControl interface.
Starting this call will enable a thread which continuously poll the PACKET_READOUT_BOTTOM and PACKET_READOUT_TOP registers and may impact performance of the control application and other SC commands. 

PacketReadout2(Tpx4ReadoutOptions) Tpx4Packets
Packet readout with options. 

PacketReadoutBurst(Tpx4BurstReadoutOptions) Tpx4Packets
Read out a predefined number of packets.
Can not be used at the same time as PacketReadout2. 

ShutterSetConfig(Tpx4ShutterConfig) Tpx4ShutterConfig
Configures the shutter.
Returned value is the actual values applied. As not all shutters are valid, the closest valid shutter duration will be chosen. 

ShutterGetConfig(ChipIndex) Tpx4ShutterConfig
Returns the current shutter configuration. 

ShutterOpen(ChipIndex) Empty
Opens the shutter (MATRIX_CTRL <= OPEN_SHUTTER). 

ShutterClose(ChipIndex) Empty
Closes the shutter (MATRIX_CTRL <= CLOSE_SHUTTER). 

ShutterStop(ChipIndex) Empty
Stops the shutter (MATRIX_CTRL <= STOP_SHUTTER). 

T0Sync(ChipIndex) Empty
Issues a T0Sync command (MATRIX_CTRL <= T0_SYNC). 

TestPulseSetConfig(Tpx4TestPulseConfig) Tpx4TestPulseConfig
Configures the test-pulse. 

TestPulseGetConfig(ChipIndex) Tpx4TestPulseConfig
Returns the current test-pulse configuration. 

TestPulseEnable(ChipIndex) Empty
Enables test-pulse (register TP_CONF.tp_enable=1). 

TestPulseDisable(ChipIndex) Empty
Disables test-pulses (register TP_CONF.tp_enable=0). 

TestPulseIsEnabled(ChipIndex) ChipBoolValue
Check if test-pulses are enabled (Returns TP_CONF.tp_enable=1). 

TestPulseEnableColumns(Tpx4TestPulseColumnEnable) Empty
Update the enabled test-pulse double-columns. 

TestPulseStart(ChipIndex) Empty
Start the test pulse (MTRIX_CTRL <= TP_EN). 

TestPulseStop(ChipIndex) Empty
Stop a running test pulse (MTRIX_CTRL <= STOP_TP). 

ReadoutSetConfig(Tpx4ReadoutConfig) Empty
Configure readout mode. 

ReadoutGetConfig(ChipIndex) Tpx4ReadoutConfig
Return readout configuration. 

StatusMonSetConfig(Tpx4StatusMonConfig) Empty
Sets the status and monitoring configuration to both halfs of the chip.

If this is not what you want, use direct register access. 

StatusMonGetConfig(ChipIndex) Tpx4StatusMonConfig
Returns the status and monitoring configuration of the bottom half.

Messages

DacValue

A single DAC value.

Field Type Description
dac Tpx4Dac DAC addressed
value uint32 DAC value

DacValueList

List of DAC values.

Field Type Description
idx uint32 Chip index
items repeated DacValue List of DAC values

ReadRegReply

Read register reply.

Field Type Description
idx uint32 Chip index
addr int32 Register address
count int32 number of registers from address
stride int32 Register stride
data bytes Register data

ReadRegRequest

Read register request.

Field Type Description
idx uint32 Chip index
addr int32 Register address
count int32 No of registers to read from regAddr.
stride int32 Stride
length int32 Optional length, when not set uses full register.

SimpleReadReply

Simple read reply for up to 32 bit values per register.

Field Type Description
idx uint32 none
addr uint32 none
val uint32 none

SimpleReadRequest

Simple read request for up to 32 bit values per register.

Field Type Description
idx uint32 none
addr uint32 none

SimpleWriteRequest

Simple write request for up to 32 bit values per register.

Field Type Description
idx uint32 none
addr uint32 none
val uint32 none
mask uint32 none

Tpx4AdcConfig

Field Type Description
idx int32 Chip index
nperiods uint32 ADC cycles 1-65535. 8192 is a good value for this.
clock_ref uint32 Clock ref 306 Hz to 20 MHz, with 50 ns steps.
Clock will be rounded to closest possible speed.

Tpx4AdcRequest

ADC conversion request.

Field Type Description
idx int32 Chip index to sample
dac_out Tpx4DacOut DAC out to sample
external bool Use external ADC (if supported)

Tpx4BroadcastPixelConfig

Pixel broadcast message.
See Timepix4::ConfigPixelsBroadcast()

Field Type Description
idx int32 Chip index
columns repeated Tpx4ColumnAddress Columns to use, or empty for all columns
config bytes 512 pixels (contains a double column of 256 pixels)

Tpx4BroadcastSPGroupConfig

SPGroup broadcast message.
See Timepix4::ConfigSPGroupsBroadcast()

Field Type Description
idx int32 Chip index
columns repeated Tpx4ColumnAddress Columns to use, or keep empty for all columns
config repeated uint32 16 SPGroup configurations, broadcast to all columns

Tpx4BurstReadoutOptions

Field Type Description
idx int32 Chip index
half Tpx4Half Which part to read
count uint32 Number of packets to read. Must be a multiple of 4.

Tpx4ColumnAddress

A double column address.

Field Type Description
half Tpx4Half Which chip half, either TPX4_BOTTOM or TPX4_TOP
column int32 Double column 0..223

Tpx4Packets

Streamed message containing TPX4 packets read out through the SlowControl interface.

Field Type Description
idx int32 Chip index
packets repeated uint64 A sequence of packets
half Tpx4Half The half (top/bottom) the packets came from. 'both' if unknown.

Tpx4PartialPixelConfig

Configures a part of the pixel matrix.
This can be a combination of Columns pixels configuration (512 pixels)
or SPGroup pixel configurations (32 pixels).

Column and SPGroup configurations may be intermixed.

See Timepix4::ConfigPixelsPartial()

Field Type Description
idx int32 Chip index
parts repeated Tpx4PartialPixelConfig.Tpx4PixelPart One or more partial pixel configurations.

Tpx4PartialPixelConfig.Tpx4PixelPart

Partial pixel configuration element.
This can either be a column (config = 512 bytes, sp_group is ignored),
or a superpixel (config = 32 bytes, column and sp_group must be set).
Any other combination will result in an error.

Field Type Description
half Tpx4Half none
column int32 none
sp_group int32 none
config bytes none

Tpx4PartialSPGroupConfig

Message to partially configure a SPGroup.
See Timepix4::ConfigSPGroupsPartial()

Field Type Description
idx int32 Chip index
parts repeated Tpx4PartialSPGroupConfig.Tpx4SPGroupPart none

Tpx4PartialSPGroupConfig.Tpx4SPGroupPart

Field Type Description
half Tpx4Half none
column int32 none
sp_group int32 none
config uint32 none

Tpx4PixelConfig

Full PixelConfiguration object.
See Timepix4::ConfigPixels.

Field Type Description
idx int32 Chip index
config bytes Pixel configuration. Must consist of 229376 bytes (448x512 pixels, full matrix top and bottom) Order: 
 For each Half(top, bottom) 
 For each colum (0..223) 
 For each SPGroup (0..15) 
 For each SuperPixel (0..3) 
 Write 8 x Pixel config (8 bits)
setTpColumns bool Enable automatically setting test-pulse columns

Tpx4ReadoutConfig

Configure the readout mode.
Note that gain and polarity are replaced by frontend mode, as polarity and gain allow for invalid settings.
(Partially) configures registers:

  • MATRIX_CONF

  • RO_CTRL_TOP/BOTTOM

  • PC24B (if pc24b_thr >= 128)

  • TOA_PRESET

  • TOA_CONF

Field Type Description
idx int32 Index
mode Tpx4ReadoutOp Mode to readout
pc24b_thr uint32 Threshold for photon counting mode (TPX4_READOUT_PC24), in hits. Note that this value is rounded to a multiple of 256.

Not setting this value will skip setting the threshold register.
gain Tpx4Gain Gain mode
Deprecated: use analog_frontend_mode.
polarity bool Set polarity (true - hole collection, false - electron collection)
Deprecated: use analog_frontend_mode.
toa_enable bool Enable Time-of-Arrival
toa_config Tpx4ToAConfig Further ToA configuration (optional, otherwise doesn't modify registers)
analog_frontend_mode Tpx4AnalogFrontEndMode Analog Front-end mode. Replaces polarity and gain.

Tpx4ReadoutOptions

Packet read-out options (over SlowControl interface).

Field Type Description
idx int32 Chip index
half Tpx4Half Which part to stream
forward_empty bool Enable forwarding of empty packets (0xffffffff00000000).
Note: Empty packets are internally suppressed for optimization purposes. As such only a single empty packet frame will be included and only if reading all top or bottom registers are empty.

Tpx4SPGroupConfig

Message for configuring ALL superpixel groups.
See Timepix4::ConfigSPGroups()

Field Type Description
idx int32 none
config repeated uint32 none

Tpx4ShutterConfig

Shutter configuration.

Field Type Description
idx int32 Chip index
mode Tpx4ShutterMode Mode to chose
input Tpx4ShutterInput Select input to control the shutter subsystem.
prog_open_duration uint64 Set shutter open duration in 25 ns ticks, only for TPX4_SHUTTER_MODE_*.
Note: The value is converted to a semi-floating point value but with positive exponent ranging from 0 to 31 and 11 bit fraction, no sign. The maximum value therefore is 0x7FF << 31, or 4395899027456 ticks, i.e. 30.5 hours.
prog_close_duration uint64 Set shutter close duration in 25 ns ticks, only for TPX4_SHUTTER_MODE_*
prog_open_us float Set shutter open duration in us.
Due to the underlying coding the duration may be modified to match the closest possible duration. Review the returned Tpx4ShutterConfig object for the actual duration.
prog_close_us float Set shutter close duration in us.
Due to the underlying coding the duration may be modified to match the closest possible duration. Review the returned Tpx4ShutterConfig object for the actual duration.

Tpx4StatusMonConfig

Status and monitoring configuration (register 0x4C02 and 0xCC02).

Field Type Description
idx int32 Chip index
enable bool Enable status and monitoring packet generation
heartbeat bool Enable the heartbeat
heartbeat_shift int32 Heartbeat shift. A heartbeat is send every (1 << heatbeat_shift) * 25 ns.
global_time_reset bool Resets the global time on T0-sync
global_time bool Enable the glboal time counter in status packets
ctrl_data_test bool Generate ctrl data test packets
signal_select Tpx4SignalSelect Signal select.

Tpx4TestPulseColumnEnable

Configure the enabled columns

Field Type Description
idx int32 Chip index
columns repeated Tpx4ColumnAddress Double columns to enable test-pulse on.
Keep empty to enable ALL columns (top and bottom, not advised!)

Tpx4TestPulseConfig

Test-pulse configuration.

Field Type Description
idx int32 Chip index
count uint32 Set TP on duration in 25 ns ticks.
Max value: 65535
period_on uint32 Set TP on duration in 25 ns ticks.
Max value: 65535
Either specify period_on_s or period_on, but not both.
period_off uint32 Set TP off duration in 25 ns ticks.
Max value: 65535
Either specify period_off_s or period_off, but not both.
period_on_us float Set TP on duration in microseconds.
Max value: 1638.4 us
Either specify period_on_s or period_on, but not both.
period_off_us float Set TP off duration in microseconds.
Max value: 1638.4 us
Either specify period_off_us or period_off, but not both.
link_shutter bool When enabled, the shutter is opened if the test-pulse is enabled.
digital bool Use digital test-pulse.
shutter2tp_latency uint32 Test pulse latency after shutter is opened, in 25 ns ticks.
Max value is 127.
phase uint32 Clock phase, in units of 1.5625 ns.
Max value is 15.
columns repeated Tpx4ColumnAddress double columns to enable test-pulse on.
Keep empty to enable ALL columns (top and bottom)

Tpx4ToAConfig

Time-of-Arrival configuration (provided in TpxReadoutConfig message).

Field Type Description
preset uint32 Time of arrival preset, loaded at T0 (0..65535)
maximum uint32 Time of arrival maximum value (1..65535). 0 will not set the value.
falling_edge bool When set the ToA triggers on falling edge (otherwise rising)
stop_on_overflow bool Set set, ToA stops on overflow
gray_counter bool When set use gray counter, otherwise binary

WriteRegReply

Write register reply.

Field Type Description
idx uint32 Returned on success

WriteRegRequest

Write register request.

Field Type Description
idx uint32 Chip index
addr int32 Register address
count int32 number of registers from address
stride int32 Register stride
data bytes Register data

Enums

Tpx4AnalogFrontEndMode

Analog front-end mode.

Configures settings according to: https://timepix4.web.cern.ch/timepix4/timepix4/ChipDescription/AnalogFrontEnd.html#id2

Name Number Description
TPX4_AFEM_USE_LEGACY 0 Use Tpx4ReadoutConfig polarity and gain properties.
TPX4_AFEM_HIGH_GAIN_ELECTRON_COLLECTION 1 High-Gain electron collection
TPX4_AFEM_LOW_GAIN_ELECTRON_COLLECTION 2 Low-Gain electron collection
TPX4_AFEM_HIGH_GAIN_HOLE_COLLECTION 3 High-Gain hole collection
TPX4_AFEM_LOW_GAIN_HOLE_COLLECTION 4 Low-Gain hole collection
TPX4_AFEM_LOG_GAIN_HOLE_COLLECTION 5 Logarithmic-Gain hole collection

Tpx4Dac

Enumeration of DAC fields. This is a combination of the ‘normal’ DACs and the GAIN dacs (VDAC)

Name Number Description
TPX4_DAC_UNKNOWN 0 none
TPX4_DAC_VBIASADC 40960 none
TPX4_DAC_VBIASDAC 40961 none
TPX4_DAC_VBIASDISCPMOS 40962 none
TPX4_DAC_VBIASDISCTRAFF 40963 none
TPX4_DAC_VBIASDISCTAILNMOS 40964 none
TPX4_DAC_VBIASIKRUM 40965 none
TPX4_DAC_VBIASLEVELSHIFT 40966 none
TPX4_DAC_VBIASPREAMP 40967 none
TPX4_DAC_VCASCDISC 40968 none
TPX4_DAC_VCASCPREAMP 40969 none
TPX4_DAC_VCONTROLVCO 40970 none
TPX4_DAC_VFBK 40971 none
TPX4_DAC_VTHRESHOLD 40972 none
TPX4_DAC_VTPULSECOARSE 40973 none
TPX4_DAC_VTPULSEFINE 40974 none
TPX4_VDAC_GAIN_VDAC_VCASCDISC 40976 none
TPX4_VDAC_GAIN_VDAC_VCASCPREAMP 40977 none
TPX4_VDAC_GAIN_VDAC_VCONTROLVCO 40978 none
TPX4_VDAC_GAIN_VDAC_VFBK 40979 none
TPX4_VDAC_GAIN_VDAC_VTHRESHOLD 40980 none
TPX4_VDAC_GAIN_VDAC_VTPULSECOARSE 40981 none
TPX4_VDAC_GAIN_VDAC_VTPULSEFINE 40982 none

Tpx4DacOut

List of DAC-out choices.

Name Number Description
TPX4_OUT_HIZ 0 High impedance
TPX4_OUT_VBIASDISCTRAFF_TOP 268435456 AEOC_TOP VbiasDiscTRAFF
TPX4_OUT_VBIASDISCPMOS_TOP 268437504 AEOC_TOP VbiasDiscPMOS
TPX4_OUT_VBIASLEVELSHIFTPMOS_TOP 268439552 AEOC_TOP VbiasLevelShiftPMOS
TPX4_OUT_VBIASDAC_BIAS_TOP 268441600 AEOC_TOP VbiasDAC_bias
TPX4_OUT_VBIASDISCTAILNMOS_TOP 268443648 AEOC_TOP VbiasDiscTailNMOS
TPX4_OUT_VBIASIKRUM_TOP 268445696 AEOC_TOP VbiasIkrum
TPX4_OUT_VBIASPREAMP_TOP 268447744 AEOC_TOP VbiasPreamp
TPX4_OUT_VCO_VCONTROL_TOP 268449792 AEOC_TOP VCO_Vcontrol
TPX4_OUT_PS_MONITOR_ANALOG_AEOC_13_TOP 268451840 AEOC_TOP PS_monitor_analog_AEOC_13
TPX4_OUT_PS_MONITOR_ANALOG_AEOC_32_TOP 268453888 AEOC_TOP PS_monitor_analog_AEOC_32
TPX4_OUT_HIZ_CENTRE 536870912 @ Reset
TPX4_OUT_VBANDGAP_100MV_AT_RES 541065216 VBandGap 100mV at Res
TPX4_OUT_TEMP_SENSE 545259520 Temp Sensor
TPX4_OUT_VBIAS_BINDAC 549453824 DAC LSB VBias
TPX4_OUT_VCASC_BINDAC 553648128 DAC LSB Cascode
TPX4_OUT_VBANDGAP_100MV 557842432 VBandGap (~100mV)
TPX4_OUT_VBIASPREAMP 562036736 VBiasPreamp (I)
TPX4_OUT_VBIASDISCTAILNMOS 566231040 VBiasDiscTailNMOS (I)
TPX4_OUT_VBIASIKRUM 570425344 VBiasIkrum (I)
TPX4_OUT_VBIASDAC 574619648 VBiasDAC (I)
TPX4_OUT_VBIASLEVELSHIFT 578813952 VBiasLevelShift (I)
TPX4_OUT_VBIASDISCPMOS 583008256 VBiasDiscPMOS (I)
TPX4_OUT_VBIASDISCTRAFF 587202560 VBiasDiscTRAFF (I)
TPX4_OUT_VBIASADC 591396864 VbiasADC
TPX4_OUT_VCASCPREAMP_BOT 595591168 VCascPreamp (V)
TPX4_OUT_VBFK_BOT 599785472 VFBK (I)
TPX4_OUT_VTPULSECOARSE_BOT 603979776 VTpulseCoarse (V)
TPX4_OUT_VCASCDISC_BOT 608174080 VCascDisc (V)
TPX4_OUT_VCONTROLVCO_BOT 612368384 VcontrolVCO
TPX4_OUT_VTHRESHOLD_BOT 616562688 VThreshold (V)
TPX4_OUT_VTPULSEFINE_BOT 620756992 VTpulseFine (V)
TPX4_OUT_VCASCPREAMP_TOP 624951296 VCascPreamp (V)
TPX4_OUT_VBFK_TOP 629145600 VFBK (I)
TPX4_OUT_VTPULSECOARSE_TOP 633339904 VTpulseCoarse (V)
TPX4_OUT_VCASCDISC_TOP 637534208 VCascDisc (V)
TPX4_OUT_VCONTROLVCO_TOP 641728512 VcontrolVCO
TPX4_OUT_VTHRESHOLD_TOP 645922816 VThreshold (V)
TPX4_OUT_VTPULSEFINE_TOP 650117120 VTpulseFine (V)
TPX4_OUT_PS_MONTIOR_ANALOG_13_0 654311424 PS_monitor placed at [270,15000]
TPX4_OUT_PS_MONTIOR_ANALOG_13_1 658505728 PS_monitor placed at [8300,15000]
TPX4_OUT_PS_MONTIOR_ANALOG_13_2 662700032 PS_monitor placed at [16330,15000]
TPX4_OUT_PS_MONTIOR_ANALOG_13_3 666894336 PS_monitor placed at [24360,15000]
TPX4_OUT_PS_MONTIOR_ANALOG_23_0 671088640 PS_monitor placed at [270,15000]
TPX4_OUT_PS_MONTIOR_ANALOG_23_1 675282944 PS_monitor placed at [16330,15000]
TPX4_OUT_PS_MONTIOR_ANALOG_23_2 679477248 PS_monitor placed at [16330,15000]
TPX4_OUT_PS_MONTIOR_ANALOG_23_3 683671552 PS_monitor placed at [24360,15000]
TPX4_OUT_PS_MONTIOR_DIGITAL_13_0 687865856 PS_monitor placed at [270,15000]
TPX4_OUT_PS_MONTIOR_DIGITAL_13_1 692060160 PS_monitor placed at [16330,15000]
TPX4_OUT_PS_MONTIOR_DIGITAL_13_2 696254464 PS_monitor placed at [16330,15000]
TPX4_OUT_PS_MONTIOR_DIGITAL_13_3 700448768 PS_monitor placed at [24360,15000]
TPX4_OUT_PS_MONTIOR_DIGITAL_23_0 704643072 PS_monitor placed at [270,15000]
TPX4_OUT_PS_MONTIOR_DIGITAL_23_1 708837376 PS_monitor placed at [16330,15000]
TPX4_OUT_PS_MONTIOR_DIGITAL_23_2 713031680 PS_monitor placed at [16330,15000]
TPX4_OUT_PS_MONTIOR_DIGITAL_23_3 717225984 PS_monitor placed at [24360,15000]
TPX4_OUT_VBIASDISCTRAFF_BOT 805306368 AEOC_BOT VbiasDiscTRAFF
TPX4_OUT_VBIASDISCPMOS_BOT 805306369 AEOC_BOT VbiasDiscPMOS
TPX4_OUT_VBIASLEVELSHIFTPMOS_BOT 805306370 AEOC_BOT VbiasLevelShiftPMOS
TPX4_OUT_VBIASDAC_BIAS_BOT 805306371 AEOC_BOT VbiasDAC_bias
TPX4_OUT_VBIASDISCTAILNMOS_BOT 805306372 AEOC_BOT VbiasDiscTailNMOS
TPX4_OUT_VBIASIKRUM_BOT 805306373 AEOC_BOT VbiasIkrum
TPX4_OUT_VBIASPREAMP_BOT 805306374 AEOC_BOT VbiasPreamp
TPX4_OUT_VCO_VCONTROL_BOT 805306375 AEOC_BOT VCO_Vcontrol
TPX4_OUT_PS_MONITOR_ANALOG_AEOC_13_BOT 805306376 AEOC_BOT PS_monitor_analog_AEOC_13
TPX4_OUT_PS_MONITOR_ANALOG_AEOC_32_BOT 805306377 AEOC_BOT PS_monitor_analog_AEOC_32
TPX4_OUT_TOP_ANALOG_IN 1073741824 External analog input from top edge periphery
TPX4_OUT_CENTRE_ANALOG_IN 1342177280 External analog input from center edge periphery
TPX4_OUT_BOT_ANALOG_IN 1610612736 External analog input from bottom edge periphery

Tpx4Gain

Gain mode.

deprecated: use analog_frontend_mode.

Name Number Description
TPX4_NO_GAIN 0 No gain applied
TPX4_LOW_GAIN 1 Low gain
TPX4_LOG_GAIN 2 Log gain (use only with polarity=true)
TPX4_LOW_LOG_GAIN 3 Low log gain (don't use this! Present for legacy reasons)

Tpx4Half

TPX4 top or bottom.

Name Number Description
TPX4_BOTH 0 none
TPX4_BOTTOM 1 none
TPX4_TOP 2 none
TPX4_UNKNOWN 3 none

Tpx4ReadoutOp

Read-out mode for data acquisition.

Name Number Description
TPX4_READOUT_TOA_TOT 0 Time over threshold mode
TPX4_READOUT_PC24 1 24 bit photon counting mdoe
TPX4_READOUT_FRAME8 2 8 bit framebased readout
TPX4_READOUT_FRAME16 3 16 bit framebase readout

Tpx4ShutterInput

Shutter input source.

Name Number Description
TPX4_SHUTTER_INPUT_PAD 0 Single shutter on trigger (shutter_select=0)
TPX4_SHUTTER_INPUT_SLOW_CONTROL 1 Shutter repeated after start (shutter_select=1)

Tpx4ShutterMode

The shutter modes.

Name Number Description
TPX4_SHUTTER_MODE_PROG_SINGLE 0 Single shutter on trigger (periodic_shutter=0, shutter_mode=1)
TPX4_SHUTTER_MODE_PROG_REPEAT 1 Shutter repeated after start (periodic_shutter=1, shutter_mode=1)
TPX4_SHUTTER_MODE_MANUAL 2 Shutter controlled by selected input (shutter_mode=0)

Tpx4SignalSelect

Status and monitoring signal select.

Name Number Description
TPX4_SIGNAL_SELECT_NONE 0 none
TPX4_SIGNAL_SELECT_CRW_NEXT_FRAME 1 none
TPX4_SIGNAL_SELECT_INVALID 15 none

peripheral.proto

Services

Peripheral

Peripheral service exposes devices on the board, not directly related to the pixelchips.

All devices have three distinct types of values:
Configuration, Sensor and Actuator.

Depending on the type you may be able to Set, or Get them.

In the back-end these peripheral values are provided by Devices, which execute the actual operations on the data. It is possible to request the status of these specific devices and to enable and disable then.

Methods 
GetSenseData(Empty) DataPointList
Request all sensor data. 

SenseNow(StringList) DataPointList
Update specific sensor values now.
StringList contains variable IDs to update.
All data-points updated.
This call is blocking and may require time depending on the number of variables requested. 

GetMetaData(StringList) MetaDataList
Returns MetaData for DataPoints.
StringList contains the IDs of which you want know the MetaData.
IDs can be of any specific variable (e.g. config, sense or actuate). 

GetConfigData(Empty) DataPointList
Returns the configuration data. 

GetActuateData(Empty) DataPointList
Returns all actuator data. 

ActuateNow(DataPointList) Empty
Sets actuator values and applies them.
This call is blocking until actuation has been applied. 

GetDeviceStatus(Empty) DeviceStatusList
Returns all devices configured and their status. 

EnableDevice(StringValue) DeviceStatus
Enable a device, will configure it if possible.
This call is blocking until the Device has been successfully enabled.
StringValue contains the name of the Device.
Returns the DeviceStatus of the specified Device. 

DisableDevice(StringValue) DeviceStatus
Disable a device with that name.
StringValue contains the name of the Device.

Messages

DataPoint

Datapoint abstraction, representing a single process variable.

Field Type Description
id string Qualified ID
value Value Value
valid bool Validity of value

DataPointList

List of data-points.

Field Type Description
items repeated DataPoint List of datapoints

DeviceStatus

Status of a device.

Field Type Description
name string Device name
part string Part name (= driver)
valid bool Whether or not the device is valid
disabled bool Whether or not the device is disabled
busname string Bus name (if any)
address int32 Address on bus
busname_mux string Bus name of I2C bus switch (if any)
address_mux int32 Address of the switch
mux_channel int32 Switch channel this device is on

DeviceStatusList

List of board devices.

Field Type Description
items repeated DeviceStatus List of DeviceStatus

MetaData

Meta-data of a datapoint.

Field Type Description
id string Qualified ID
unit string Unit
desc string Description
role DataRole Data role

MetaDataList

Field Type Description
items repeated MetaData none

Value

Field Type Description
type ValueType Type of the value
oneof value.int_value int32 Value, if type is INT
oneof value.float_value float Value, if type is FLOAT
oneof value.bool_value bool Value, if type is BOOLEAN
oneof value.string_value string Value, if type is STRING

Enums

DataRole

Data role of the datapoint.

Name Number Description
SENSOR 0 Data is a sensor value (read only)
ACTUATOR 1 Data is an actuator value
CONFIG 2 Data is a configuration value

ValueType

Type of value.

Name Number Description
INVALID 0 Invalid type (not a type)
INT 1 Integer type (32-bits signed)
FLOAT 2 Floating point type
BOOLEAN 3 Boolean type.
STRING 4 String type....

daq.proto

Services

Daq

SPIDR4 DAQ service.

Methods 
GetVersion(Empty) Version
Returns the build version of the DAQ server. 

GetLogging(Empty) LogLine
Returns console logging as a stream. 

ConfigPipeline(PipelineConfig) Empty
Configures the pipeline, a source to target mapping. 

ConfigDaq(DaqConfig) DaqConfig
Configure the DAQ settings. 

Start(RunProperties) RunProperties
Start the data-acquisition.
Returns the run-properties as applied. 

Stop(Empty) DaqStatus
Stop the data-acquisition and returns the last DaqStatus object.
Contrary to GetStatus, this will return ALL files written during the run, not only those which are new. 

IsRunning(Empty) BoolValue
Check if the DAQ is running. 

GetStatus(Empty) DaqStatus
Get a stream of DAQ status object, sent roughly every half a second.
Note that if the DAQ is not running, no DaqStatus objects will be generated. Check function IsRunning() whether or not the DAQ is running. 

InsertUserData(UserDataFrame) BoolValue
Insert a custom user-data packet into a stream.
If the acquisition is not yet running, packets will be inserted at the beginning of the stream, otherwise they end up embedded in the data stream.
Returns a boolean indicating whether there are user packets still in the queue to be inserted in the data stream (always true when a packet is inserted, but calling this method without an actual packet to insert can be used to poll the status of this queue). 

EnablePixelInspection(EnableMessage) Empty
Enable or disable 'pixel inspection' in a stream, i.e. counting pixels and EoC occurrences. 

GetPixelPacketCount(UInt32Value) UInt64Value
Request the number of 64-bit pixel packets processed (requires active 'pixel inspection'). 

GetShutterRiseCount(UInt32Value) UInt64Value
Request the number of ShutterRise occurrences (requires active 'pixel inspection'). 

GetShutterFallCount(UInt32Value) UInt64Value
Request the number of ShutterFall occurrences (requires active 'pixel inspection'). 

GetHeartbeatCount(UInt32Value) UInt64Value
Request the number of Heartbeat occurrences (requires active 'pixel inspection').

Messages

Consumer

A DAQ consumer.

Field Type Description
oneof target.file_destination FileDestination none
oneof target.udp_address InetAddress none

ConsumerStats

Field Type Description
consumed uint64 Bytes consumed
userdataqueue_count uint32 Number of items (still) in the user data output queue
artifacts repeated string String list of artifacts generated.
When using the file-type consumer the artifacts are file names.

DaqConfig

Message to configure the DAQ process. Currently there is nothing to configure, but we’re sure there will be something to configure in the future!

DaqStatus

Status of the DAQ process.

Field Type Description
stopping bool Whether or not the DAQ is stopping
ts double Time at which the message was generated. Fractional Unix time.
runtime double Time the DAQ process is running, in seconds
stream_stats repeated StreamStats For each stream in the pipeline, run-time information

EnableMessage

Enable or disable a feature of a selected stream.

Field Type Description
stream_idx uint32 Stream index, 0 for first, 1 for second, etc.
enable bool Enable or disable.

FileDestination

Data file destination parameters.

Field Type Description
basename string none
no_date bool none
max_chunk_size uint32 Maximum chunk size in a file, in MB, leave 0 for default (=16 MB). A chunk is a fundamental unit of the SPIDR4 data format. Larger chunks offer better efficiency, but can be more difficult to handle.
max_file_size uint32 Maximum file-size in MB, before creating a new one, leave 0 for default (=4096 MB).

PipelineConfig

A pipeline config.

Field Type Description
streams repeated Stream Configure a number of streams Note: The first stream gets index 0, second index 1, and so on.

Receiver

A DAQ Receiver.

Field Type Description
oneof source.xgbe_address InetAddress none
oneof source.pci_channel uint32 none
buffer_size uint32 Receive buffer size, per pipeline, in MB, leave 0 for default (=1024 MB). The amount of memory allocated for this receiver. The combined amount of allocated memory for all receivers must not exceed the amount of available memory allocated by the cmem driver (at host bootup time), or, if the cmem driver is not used (cmem is mandatory for PCIe read-out only), must not exceed available host user memory.

RunProperties

Properties specific to a DAQ run.

Field Type Description
run_no uint32 The run number to advertise
daq_secs uint32 Number of seconds to run te data acquisition, 0 for infinite

Stream

A part of a pipeline.

Field Type Description
receiver Receiver The receiver
consumers repeated Consumer Consumers, currently limited to a single target
controller_address string The address of the SPIDR4 controller associated with this stream
chip_index int32 The index of the Timepix4 chip associated with this stream
custom_header uint64 Custom frame header for data chunks, used if unequal to zero
include_chip_config bool Whether to include the Timepix4 configuration data (register contents) in the stream

StreamStats

Stream statistics

Field Type Description
received uint64 Bytes received
consumer_stats repeated ConsumerStats Per consumer information

UserDataFrame

Insert user-data frame into a stream during or before DAQ.
Please see the SPIDR4 data file format.
For the frame header:

  • group ID always set to 7

  • content-encoding depends on whether binary (0) or json (1)is provided

  • content ID is the lower 10 bits from the content_id field (>10 bits will be ignored)

Field Type Description
stream_idx uint32 Stream index, 0 for first, 1 for second, etc.
content_id uint32 User-data content type identifier.
Defined by the user to identify the content of the frame. Range: 0..1023
oneof data.binary bytes Binary data to insert
oneof data.json string JSON data to insert
oneof data.status uint32 Status request (no data frame inserted)

Scalar Value Types

.proto Type Notes C++ Type Java Type Python Type
double double double float
float float float float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long
uint32 Uses variable-length encoding. uint32 int int/long
uint64 Uses variable-length encoding. uint64 long int/long
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long
sfixed32 Always four bytes. int32 int int
sfixed64 Always eight bytes. int64 long int/long
bool bool boolean boolean
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode
bytes May contain any arbitrary sequence of bytes. string ByteString str