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 -r|-R -S -s -i -I -m ||list [val] Options: -h : Show this help text. -E : Show a number of examples using tpx4item. -v : Show the version number. -c : (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 : 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 : Register stride when writing to all registers of a named item (default: 1). (only in combination with option -R). -s : Separate the named bitfield into sub-fields of bits each. -i : Single sub-field index to read or write (in combination with option -s). -I : 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 : Writing a register or bitfield value, only bits corresponding to bits in equal to one are modified, the rest remain untouched; is given as a hexadecimal number. : 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). : 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). : 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". 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 -B -T -C -G -p 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 : (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 : Enable (1) or disable (0) the CTRL-DATA test packets. -G : Enable (1) or disable (0) the Global Timer Counter: affects the contents of the Heartbeat and CTRL-DATA packets. -p : Enable or disable Heartbeat packets (disabled for is 0, enabled for between 6 and 23 -> period = (2^ + 1)*25ns). Examples of : 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 [] Stop, restart, power off or reset a SPIDR4. -h : Show this help text. -v : Show the version number. -c : (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 : 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 Display the SPIDR4 Controller ('control app') output and keep the connection open. Use to disconnect and exit. Options: -h : Show this help text. -v : Show the version number. -c : (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 ] [-R] |
|list [val] -h : Show this help text. -v : Show the version number. -c : 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. : a name such as TriggerControl or TRIGGERC (case-insensitive, use 'list' to see all known names).
: A register address (hexadecimal). list : (as literal string) Display meta-info on all known registers, one line per register, in a column-wise fashion. : 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 -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 : 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 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 -s -d [-b: [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 : (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 : IP address to set as the 10GbE source address. -d : IP address to set as the 10GbE destination address plus port number. -b : 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)