Low-level software tools¶
Note that some, most or all of the tools described below, may have python equivalents, which are described elsewhere (?).
tpx4item¶
Description¶
The tpx4item tool allows a user to read or write an item in a Timepix4 device connected to a SPIDR4. An item is a register address or name, or the name of a bit field.
Item names adhere to the ‘official’ naming in the Timepix4 manual.
The names are case insensitive and ‘_’ and ‘-‘
characters in the name are treated identically.
Register names have to start with “reg_” followed by the name
as presented in the manual, while bit field names are preceded
by their register name, but without “reg_”.
To see a full list of registers and bit fields, including meta-information
on each such as address and size, type tpx4item list.
A name does not have to be the ‘complete’ name, but must be unique
in the list of Timepix4 item names;
for example: “pixel-bo” is sufficient to select the bit field
named in full by the tool as: “PIXEL_BOT_PIXEL_COLUMN_CONFIG”.
In case the name given does not uniquely match a single named register or bit field
a list of names is shown (either registers or bit fields) that match
with the given name string.
In the case of bit fields this can be a list of names that contain
the given item string anywhere in their full name (try for example tpx4item top).
If no SPIDR4 controller address (option -c) is given, information about the item is displayed, such as full name, (base) address, size in bits and a description. After being read out from a Timepix4 device, registers and bit fields are displayed most-significant part first. If a value is provided in addition to item name or address, that value is written into the Timepix4 item, if the value is valid and within the item’s value range. Multiple registers or bit fields of the same ‘type’ may be read or written in one operation.
This is the ‘usage’ of tpx4item, listing the available options:
Usage: tpx4item -h|E|v -M -c<addr> -r<index>|-R -S<stride>
-s<size> -i<index> -I<stride> -m<mask> <item_name>|<addr>|list [val]
Options:
-h : Show this help text.
-E : Show a number of examples using tpx4item.
-v : Show the version number.
-c <addr> : (IP) address of the SPIDR4 Controller,
or select by number from this list:
0 = 192.168.1.10
1 = 192.168.100.10
2 = 192.16.192.232
3 = 192.168.1.11
4 = 192.168.199.10
-M : Apply item request to a Medipix4 instead of a Timepix4 device
(when not using option -c; otherwise the chip type is auto-detected).
-r <index> : Register index (in case of multiple registers),
in case a register name or bitfield name is given.
-R : Read or write *all* registers or bitfields
with the given name (instead of option -r).
-S <stride>: Register stride when writing to all registers of a named item (default: 1).
(only in combination with option -R).
-s <size> : Separate the named bitfield into sub-fields of <size> bits each.
-i <index> : Single sub-field index to read or write
(in combination with option -s).
-I <stride>: The sub-field 'stride' or increment, in number of sub-fields with
size in bits as defined by option -s: write each 'stride'-th field.
Reading is always with 'stride'=1 (read all sub-fields).
(in combination with option -s; instead of option -i; default: 0).
-m <mask> : Writing a register or bitfield value, only bits corresponding to bits
in <mask> equal to one are modified, the rest remain untouched;
<mask> is given as a hexadecimal number.
<item_name> : A name such as REG_ROUTER_BOT or reg-router-b,
or ROUTER_BOT_CHAN_ENABLE or router-bot-chan, etc.
(bitfields are named preceded by their register 'abbreviation')
(names are case-insensitive, use 'list' to list all known names).
<addr> : A register address (hexadecimal; "0x" not required).
list : (as literal string) Display meta-info on all known registers, followed
by all known bitfields, one line per register or bitfield,
in a column-wise fashion; in combination with option -c the current value
of each Timepix4 item is included (replacing the item description string).
<val> : if provided the value is written to the item on the Timepix4 device
(bitfield, register of sub-field; hex (with 0x) or decimal);
if no value is given the item value is read out and displayed.
If *no* SPIDR4 Controller address is provided,
only meta-info about the item is displayed.
Examples using tpx4item¶
Below find some examples of tpx4item tool usage, all with option “-c 2”, meaning a SPIDR4 Controller at IP address 192.16.192.232 is addressed.
Read a register by address, register name or field name, respectively:
$ tpx4item -c2 6100
SPIDR4 Controller @ 192.16.192.232
->Info: name=REG_PIXEL_GR_BOT (base)address=0x6100 (3584x) bytes=32 "PixelGroupBottom"
Register 0x6100: (MSByte first)
30 28 A0 A3 69 20 29 A8 70 00 31 4B 11 20 A4 B1 08 01 6D 21 60 67 20 23 4B 6C 20 22 ED 30 4B 24
$ tpx4item -c2 reg-pixel-gr-bot
SPIDR4 Controller @ 192.16.192.232
->Info: name=REG_PIXEL_GR_BOT (base)address=0x6100 (3584x) bytes=32 "PixelGroupBottom"
Register 0x6100: (MSByte first)
30 28 A0 A3 69 20 29 A8 70 00 31 4B 11 20 A4 B1 08 01 6D 21 60 67 20 23 4B 6C 20 22 ED 30 4B 24
$ tpx4item -c2 pixel-gr-bot
SPIDR4 Controller @ 192.16.192.232
->Info: name=PIXEL_GR_BOT_PIXEL_GROUP_CONFIG (base)address=0x6100 (3584x) R/W bits=256 [255:0]
"Pixel configuration data"
Bitfield in Register 0x6100: (MSByte first)
30 28 A0 A3 69 20 29 A8 70 00 31 4B 11 20 A4 B1 08 01 6D 21 60 67 20 23 4B 6C 20 22 ED 30 4B 24
Read third byte (“-s8 -i2”) of this register:
$ tpx4item -c2 -s8 -i2 pixel-gr-bot
SPIDR4 Controller @ 192.16.192.232
->Info: name=PIXEL_GR_BOT_PIXEL_GROUP_CONFIG (base)address=0x6100 (3584x) R/W bits=256 [255:0]
"Pixel configuration data"
Bitfield in Register 0x6100 (subfield=8bits,index=2,stride=0):
30
Write 0 to 3rd byte (“-i2”) in the register:
$ tpx4item -c2 -s8 -i2 pixel-gr-bot 0
Write 0 to all bytes (“-s8 -I1”) in the register:
$ tpx4item -c2 -s8 -I1 pixel-gr-bot 0
Write 0x34 to all bytes in the register starting from byte 10 (“-i10”):
$ tpx4item -c2 -s8 -I1 -i10 pixel-gr-bot 0x33
Reading back the result of this operation (note the least-significant byte is the right-most displayed byte):
$ tpx4item -c2 pixel-gr-bot
SPIDR4 Controller @ 192.16.192.232
->Info: name=PIXEL_GR_BOT_PIXEL_GROUP_CONFIG (base)address=0x6100 (3584x) R/W bits=256 [255:0]
"Pixel configuration data"
Bitfield in Register 0x6100: (MSByte first)
33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 00 00 00 00 00 00 00 00 00 00
Set every 8th bit (“-s1 -I8”) in the register starting from bit 7 (“-i 7”) to 1:
$ tpx4item -c2 -s1 -I8 -i7 pixel-gr-bot 1
or alternatively (more elegantly, assuming the register has 8-bit sub-fields): Set bit 7 in each byte (“-s8 -I1”) of the register, using mask 80h (“-m0x80”):
$ tpx4item -c2 -s8 -I1 -m0x80 pixel-gr-bot 0x80
Reading back the result of this operation:
$ tpx4item -c 2 pixel-gr-bot
SPIDR4 Controller @ 192.16.192.232
->Info: name=PIXEL_GR_BOT_PIXEL_GROUP_CONFIG (base)address=0x6100 (3584x) R/W bits=256 [255:0]
"Pixel configuration data"
Bitfield in Register 0x6100: (MSByte first)
B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 B3 80 80 80 80 80 80 80 80 80 80
Clear bit 7 in all bytes in the register starting from byte 8:
$ tpx4item -c2 -s8 -i8 -I1 -m0x80 pixel-gr-bot 0x00
Reading back the result of this operation:
$ tpx4item -c2 pixel-gr-bot
SPIDR4 Controller @ 192.16.192.232
->Info: name=PIXEL_GR_BOT_PIXEL_GROUP_CONFIG (base)address=0x6100 (3584x) RW bits=256 [255:0]
"Pixel configuration data"
Bitfield in Register 0x6100:
33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 00 00 80 80 80 80 80 80 80 80
To do the same in a selected register of the 3584 registers of this type use option “-r<index>”. To do the same to all 3584 registers at once use option “-R”. To do the same to every 16th of the 3584 registers at once add options “-R -S16”.
tpx4hb¶
Tool tpx4hb can be used to display and/or configure the ‘Heartbeat’ packet generation of the Timepix4 chip (as well as enabling/disabling CTRL-DATA packet generation).
This is the ‘usage’ of tpx4hb, listing the available options:
Usage: tpx4hb -h|v -c<addr> -B -T -C<ena> -G<ena> -p<period>
Display or configure a SPIDR4 Timepix4 device's (device #0)
Heartbeat and CTRL-DATA packet generation settings.
-h : Show this help text.
-v : Show the version number.
-c <addr> : (IP) address of the SPIDR4 Controller,
or select by number from this predefined list:
0 = 192.168.1.10
1 = 192.168.100.10
2 = 192.16.192.232
3 = 192.168.1.11
4 = 192.168.199.10
-B : Operate on Timepix4 Bottom half only (default: both).
-T : Operate on Timepix4 Top half only (default: both).
-C <ena> : Enable (1) or disable (0) the CTRL-DATA test packets.
-G <ena> : Enable (1) or disable (0) the Global Timer Counter:
affects the contents of the Heartbeat and CTRL-DATA packets.
-p <period>: Enable or disable Heartbeat packets
(disabled for <period> is 0, enabled for <period>
between 6 and 23 -> period = (2^<period> + 1)*25ns).
Examples of <period>: 6 -> 615 KHz, 10 -> 39 KHz, 15 -> 1221 Hz
20 -> 38.1 Hz, 23 -> 4.768 Hz.
Starting Heartbeat generation on a Timepix4 (both TOP and BOTTOM), and checking afterwards:
$ tpx4hb -c2 -p10
SPIDR4 Controller @ 192.16.192.232
=> TOP:
Heartbeat period: set to 10
=> BOT:
Heartbeat period: set to 10
$ tpx4hb -c2
SPIDR4 Controller @ 192.16.192.232
=> TOP:
Status packets : ENA
Global time cntr: DIS
Heartbeat : ENA
Heartbeat period: 10 (period=1025: 39024.4 Hz)
CTRL-DATA test : DIS
=> BOT:
Status packets : ENA
Global time cntr: DIS
Heartbeat : ENA
Heartbeat period: 10 (period=1025: 39024.4 Hz)
CTRL-DATA test : DIS
tpx4reset¶
Tool tpx4reset instructs the SPIDR4 to execute either a pixel matrix reset or a ‘full’ reset (including various configuration actions) on the (for the time being, single) connected Timepix4 chip:
$ tpx4reset -c 2
SPIDR4 Controller @ 192.16.192.232
Matrix reset TPX4 OKAY
$ tpx4reset -c 2 -F
SPIDR4 Controller @ 192.16.192.232
Reset TPX4 OKAY
spidr4action¶
Tool spidr4action allows a user to stop or restart the control application on the SPIDR4 or power off or reset the SPIDR4:
$ spidr4restart -c2
SPIDR4 Controller @ 192.16.192.232
Restart OKAY
This is the ‘usage’ of spidr4action, listing available options:
Usage: spidr4action [-h|v] -c <addr> [<action>]
Stop, restart, power off or reset a SPIDR4.
-h : Show this help text.
-v : Show the version number.
-c <addr> : (IP) address of the SPIDR4 Controller,
or select by number from this predefined list:
0 = 192.168.1.10
1 = 192.168.100.10
2 = 192.16.192.232
3 = 192.168.1.11
4 = 192.168.199.10
<action> : String to select action to take (default: restart),
one of:
"stop" (Stop RPC service),
"restart" (Restart RPC service),
"shutdown" (Power off SPIDR4),
"reboot" (Reboots SPIDR4).
spidr4log¶
This is the ‘usage’ of spidr4log:
Usage: spidr4log {-h|v] -c<addr>
Display the SPIDR4 Controller ('control app') output and keep the connection open.
Use <Ctrl-C> to disconnect and exit.
Options:
-h : Show this help text.
-v : Show the version number.
-c <addr> : (IP) address of the SPIDR4 Controller,
or select by index number from this predefined list:
0 = 192.168.1.10
1 = 192.168.100.10
2 = 192.16.192.232
3 = 192.168.1.11
4 = 192.168.199.10
spidr4reg¶
Description¶
The spidr4reg tool allows a user to read and write the 32-bit registers defined in the SPIDR4 board.
This is the ‘usage’ of spidr4reg, listing available options:
$ spidr4reg -h
Usage: spidr4reg [-h|v] [-c <addr>] [-R] <reg_name>|<address>|list [val]
-h : Show this help text.
-v : Show the version number.
-c <addr> : If provided, (IP) address of the SPIDR4 Controller to connect to,
or select by number from this predefined list:
0 = 192.168.1.10
1 = 192.168.100.10
2 = 192.16.192.232
3 = 192.168.1.11
4 = 192.168.199.10
-R : Reads and displays all registers.
<reg_name> : a name such as TriggerControl or TRIGGERC
(case-insensitive, use 'list' to see all known names).
<address> : A register address (hexadecimal).
list : (as literal string) Display meta-info on all known registers,
one line per register, in a column-wise fashion.
<val> : If provided the value is written to the register,
if no value is given the item value is read out and displayed.
If *no* SPIDR4 controller address is provided,
only meta-info about the register is displayed.
Examples with spidr4reg¶
Write a value to register TRIGGER_CONTROL:
$ spidr4reg -c 2 trigger-c 1234
SPIDR4 Controller @ 192.16.192.232
Register 0x43C00004: Write 0x4D2 OKAY
Reading back register TRIGGER_CONTROL gives both information about the register and the register contents:
$ spidr4reg -c 2 trigger-c
SPIDR4 Controller @ 192.16.192.232
->Info: name=TRIGGER_CONTROL address=0x0004 "Trigger mode, reset, start/stop auto, etc"
Register 0x43C00004: 0x000004D2
Read all known (named) SPIDR4 registers:
$ spidr4reg -R -c 2
SPIDR4 Controller @ 192.16.192.232
0x43C00000: 00000BA5 FIRMWARE_VERSION
0x43C00004: 00000000 TRIGGER_CONTROL
0x43C00008: 00000000 TRIGGER_FREQUENCY
0x43C0000C: 00000000 TRIGGER_PERIOD
0x43C00010: AAAAAAAA EXTERNAL_TRIGGER_COUNTER
0x43C00014: BBBBBBBB EXTERNAL_SHUTTER_COUNTER
0x43C00018: 00002BA8 FAN_CONTROL
0x43C0001C: 00000000 FAN_READ
0x43C00020: 00000000 MAC_SRC1_MSB
0x43C00024: 00000000 MAC_SRC1_LSB
0x43C00028: 00000000 MAC_SRC2_MSB
0x43C0002C: 00000000 MAC_SRC2_LSB
0x43C00030: 00000000 MAC_DST1_MSB
0x43C00034: 00000000 MAC_DST1_LSB
0x43C00038: 00000000 MAC_DST2_MSB
0x43C0003C: 00000000 MAC_DST2_LSB
0x43C00040: 00000000 IP_SRC1
0x43C00044: 00000000 IP_SRC2
0x43C00048: 00000000 IP_DST1
0x43C0004C: 00000000 IP_DST2
0x43C00050: 00000000 PORT_SRC1
0x43C00054: 00000000 PORT_SRC2
0x43C00058: 00000000 PORT_DST1
0x43C0005C: 00000000 PORT_DST2
0x43C00060: 00000000 SFP_CONFIG
0x43C00064: 00000000 EMULATOR_CTRL
0x43C00068: 00000000 SC_TX_DATA
0x43C0006C: 00000000 SC_RX_DATA
0x43C00070: 000000C0 SC_CTRL
0x43C00074: 00000005 SC_STATUS
0x43C00078: 00000000 DELAY_CONTROL
0x43C0007C: 99A8CC14 FPGA_BITFILE_DATE
spidr4stats¶
This is the ‘usage’ of spidr4stats, listing available options:
Usage: spidr4stats -h|v -c<addr> -d -r
Reads out and displays a snapshot of the Timepix4 packet counters;
the next read-out displays the counter increments since the previous read-out.
Options:
-h : Show this help text.
-v : Show the version number.
-c <addr> : If provided, (IP) address of the SPIDR4 Controller to connect to,
or select by index number from this predefined list:
0 = 192.168.1.10
1 = 192.168.100.10
2 = 192.16.192.232
3 = 192.168.1.11
4 = 192.168.199.10
-D|d : Disable the statistics counters.
-R|r : Reset the statistics counters (and enable).
With Heartbeat generation enabled, this is an example of spidr4stats output:
$ spidr4stats -c2
SPIDR4 Controller @ 192.16.192.232
=> TOP
HITCOUNTER : 0
HEARTBEAT : 38098
SHUTTERRISE: 0
SHUTTERFALL: 0
T0SYNC : 0
OTHERS : 0
INVALID : 0
=> BOTTOM
HITCOUNTER : 0
HEARTBEAT : 38098
SHUTTERRISE: 0
SHUTTERFALL: 0
T0SYNC : 0
OTHERS : 0
INVALID : 0
spidr4streamconf¶
Tool spidr4streamconf displays a SPIDR4’s stream configuration, for example:
$ spidr4streamconf -c2
SPIDR4 Controller @ 192.16.192.232
=> Stream(s):
10GbE:
Primary: src=192.168.100.2 dest=192.168.100.1:8192,8193 MAC=ff:ff:ff:ff:ff:ff
Secondary: src= dest=:0 MAC=
(Chip-index=0)
or:
$ spidr4streamconf -c2
SPIDR4 Controller @ 192.16.192.232
=> Stream(s):
Optical:
Channels = 0x0000ffff (Top bit0-7, Bot bit8-15)
LinkSpeed = 5120 (Chip-index=0)
or:
$ spidr4streamconf -c2
SPIDR4 Controller @ 192.16.192.232
<none>
spidr4version¶
Tool spidr4version displays version and commit info about the SPIDR4 controller application software, firmware, gateware, plus a serial number of the module, and info about the installed chipboard and chip(s):
$ spidr4version -c2
SPIDR4 Controller @ 192.16.192.232
Controller: 'SPIDR4 Control application' Version 2.5.0, Build: 2025-05-12T07:53:00Z, Commit: v2.5.0
Firmware : 'SPIDR4 Firmware' Version 2.5.0, Build: 20180309123456, Commit: v2.5.0
Gateware : 0x81EC74F3 Date: 2025-05-12 13:42:30
Serial : 100080342874D097
Chipboard : NIKHEF_TPX4_V3, SN 129
TPX4 connected: 1
0: index=0 ID=000000F1 Rev=2
spidr4xgbe¶
Tool spidr4xgbe can be used to configure a SPIDR4’s 10GbE data link.
This is the ‘usage’ of spidr4stats, listing available options:
Usage: spidr4xgbe [-h|v] -c<addr> -s<src_addr> -d<dest_addr:port> [-b:<port> [none]
Configure a SPIDR4's 10GbE connection: source and destination address.
(NB: configures only the primary of the two available SPIDR4 SFPs.)
Use "none" to disconnect/unconfigure SPIDR4 Timepix4 data streams.
Options:
-h : Show this help text.
-v : Show the version number.
-c <addr> : (IP) address of the SPIDR4 Controller,
or select by index number from this predefined list:
0 = 192.168.1.10
1 = 192.168.100.10
2 = 192.16.192.232
3 = 192.168.1.11
4 = 192.168.199.10
-s <src_addr> : IP address to set as the 10GbE source address.
-d <dest_addr:port>: IP address to set as the 10GbE destination address plus port number.
-b <port> : Port number for BOTTOM data (default: TOP port +1).
"none" : Literal string (in combination with -c) to disable
the SPIDR4 data streams.
Example:
$ spidr4xgbe -c2 -s192.168.100.11 -d192.168.100.1:8100 -b8200
SPIDR4 Controller @ 192.16.192.232
Resulting configuration:
$ spidr4streamconf -c2
SPIDR4 Controller @ 192.16.192.232
=> Stream(s):
10GbE:
Primary: src=192.168.100.11 dest=192.168.100.1:8100,8200 MAC=ff:ff:ff:ff:ff:ff
Secondary: src= dest=:0 MAC=
(Chip-index=0)
Note that e.g. sdaq with option -c given, configures the SPIDR4 10GbE link according to the datastream address(es) provided (unless option -N is given), so a configuration similar to the one above is made automatically running sdaq like this:
$ sdaq -c2 192.168.100.1:8100,8200
Resulting configuration (note however that the source address in this case has been set by sdaq to 192.168.100.2):
s spidr4streamconf -c2
SPIDR4 Controller @ 192.16.192.232
=> Stream(s):
10GbE:
Primary: src=192.168.100.2 dest=192.168.100.1:8100,8201 MAC=ff:ff:ff:ff:ff:ff
Secondary: src= dest=:0 MAC=
(Chip-index=0)