oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/analyzers/protocols/jtag.py

@@ -90,19 +90,19 @@ class JTAGDecoder(SyncDecoder):
     longname = "Joint Test Action Group (IEEE 1149.1)"
     desc = "JTAG/Boundary-Scan protocol decoder"
 
-    channels = [  # noqa: RUF012
+    channels = [
         ChannelDef("tck", "TCK", "Test Clock", required=True),
         ChannelDef("tms", "TMS", "Test Mode Select", required=True),
         ChannelDef("tdi", "TDI", "Test Data In", required=True),
     ]
 
-    optional_channels = [  # noqa: RUF012
+    optional_channels = [
         ChannelDef("tdo", "TDO", "Test Data Out", required=False),
     ]
 
-    options = []  # noqa: RUF012
+    options = []
 
-    annotations = [  # noqa: RUF012
+    annotations = [
         ("state", "TAP state"),
         ("ir", "Instruction register"),
         ("dr", "Data register"),
@@ -147,17 +147,7 @@ class JTAGDecoder(SyncDecoder):
         if tck is None or tms is None or tdi is None:
             return
 
-        n_samples = min(len(tck), len(tms), len(tdi))
-        if tdo is not None:
-            n_samples = min(n_samples, len(tdo))
-
-        tck = tck[:n_samples]
-        tms = tms[:n_samples]
-        tdi = tdi[:n_samples]
-        if tdo is not None:
-            tdo = tdo[:n_samples]
-
-        # Find rising edges of TCK (state updates on rising edge)
+        tck, tms, tdi, tdo = self._align_signals(tck, tms, tdi, tdo)
         rising_edges = np.where(~tck[:-1] & tck[1:])[0] + 1
 
         if len(rising_edges) == 0:
@@ -167,95 +157,17 @@ class JTAGDecoder(SyncDecoder):
         trans_num = 0
 
         for edge_idx in rising_edges:
-            # Sample TMS at rising edge
             tms_val = bool(tms[edge_idx])
-
-            # Update TAP state
             new_state = self._next_state(self._tap_state, tms_val)
 
-            # Handle state-specific actions
+            # Handle data shifting in SHIFT states
             if self._tap_state in (TAPState.SHIFT_IR, TAPState.SHIFT_DR):
-                # Shift data
-                tdi_bit = 1 if tdi[edge_idx] else 0
-                self._shift_bits_tdi.append(tdi_bit)
+                self._shift_data_bit(edge_idx, tdi, tdo)
 
-                if tdo is not None:
-                    tdo_bit = 1 if tdo[edge_idx] else 0
-                    self._shift_bits_tdo.append(tdo_bit)
-
-            # Detect state transitions
+            # Handle state transitions and emit packets
             if new_state != self._tap_state:
-                # Emit packet on state change if we have shifted data
-                if self._tap_state == TAPState.SHIFT_IR and len(self._shift_bits_tdi) > 0:
-                    # Emit IR shift
-                    ir_value = self._bits_to_value(self._shift_bits_tdi)
-                    start_time = state_start_idx / sample_rate
-                    end_time = edge_idx / sample_rate
-
-                    instruction_name = JTAG_INSTRUCTIONS.get(ir_value, "UNKNOWN")
-
-                    self.put_annotation(
-                        start_time,
-                        end_time,
-                        AnnotationLevel.FIELDS,
-                        f"IR: 0x{ir_value:02X} ({instruction_name})",
-                    )
-
-                    annotations = {
-                        "transaction_num": trans_num,
-                        "tap_state": self._tap_state.value,
-                        "ir_value": ir_value,
-                        "ir_bits": len(self._shift_bits_tdi),
-                        "instruction": instruction_name,
-                    }
-
-                    packet = ProtocolPacket(
-                        timestamp=start_time,
-                        protocol="jtag",
-                        data=bytes([ir_value]),
-                        annotations=annotations,
-                        errors=[],
-                    )
-
-                    yield packet
-                    trans_num += 1
-
-                elif self._tap_state == TAPState.SHIFT_DR and len(self._shift_bits_tdi) > 0:
-                    # Emit DR shift
-                    dr_value_tdi = self._bits_to_value(self._shift_bits_tdi)
-                    start_time = state_start_idx / sample_rate
-                    end_time = edge_idx / sample_rate
-
-                    # Convert to bytes
-                    byte_count = (len(self._shift_bits_tdi) + 7) // 8
-                    dr_bytes = dr_value_tdi.to_bytes(byte_count, "little")
-
-                    self.put_annotation(
-                        start_time,
-                        end_time,
-                        AnnotationLevel.FIELDS,
-                        f"DR: 0x{dr_value_tdi:X} ({len(self._shift_bits_tdi)} bits)",
-                    )
-
-                    annotations = {
-                        "transaction_num": trans_num,
-                        "tap_state": self._tap_state.value,
-                        "dr_value_tdi": dr_value_tdi,
-                        "dr_bits": len(self._shift_bits_tdi),
-                    }
-
-                    if tdo is not None and len(self._shift_bits_tdo) > 0:
-                        dr_value_tdo = self._bits_to_value(self._shift_bits_tdo)
-                        annotations["dr_value_tdo"] = dr_value_tdo
-
-                    packet = ProtocolPacket(
-                        timestamp=start_time,
-                        protocol="jtag",
-                        data=dr_bytes,
-                        annotations=annotations,
-                        errors=[],
-                    )
-
+                packet = self._emit_state_packet(state_start_idx, edge_idx, sample_rate, trans_num)
+                if packet is not None:
                     yield packet
                     trans_num += 1
 
@@ -267,6 +179,176 @@ class JTAGDecoder(SyncDecoder):
                 self._tap_state = new_state
                 state_start_idx = edge_idx
 
+    def _align_signals(
+        self,
+        tck: NDArray[np.bool_],
+        tms: NDArray[np.bool_],
+        tdi: NDArray[np.bool_],
+        tdo: NDArray[np.bool_] | None,
+    ) -> tuple[NDArray[np.bool_], NDArray[np.bool_], NDArray[np.bool_], NDArray[np.bool_] | None]:
+        """Align all signals to the same length.
+
+        Args:
+            tck: Test Clock signal.
+            tms: Test Mode Select signal.
+            tdi: Test Data In signal.
+            tdo: Test Data Out signal (optional).
+
+        Returns:
+            Tuple of aligned signals (tck, tms, tdi, tdo).
+        """
+        n_samples = min(len(tck), len(tms), len(tdi))
+        if tdo is not None:
+            n_samples = min(n_samples, len(tdo))
+
+        return (
+            tck[:n_samples],
+            tms[:n_samples],
+            tdi[:n_samples],
+            tdo[:n_samples] if tdo is not None else None,
+        )
+
+    def _shift_data_bit(
+        self,
+        edge_idx: int,
+        tdi: NDArray[np.bool_],
+        tdo: NDArray[np.bool_] | None,
+    ) -> None:
+        """Shift a single bit of data on TDI/TDO.
+
+        Args:
+            edge_idx: Edge index where shift occurs.
+            tdi: Test Data In signal.
+            tdo: Test Data Out signal (optional).
+        """
+        tdi_bit = 1 if tdi[edge_idx] else 0
+        self._shift_bits_tdi.append(tdi_bit)
+
+        if tdo is not None:
+            tdo_bit = 1 if tdo[edge_idx] else 0
+            self._shift_bits_tdo.append(tdo_bit)
+
+    def _emit_state_packet(
+        self,
+        state_start_idx: int,
+        edge_idx: int,
+        sample_rate: float,
+        trans_num: int,
+    ) -> ProtocolPacket | None:
+        """Emit packet on state change if we have shifted data.
+
+        Args:
+            state_start_idx: Start index of current state.
+            edge_idx: Current edge index.
+            sample_rate: Sample rate in Hz.
+            trans_num: Transaction number.
+
+        Returns:
+            ProtocolPacket if data was shifted, None otherwise.
+        """
+        if self._tap_state == TAPState.SHIFT_IR and len(self._shift_bits_tdi) > 0:
+            return self._create_ir_packet(state_start_idx, edge_idx, sample_rate, trans_num)
+        elif self._tap_state == TAPState.SHIFT_DR and len(self._shift_bits_tdi) > 0:
+            return self._create_dr_packet(state_start_idx, edge_idx, sample_rate, trans_num)
+        return None
+
+    def _create_ir_packet(
+        self,
+        state_start_idx: int,
+        edge_idx: int,
+        sample_rate: float,
+        trans_num: int,
+    ) -> ProtocolPacket:
+        """Create IR shift packet.
+
+        Args:
+            state_start_idx: Start index of shift state.
+            edge_idx: End index of shift state.
+            sample_rate: Sample rate in Hz.
+            trans_num: Transaction number.
+
+        Returns:
+            ProtocolPacket for IR shift.
+        """
+        ir_value = self._bits_to_value(self._shift_bits_tdi)
+        start_time = state_start_idx / sample_rate
+        end_time = edge_idx / sample_rate
+        instruction_name = JTAG_INSTRUCTIONS.get(ir_value, "UNKNOWN")
+
+        self.put_annotation(
+            start_time,
+            end_time,
+            AnnotationLevel.FIELDS,
+            f"IR: 0x{ir_value:02X} ({instruction_name})",
+        )
+
+        annotations = {
+            "transaction_num": trans_num,
+            "tap_state": self._tap_state.value,
+            "ir_value": ir_value,
+            "ir_bits": len(self._shift_bits_tdi),
+            "instruction": instruction_name,
+        }
+
+        return ProtocolPacket(
+            timestamp=start_time,
+            protocol="jtag",
+            data=bytes([ir_value]),
+            annotations=annotations,
+            errors=[],
+        )
+
+    def _create_dr_packet(
+        self,
+        state_start_idx: int,
+        edge_idx: int,
+        sample_rate: float,
+        trans_num: int,
+    ) -> ProtocolPacket:
+        """Create DR shift packet.
+
+        Args:
+            state_start_idx: Start index of shift state.
+            edge_idx: End index of shift state.
+            sample_rate: Sample rate in Hz.
+            trans_num: Transaction number.
+
+        Returns:
+            ProtocolPacket for DR shift.
+        """
+        dr_value_tdi = self._bits_to_value(self._shift_bits_tdi)
+        start_time = state_start_idx / sample_rate
+        end_time = edge_idx / sample_rate
+
+        byte_count = (len(self._shift_bits_tdi) + 7) // 8
+        dr_bytes = dr_value_tdi.to_bytes(byte_count, "little")
+
+        self.put_annotation(
+            start_time,
+            end_time,
+            AnnotationLevel.FIELDS,
+            f"DR: 0x{dr_value_tdi:X} ({len(self._shift_bits_tdi)} bits)",
+        )
+
+        annotations = {
+            "transaction_num": trans_num,
+            "tap_state": self._tap_state.value,
+            "dr_value_tdi": dr_value_tdi,
+            "dr_bits": len(self._shift_bits_tdi),
+        }
+
+        if len(self._shift_bits_tdo) > 0:
+            dr_value_tdo = self._bits_to_value(self._shift_bits_tdo)
+            annotations["dr_value_tdo"] = dr_value_tdo
+
+        return ProtocolPacket(
+            timestamp=start_time,
+            protocol="jtag",
+            data=dr_bytes,
+            annotations=annotations,
+            errors=[],
+        )
+
     def _next_state(self, current: TAPState, tms: bool) -> TAPState:
         """Compute next TAP state based on TMS value.
 

oscura/analyzers/protocols/lin.py

@@ -63,13 +63,13 @@ class LINDecoder(AsyncDecoder):
     longname = "Local Interconnect Network"
     desc = "LIN automotive bus protocol decoder"
 
-    channels = [  # noqa: RUF012
+    channels = [
         ChannelDef("bus", "BUS", "LIN bus signal", required=True),
     ]
 
-    optional_channels = []  # noqa: RUF012
+    optional_channels = []
 
-    options = [  # noqa: RUF012
+    options = [
         OptionDef(
             "baudrate",
             "Baud rate",
@@ -86,7 +86,7 @@ class LINDecoder(AsyncDecoder):
         ),
     ]
 
-    annotations = [  # noqa: RUF012
+    annotations = [
         ("sync", "Sync field"),
         ("pid", "Protected identifier"),
         ("data", "Data bytes"),
@@ -127,14 +127,7 @@ class LINDecoder(AsyncDecoder):
             >>> for packet in decoder.decode(trace):
             ...     print(f"Data: {packet.data.hex()}")
         """
-        # Convert to digital if needed
-        if isinstance(trace, WaveformTrace):
-            from oscura.analyzers.digital.extraction import to_digital
-
-            digital_trace = to_digital(trace, threshold="auto")
-        else:
-            digital_trace = trace
-
+        digital_trace = self._prepare_digital_trace(trace)
         data = digital_trace.data
         sample_rate = digital_trace.metadata.sample_rate
 
@@ -145,121 +138,233 @@ class LINDecoder(AsyncDecoder):
         frame_num = 0
 
         while idx < len(data):
-            # Look for break field (dominant for at least 13 bit times)
-            break_start = self._find_break_field(data, idx, bit_period)
-            if break_start is None:
+            frame_result = self._try_decode_frame(
+                data, idx, bit_period, half_bit, sample_rate, frame_num
+            )
+
+            if frame_result is None:
                 break
 
-            # After break field, find the end of the dominant period (break)
-            # and skip the delimiter (recessive) to reach the sync byte
-            sync_start_idx = break_start
-            while sync_start_idx < len(data) and not data[sync_start_idx]:
-                sync_start_idx += 1
+            packet, next_idx = frame_result
+            yield packet
 
-            # Skip delimiter (recessive period) to reach sync byte start bit
-            # The delimiter is at least 1 bit time recessive
-            while sync_start_idx < len(data) and data[sync_start_idx]:
-                sync_start_idx += 1
+            frame_num += 1
+            idx = next_idx
 
-            if sync_start_idx >= len(data):
-                break
+    def _prepare_digital_trace(self, trace: DigitalTrace | WaveformTrace) -> DigitalTrace:
+        """Convert trace to digital format if needed."""
+        if isinstance(trace, WaveformTrace):
+            from oscura.analyzers.digital.extraction import to_digital
+
+            return to_digital(trace, threshold="auto")
+        return trace
+
+    def _try_decode_frame(
+        self,
+        data: NDArray[np.bool_],
+        idx: int,
+        bit_period: float,
+        half_bit: float,
+        sample_rate: float,
+        frame_num: int,
+    ) -> tuple[ProtocolPacket, int] | None:
+        """Attempt to decode a single LIN frame."""
+        break_start = self._find_break_field(data, idx, bit_period)
+        if break_start is None:
+            return None
+
+        sync_start_idx = self._find_sync_start(data, break_start)
+        if sync_start_idx >= len(data):
+            return None
+
+        sync_byte, sync_errors = self._decode_sync_field(data, sync_start_idx, bit_period, half_bit)
+        pid_byte, pid_errors, frame_id = self._decode_pid_field(
+            data, sync_start_idx, bit_period, half_bit
+        )
+
+        if pid_byte is None:
+            return None
+
+        data_length = self._get_data_length(frame_id)
+        data_bytes, data_errors = self._decode_data_fields(
+            data, sync_start_idx, bit_period, half_bit, data_length
+        )
+        checksum_byte, checksum_errors = self._decode_checksum_field(
+            data, sync_start_idx, bit_period, half_bit, data_length, frame_id, data_bytes
+        )
+
+        packet = self._create_lin_packet(
+            break_start,
+            sync_start_idx,
+            bit_period,
+            data_length,
+            sample_rate,
+            sync_errors,
+            pid_errors,
+            data_errors,
+            checksum_errors,
+            frame_num,
+            frame_id,
+            pid_byte,
+            checksum_byte,
+            data_bytes,
+        )
+
+        next_idx = int(sync_start_idx + (10 + 10 + data_length * 10 + 10) * bit_period)
+        return packet, next_idx
+
+    def _find_sync_start(self, data: NDArray[np.bool_], break_start: int) -> int:
+        """Find start of sync byte after break field."""
+        sync_start_idx = break_start
+        while sync_start_idx < len(data) and not data[sync_start_idx]:
+            sync_start_idx += 1
+
+        while sync_start_idx < len(data) and data[sync_start_idx]:
+            sync_start_idx += 1
+
+        return sync_start_idx
+
+    def _decode_sync_field(
+        self,
+        data: NDArray[np.bool_],
+        sync_start_idx: int,
+        bit_period: float,
+        half_bit: float,
+    ) -> tuple[int, list[str]]:
+        """Decode and validate sync field."""
+        sync_byte, sync_errors = self._decode_byte(data, sync_start_idx, bit_period, half_bit)
+
+        if sync_byte != 0x55:
+            sync_errors.append(f"Invalid sync field: 0x{sync_byte:02X} (expected 0x55)")
+
+        return sync_byte, sync_errors
 
-            # Sync field is 0x55 (01010101)
-            sync_byte, sync_errors = self._decode_byte(data, sync_start_idx, bit_period, half_bit)
+    def _decode_pid_field(
+        self,
+        data: NDArray[np.bool_],
+        sync_start_idx: int,
+        bit_period: float,
+        half_bit: float,
+    ) -> tuple[int | None, list[str], int]:
+        """Decode and validate PID field."""
+        pid_start_idx = int(sync_start_idx + 10 * bit_period)
+        if pid_start_idx >= len(data):
+            return None, [], 0
+
+        pid_byte, pid_errors = self._decode_byte(data, pid_start_idx, bit_period, half_bit)
+
+        frame_id = pid_byte & 0x3F
+        parity = (pid_byte >> 6) & 0x03
+        expected_parity = self._compute_parity(frame_id)
+
+        if parity != expected_parity:
+            pid_errors.append(f"Parity error: {parity} (expected {expected_parity})")
 
-            if sync_byte != 0x55:
-                sync_errors.append(f"Invalid sync field: 0x{sync_byte:02X} (expected 0x55)")
+        return pid_byte, pid_errors, frame_id
 
-            # Protected identifier (PID)
-            pid_start_idx = int(sync_start_idx + 10 * bit_period)
-            if pid_start_idx >= len(data):
+    def _decode_data_fields(
+        self,
+        data: NDArray[np.bool_],
+        sync_start_idx: int,
+        bit_period: float,
+        half_bit: float,
+        data_length: int,
+    ) -> tuple[list[int], list[str]]:
+        """Decode all data bytes."""
+        data_bytes = []
+        data_errors = []
+        data_start_idx = int(sync_start_idx + 20 * bit_period)
+
+        for i in range(data_length):
+            byte_start_idx = int(data_start_idx + i * 10 * bit_period)
+            if byte_start_idx >= len(data):
                 break
 
-            pid_byte, pid_errors = self._decode_byte(data, pid_start_idx, bit_period, half_bit)
-
-            # Extract ID and parity
-            frame_id = pid_byte & 0x3F
-            parity = (pid_byte >> 6) & 0x03
-
-            # Validate parity
-            expected_parity = self._compute_parity(frame_id)
-            if parity != expected_parity:
-                pid_errors.append(f"Parity error: {parity} (expected {expected_parity})")
-
-            # Data length depends on frame ID
-            data_length = self._get_data_length(frame_id)
-
-            # Decode data bytes
-            data_bytes = []
-            data_errors = []
-            data_start_idx = int(pid_start_idx + 10 * bit_period)
-
-            for i in range(data_length):
-                byte_start_idx = int(data_start_idx + i * 10 * bit_period)
-                if byte_start_idx >= len(data):
-                    break
-
-                byte_val, byte_errors = self._decode_byte(
-                    data, byte_start_idx, bit_period, half_bit
-                )
-                data_bytes.append(byte_val)
-                data_errors.extend(byte_errors)
-
-            # Decode checksum
-            checksum_start_idx = int(data_start_idx + data_length * 10 * bit_period)
-            if checksum_start_idx < len(data):
-                checksum_byte, checksum_errors = self._decode_byte(
-                    data, checksum_start_idx, bit_period, half_bit
-                )
-
-                # Validate checksum
-                expected_checksum = self._compute_checksum(frame_id, data_bytes)
-                if checksum_byte != expected_checksum:
-                    checksum_errors.append(
-                        f"Checksum error: 0x{checksum_byte:02X} (expected 0x{expected_checksum:02X})"
-                    )
-            else:
-                checksum_byte = 0
-                checksum_errors = ["Missing checksum"]
-
-            # Calculate timestamps
-            start_time = break_start / sample_rate
-            end_time = (checksum_start_idx + 10 * bit_period) / sample_rate
-
-            # Collect all errors
-            errors = sync_errors + pid_errors + data_errors + checksum_errors
-
-            # Add annotations
-            self.put_annotation(
-                start_time,
-                end_time,
-                AnnotationLevel.PACKETS,
-                f"ID: 0x{frame_id:02X}",
-                data=bytes(data_bytes),
-            )
+            byte_val, byte_errors = self._decode_byte(data, byte_start_idx, bit_period, half_bit)
+            data_bytes.append(byte_val)
+            data_errors.extend(byte_errors)
+
+        return data_bytes, data_errors
 
-            # Create packet
-            annotations = {
-                "frame_num": frame_num,
-                "frame_id": frame_id,
-                "pid": pid_byte,
-                "data_length": data_length,
-                "checksum": checksum_byte,
-                "version": self._version.value,
-            }
-
-            packet = ProtocolPacket(
-                timestamp=start_time,
-                protocol="lin",
-                data=bytes(data_bytes),
-                annotations=annotations,
-                errors=errors,
+    def _decode_checksum_field(
+        self,
+        data: NDArray[np.bool_],
+        sync_start_idx: int,
+        bit_period: float,
+        half_bit: float,
+        data_length: int,
+        frame_id: int,
+        data_bytes: list[int],
+    ) -> tuple[int, list[str]]:
+        """Decode and validate checksum field."""
+        data_start_idx = int(sync_start_idx + 20 * bit_period)
+        checksum_start_idx = int(data_start_idx + data_length * 10 * bit_period)
+
+        if checksum_start_idx >= len(data):
+            return 0, ["Missing checksum"]
+
+        checksum_byte, checksum_errors = self._decode_byte(
+            data, checksum_start_idx, bit_period, half_bit
+        )
+
+        expected_checksum = self._compute_checksum(frame_id, data_bytes)
+        if checksum_byte != expected_checksum:
+            checksum_errors.append(
+                f"Checksum error: 0x{checksum_byte:02X} (expected 0x{expected_checksum:02X})"
             )
 
-            yield packet
+        return checksum_byte, checksum_errors
 
-            frame_num += 1
-            idx = int(checksum_start_idx + 10 * bit_period)
+    def _create_lin_packet(
+        self,
+        break_start: int,
+        sync_start_idx: int,
+        bit_period: float,
+        data_length: int,
+        sample_rate: float,
+        sync_errors: list[str],
+        pid_errors: list[str],
+        data_errors: list[str],
+        checksum_errors: list[str],
+        frame_num: int,
+        frame_id: int,
+        pid_byte: int,
+        checksum_byte: int,
+        data_bytes: list[int],
+    ) -> ProtocolPacket:
+        """Create LIN protocol packet from decoded fields."""
+        data_start_idx = int(sync_start_idx + 20 * bit_period)
+        checksum_start_idx = int(data_start_idx + data_length * 10 * bit_period)
+
+        start_time = break_start / sample_rate
+        end_time = (checksum_start_idx + 10 * bit_period) / sample_rate
+
+        errors = sync_errors + pid_errors + data_errors + checksum_errors
+
+        self.put_annotation(
+            start_time,
+            end_time,
+            AnnotationLevel.PACKETS,
+            f"ID: 0x{frame_id:02X}",
+            data=bytes(data_bytes),
+        )
+
+        annotations = {
+            "frame_num": frame_num,
+            "frame_id": frame_id,
+            "pid": pid_byte,
+            "data_length": data_length,
+            "checksum": checksum_byte,
+            "version": self._version.value,
+        }
+
+        return ProtocolPacket(
+            timestamp=start_time,
+            protocol="lin",
+            data=bytes(data_bytes),
+            annotations=annotations,
+            errors=errors,
+        )
 
     def _find_break_field(
         self,