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

oscura/automotive/uds/decoder.py

@@ -128,10 +128,13 @@ class UDSDecoder:
         # Handle ISO-TP single frame
         if message.data[0] <= 0x07:
             first_byte = message.data[1]
+            # Negative response needs: PCI + 0x7F + Requested SID + NRC = 4 bytes minimum
+            if first_byte == 0x7F:
+                return len(message.data) >= 4
         else:
             first_byte = message.data[0]
 
-        # Negative response
+        # Negative response (non-ISO-TP format)
         if first_byte == 0x7F:
             return len(message.data) >= 3
 
@@ -152,93 +155,172 @@ class UDSDecoder:
 
         Returns:
             UDSService, UDSNegativeResponse, or None if not a valid UDS message.
+
+        Example:
+            >>> msg = CANMessage(id=0x7E0, data=bytes([0x02, 0x10, 0x01]))
+            >>> service = UDSDecoder.decode_service(msg)
+            >>> print(service.name if service else "Invalid")
         """
         if len(message.data) < 2:
             return None
 
-        # Check for ISO-TP single frame header (0x0X = length)
-        iso_tp_offset = 0
-        uds_length = None
-        if message.data[0] <= 0x07:
-            iso_tp_offset = 1
-            uds_length = message.data[0]  # Length field tells us actual UDS payload size
-
-        # Extract UDS data (respecting length if ISO-TP)
-        if uds_length is not None:
-            # ISO-TP: extract exactly uds_length bytes starting after length byte
-            if len(message.data) < iso_tp_offset + uds_length:
-                return None
-            data = message.data[iso_tp_offset : iso_tp_offset + uds_length]
+        # Extract UDS payload from ISO-TP frame if needed
+        data = UDSDecoder._extract_uds_payload(message.data)
+        if not data:
+            return None
+
+        # Check for negative response
+        if data[0] == 0x7F:
+            return UDSDecoder._decode_negative_response(data)
+
+        # Determine SID and request/response type
+        sid_info = UDSDecoder._parse_sid_byte(data[0])
+        if sid_info is None:
+            return None
+
+        sid, canonical_sid, is_request = sid_info
+        service_name = _SERVICE_NAMES[canonical_sid]
+
+        # Extract sub-function and payload
+        sub_function, payload = UDSDecoder._extract_subfunction_and_payload(
+            data, canonical_sid, is_request
+        )
+
+        return UDSService(
+            sid=sid,
+            name=service_name,
+            request=is_request,
+            sub_function=sub_function,
+            data=payload,
+        )
+
+    @staticmethod
+    def _extract_uds_payload(message_data: bytes) -> bytes:
+        """Extract UDS payload from CAN message data.
+
+        Handles ISO-TP single frame format (first byte ≤0x07 indicates length).
+
+        Args:
+            message_data: Raw CAN message data.
+
+        Returns:
+            UDS payload bytes (empty if invalid).
+        """
+        if message_data[0] <= 0x07:
+            # ISO-TP single frame: [length, ...UDS data...]
+            uds_length = message_data[0]
+            if len(message_data) < 1 + uds_length:
+                return b""
+            return message_data[1 : 1 + uds_length]
         else:
-            # Direct UDS: use all remaining bytes
-            data = message.data[iso_tp_offset:]
+            # Direct UDS: all bytes are UDS data
+            return message_data
 
-        if not data:
+    @staticmethod
+    def _decode_negative_response(data: bytes) -> UDSNegativeResponse | None:
+        """Decode UDS negative response.
+
+        Format: [0x7F, requested_SID, NRC]
+
+        Args:
+            data: UDS payload starting with 0x7F.
+
+        Returns:
+            UDSNegativeResponse or None if invalid format.
+        """
+        if len(data) < 3:
             return None
 
-        first_byte = data[0]
+        requested_sid = data[1]
+        nrc = data[2]
+        nrc_name = _NRC_NAMES.get(nrc, f"unknownNRC_0x{nrc:02X}")
 
-        # Negative response: [0x7F, requested_SID, NRC]
-        if first_byte == 0x7F:
-            if len(data) < 3:
-                return None
-            requested_sid = data[1]
-            nrc = data[2]
-            nrc_name = _NRC_NAMES.get(nrc, f"unknownNRC_0x{nrc:02X}")
-            return UDSNegativeResponse(
-                requested_sid=requested_sid,
-                nrc=nrc,
-                nrc_name=nrc_name,
-            )
-
-        # Check for positive response (SID + 0x40)
-        # Response SIDs are in range 0x40-0x7F (corresponding to request SIDs 0x00-0x3F)
-        # and 0xC0-0xFF (corresponding to request SIDs 0x80-0xBF)
+        return UDSNegativeResponse(
+            requested_sid=requested_sid,
+            nrc=nrc,
+            nrc_name=nrc_name,
+        )
+
+    @staticmethod
+    def _parse_sid_byte(first_byte: int) -> tuple[int, int, bool] | None:
+        """Parse SID and request/response type from first UDS byte.
+
+        Args:
+            first_byte: First byte of UDS payload.
+
+        Returns:
+            Tuple of (actual_sid, canonical_sid, is_request) or None if unknown service.
+            - actual_sid: The SID byte from message (0x50 for responses, 0x10 for requests)
+            - canonical_sid: The canonical service ID for name lookup (always 0x10)
+            - is_request: True if request, False if response
+
+        Notes:
+            - Response SIDs: 0x40-0x7F (request 0x00-0x3F + 0x40)
+            - Response SIDs: 0xC0-0xFF (request 0x80-0xBF + 0x40)
+            - Request SIDs: 0x00-0x3F, 0x80-0xBF
+        """
         if 0x40 <= first_byte < 0x80:
             # Positive response to service 0x00-0x3F
-            sid = first_byte - 0x40
+            sid = first_byte  # Keep actual response SID (e.g., 0x50)
+            canonical_sid = first_byte - 0x40  # Request SID for validation (e.g., 0x10)
             is_request = False
         elif first_byte >= 0xC0:
             # Positive response to service 0x80-0xBF
-            sid = first_byte - 0x40
+            sid = first_byte  # Keep actual response SID
+            canonical_sid = first_byte - 0x40  # Request SID for validation
             is_request = False
         else:
             # Request (0x00-0x3F or 0x80-0xBF)
             sid = first_byte
+            canonical_sid = first_byte
             is_request = True
 
-        # Unknown service
-        if sid not in _SERVICE_NAMES:
+        # Validate service is known (use canonical request SID)
+        if canonical_sid not in _SERVICE_NAMES:
             return None
 
-        service_name = _SERVICE_NAMES[sid]
+        return (sid, canonical_sid, is_request)
+
+    @staticmethod
+    def _extract_subfunction_and_payload(
+        data: bytes, sid: int, is_request: bool
+    ) -> tuple[int | None, bytes]:
+        """Extract sub-function and payload from UDS service data.
+
+        Args:
+            data: UDS payload bytes.
+            sid: Service ID.
+            is_request: True if request, False if response.
 
-        # Extract sub-function if present
+        Returns:
+            Tuple of (sub_function, payload_bytes).
+
+        Notes:
+            Some services echo sub-function in responses: 0x10, 0x11, 0x27, 0x28, 0x31, 0x3E, 0x85.
+        """
         sub_function = None
         payload_offset = 1
 
-        if is_request and sid in _SERVICES_WITH_SUBFUNCTIONS:
+        if sid not in _SERVICES_WITH_SUBFUNCTIONS:
+            # No sub-function for this service
+            payload = data[payload_offset:] if len(data) > payload_offset else b""
+            return (sub_function, payload)
+
+        # Extract sub-function if data contains it
+        if is_request:
             if len(data) >= 2:
-                # Sub-function may have suppress positive response bit (0x80)
+                # Mask off suppress positive response bit (0x80)
+                sub_function = data[1] & 0x7F
+                payload_offset = 2
+        else:
+            # Response may echo sub-function for certain services
+            _SERVICES_WITH_ECHO = {0x10, 0x11, 0x27, 0x28, 0x31, 0x3E, 0x85}
+            if sid in _SERVICES_WITH_ECHO and len(data) >= 2:
                 sub_function = data[1] & 0x7F
                 payload_offset = 2
-        elif not is_request and sid in _SERVICES_WITH_SUBFUNCTIONS:
-            # Response may echo sub-function for some services
-            if sid in {0x10, 0x11, 0x27, 0x28, 0x31, 0x3E, 0x85}:
-                if len(data) >= 2:
-                    sub_function = data[1] & 0x7F
-                    payload_offset = 2
-
-        # Extract remaining data payload
-        payload = data[payload_offset:] if len(data) > payload_offset else b""
 
-        return UDSService(
-            sid=sid,
-            name=service_name,
-            request=is_request,
-            sub_function=sub_function,
-            data=payload,
-        )
+        payload = data[payload_offset:] if len(data) > payload_offset else b""
+        return (sub_function, payload)
 
     @staticmethod
     def get_service_name(sid: int) -> str:

oscura/automotive/uds/models.py

@@ -16,7 +16,8 @@ class UDSService:
     """A decoded UDS service.
 
     Attributes:
-        sid: Service ID (0x10-0xFF).
+        sid: Service ID (0x10-0xFF). For responses, this is the response SID (e.g., 0x50),
+             not the request SID (0x10).
         name: Human-readable service name.
         request: True if request message, False if positive response.
         sub_function: Sub-function byte (if applicable).
@@ -29,6 +30,11 @@ class UDSService:
     sub_function: int | None = None
     data: bytes = b""
 
+    @property
+    def is_response(self) -> bool:
+        """True if this is a response message."""
+        return not self.request
+
     def __repr__(self) -> str:
         """Human-readable representation."""
         msg_type = "Request" if self.request else "Response"

oscura/automotive/visualization.py

@@ -63,7 +63,7 @@ def plot_bus_timeline(
         msg_list: list[CANMessage] = [plot_messages]
     else:
         # Must be list[CANMessage] from slice
-        msg_list = plot_messages  # type: ignore[assignment]
+        msg_list = plot_messages
 
     # Extract timestamps and IDs
     timestamps = [_get_timestamp(msg) for msg in msg_list]

oscura/cli/analyze.py

@@ -0,0 +1,348 @@
+"""Oscura Analyze Command - Full Analysis Workflow.
+
+Provides CLI for running complete analysis workflows on waveform files with
+automatic protocol detection, signal characterization, and comprehensive reporting.
+
+
+Example:
+    $ oscura analyze signal.wfm
+    $ oscura analyze capture.wfm --protocol uart --export-dir output/
+    $ oscura analyze data.wfm --interactive
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import click
+
+from oscura.cli.main import format_output
+from oscura.cli.progress import ProgressReporter
+from oscura.sessions.legacy import Session
+
+logger = logging.getLogger("oscura.cli.analyze")
+
+
+@click.command()
+@click.argument("file", type=click.Path(exists=True))
+@click.option(
+    "--protocol",
+    type=str,
+    default="auto",
+    help="Protocol hint (auto for auto-detection).",
+)
+@click.option(
+    "--export-dir",
+    type=click.Path(),
+    default=None,
+    help="Directory to export results (default: ./oscura_output).",
+)
+@click.option(
+    "--interactive",
+    "-i",
+    is_flag=True,
+    help="Interactive mode with prompts.",
+)
+@click.option(
+    "--output",
+    type=click.Choice(["json", "csv", "html", "table"], case_sensitive=False),
+    default="table",
+    help="Output format (default: table).",
+)
+@click.option(
+    "--save-session",
+    type=click.Path(),
+    default=None,
+    help="Save analysis session to file (.tks).",
+)
+@click.pass_context
+def analyze(
+    ctx: click.Context,
+    file: str,
+    protocol: str,
+    export_dir: str | None,
+    interactive: bool,
+    output: str,
+    save_session: str | None,
+) -> None:
+    """Run full analysis workflow on waveform file.
+
+    Performs comprehensive analysis including signal characterization,
+    protocol detection and decoding, spectral analysis, and generates
+    detailed reports.
+
+    Args:
+        ctx: Click context object.
+        file: Path to waveform file to analyze.
+        protocol: Protocol hint or 'auto' for detection.
+        export_dir: Directory for exported results.
+        interactive: Enable interactive prompts.
+        output: Output format.
+        save_session: Path to save session file.
+
+    Examples:
+
+        \b
+        # Full auto analysis
+        $ oscura analyze capture.wfm
+
+        \b
+        # With protocol hint and export
+        $ oscura analyze signal.wfm \\
+            --protocol uart \\
+            --export-dir analysis_results/
+
+        \b
+        # Interactive mode
+        $ oscura analyze data.wfm --interactive
+    """
+    verbose = ctx.obj.get("verbose", 0)
+    quiet = ctx.obj.get("quiet", False)
+
+    if verbose:
+        logger.info(f"Analyzing: {file}")
+
+    try:
+        results = _perform_analysis_workflow(
+            file, protocol, export_dir, interactive, quiet, save_session
+        )
+        formatted = format_output(results, output)
+        click.echo(formatted)
+
+    except Exception as e:
+        logger.error(f"Analysis failed: {e}")
+        if verbose > 1:
+            raise
+        click.echo(f"Error: {e}", err=True)
+        ctx.exit(1)
+
+
+def _perform_analysis_workflow(
+    file: str,
+    protocol: str,
+    export_dir: str | None,
+    interactive: bool,
+    quiet: bool,
+    save_session: str | None,
+) -> dict[str, Any]:
+    """Perform complete analysis workflow."""
+    from oscura.loaders import load
+
+    progress = ProgressReporter(quiet=quiet, stages=5)
+
+    # Stage 1: Load file
+    progress.start_stage("Loading file")
+    trace = load(file)
+    progress.complete_stage()
+
+    # Stage 2: Signal characterization
+    progress.start_stage("Characterizing signal")
+    signal_char = _characterize_signal(trace)
+    progress.complete_stage()
+
+    # Stage 3: Protocol detection
+    progress.start_stage("Detecting protocol")
+    protocol_info = _detect_and_prepare_protocol(trace, protocol, interactive)
+    progress.complete_stage()
+
+    # Stage 4: Protocol decoding
+    progress.start_stage("Decoding protocol")
+    decoded = _decode_protocol(trace, protocol_info["protocol"])
+    progress.complete_stage()
+
+    # Stage 5: Generate report
+    progress.start_stage("Generating report")
+    results = _build_analysis_results(
+        file, signal_char, protocol_info, decoded, export_dir, save_session, trace
+    )
+    progress.complete_stage()
+    progress.finish()
+
+    return results
+
+
+def _detect_and_prepare_protocol(trace: Any, protocol: str, interactive: bool) -> dict[str, Any]:
+    """Detect and prepare protocol information."""
+    if protocol == "auto":
+        detected = _detect_protocol(trace, interactive=interactive)
+        protocol = detected["protocol"]
+    return {"protocol": protocol, "auto_detected": protocol == "auto"}
+
+
+def _build_analysis_results(
+    file: str,
+    signal_char: dict[str, Any],
+    protocol_info: dict[str, Any],
+    decoded: dict[str, Any],
+    export_dir: str | None,
+    save_session: str | None,
+    trace: Any,
+) -> dict[str, Any]:
+    """Build final analysis results with optional exports."""
+    results = {
+        "file": str(Path(file).name),
+        **signal_char,
+        **protocol_info,
+        **decoded,
+    }
+
+    if export_dir:
+        export_path = Path(export_dir)
+        export_path.mkdir(parents=True, exist_ok=True)
+        _export_results(results, export_path)
+        results["export_dir"] = str(export_path)
+
+    if save_session:
+        session = Session(name=Path(file).stem)
+        session.add_trace("main", trace)
+        session.metadata["analysis_results"] = results
+        session.save(save_session)
+        results["session_file"] = save_session
+
+    return results
+
+
+def _characterize_signal(trace: Any) -> dict[str, Any]:
+    """Characterize signal properties.
+
+    Args:
+        trace: Waveform trace to characterize.
+
+    Returns:
+        Dictionary of signal characteristics.
+    """
+    import numpy as np
+
+    from oscura.analyzers.waveform.measurements import fall_time, rise_time
+
+    data = trace.data
+    sample_rate = trace.metadata.sample_rate
+
+    rt = rise_time(trace)
+    ft = fall_time(trace)
+
+    return {
+        "sample_rate": f"{sample_rate / 1e6:.1f} MHz",
+        "samples": len(data),
+        "duration": f"{len(data) / sample_rate * 1e3:.3f} ms",
+        "amplitude": f"{float(data.max() - data.min()):.3f} V",
+        "rise_time": f"{rt * 1e9:.2f} ns" if not np.isnan(rt) else "N/A",
+        "fall_time": f"{ft * 1e9:.2f} ns" if not np.isnan(ft) else "N/A",
+    }
+
+
+def _detect_protocol(trace: Any, interactive: bool = False) -> dict[str, Any]:
+    """Detect protocol from trace.
+
+    Args:
+        trace: Trace to analyze.
+        interactive: If True, prompt for confirmation.
+
+    Returns:
+        Detection results.
+    """
+    from oscura.inference.protocol import detect_protocol
+
+    detection = detect_protocol(trace, min_confidence=0.5, return_candidates=True)
+
+    if interactive and detection.get("confidence", 0) < 0.9:
+        click.echo(f"\nDetected protocol: {detection['protocol']}")
+        click.echo(f"Confidence: {detection['confidence']:.1%}")
+
+        if not click.confirm("Use this protocol?", default=True):
+            # Show candidates
+            candidates = detection.get("candidates", [])
+            if candidates:
+                click.echo("\nOther candidates:")
+                for i, cand in enumerate(candidates[:5], 1):
+                    click.echo(f"  {i}. {cand['protocol']} ({cand['confidence']:.1%})")
+
+                choice = click.prompt("Select protocol (1-5, or 0 for manual)", type=int, default=1)
+                if 1 <= choice <= len(candidates):
+                    detection = candidates[choice - 1]
+                elif choice == 0:
+                    manual = click.prompt("Enter protocol name", type=str)
+                    detection = {"protocol": manual, "confidence": 1.0}
+
+    return detection
+
+
+def _decode_protocol(trace: Any, protocol: str) -> dict[str, Any]:
+    """Decode protocol from trace.
+
+    Args:
+        trace: Trace to decode.
+        protocol: Protocol name.
+
+    Returns:
+        Decoding results.
+    """
+    from oscura.core.types import DigitalTrace
+
+    # Convert to digital if needed
+    if not isinstance(trace, DigitalTrace):
+        import numpy as np
+
+        threshold = (np.max(trace.data) + np.min(trace.data)) / 2
+        digital_data = trace.data > threshold
+        digital_trace = DigitalTrace(data=digital_data, metadata=trace.metadata)
+    else:
+        digital_trace = trace
+
+    # Decode based on protocol
+    packets: list[Any] = []
+    if protocol.lower() == "uart":
+        from oscura.analyzers.protocols.uart import UARTDecoder
+
+        uart_decoder = UARTDecoder(baudrate=0)  # Auto-detect
+        packets = list(uart_decoder.decode(digital_trace))
+    elif protocol.lower() == "spi":
+        from oscura.analyzers.protocols.spi import SPIDecoder
+
+        spi_decoder = SPIDecoder()
+        packets = list(
+            spi_decoder.decode(
+                clk=digital_trace.data,
+                mosi=digital_trace.data,
+                sample_rate=trace.metadata.sample_rate,
+            )
+        )
+    elif protocol.lower() == "i2c":
+        from oscura.analyzers.protocols.i2c import I2CDecoder
+
+        i2c_decoder = I2CDecoder()
+        packets = list(
+            i2c_decoder.decode(
+                scl=digital_trace.data,
+                sda=digital_trace.data,
+                sample_rate=trace.metadata.sample_rate,
+            )
+        )
+
+    return {
+        "packets_decoded": len(packets),
+        "errors": sum(1 for p in packets if p.errors),
+    }
+
+
+def _export_results(results: dict[str, Any], export_dir: Path) -> None:
+    """Export results to directory.
+
+    Args:
+        results: Results dictionary.
+        export_dir: Export directory path.
+    """
+    import json
+
+    # Export JSON
+    json_path = export_dir / "analysis_results.json"
+    with open(json_path, "w") as f:
+        json.dump(results, f, indent=2, default=str)
+
+    # Export HTML report
+    html_path = export_dir / "analysis_report.html"
+    html_content = format_output(results, "html")
+    with open(html_path, "w") as f:
+        f.write(html_content)