Data file format¶
<The information in this section is preliminary and subject to change>
The SPIDR4 file format is a generic format for storing pixel data from Timepix4/Medipix4 devices. The format has been designed to be flexible and versatile.
General format¶
The SPIDR4 file format is a simple framed format, and the global structure is as follows:
The format starts with a magic marker of 8 bytes consisting of the ASCII characters: SPIDR4\0\0
Where \0 stands for a ZERO char. In the future the first \0 may be replaced,
but the second should always remain.
Frame format¶
The SPIDR4 file format contains multiple frames. Each frame starts with a frame header, followed by its content. The frame-header is 8 bytes long, and its content also has a size that is a multiple of 8 bytes. As such the format is 64-bits aligned. The frame header must be read as a 64-bit little-endian word, which can then be interpreted as having the following fields:
The fields have the following meaning:
Frame type: Defines what type of content is inside this frame.
Stream ID: Uniquely identifies the stream within the context of the experiment
Content Size: Size of the content (excluding header) in 64 bit words. As such it is possible to have a content of up to 32 GByte. A zero-sized content is possible, meaning another header or file end is immediately following this header.
Frame type¶
The frame type is a ‘free’ value indicating the type of the content. Defined as a single value, the value consists of two parts, a group ID and a content ID.
Top nibble (bits 15..12) is the Group ID to which the frame belongs
Middle 2 bits (11..10) represents a Content Encoding
Bottom 10 bits (bits 9..0) is the Content ID within this group+encoding
The actual frame type values are described in the sections below.
Stream ID¶
The Stream ID uniquely identifies the source of the data. This may be the Chip ID + Bottom/Top part indicator, but also may be configured a combination of [Board-ID,Quad Position,Bottom/Top].
Group IDs and Content Encoding¶
Group ID¶
The following Group IDs have been defined:
Group ID |
Group name |
|---|---|
0 |
Pixel data |
1 |
Configuration & Settings |
2 |
Environmental & sensor data |
3..6 |
reserved for future use |
7 |
User data / undefined (will not be defined by SPIDR4) |
8..15 |
unused |
Content Encoding¶
Encodings are useful to extract different types of data from a stream without exact knowledge of content. There are 4 possible classes, of which only 2 are defined for now.
Encoding class |
Description |
|---|---|
00 |
Binary data (8-byte aligned) |
01 |
JSON data (padded with zeroes, 8-byte aligned) |
10 |
reserved |
11 |
Other/user |
Next follows a list of all types of content per group. More detailed explanations to follow.
Group ‘Pixel Data’¶
Encoding: binary¶
Frame type |
Name |
Content description |
|---|---|---|
0000 |
TPX4TOATOTT |
Timepix4 ToA/ToT data (top half) |
0001 |
TPX4TOATOTB |
Timepix4 ToA/ToT data (bottom half) |
0002 |
TPX4TOATOT |
Timepix4 ToA/ToT data (unspecified source) |
0010 |
TPX4PC24T |
Timepix4 24-bit PC data (top half) |
0011 |
TPX4PC24B |
Timepix4 24-bit PC data (bottom half) |
0012 |
TPX4PC24 |
Timepix4 24-bit PC data (unspecified source) |
0020 |
TPX4FRAME8T |
Timepix4 8-bit frame data (top half) |
0021 |
TPX4FRAME8B |
Timepix4 8-bit frame data (bottom half) |
0022 |
TPX4FRAME8 |
Timepix4 8-bit frame data (unspecified source) |
0030 |
TPX4FRAME16T |
Timepix4 16-bit frame data (top half) |
0031 |
TPX4FRAME16B |
Timepix4 16-bit frame data (bottom half) |
0032 |
TPX4FRAME16 |
Timepix4 16-bit frame data (unspecified source) |
Group ‘Configuration & Settings’¶
Encoding: binary¶
Frame type |
Name |
Content description |
|---|---|---|
1000 |
TPX4PIXCFG |
Timepix4 pixel configuration data in a binary format |
1004 |
TPX4CFG |
Dump of all Timepix4 registers in a binary format |
TPX4PIXCFG: Binary dump of the Timepix4 pixel configuration: repeating sequence of 4-byte register address plus 4-byte number of bytes value followed by the register’s data bytes, padded up to the next multiple of 8 bytes.
TPX4CFG: Binary dump of all Timepix4 registers, same format as TPX4PIXCFG.
Encoding: JSON¶
Frame type |
Name |
Content description |
|---|---|---|
1400 |
TPX4PIXCFG |
Timepix4 pixel configuration data in JSON format |
1401 |
CHIPINFO |
JSON with information about the chip |
1402 |
BOARDINFO |
JSON with information about the board |
1403 |
RUNINFO |
JSON with information about the run |
1404 |
TPX4CFG |
JSON with the Timepix4 configuration other than Pixel configuration |
1405 |
CTRLCFG |
JSON with the SPIDR4 Controller configuration |
CHIPINFO: JSON blob containing Chip position, ID and type. Maybe also other things.
BOARDINFO: JSON blob containing information about the SPIDR4 board, such as the board ID, the sensors available.
RUNINFO: JSON blob containing information about the run, such as date, time, name of responsible person.
TPX4CFG: Other Timepix4 configuration information, such as digital pixels, DAC settings.
CTRLCFG: SPIDR4 Controller configuration, such as shutter / trigger settings, timing provider, lane configuration, etc..