L2SS-192: Added description of source_info fields.

devices/SDP_statistics.py

@@ -65,7 +65,21 @@ class StatisticsPacket(object):
 
     @property
     def source_info(self) -> int:
-        """ Return a dict with the source_info flags. """
+        """ Return a dict with the source_info flags. The dict contains the following fields:
+        
+            _raw:                    raw value of the source_info field in the packet, as an integer.
+            antenna_band_index:      antenna type. 0 = low band, 1 = high band.
+            nyquist_zone_index:      nyquist zone of filter:
+                                         0 =           0 -- 1/2 * t_adc Hz (low band),
+                                         1 = 1/2 * t_adc -- t_adc Hz       (high band),
+                                         2 =       t_adc -- 3/2 * t_adc Hz (high band).
+            t_adc:                   sampling clock. 0 = 160 MHz, 1 = 200 MHz.
+            fsub_type:               sampling method. 0 = critically sampled, 1 = oversampled.
+            payload_error:           0 = data is ok, 1 = data is corrupted (a fault was encountered).
+            beam_repositioning_flag: 0 = data is ok, 1 = beam got repositioned during packet construction (BST only).
+            subband_calibrated_flag: 1 = subband data had subband calibration values applied, 0 = not
+            reserved:                reserved bits
+            gn_index:                global index of FPGA that emitted this packet. """
 
         bits = unpack("<H",self.packet[8:10])[0]
 
@@ -103,10 +117,13 @@ class StatisticsPacket(object):
 
     @property
     def data_id(self) -> int:
+        """ Returns the generic data identifier. """
+
         return unpack("<I",self.packet[14:18])[0]
 
     @property
     def nof_signal_inputs(self) -> int:
+        """ Number of inputs that were used for constructing the payload. """
         return unpack("<B",self.packet[18:19])[0]
 
     @property
@@ -144,7 +161,7 @@ class StatisticsPacket(object):
         return datetime.fromtimestamp(self.block_serial_number * self.block_period, timezone.utc)
 
     def header(self) -> dict:
-        """ Return the header as a dict. """
+        """ Return all the header fields as a dict. """
 
         return {
           "marker": self.marker,
@@ -169,9 +186,12 @@ class StatisticsPacket(object):
     def payload_sst(self) -> numpy.array:
         """ The payload of this packet, interpreted as SST data. """
 
+        if self.marker != 'S':
+            raise Exception("Payload of SST requested of a non-SST packet. Actual packet marker is '{}', but must be 'S'.".format(self.marker))
+
         # derive which and how many elements to read from the packet header
-        bytes_to_unsigned_struct_type = { 1: 'B', 2: 'H', 4: 'I', 8: 'Q' }
-        format_str = "<{}{}".format(self.nof_statistics_per_packet, bytes_to_unsigned_struct_type[self.nof_bytes_per_statistic])
+        bytecount_to_unsigned_struct_type = { 1: 'B', 2: 'H', 4: 'I', 8: 'Q' }
+        format_str = "<{}{}".format(self.nof_statistics_per_packet, bytecount_to_unsigned_struct_type[self.nof_bytes_per_statistic])
 
         return numpy.array(unpack(format_str, self.packet[32:32+calcsize(format_str)]))