oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/automotive/can/stimulus_response.py

@@ -0,0 +1,461 @@
+"""Stimulus-response mapping for CAN bus reverse engineering.
+
+This module helps identify which CAN messages and signals change in response
+to user actions, enabling rapid identification of relevant data during reverse
+engineering work.
+
+The primary use case is comparing:
+1. Baseline capture (no actions)
+2. Stimulus capture (button press, pedal movement, etc.)
+
+This allows answering questions like:
+- "What messages change when I press the brake?"
+- "Which signals react to throttle position?"
+- "What initializes when I turn the key?"
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import numpy as np
+from scipy import stats
+
+if TYPE_CHECKING:
+    from oscura.automotive.can.models import CANMessage
+    from oscura.automotive.can.session import CANSession
+
+__all__ = [
+    "ByteChange",
+    "FrequencyChange",
+    "StimulusResponseAnalyzer",
+    "StimulusResponseReport",
+]
+
+
+@dataclass
+class ByteChange:
+    """Detected change in a specific byte position.
+
+    Attributes:
+        byte_position: Byte position (0-7 for CAN 2.0).
+        baseline_values: Set of values observed in baseline.
+        stimulus_values: Set of values observed in stimulus.
+        change_magnitude: Normalized change magnitude (0.0-1.0).
+        value_range_change: Change in value range (max - min).
+        mean_change: Change in mean value.
+        new_values: Values that appear only in stimulus.
+        disappeared_values: Values that appear only in baseline.
+    """
+
+    byte_position: int
+    baseline_values: set[int]
+    stimulus_values: set[int]
+    change_magnitude: float
+    value_range_change: float
+    mean_change: float
+    new_values: set[int] = field(default_factory=set)
+    disappeared_values: set[int] = field(default_factory=set)
+
+    def __post_init__(self) -> None:
+        """Calculate derived fields."""
+        self.new_values = self.stimulus_values - self.baseline_values
+        self.disappeared_values = self.baseline_values - self.stimulus_values
+
+
+@dataclass
+class FrequencyChange:
+    """Detected frequency change for a message ID.
+
+    Attributes:
+        message_id: CAN arbitration ID.
+        baseline_hz: Frequency in baseline (Hz).
+        stimulus_hz: Frequency in stimulus (Hz).
+        change_ratio: Ratio of stimulus to baseline frequency.
+        change_type: Type of change ('increased', 'decreased', 'appeared', 'disappeared').
+        significance: Statistical significance (0.0-1.0).
+    """
+
+    message_id: int
+    baseline_hz: float
+    stimulus_hz: float
+    change_ratio: float
+    change_type: str
+    significance: float
+
+    def __repr__(self) -> str:
+        """Human-readable representation."""
+        return (
+            f"FrequencyChange(0x{self.message_id:03X}: "
+            f"{self.baseline_hz:.1f}Hz -> {self.stimulus_hz:.1f}Hz, "
+            f"ratio={self.change_ratio:.2f}, {self.change_type})"
+        )
+
+
+@dataclass
+class StimulusResponseReport:
+    """Complete stimulus-response analysis report.
+
+    Attributes:
+        changed_messages: Message IDs with detected changes.
+        new_messages: Message IDs only in stimulus.
+        disappeared_messages: Message IDs only in baseline.
+        frequency_changes: Frequency changes by message ID.
+        byte_changes: Byte-level changes by message ID.
+        duration_baseline: Duration of baseline session (seconds).
+        duration_stimulus: Duration of stimulus session (seconds).
+        confidence_threshold: Minimum confidence used for detection.
+    """
+
+    changed_messages: list[int]
+    new_messages: list[int]
+    disappeared_messages: list[int]
+    frequency_changes: dict[int, FrequencyChange]
+    byte_changes: dict[int, list[ByteChange]]
+    duration_baseline: float
+    duration_stimulus: float
+    confidence_threshold: float
+
+    def summary(self) -> str:
+        """Generate human-readable summary.
+
+        Returns:
+            Multi-line summary string.
+        """
+        lines = [
+            "=== Stimulus-Response Analysis ===",
+            f"Baseline duration: {self.duration_baseline:.2f}s",
+            f"Stimulus duration: {self.duration_stimulus:.2f}s",
+            f"Confidence threshold: {self.confidence_threshold:.2f}",
+            "",
+        ]
+
+        if self.new_messages:
+            lines.append(f"New Messages ({len(self.new_messages)}):")
+            for msg_id in sorted(self.new_messages):
+                lines.append(f"  0x{msg_id:03X}")
+            lines.append("")
+
+        if self.disappeared_messages:
+            lines.append(f"Disappeared Messages ({len(self.disappeared_messages)}):")
+            for msg_id in sorted(self.disappeared_messages):
+                lines.append(f"  0x{msg_id:03X}")
+            lines.append("")
+
+        if self.frequency_changes:
+            lines.append(f"Frequency Changes ({len(self.frequency_changes)}):")
+            for msg_id in sorted(self.frequency_changes.keys()):
+                fc = self.frequency_changes[msg_id]
+                lines.append(
+                    f"  0x{msg_id:03X}: {fc.baseline_hz:.1f}Hz -> {fc.stimulus_hz:.1f}Hz "
+                    f"({fc.change_type}, sig={fc.significance:.2f})"
+                )
+            lines.append("")
+
+        if self.byte_changes:
+            lines.append(f"Byte-Level Changes ({len(self.byte_changes)} messages):")
+            for msg_id in sorted(self.byte_changes.keys()):
+                changes = self.byte_changes[msg_id]
+                lines.append(f"  0x{msg_id:03X}: {len(changes)} bytes changed")
+                for bc in changes:
+                    lines.append(
+                        f"    Byte {bc.byte_position}: "
+                        f"magnitude={bc.change_magnitude:.2f}, "
+                        f"mean_change={bc.mean_change:.1f}"
+                    )
+            lines.append("")
+
+        if not any([self.new_messages, self.disappeared_messages, self.changed_messages]):
+            lines.append("No significant changes detected.")
+
+        return "\n".join(lines)
+
+
+class StimulusResponseAnalyzer:
+    """Analyzer for detecting CAN message changes between sessions.
+
+    This class compares a baseline session (no user action) against a stimulus
+    session (with user action) to identify which messages and signals respond
+    to the stimulus.
+    """
+
+    def detect_responses(
+        self,
+        baseline_session: CANSession,
+        stimulus_session: CANSession,
+        time_window_ms: float = 100,
+        change_threshold: float = 0.1,
+    ) -> StimulusResponseReport:
+        """Detect which messages changed between sessions.
+
+        Args:
+            baseline_session: Baseline capture (no action).
+            stimulus_session: Stimulus capture (with action).
+            time_window_ms: Time window for aligning messages (milliseconds).
+            change_threshold: Minimum normalized change to report (0.0-1.0).
+
+        Returns:
+            StimulusResponseReport with detected changes.
+        """
+        # Get message IDs from both sessions
+        baseline_ids = baseline_session.unique_ids()
+        stimulus_ids = stimulus_session.unique_ids()
+
+        # Detect new and disappeared messages
+        new_messages = sorted(stimulus_ids - baseline_ids)
+        disappeared_messages = sorted(baseline_ids - stimulus_ids)
+
+        # Messages present in both sessions
+        common_ids = baseline_ids & stimulus_ids
+
+        # Detect frequency changes
+        frequency_changes = {}
+        for msg_id in common_ids:
+            freq_change = self._detect_frequency_change(baseline_session, stimulus_session, msg_id)
+            if freq_change and freq_change.significance >= change_threshold:
+                frequency_changes[msg_id] = freq_change
+
+        # Detect byte-level changes
+        byte_changes = {}
+        changed_messages = []
+        for msg_id in common_ids:
+            changes = self.analyze_signal_changes(
+                baseline_session, stimulus_session, msg_id, byte_threshold=1
+            )
+            # Filter by change threshold
+            significant_changes = [c for c in changes if c.change_magnitude >= change_threshold]
+            if significant_changes:
+                byte_changes[msg_id] = significant_changes
+                changed_messages.append(msg_id)
+
+        # Get durations
+        baseline_start, baseline_end = baseline_session.time_range()
+        stimulus_start, stimulus_end = stimulus_session.time_range()
+
+        return StimulusResponseReport(
+            changed_messages=sorted(set(changed_messages) | set(frequency_changes.keys())),
+            new_messages=new_messages,
+            disappeared_messages=disappeared_messages,
+            frequency_changes=frequency_changes,
+            byte_changes=byte_changes,
+            duration_baseline=baseline_end - baseline_start,
+            duration_stimulus=stimulus_end - stimulus_start,
+            confidence_threshold=change_threshold,
+        )
+
+    def analyze_signal_changes(
+        self,
+        baseline_session: CANSession,
+        stimulus_session: CANSession,
+        message_id: int,
+        byte_threshold: int = 1,
+    ) -> list[ByteChange]:
+        """Analyze byte-level changes in a specific message.
+
+        Args:
+            baseline_session: Baseline capture.
+            stimulus_session: Stimulus capture.
+            message_id: CAN arbitration ID to analyze.
+            byte_threshold: Minimum number of unique values to consider changing.
+
+        Returns:
+            List of ByteChange objects for changed bytes.
+        """
+        # Get messages for this ID from both sessions
+        baseline_msgs = baseline_session._messages.filter_by_id(message_id)
+        stimulus_msgs = stimulus_session._messages.filter_by_id(message_id)
+
+        if not baseline_msgs.messages or not stimulus_msgs.messages:
+            return []
+
+        # Determine max DLC
+        max_dlc = max(
+            max(msg.dlc for msg in baseline_msgs.messages),
+            max(msg.dlc for msg in stimulus_msgs.messages),
+        )
+
+        changes = []
+        for byte_pos in range(max_dlc):
+            # Extract byte values from both sessions
+            baseline_values = [
+                msg.data[byte_pos] for msg in baseline_msgs.messages if len(msg.data) > byte_pos
+            ]
+            stimulus_values = [
+                msg.data[byte_pos] for msg in stimulus_msgs.messages if len(msg.data) > byte_pos
+            ]
+
+            if not baseline_values or not stimulus_values:
+                continue
+
+            # Analyze changes
+            baseline_set = set(baseline_values)
+            stimulus_set = set(stimulus_values)
+
+            # Skip if not enough unique values
+            if len(baseline_set) < byte_threshold and len(stimulus_set) < byte_threshold:
+                continue
+
+            # Calculate statistics
+            baseline_arr = np.array(baseline_values)
+            stimulus_arr = np.array(stimulus_values)
+
+            baseline_mean = float(np.mean(baseline_arr))
+            stimulus_mean = float(np.mean(stimulus_arr))
+            mean_change = stimulus_mean - baseline_mean
+
+            baseline_range = float(np.max(baseline_arr) - np.min(baseline_arr))
+            stimulus_range = float(np.max(stimulus_arr) - np.min(stimulus_arr))
+            value_range_change = stimulus_range - baseline_range
+
+            # Calculate normalized change magnitude using multiple factors
+            # 1. Mean change (normalized by full byte range)
+            mean_change_norm = abs(mean_change) / 255.0
+
+            # 2. Range change (normalized by full byte range)
+            range_change_norm = abs(value_range_change) / 255.0
+
+            # 3. Set difference (Jaccard distance)
+            union_size = len(baseline_set | stimulus_set)
+            intersection_size = len(baseline_set & stimulus_set)
+            if union_size > 0:
+                jaccard_dist = 1.0 - (intersection_size / union_size)
+            else:
+                jaccard_dist = 0.0
+
+            # 4. Distribution change (Kolmogorov-Smirnov test)
+            try:
+                ks_stat, _ = stats.ks_2samp(baseline_arr, stimulus_arr)
+                ks_change_norm = float(ks_stat)
+            except Exception:
+                ks_change_norm = 0.0
+
+            # Combine factors (weighted average)
+            change_magnitude = (
+                0.3 * mean_change_norm
+                + 0.2 * range_change_norm
+                + 0.3 * jaccard_dist
+                + 0.2 * ks_change_norm
+            )
+
+            # Only report if there's a meaningful change
+            if change_magnitude > 0.0:
+                changes.append(
+                    ByteChange(
+                        byte_position=byte_pos,
+                        baseline_values=baseline_set,
+                        stimulus_values=stimulus_set,
+                        change_magnitude=change_magnitude,
+                        value_range_change=value_range_change,
+                        mean_change=mean_change,
+                    )
+                )
+
+        return changes
+
+    def find_responsive_messages(
+        self,
+        baseline_session: CANSession,
+        stimulus_session: CANSession,
+    ) -> list[int]:
+        """Find message IDs that changed.
+
+        This is a convenience method that returns just the list of message IDs
+        that showed any type of change.
+
+        Args:
+            baseline_session: Baseline capture.
+            stimulus_session: Stimulus capture.
+
+        Returns:
+            Sorted list of message IDs that changed.
+        """
+        report = self.detect_responses(baseline_session, stimulus_session)
+        return report.changed_messages + report.new_messages
+
+    def _detect_frequency_change(
+        self,
+        baseline_session: CANSession,
+        stimulus_session: CANSession,
+        message_id: int,
+    ) -> FrequencyChange | None:
+        """Detect frequency change for a specific message ID.
+
+        Args:
+            baseline_session: Baseline capture.
+            stimulus_session: Stimulus capture.
+            message_id: CAN arbitration ID.
+
+        Returns:
+            FrequencyChange if detected, None otherwise.
+        """
+        # Get messages
+        baseline_msgs = baseline_session._messages.filter_by_id(message_id)
+        stimulus_msgs = stimulus_session._messages.filter_by_id(message_id)
+
+        # Calculate frequencies
+        baseline_hz = self._calculate_frequency(
+            baseline_msgs.messages, baseline_session.time_range()
+        )
+        stimulus_hz = self._calculate_frequency(
+            stimulus_msgs.messages, stimulus_session.time_range()
+        )
+
+        # Determine change type and ratio
+        if baseline_hz == 0.0 and stimulus_hz > 0.0:
+            change_type = "appeared"
+            change_ratio = float("inf")
+            significance = 1.0
+        elif stimulus_hz == 0.0 and baseline_hz > 0.0:
+            change_type = "disappeared"
+            change_ratio = 0.0
+            significance = 1.0
+        elif baseline_hz > 0.0:
+            change_ratio = stimulus_hz / baseline_hz
+
+            # Determine if change is significant
+            # Use a threshold of 20% change
+            if change_ratio > 1.2:
+                change_type = "increased"
+                significance = min(1.0, (change_ratio - 1.0) / 1.0)
+            elif change_ratio < 0.8:
+                change_type = "decreased"
+                significance = min(1.0, (1.0 - change_ratio) / 1.0)
+            else:
+                # No significant change
+                return None
+        else:
+            # Both frequencies are zero
+            return None
+
+        return FrequencyChange(
+            message_id=message_id,
+            baseline_hz=baseline_hz,
+            stimulus_hz=stimulus_hz,
+            change_ratio=change_ratio,
+            change_type=change_type,
+            significance=significance,
+        )
+
+    @staticmethod
+    def _calculate_frequency(messages: list[CANMessage], time_range: tuple[float, float]) -> float:
+        """Calculate message frequency.
+
+        Args:
+            messages: List of CAN messages.
+            time_range: Tuple of (start_time, end_time).
+
+        Returns:
+            Frequency in Hz.
+        """
+        if not messages or len(messages) < 2:
+            return 0.0
+
+        start_time, end_time = time_range
+        duration = end_time - start_time
+
+        if duration <= 0.0:
+            return 0.0
+
+        # Use message count divided by duration
+        return (len(messages) - 1) / duration

oscura/automotive/dbc/__init__.py

@@ -0,0 +1,15 @@
+"""DBC database support for CAN signal definitions.
+
+This module provides DBC file parsing and generation capabilities.
+"""
+
+from __future__ import annotations
+
+__all__ = ["DBCGenerator", "DBCParser", "load_dbc"]
+
+try:
+    from oscura.automotive.dbc.generator import DBCGenerator
+    from oscura.automotive.dbc.parser import DBCParser, load_dbc
+except ImportError:
+    # Optional dependencies not installed
+    pass

oscura/automotive/dbc/generator.py

@@ -0,0 +1,156 @@
+"""DBC file generator from discovery documents.
+
+This module generates standard DBC files from TraceKit discovery documents,
+enabling export of reverse-engineered protocols to industry-standard format.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from oscura.automotive.can.discovery import (
+        DiscoveryDocument,
+    )
+    from oscura.automotive.can.session import CANSession
+
+__all__ = ["DBCGenerator"]
+
+
+class DBCGenerator:
+    """Generate DBC files from discovery documents."""
+
+    @staticmethod
+    def generate(
+        discovery: DiscoveryDocument,
+        output_path: Path | str,
+        min_confidence: float = 0.0,
+        include_comments: bool = True,
+    ) -> None:
+        """Generate DBC file from discovery document.
+
+        Args:
+            discovery: DiscoveryDocument with discovered signals.
+            output_path: Output DBC file path.
+            min_confidence: Minimum confidence threshold for including signals.
+            include_comments: Include evidence as comments in DBC.
+        """
+        path = Path(output_path)
+
+        lines = []
+
+        # DBC header
+        lines.append('VERSION ""')
+        lines.append("")
+        lines.append("NS_ :")
+        lines.append("")
+        lines.append("BS_:")
+        lines.append("")
+        lines.append("BU_:")  # No nodes defined
+        lines.append("")
+
+        # Generate messages
+        for msg in sorted(discovery.messages.values(), key=lambda m: m.id):
+            # Filter signals by confidence
+            signals = [s for s in msg.signals if s.confidence >= min_confidence]
+
+            if not signals:
+                continue  # Skip messages with no high-confidence signals
+
+            # Message definition
+            # Format: BO_ <ID> <Name>: <DLC> <Transmitter>
+            transmitter = msg.transmitter if msg.transmitter else "Vector__XXX"
+            lines.append(f"BO_ {msg.id} {msg.name}: {msg.length} {transmitter}")
+
+            # Signals
+            for sig in signals:
+                # Format: SG_ <Name> : <StartBit>|<Length>@<ByteOrder><ValueType> (<Scale>,<Offset>) [<Min>|<Max>] "<Unit>" <Receiver>
+                byte_order = "0" if sig.byte_order == "big_endian" else "1"
+                value_type = "+" if sig.value_type == "unsigned" else "-"
+
+                min_val = sig.min_value if sig.min_value is not None else 0
+                max_val = sig.max_value if sig.max_value is not None else 0
+
+                signal_line = (
+                    f" SG_ {sig.name} : {sig.start_bit}|{sig.length}@{byte_order}{value_type} "
+                    f"({sig.scale},{sig.offset}) [{min_val}|{max_val}] "
+                    f'"{sig.unit}" Vector__XXX'
+                )
+
+                lines.append(signal_line)
+
+                # Add comment if evidence exists
+                if include_comments and sig.evidence:
+                    evidence_str = "; ".join(sig.evidence)
+                    # DBC comments format: CM_ SG_ <ID> <SignalName> "<Comment>";
+                    comment_line = f'CM_ SG_ {msg.id} {sig.name} "{evidence_str}";'
+                    lines.append("")
+                    lines.append(comment_line)
+
+            lines.append("")
+
+        # Write file with latin-1 encoding (DBC standard)
+        with open(path, "w", encoding="latin-1") as f:
+            f.write("\n".join(lines))
+
+    @staticmethod
+    def generate_from_session(
+        session: CANSession,
+        output_path: Path | str,
+        min_confidence: float = 0.8,  # noqa: ARG004 - API compatibility parameter
+    ) -> None:
+        """Generate DBC file from CANSession with documented signals.
+
+        Args:
+            session: CANSession with documented signals.
+            output_path: Output DBC file path.
+            min_confidence: Minimum confidence threshold (reserved for future use).
+        """
+        from oscura.automotive.can.discovery import (
+            DiscoveryDocument,
+            MessageDiscovery,
+            SignalDiscovery,
+        )
+
+        # Build discovery document from session
+        doc = DiscoveryDocument()
+
+        # Get all unique IDs that have documented signals
+        for arb_id in session.unique_ids():
+            try:
+                msg_wrapper = session.message(arb_id)
+                documented = msg_wrapper.get_documented_signals()
+
+                if documented:
+                    # Create message discovery
+                    analysis = session.analyze_message(arb_id)
+
+                    signal_discoveries = []
+                    for sig_def in documented.values():
+                        sig_disc = SignalDiscovery.from_definition(
+                            sig_def,
+                            confidence=1.0,
+                            evidence=[],
+                        )
+                        signal_discoveries.append(sig_disc)
+
+                    msg_disc = MessageDiscovery(
+                        id=arb_id,
+                        name=f"Message_{arb_id:03X}",
+                        length=max(
+                            msg.dlc for msg in session._messages.filter_by_id(arb_id).messages
+                        ),
+                        cycle_time_ms=analysis.period_ms,
+                        confidence=1.0,
+                        signals=signal_discoveries,
+                    )
+
+                    doc.add_message(msg_disc)
+
+            except Exception:
+                # Skip messages without documented signals
+                pass
+
+        # Generate DBC
+        DBCGenerator.generate(doc, output_path, min_confidence=0.0)