.. _HitTypes:

Payload Types - Hits
--------------------

The following hit and trigger types are currently supported by
``payload-parsing``. Below are the byte maps for the various payloads. This
information is likely incomplete, as it is derived from the code and previous
docs were quite out of date... Additional payload mapping information can be
found :wiki:`here <Payloads>`.


Type 10
^^^^^^^

The V2-4 engineering format DOM hit (a DOM hit which is either passed to the
StringHub's back-end Sender class or which is saved to a HitSpool file).

+---------------+--------+-------------------------------------------+
| Byte Location | Length | Description                               |
+===============+========+===========================================+
| 32            | 4      | MBID                                      |
+---------------+--------+-------------------------------------------+
| 48            | 4      | DOM Launch Time                           |
+---------------+--------+-------------------------------------------+
| 58            | 2      | Raw Format Information                    |
+---------------+--------+-------------------------------------------+
| 60            | 1      | ATWD ID                                   |
+---------------+--------+-------------------------------------------+
| 61            | 1      | FADC Payload Length                       |
+---------------+--------+-------------------------------------------+
| 62            | 1      | ATWD format flag byte #0 - controls ch0/1 |
+---------------+--------+-------------------------------------------+
| 63            | 1      | ATWD format flag byte #1 - controls ch2/3 |
+---------------+--------+-------------------------------------------+
| 64            | 1      | Trigger Type                              |
+---------------+--------+-------------------------------------------+
| 65            | 1      | Padding Byte                              |
+---------------+--------+-------------------------------------------+
| 66            | 6      | DOM clock as 6 bytes in MSB order         |
+---------------+--------+-------------------------------------------+
| 72            | *N*    | FADC Samples                              |
+---------------+--------+-------------------------------------------+
| 72 + *N*      | *M*    | ATWD Samples                              |
+---------------+--------+-------------------------------------------+

Type 11
^^^^^^^

A composite container for DOM readout data.

+---------------+----------+-----------------------------------------------------------+
| Byte Location | Length   | Description                                               |
+===============+==========+===========================================================+
| 0             | 4        | Payload Length                                            |
+---------------+----------+-----------------------------------------------------------+
| 4             | 4        | Payload ID (value = 11)                                   |
+---------------+----------+-----------------------------------------------------------+
| 8             | 8        | Payload Time                                              |
+---------------+----------+-----------------------------------------------------------+
| 16            | 2        | RecType                                                   |
+---------------+----------+-----------------------------------------------------------+
| 18            | 2        | UID                                                       |
+---------------+----------+-----------------------------------------------------------+
| 22            | 2        | Payload Number                                            |
+---------------+----------+-----------------------------------------------------------+
| 24            | 2        | Payload Last                                              |
+---------------+----------+-----------------------------------------------------------+
| 26            | 4        | Source ID Number                                          |
+---------------+----------+-----------------------------------------------------------+
| 30            | 8        | Start Time                                                |
+---------------+----------+-----------------------------------------------------------+
| 38            | 8        | End Time                                                  |
+---------------+----------+-----------------------------------------------------------+
| 46            | 4        | Length of composite payload                               |
+---------------+----------+-----------------------------------------------------------+
| 50            | 2        | Type of composite payload (always seems to be '1')        |
+---------------+----------+-----------------------------------------------------------+
| 52            | 2        | *N* of Composite Payloads                                 |
+---------------+----------+-----------------------------------------------------------+
| 54            | Variable | Bunch of payloads of type '10' (the engineering data) or  |
|               |          | type '18' (the delta-compressed data).                    |
+---------------+----------+-----------------------------------------------------------+

Type 18
^^^^^^^

A V2-4 delta-compressed payload.

+---------------+--------+---------------------------------------+
| Byte Location | Length | Description                           |
+===============+========+=======================================+
| 8             | 8      | DOM Launch Time                       |
+---------------+--------+---------------------------------------+
| 28            | 8      | MBID                                  |
+---------------+--------+---------------------------------------+
| 40            | 2      | HitFlag                               |
+---------------+--------+---------------------------------------+
| 50            | 4      | WORD1 from the compressed data        |
+---------------+--------+---------------------------------------+
| 54            | 4      | WORD3 from the compressed data        |
+---------------+--------+---------------------------------------+
| 58            | Varies | *N* compressed words encoded in WORD1 |
+---------------+--------+---------------------------------------+

WORD1 and WORD3 are described in :docushare:`this document <20568>`. They have the
following bit format.

**WORD1**

+--------------+--------+------------------------------------------------------------+
| Bit Position | Length | Description                                                |
+==============+========+============================================================+
| 31           | 1      | Compression Flag                                           |
+--------------+--------+------------------------------------------------------------+
| 30           | 1      | Minimum Bias Flag                                          |
+--------------+--------+------------------------------------------------------------+
| 29           | 12     | Trigger Word                                               |
+--------------+--------+------------------------------------------------------------+
| 17           | 2      | Local Coincidence (01 below, 10 above, 11 below and above) |
+--------------+--------+------------------------------------------------------------+
| 15           | 1      | fADC available                                             |
+--------------+--------+------------------------------------------------------------+
| 14           | 1      | ATWD available                                             |
+--------------+--------+------------------------------------------------------------+
| 13           | 2      | ATWD Size                                                  |
+--------------+--------+------------------------------------------------------------+
| 11           | 1      | ATWD A or B                                                |
+--------------+--------+------------------------------------------------------------+
| 10           | 11     | Hit Size                                                   |
+--------------+--------+------------------------------------------------------------+

**WORD3**

+--------------+--------+-----------------+
| Bit Position | Length | Description     |
+==============+========+=================+
| 31           | 1      | Peak Range      |
+--------------+--------+-----------------+
| 30           | 4      | Peak Sample     |
+--------------+--------+-----------------+
| 26           | 9      | Pre-Peak Count  |
+--------------+--------+-----------------+
| 17           | 9      | Peak Count      |
+--------------+--------+-----------------+
| 8            | 9      | Post-Peak Count |
+--------------+--------+-----------------+

Type 25
^^^^^^^

The V5 delta-compressed hit records including OMKeys, and the HitFlags.

+---------------+--------+---------------------------------------+
| Byte Location | Length | Description                           |
+===============+========+=======================================+
| 2             | 1      | Hit Record Type (should be 1)         |
+---------------+--------+---------------------------------------+
| 3             | 1      | HitFlags                              |
+---------------+--------+---------------------------------------+
| 4             | 2      | ChannelID                             |
+---------------+--------+---------------------------------------+
| 6             | 4      | DOM Launch Time                       |
+---------------+--------+---------------------------------------+
| 10            | 4      | WORD1 from the compressed data        |
+---------------+--------+---------------------------------------+
| 14            | 4      | WORD3 from the compressed data        |
+---------------+--------+---------------------------------------+
| 18            | Varies | *N* compressed words encoded in WORD1 |
+---------------+--------+---------------------------------------+

Type 26
^^^^^^^

The V5 engineering hit records, concise format.

+---------------+--------+-------------------------------+
| Byte Location | Length | Description                   |
+===============+========+===============================+
| 2             | 1      | Hit Record Type (should be 1) |
+---------------+--------+-------------------------------+
| 3             | 1      | HitFlags                      |
+---------------+--------+-------------------------------+
| 4             | 2      | ChannelID                     |
+---------------+--------+-------------------------------+
| 6             | 4      | DOM Launch Time               |
+---------------+--------+-------------------------------+
| 10            | 1      | ATWD ID                       |
+---------------+--------+-------------------------------+
| 11            | 1      | FADC Payload Length           |
+---------------+--------+-------------------------------+
| 12            | *N*    | FADC Samples                  |
+---------------+--------+-------------------------------+
| 12 + *N*      | *M*    | ATWD Samples                  |
+---------------+--------+-------------------------------+

Type 27
^^^^^^^

The V6 delta-compressed hit records.

+---------------+--------+---------------------------------------+
| Byte Location | Length | Description                           |
+===============+========+=======================================+
| 3             | 1      | HitFlags                              |
+---------------+--------+---------------------------------------+
| 4             | 2      | ChannelID                             |
+---------------+--------+---------------------------------------+
| 6             | 4      | DOM Launch Time                       |
+---------------+--------+---------------------------------------+
| 10            | 4      | WORD1 from the compressed data        |
+---------------+--------+---------------------------------------+
| 14            | 4      | WORD3 from the compressed data        |
+---------------+--------+---------------------------------------+
| 18            | Varies | *N* compressed words encoded in WORD1 |
+---------------+--------+---------------------------------------+

Payload Types - Triggers
------------------------

Payloads encapsulating trigger requests.

Type 9
^^^^^^

Triggers payload for V2 events.

+---------------+----------+----------------------------------------------+
| Byte Location | Length   | Description                                  |
+===============+==========+==============================================+
| 0             | 4        | Payload Length                               |
+---------------+----------+----------------------------------------------+
| 4             | 4        | Payload ID (value=9)                         |
+---------------+----------+----------------------------------------------+
| 8             | 8        | Payload Time                                 |
+---------------+----------+----------------------------------------------+
| 16            | 2        | Rec Types (?)                                |
+---------------+----------+----------------------------------------------+
| 18            | 4        | UID (?)                                      |
+---------------+----------+----------------------------------------------+
| 22            | 4        | Trigger Types                                |
+---------------+----------+----------------------------------------------+
| 26            | 4        | Trigger Config ID                            |
+---------------+----------+----------------------------------------------+
| 30            | 4        | Source ID                                    |
+---------------+----------+----------------------------------------------+
| 34            | 8        | Trigger Start Time                           |
+---------------+----------+----------------------------------------------+
| 42            | 8        | Trigger End Time                             |
+---------------+----------+----------------------------------------------+
| 50            | 2        | Readout Request Types                        |
+---------------+----------+----------------------------------------------+
| 52            | 4        | Trigger UID                                  |
+---------------+----------+----------------------------------------------+
| 56            | 4        | Source ID                                    |
+---------------+----------+----------------------------------------------+
| 60            | 4        | *N* ReadoutRequestElementRecords (see below) |
+---------------+----------+----------------------------------------------+
| 64            | 32 * *N* | Bundle of ReadoutRequestElementRecord        |
+---------------+----------+----------------------------------------------+
| 64 + 32 * *N* | 4        | Length of composite records                  |
+---------------+----------+----------------------------------------------+
| 68 + 32 * *N* | 2        | Composite Types (value=1)                    |
+---------------+----------+----------------------------------------------+
| 70 + 32 * N   | 4        | Number of Composite Payloads of type '9'.    |
+---------------+----------+----------------------------------------------+

**ReadoutRequestElementRecord**

+---------------+--------+--------------------+
| Byte Location | Length | Description        |
+===============+========+====================+
| 0             | 4      | Readout Types      |
+---------------+--------+--------------------+
| 4             | 4      | Source ID          |
+---------------+--------+--------------------+
| 8             | 8      | Trigger Start Time |
+---------------+--------+--------------------+
| 16            | 8      | Trigger End Time   |
+---------------+--------+--------------------+
| 24            | 8      | DOM ID             |
+---------------+--------+--------------------+

Type 91
^^^^^^^

Triggers payload for V5 or V6 events.

+---------------+--------+--------------------------+
| Byte Location | Length | Description              |
+===============+========+==========================+
| 0             | 4      | Trigger Type             |
+---------------+--------+--------------------------+
| 4             | 4      | Trigger Configuration ID |
+---------------+--------+--------------------------+
| 8             | 4      | Trigger Source ID        |
+---------------+--------+--------------------------+
| 12            | 4      | Trigger Start Time       |
+---------------+--------+--------------------------+
| 16            | 4      | Trigger End Time         |
+---------------+--------+--------------------------+