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

oscura/automotive/loaders/mdf.py

@@ -0,0 +1,331 @@
+"""ASAM MDF/MF4 (Measurement Data Format) file loader.
+
+This module provides loading of MDF4/MF4 files using the asammdf library.
+MDF is an industry-standard format for storing measurement data,
+commonly used with CAN bus loggers like CANedge.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from oscura.automotive.can.models import CANMessage, CANMessageList
+
+if TYPE_CHECKING:
+    import numpy.typing as npt
+
+__all__ = ["load_mdf"]
+
+
+def load_mdf(file_path: Path | str) -> CANMessageList:
+    """Load CAN messages from an MDF/MF4 file.
+
+    This loader supports both MDF3 and MDF4 (MF4) formats. It handles various
+    CAN logging structures commonly found in MDF files from tools like CANedge,
+    Vector CANalyzer, ETAS INCA, and others.
+
+    The loader attempts multiple extraction strategies:
+    1. Bus logging format (CAN frames as structured records)
+    2. Signal-based format (CAN ID, data, timestamps as separate channels)
+    3. Raw frame format (binary CAN frames)
+
+    Args:
+        file_path: Path to the MDF/MF4 file.
+
+    Returns:
+        CANMessageList containing all parsed CAN messages.
+
+    Raises:
+        ImportError: If asammdf is not installed.
+        FileNotFoundError: If file doesn't exist.
+        ValueError: If file cannot be parsed or contains no CAN data.
+
+    Example:
+        >>> messages = load_mdf("capture.mf4")
+        >>> print(f"Loaded {len(messages)} messages")
+        >>> print(f"Unique IDs: {len(messages.unique_ids())}")
+    """
+    try:
+        from asammdf import MDF  # type: ignore[import-untyped]
+    except ImportError as e:
+        raise ImportError(
+            "asammdf is required for MDF/MF4 file support. "
+            "Install with: pip install 'oscura[automotive]'"
+        ) from e
+
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"MDF file not found: {path}")
+
+    messages = CANMessageList()
+
+    try:
+        # Open MDF file (supports both MDF3 and MDF4)
+        with MDF(str(path)) as mdf:
+            # Strategy 1: Try to extract CAN bus logging data
+            # Look for channels with CAN-related names
+            _extract_can_bus_logging(mdf, messages)
+
+            # Strategy 2: If no messages found, try signal-based extraction
+            # Some MDF files store CAN ID, data, timestamp as separate signals
+            if not messages.messages:
+                _extract_can_signals(mdf, messages)
+
+            # Strategy 3: Try iterating through all channels looking for CAN data patterns
+            if not messages.messages:
+                _extract_can_channels(mdf, messages)
+
+    except Exception as e:
+        raise ValueError(f"Failed to parse MDF file {path}: {e}") from e
+
+    if not messages.messages:
+        raise ValueError(
+            f"No CAN messages found in MDF file {path}. "
+            "File may not contain CAN bus data or uses unsupported format."
+        )
+
+    return messages
+
+
+def _extract_can_bus_logging(mdf: Any, messages: CANMessageList) -> None:
+    """Extract CAN messages from bus logging format.
+
+    This handles MDF files that store CAN frames as structured bus logging data,
+    common in Vector tools and CANedge loggers.
+
+    Args:
+        mdf: Opened MDF file object.
+        messages: CANMessageList to append extracted messages to.
+    """
+    # Common CAN bus logging channel patterns
+    can_bus_patterns = [
+        "CAN_DataFrame",
+        "CANBus",
+        "CAN_Message",
+        "CAN.DataFrames",
+        "CAN Bus",
+    ]
+
+    for channel_name in mdf.channels_db:
+        # Check if channel name matches CAN bus logging pattern
+        if any(pattern in channel_name for pattern in can_bus_patterns):
+            try:
+                signal = mdf.get(channel_name)
+
+                # Extract timestamps
+                timestamps = signal.timestamps
+
+                # CAN data could be in samples (structured) or as raw bytes
+                samples = signal.samples
+
+                # Handle different sample structures
+                if hasattr(samples, "dtype") and samples.dtype.names:
+                    # Structured array with fields
+                    _extract_structured_can_frames(samples, timestamps, messages)
+                else:
+                    # Try to interpret as raw CAN frames
+                    _extract_raw_can_frames(samples, timestamps, messages)
+
+            except Exception:
+                # Skip channels that fail to parse
+                continue
+
+
+def _extract_structured_can_frames(
+    samples: npt.NDArray[Any], timestamps: npt.NDArray[Any], messages: CANMessageList
+) -> None:
+    """Extract CAN messages from structured array format.
+
+    Args:
+        samples: Structured numpy array with CAN frame fields.
+        timestamps: Array of timestamps.
+        messages: CANMessageList to append to.
+    """
+    # Common field names in structured CAN logging
+    id_fields = ["ID", "id", "BusID", "Identifier", "ArbitrationID"]
+    data_fields = ["Data", "data", "DataBytes", "Payload"]
+    dlc_fields = ["DLC", "dlc", "DataLength"]
+
+    # Find which fields are present
+    field_names = samples.dtype.names
+    if not field_names:
+        return
+
+    id_field = next((f for f in id_fields if f in field_names), None)
+    data_field = next((f for f in data_fields if f in field_names), None)
+    dlc_field = next((f for f in dlc_fields if f in field_names), None)
+
+    if not id_field:
+        return
+
+    for i in range(len(samples)):
+        try:
+            # Extract CAN ID
+            arb_id = int(samples[id_field][i])
+
+            # Extract data bytes
+            if data_field:
+                data_bytes = samples[data_field][i]
+                if isinstance(data_bytes, bytes):
+                    data = data_bytes
+                else:
+                    # Convert array to bytes
+                    data = bytes(data_bytes)
+            else:
+                data = b""
+
+            # Extract DLC if available
+            if dlc_field:
+                dlc = int(samples[dlc_field][i])
+                data = data[:dlc]
+
+            # Determine if extended ID
+            is_extended = arb_id > 0x7FF
+
+            # Create message
+            can_msg = CANMessage(
+                arbitration_id=arb_id,
+                timestamp=float(timestamps[i]),
+                data=data,
+                is_extended=is_extended,
+                is_fd=False,  # MDF doesn't typically indicate CAN-FD
+                channel=0,  # Channel info not always available in MDF
+            )
+            messages.append(can_msg)
+
+        except (IndexError, ValueError, TypeError):
+            # Skip malformed frames
+            continue
+
+
+def _extract_raw_can_frames(
+    samples: npt.NDArray[Any], timestamps: npt.NDArray[Any], messages: CANMessageList
+) -> None:
+    """Extract CAN messages from raw byte format.
+
+    Args:
+        samples: Raw bytes array.
+        timestamps: Array of timestamps.
+        messages: CANMessageList to append to.
+    """
+    # Attempt to parse raw CAN frames
+    # Typical raw CAN frame: [ID (4 bytes)] [DLC (1 byte)] [Data (up to 8 bytes)]
+    for i in range(len(samples)):
+        try:
+            frame = samples[i]
+            if isinstance(frame, bytes) and len(frame) >= 5:
+                # Parse standard raw CAN frame structure
+                arb_id = int.from_bytes(frame[0:4], byteorder="little")
+                dlc = min(frame[4], 8)
+                data = frame[5 : 5 + dlc]
+
+                # Determine if extended ID
+                is_extended = arb_id > 0x7FF
+
+                can_msg = CANMessage(
+                    arbitration_id=arb_id,
+                    timestamp=float(timestamps[i]),
+                    data=data,
+                    is_extended=is_extended,
+                    is_fd=False,
+                    channel=0,
+                )
+                messages.append(can_msg)
+
+        except (IndexError, ValueError, TypeError):
+            continue
+
+
+def _extract_can_signals(mdf: Any, messages: CANMessageList) -> None:
+    """Extract CAN messages from separate signal channels.
+
+    This handles MDF files where CAN ID, data, and timestamps are stored
+    as separate channels/signals.
+
+    Args:
+        mdf: Opened MDF file object.
+        messages: CANMessageList to append to.
+    """
+    # Look for separate CAN ID and data channels
+    id_patterns = ["CAN_ID", "CANID", "CAN.ID", "Identifier"]
+    data_patterns = ["CAN_Data", "CANData", "CAN.Data", "Payload"]
+
+    id_channels = []
+    data_channels = []
+
+    for channel_name in mdf.channels_db:
+        if any(pattern in channel_name for pattern in id_patterns):
+            id_channels.append(channel_name)
+        elif any(pattern in channel_name for pattern in data_patterns):
+            data_channels.append(channel_name)
+
+    # Try to match ID and data channels
+    for id_channel in id_channels:
+        for data_channel in data_channels:
+            try:
+                id_signal = mdf.get(id_channel)
+                data_signal = mdf.get(data_channel)
+
+                # Ensure same length
+                if len(id_signal.timestamps) != len(data_signal.timestamps):
+                    continue
+
+                # Extract messages
+                for i in range(len(id_signal.timestamps)):
+                    arb_id = int(id_signal.samples[i])
+                    data = bytes(data_signal.samples[i])
+                    timestamp = float(id_signal.timestamps[i])
+
+                    is_extended = arb_id > 0x7FF
+
+                    can_msg = CANMessage(
+                        arbitration_id=arb_id,
+                        timestamp=timestamp,
+                        data=data,
+                        is_extended=is_extended,
+                        is_fd=False,
+                        channel=0,
+                    )
+                    messages.append(can_msg)
+
+            except Exception:
+                continue
+
+
+def _extract_can_channels(mdf: Any, messages: CANMessageList) -> None:
+    """Extract CAN messages by searching all channels for CAN patterns.
+
+    This is a fallback strategy that looks for any channel containing
+    'CAN' in the name and attempts to extract CAN data.
+
+    Args:
+        mdf: Opened MDF file object.
+        messages: CANMessageList to append to.
+    """
+    can_keywords = ["CAN", "can"]
+
+    for channel_name in mdf.channels_db:
+        # Only process channels with CAN in the name
+        if not any(keyword in channel_name for keyword in can_keywords):
+            continue
+
+        try:
+            signal = mdf.get(channel_name)
+            timestamps = signal.timestamps
+            samples = signal.samples
+
+            # Try different interpretations
+            if hasattr(samples, "dtype"):
+                if samples.dtype.names:
+                    # Structured
+                    _extract_structured_can_frames(samples, timestamps, messages)
+                elif samples.dtype == "uint32" or samples.dtype == "int32":
+                    # Could be CAN IDs
+                    pass
+                elif len(samples.shape) == 2 and samples.shape[1] >= 8:
+                    # Could be CAN data bytes
+                    pass
+
+        except Exception:
+            continue

oscura/automotive/loaders/pcap.py

@@ -0,0 +1,132 @@
+"""PCAP file loader for CAN bus data.
+
+This module provides loading of PCAP files containing SocketCAN frames.
+PCAP is a common packet capture format that can contain CAN frames from
+network interfaces or recorded with tools like Wireshark or tcpdump.
+
+Supported formats:
+    - SocketCAN frames (Linux can0, can1, etc.)
+    - CAN frames from pcap-ng format
+
+Requirements:
+    - scapy library (install with: uv pip install scapy)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from oscura.automotive.can.models import CANMessage, CANMessageList
+
+if TYPE_CHECKING:
+    from scapy.packet import Packet  # type: ignore[import-not-found]
+
+__all__ = ["load_pcap"]
+
+
+def load_pcap(file_path: Path | str) -> CANMessageList:
+    """Load CAN messages from a PCAP file.
+
+    This function reads PCAP files containing SocketCAN frames and converts
+    them to TraceKit's CANMessage format. It uses scapy to parse the PCAP
+    file and extract CAN frames.
+
+    Args:
+        file_path: Path to the PCAP or PCAPNG file.
+
+    Returns:
+        CANMessageList containing all parsed CAN messages.
+
+    Raises:
+        FileNotFoundError: If file doesn't exist.
+        ImportError: If scapy is not installed.
+        ValueError: If file cannot be parsed or contains no CAN frames.
+
+    Example:
+        >>> messages = load_pcap("capture.pcap")
+        >>> print(f"Loaded {len(messages)} messages")
+
+    Note:
+        Requires scapy to be installed:
+            uv pip install oscura[automotive]
+
+        Or manually:
+            uv pip install scapy
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"PCAP file not found: {path}")
+
+    try:
+        from scapy.all import rdpcap  # type: ignore[import-not-found]
+        from scapy.layers.can import CAN  # type: ignore[import-not-found]
+    except ImportError as e:
+        msg = "scapy library is required for PCAP loading. Install with: uv pip install scapy"
+        raise ImportError(msg) from e
+
+    messages = CANMessageList()
+
+    try:
+        # Read PCAP file
+        packets = rdpcap(str(path))
+
+        # Extract CAN frames
+        first_timestamp: float | None = None
+        for packet in packets:
+            # Check if packet contains CAN layer
+            if CAN in packet:
+                can_frame: Packet = packet[CAN]
+
+                # Get timestamp
+                if hasattr(packet, "time"):
+                    if first_timestamp is None:
+                        first_timestamp = float(packet.time)
+                    timestamp = float(packet.time) - first_timestamp
+                else:
+                    timestamp = 0.0
+
+                # Extract CAN ID and data
+                arb_id = int(can_frame.identifier)
+
+                # Get data bytes (scapy stores CAN data as bytes)
+                if hasattr(can_frame, "data"):
+                    data = bytes(can_frame.data)
+                else:
+                    data = b""
+
+                # Determine if extended ID (bit 31 indicates extended format)
+                # SocketCAN uses bit 31 for extended frame flag
+                is_extended = bool(arb_id & 0x80000000)
+                if is_extended:
+                    arb_id = arb_id & 0x1FFFFFFF  # Mask to get 29-bit ID
+
+                # Determine if CAN-FD (scapy may have an FD flag)
+                is_fd = hasattr(can_frame, "flags") and (can_frame.flags & 0x01)
+
+                # Extract channel if available
+                channel = 0
+                if hasattr(can_frame, "channel"):
+                    channel = int(can_frame.channel)
+
+                # Create CANMessage
+                can_msg = CANMessage(
+                    arbitration_id=arb_id,
+                    timestamp=timestamp,
+                    data=data,
+                    is_extended=is_extended,
+                    is_fd=is_fd,
+                    channel=channel,
+                )
+                messages.append(can_msg)
+
+    except Exception as e:
+        raise ValueError(f"Failed to parse PCAP file {path}: {e}") from e
+
+    if len(messages) == 0:
+        raise ValueError(
+            f"No CAN frames found in PCAP file {path}. "
+            "Ensure the capture contains SocketCAN or CAN frames."
+        )
+
+    return messages

oscura/automotive/obd/__init__.py

@@ -0,0 +1,14 @@
+"""OBD-II diagnostic protocol support.
+
+This module provides OBD-II (On-Board Diagnostics) protocol decoding
+for standard vehicle diagnostics.
+"""
+
+from __future__ import annotations
+
+__all__ = ["PID", "OBD2Decoder", "OBD2Response"]
+
+try:
+    from oscura.automotive.obd.decoder import PID, OBD2Decoder, OBD2Response
+except ImportError:
+    pass