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

oscura/automotive/loaders/__init__.py

@@ -0,0 +1,35 @@
+"""Automotive file format loaders.
+
+This module provides loaders for common automotive logging file formats:
+- BLF (Vector Binary Logging Format)
+- ASC (Vector ASCII Format)
+- MDF/MF4 (ASAM Measurement Data Format)
+- CSV (Comma-Separated Values)
+- PCAP (Packet Capture - SocketCAN)
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "detect_format",
+    "load_asc",
+    "load_automotive_log",
+    "load_blf",
+    "load_csv_can",
+    "load_mdf",
+    "load_pcap",
+]
+
+try:
+    from oscura.automotive.loaders.asc import load_asc
+    from oscura.automotive.loaders.blf import load_blf
+    from oscura.automotive.loaders.csv_can import load_csv_can
+    from oscura.automotive.loaders.dispatcher import (
+        detect_format,
+        load_automotive_log,
+    )
+    from oscura.automotive.loaders.mdf import load_mdf
+    from oscura.automotive.loaders.pcap import load_pcap
+except ImportError:
+    # Optional dependencies not installed
+    pass

oscura/automotive/loaders/asc.py

@@ -0,0 +1,98 @@
+"""Vector ASC (ASCII Format) file loader.
+
+This module provides loading of Vector ASC files. ASC is a human-readable
+text format used by Vector tools for logging CAN bus data.
+
+ASC format example:
+    date Mon Jul 15 10:30:45.123 2024
+    0.000000 1 123 Rx d 8 01 02 03 04 05 06 07 08
+    0.010000 1 280 Rx d 8 0A 0B 0C 0D 0E 0F 10 11
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from oscura.automotive.can.models import CANMessage, CANMessageList
+
+__all__ = ["load_asc"]
+
+
+def load_asc(file_path: Path | str) -> CANMessageList:
+    """Load CAN messages from a Vector ASC file.
+
+    Args:
+        file_path: Path to the ASC file.
+
+    Returns:
+        CANMessageList containing all parsed CAN messages.
+
+    Raises:
+        FileNotFoundError: If file doesn't exist.
+        ValueError: If file cannot be parsed.
+
+    Example:
+        >>> messages = load_asc("capture.asc")
+        >>> print(f"Loaded {len(messages)} messages")
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"ASC file not found: {path}")
+
+    messages = CANMessageList()
+
+    # Regex pattern for CAN message lines
+    # Format: <timestamp> <channel> <ID> <direction> <type> <DLC> <data bytes>
+    # Example: 0.123456 1 123 Rx d 8 01 02 03 04 05 06 07 08
+    pattern = re.compile(
+        r"^\s*(\d+\.\d+)\s+"  # timestamp
+        r"(\d+)\s+"  # channel
+        r"([0-9A-Fa-f]+)\s+"  # CAN ID (hex)
+        r"(Rx|Tx)\s+"  # direction
+        r"d\s+"  # type (d = data frame)
+        r"(\d+)\s+"  # DLC
+        r"((?:[0-9A-Fa-f]{2}\s*)*)"  # data bytes
+    )
+
+    try:
+        with open(path, encoding="utf-8", errors="ignore") as f:
+            for line in f:
+                # Skip comments and header lines
+                if line.startswith("//") or line.startswith("date"):
+                    continue
+
+                # Try to parse as CAN message
+                match = pattern.match(line)
+                if match:
+                    timestamp_str, channel_str, id_str, direction, dlc_str, data_str = (
+                        match.groups()
+                    )
+
+                    # Parse components
+                    timestamp = float(timestamp_str)
+                    channel = int(channel_str)
+                    arb_id = int(id_str, 16)
+                    int(dlc_str)
+
+                    # Parse data bytes
+                    data_bytes = bytes.fromhex(data_str.replace(" ", ""))
+
+                    # Determine if extended ID (typically > 0x7FF)
+                    is_extended = arb_id > 0x7FF
+
+                    # Create message
+                    can_msg = CANMessage(
+                        arbitration_id=arb_id,
+                        timestamp=timestamp,
+                        data=data_bytes,
+                        is_extended=is_extended,
+                        is_fd=False,  # ASC typically doesn't indicate FD
+                        channel=channel,
+                    )
+                    messages.append(can_msg)
+
+    except Exception as e:
+        raise ValueError(f"Failed to parse ASC file {path}: {e}") from e
+
+    return messages

oscura/automotive/loaders/blf.py

@@ -0,0 +1,77 @@
+"""Vector BLF (Binary Logging Format) file loader.
+
+This module provides loading of Vector BLF files using the python-can library.
+BLF is a proprietary binary format used by Vector tools (CANoe, CANalyzer, etc.)
+for logging CAN bus data.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from oscura.automotive.can.models import CANMessage, CANMessageList
+
+__all__ = ["load_blf"]
+
+
+def load_blf(file_path: Path | str) -> CANMessageList:
+    """Load CAN messages from a Vector BLF file.
+
+    Args:
+        file_path: Path to the BLF file.
+
+    Returns:
+        CANMessageList containing all parsed CAN messages.
+
+    Raises:
+        ImportError: If python-can is not installed.
+        FileNotFoundError: If file doesn't exist.
+        ValueError: If file cannot be parsed.
+
+    Example:
+        >>> messages = load_blf("capture.blf")
+        >>> print(f"Loaded {len(messages)} messages")
+        >>> print(f"Unique IDs: {len(messages.unique_ids())}")
+    """
+    try:
+        import can  # type: ignore[import-untyped]
+    except ImportError as e:
+        raise ImportError(
+            "python-can is required for BLF file support. "
+            "Install with: pip install 'oscura[automotive]'"
+        ) from e
+
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"BLF file not found: {path}")
+
+    messages = CANMessageList()
+
+    try:
+        # Open BLF file using python-can
+        with can.BLFReader(str(path)) as reader:
+            for msg in reader:
+                # Convert python-can Message to our CANMessage
+                # Extract channel number (python-can may return various types)
+                channel = 0
+                if hasattr(msg, "channel"):
+                    ch = msg.channel
+                    if isinstance(ch, int):
+                        channel = ch
+                    elif ch is not None:
+                        channel = int(ch)  # type: ignore[arg-type]
+
+                can_msg = CANMessage(
+                    arbitration_id=msg.arbitration_id,
+                    timestamp=msg.timestamp,
+                    data=bytes(msg.data),
+                    is_extended=msg.is_extended_id,
+                    is_fd=msg.is_fd,
+                    channel=channel,
+                )
+                messages.append(can_msg)
+
+    except Exception as e:
+        raise ValueError(f"Failed to parse BLF file {path}: {e}") from e
+
+    return messages

oscura/automotive/loaders/csv_can.py

@@ -0,0 +1,136 @@
+"""CSV CAN log file loader.
+
+This module provides loading of CAN data from CSV files.
+Supports various CSV formats commonly used for CAN logging.
+
+Common CSV format:
+    timestamp,id,data
+    0.000000,0x123,0102030405060708
+    0.010000,0x280,0A0B0C0D0E0F1011
+"""
+
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+
+from oscura.automotive.can.models import CANMessage, CANMessageList
+
+__all__ = ["load_csv_can"]
+
+
+def load_csv_can(file_path: Path | str, delimiter: str = ",") -> CANMessageList:
+    """Load CAN messages from a CSV file.
+
+    This function attempts to automatically detect the CSV column layout
+    and parse CAN messages accordingly.
+
+    Expected columns (case-insensitive, order-independent):
+    - timestamp or time: Message timestamp
+    - id or can_id or arbitration_id: CAN ID (hex or decimal)
+    - data or payload: Data bytes (hex string)
+    - Optional: channel, dlc, extended, etc.
+
+    Args:
+        file_path: Path to the CSV file.
+        delimiter: CSV delimiter character.
+
+    Returns:
+        CANMessageList containing all parsed CAN messages.
+
+    Raises:
+        FileNotFoundError: If file doesn't exist.
+        ValueError: If file cannot be parsed or has unexpected format.
+
+    Example:
+        >>> messages = load_csv_can("capture.csv")
+        >>> print(f"Loaded {len(messages)} messages")
+    """
+    path = Path(file_path)
+    if not path.exists():
+        raise FileNotFoundError(f"CSV file not found: {path}")
+
+    messages = CANMessageList()
+
+    try:
+        with open(path, encoding="utf-8") as f:
+            reader = csv.DictReader(f, delimiter=delimiter)
+
+            # Try to detect column names
+            if not reader.fieldnames:
+                raise ValueError("CSV file has no header row")
+
+            # Normalize column names to lowercase for easier matching
+            fieldnames = [name.lower().strip() for name in reader.fieldnames]
+
+            # Find required columns
+            timestamp_col = None
+            id_col = None
+            data_col = None
+
+            for col in fieldnames:
+                if "timestamp" in col or col == "time" or col == "t":
+                    timestamp_col = col
+                elif "id" in col or col == "can_id" or col == "arbitration_id":
+                    id_col = col
+                elif "data" in col or col == "payload" or col == "bytes":
+                    data_col = col
+
+            if not all([timestamp_col, id_col, data_col]):
+                raise ValueError(
+                    f"CSV file missing required columns. "
+                    f"Found: {fieldnames}. "
+                    f"Need: timestamp, id, data"
+                )
+
+            # Parse messages
+            for row_dict in reader:
+                # Create lowercase dict for case-insensitive access
+                row = {k.lower().strip(): v for k, v in row_dict.items()}
+
+                try:
+                    # Parse timestamp
+                    timestamp = float(row[timestamp_col])
+
+                    # Parse ID (handle hex or decimal)
+                    id_str = row[id_col].strip()
+                    if id_str.startswith("0x") or id_str.startswith("0X"):
+                        arb_id = int(id_str, 16)
+                    else:
+                        # Try as int first, then hex
+                        try:
+                            arb_id = int(id_str)
+                        except ValueError:
+                            arb_id = int(id_str, 16)
+
+                    # Parse data bytes
+                    data_str = row[data_col].strip()
+                    # Remove common separators and spaces
+                    data_str = data_str.replace(" ", "").replace(":", "").replace("-", "")
+                    # Remove 0x prefix if present
+                    if data_str.startswith("0x") or data_str.startswith("0X"):
+                        data_str = data_str[2:]
+                    data_bytes = bytes.fromhex(data_str)
+
+                    # Determine if extended (>11 bits = 0x7FF)
+                    is_extended = arb_id > 0x7FF
+
+                    # Create message
+                    can_msg = CANMessage(
+                        arbitration_id=arb_id,
+                        timestamp=timestamp,
+                        data=data_bytes,
+                        is_extended=is_extended,
+                        is_fd=False,
+                        channel=0,
+                    )
+                    messages.append(can_msg)
+
+                except (ValueError, KeyError):
+                    # Skip malformed rows
+                    continue
+
+    except Exception as e:
+        raise ValueError(f"Failed to parse CSV file {path}: {e}") from e
+
+    return messages

oscura/automotive/loaders/dispatcher.py

@@ -0,0 +1,136 @@
+"""Automatic file format detection and loading dispatcher.
+
+This module provides automatic detection of automotive log file formats
+and dispatching to the appropriate loader.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from oscura.automotive.can.models import CANMessageList
+
+__all__ = ["detect_format", "load_automotive_log"]
+
+
+def detect_format(file_path: Path | str) -> str:
+    """Detect automotive log file format.
+
+    Args:
+        file_path: Path to the file.
+
+    Returns:
+        str: Format name: 'blf', 'asc', 'mdf', 'csv', 'pcap', or 'unknown'.
+    """
+    path = Path(file_path)
+
+    # Check extension first
+    ext = path.suffix.lower()
+
+    if ext == ".blf":
+        return "blf"
+    elif ext == ".asc":
+        return "asc"
+    elif ext in [".mdf", ".mf4", ".dat"]:
+        return "mdf"
+    elif ext == ".csv":
+        return "csv"
+    elif ext in [".pcap", ".pcapng"]:
+        return "pcap"
+
+    # If extension is ambiguous, check file contents
+    try:
+        with open(path, "rb") as f:
+            header = f.read(16)
+
+            # BLF magic: "LOGG"
+            if header[:4] == b"LOGG":
+                return "blf"
+
+            # MDF magic: "MDF" or "HDBlock"
+            if b"MDF" in header or b"HD" in header[:8]:
+                return "mdf"
+
+            # PCAP magic
+            if header[:4] in [b"\xd4\xc3\xb2\xa1", b"\xa1\xb2\xc3\xd4"]:
+                return "pcap"
+
+    except Exception:
+        pass
+
+    # Try as text file
+    try:
+        with open(path, encoding="utf-8") as f:
+            first_line = f.readline().strip()
+
+            # ASC files typically start with "date" or timestamp
+            if first_line.startswith("date") or "CAN" in first_line:
+                return "asc"
+
+            # CSV with CAN data
+            if "," in first_line and ("id" in first_line.lower() or "can" in first_line.lower()):
+                return "csv"
+
+    except Exception:
+        pass
+
+    return "unknown"
+
+
+def load_automotive_log(file_path: Path | str) -> CANMessageList:
+    """Load automotive log file, automatically detecting format.
+
+    This function automatically detects the file format and uses the
+    appropriate loader.
+
+    Args:
+        file_path: Path to the automotive log file.
+
+    Returns:
+        CANMessageList containing all parsed messages.
+
+    Raises:
+        FileNotFoundError: If the specified file does not exist.
+        ValueError: If file format cannot be determined or is unsupported.
+    """
+    path = Path(file_path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    # Detect format
+    fmt = detect_format(path)
+
+    if fmt == "unknown":
+        raise ValueError(f"Unknown or unsupported file format: {path}")
+
+    # Import and dispatch
+    if fmt == "blf":
+        from oscura.automotive.loaders.blf import load_blf
+
+        return load_blf(path)
+
+    elif fmt == "asc":
+        from oscura.automotive.loaders.asc import load_asc
+
+        return load_asc(path)
+
+    elif fmt == "mdf":
+        from oscura.automotive.loaders.mdf import load_mdf
+
+        return load_mdf(path)
+
+    elif fmt == "csv":
+        from oscura.automotive.loaders.csv_can import load_csv_can
+
+        return load_csv_can(path)
+
+    elif fmt == "pcap":
+        from oscura.automotive.loaders.pcap import load_pcap
+
+        return load_pcap(path)
+
+    else:
+        raise ValueError(f"Unsupported format: {fmt}")