oscura 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

oscura/automotive/j1939/spns.py

@@ -0,0 +1,326 @@
+"""J1939 Suspect Parameter Number (SPN) definitions.
+
+This module provides standard SPN definitions for common J1939 parameters
+according to SAE J1939/71 (Vehicle Application Layer).
+
+Example:
+    >>> from oscura.automotive.j1939.spns import get_standard_spns
+    >>> spns = get_standard_spns()
+    >>> engine_speed = next(s for s in spns[61444] if s.spn == 190)
+    >>> engine_speed.name
+    'Engine Speed'
+    >>> engine_speed.unit
+    'rpm'
+"""
+
+from __future__ import annotations
+
+from oscura.automotive.j1939.analyzer import J1939SPN
+
+__all__ = [
+    "STANDARD_SPNS",
+    "get_standard_spns",
+]
+
+
+def get_standard_spns() -> dict[int, list[J1939SPN]]:
+    """Get standard SPN definitions for common PGNs.
+
+    Returns:
+        Dictionary mapping PGN to list of SPNs.
+
+    Example:
+        >>> spns = get_standard_spns()
+        >>> 61444 in spns  # EEC1
+        True
+        >>> len(spns[61444])
+        8
+    """
+    return STANDARD_SPNS.copy()
+
+
+# Standard SPN definitions per SAE J1939/71
+STANDARD_SPNS: dict[int, list[J1939SPN]] = {
+    # PGN 61444 - Electronic Engine Controller 1 (EEC1)
+    61444: [
+        J1939SPN(
+            spn=190,
+            name="Engine Speed",
+            start_bit=24,
+            bit_length=16,
+            resolution=0.125,
+            offset=0.0,
+            unit="rpm",
+            data_range=(0.0, 8031.875),
+        ),
+        J1939SPN(
+            spn=899,
+            name="Engine Torque Mode",
+            start_bit=0,
+            bit_length=4,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 15.0),
+        ),
+        J1939SPN(
+            spn=512,
+            name="Driver's Demand Engine Percent Torque",
+            start_bit=8,
+            bit_length=8,
+            resolution=1.0,
+            offset=-125.0,
+            unit="%",
+            data_range=(-125.0, 125.0),
+        ),
+        J1939SPN(
+            spn=513,
+            name="Actual Engine Percent Torque",
+            start_bit=16,
+            bit_length=8,
+            resolution=1.0,
+            offset=-125.0,
+            unit="%",
+            data_range=(-125.0, 125.0),
+        ),
+        J1939SPN(
+            spn=1483,
+            name="Source Address of Controlling Device",
+            start_bit=40,
+            bit_length=8,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 255.0),
+        ),
+        J1939SPN(
+            spn=1675,
+            name="Engine Starter Mode",
+            start_bit=4,
+            bit_length=4,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 15.0),
+        ),
+        J1939SPN(
+            spn=2432,
+            name="Engine Demand Percent Torque",
+            start_bit=48,
+            bit_length=8,
+            resolution=1.0,
+            offset=-125.0,
+            unit="%",
+            data_range=(-125.0, 125.0),
+        ),
+    ],
+    # PGN 61443 - Electronic Engine Controller 2 (EEC2)
+    61443: [
+        J1939SPN(
+            spn=91,
+            name="Accelerator Pedal Position 1",
+            start_bit=0,
+            bit_length=8,
+            resolution=0.4,
+            offset=0.0,
+            unit="%",
+            data_range=(0.0, 100.0),
+        ),
+        J1939SPN(
+            spn=92,
+            name="Engine Percent Load At Current Speed",
+            start_bit=8,
+            bit_length=8,
+            resolution=1.0,
+            offset=0.0,
+            unit="%",
+            data_range=(0.0, 250.0),
+        ),
+        J1939SPN(
+            spn=974,
+            name="Remote Accelerator Pedal Position",
+            start_bit=16,
+            bit_length=8,
+            resolution=0.4,
+            offset=0.0,
+            unit="%",
+            data_range=(0.0, 100.0),
+        ),
+        J1939SPN(
+            spn=29,
+            name="Accelerator Pedal Position 2",
+            start_bit=24,
+            bit_length=8,
+            resolution=0.4,
+            offset=0.0,
+            unit="%",
+            data_range=(0.0, 100.0),
+        ),
+        J1939SPN(
+            spn=3357,
+            name="Vehicle Acceleration Rate Limit Status",
+            start_bit=32,
+            bit_length=2,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 3.0),
+        ),
+    ],
+    # PGN 65265 - Cruise Control/Vehicle Speed (CCVS1)
+    65265: [
+        J1939SPN(
+            spn=84,
+            name="Wheel-Based Vehicle Speed",
+            start_bit=8,
+            bit_length=16,
+            resolution=0.00390625,
+            offset=0.0,
+            unit="km/h",
+            data_range=(0.0, 250.996),
+        ),
+        J1939SPN(
+            spn=595,
+            name="Cruise Control Active",
+            start_bit=0,
+            bit_length=2,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 3.0),
+        ),
+        J1939SPN(
+            spn=596,
+            name="Cruise Control Enable Switch",
+            start_bit=2,
+            bit_length=2,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 3.0),
+        ),
+        J1939SPN(
+            spn=597,
+            name="Brake Switch",
+            start_bit=4,
+            bit_length=2,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 3.0),
+        ),
+        J1939SPN(
+            spn=598,
+            name="Clutch Switch",
+            start_bit=6,
+            bit_length=2,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 3.0),
+        ),
+        J1939SPN(
+            spn=599,
+            name="Cruise Control Set Switch",
+            start_bit=24,
+            bit_length=2,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 3.0),
+        ),
+        J1939SPN(
+            spn=600,
+            name="Cruise Control Coast Switch",
+            start_bit=26,
+            bit_length=2,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 3.0),
+        ),
+        J1939SPN(
+            spn=601,
+            name="Cruise Control Resume Switch",
+            start_bit=28,
+            bit_length=2,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 3.0),
+        ),
+        J1939SPN(
+            spn=602,
+            name="Cruise Control Accelerate Switch",
+            start_bit=30,
+            bit_length=2,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 3.0),
+        ),
+        J1939SPN(
+            spn=1633,
+            name="Cruise Control Set Speed",
+            start_bit=32,
+            bit_length=8,
+            resolution=1.0,
+            offset=0.0,
+            unit="km/h",
+            data_range=(0.0, 250.0),
+        ),
+        J1939SPN(
+            spn=976,
+            name="PTO State",
+            start_bit=40,
+            bit_length=5,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 31.0),
+        ),
+    ],
+    # PGN 65226 - Active Diagnostic Trouble Codes (DM1)
+    65226: [
+        J1939SPN(
+            spn=1213,
+            name="Malfunction Indicator Lamp Status",
+            start_bit=0,
+            bit_length=2,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 3.0),
+        ),
+        J1939SPN(
+            spn=623,
+            name="Red Stop Lamp Status",
+            start_bit=2,
+            bit_length=2,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 3.0),
+        ),
+        J1939SPN(
+            spn=624,
+            name="Amber Warning Lamp Status",
+            start_bit=4,
+            bit_length=2,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 3.0),
+        ),
+        J1939SPN(
+            spn=987,
+            name="Protect Lamp Status",
+            start_bit=6,
+            bit_length=2,
+            resolution=1.0,
+            offset=0.0,
+            unit="",
+            data_range=(0.0, 3.0),
+        ),
+    ],
+}

oscura/automotive/j1939/transport.py

@@ -0,0 +1,306 @@
+"""J1939 Transport Protocol (TP) implementation.
+
+This module implements J1939 transport protocol for multi-packet message
+transfer, including:
+- TP.CM (Connection Management): RTS, CTS, EOM_ACK, BAM, ABORT
+- TP.DT (Data Transfer): Sequence-based packet delivery
+- Session management and reassembly
+
+References:
+    SAE J1939/21 - Data Link Layer (Transport Protocol)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "TransportProtocol",
+    "TransportSession",
+]
+
+
+@dataclass
+class TransportSession:
+    """Active transport protocol session.
+
+    Attributes:
+        source_address: Source address initiating transfer.
+        dest_address: Destination address (0xFF for broadcast).
+        data_pgn: PGN of the data being transferred.
+        total_size: Total message size in bytes.
+        total_packets: Total number of packets.
+        max_packets: Maximum packets per CTS (connection mode only).
+        packets: Received packets (sequence -> data).
+        started_at: Session start timestamp.
+        last_timestamp: Last packet timestamp.
+        is_broadcast: True for BAM (broadcast), False for RTS/CTS.
+    """
+
+    source_address: int
+    dest_address: int
+    data_pgn: int
+    total_size: int
+    total_packets: int
+    max_packets: int = 0xFF
+    packets: dict[int, bytes] = field(default_factory=dict)
+    started_at: float = 0.0
+    last_timestamp: float = 0.0
+    is_broadcast: bool = False
+
+    def is_complete(self) -> bool:
+        """Check if all packets received.
+
+        Returns:
+            True if all packets received.
+
+        Example:
+            >>> session = TransportSession(0, 0xFF, 61444, 32, 5)
+            >>> session.is_complete()
+            False
+            >>> for i in range(1, 6):
+            ...     session.packets[i] = b'\\x00' * 7
+            >>> session.is_complete()
+            True
+        """
+        return len(self.packets) == self.total_packets
+
+    def reassemble(self) -> bytes:
+        """Reassemble complete message from packets.
+
+        Returns:
+            Reassembled message data.
+
+        Raises:
+            ValueError: If session is incomplete.
+
+        Example:
+            >>> session = TransportSession(0, 0xFF, 61444, 14, 2)
+            >>> session.packets[1] = b'\\x00\\x01\\x02\\x03\\x04\\x05\\x06'
+            >>> session.packets[2] = b'\\x07\\x08\\x09\\x0a\\x0b\\x0c\\x0d'
+            >>> data = session.reassemble()
+            >>> len(data)
+            14
+        """
+        if not self.is_complete():
+            raise ValueError(f"Session incomplete: {len(self.packets)}/{self.total_packets}")
+
+        # Reassemble in sequence order
+        complete_data = b"".join(self.packets[i] for i in range(1, self.total_packets + 1))
+
+        # Trim to actual size (last packet may be padded)
+        return complete_data[: self.total_size]
+
+
+class TransportProtocol:
+    """J1939 Transport Protocol handler.
+
+    Manages multi-packet message transfer sessions for messages
+    larger than 8 bytes using TP.CM and TP.DT.
+
+    Example:
+        >>> tp = TransportProtocol()
+        >>> # Parse TP.CM RTS
+        >>> cm_info = tp.parse_cm(b'\\x10\\x20\\x00\\x05\\xff\\xf0\\x04\\x00')
+        >>> cm_info['control']
+        'RTS'
+        >>> cm_info['total_size']
+        32
+    """
+
+    # PGN for transport protocol
+    PGN_TP_CM = 60160  # Connection Management
+    PGN_TP_DT = 60416  # Data Transfer
+
+    # Connection Management control bytes
+    CM_RTS = 16  # Request To Send
+    CM_CTS = 17  # Clear To Send
+    CM_EOM_ACK = 19  # End of Message Acknowledgment
+    CM_BAM = 32  # Broadcast Announce Message
+    CM_ABORT = 255  # Connection Abort
+
+    def __init__(self) -> None:
+        """Initialize transport protocol handler."""
+        # Active sessions: (source_addr, dest_addr) -> session
+        self.sessions: dict[tuple[int, int], TransportSession] = {}
+
+    def parse_cm(self, data: bytes) -> dict[str, Any] | None:
+        """Parse TP.CM (Connection Management) message.
+
+        TP.CM format (8 bytes):
+        - Byte 0: Control byte (RTS/CTS/EOM_ACK/BAM/ABORT)
+        - Byte 1-2: Total message size (little-endian)
+        - Byte 3: Total packets
+        - Byte 4: Max packets (CTS) or Reserved (RTS/BAM)
+        - Byte 5-7: PGN of data (little-endian, 3 bytes)
+
+        Args:
+            data: TP.CM message data (8 bytes).
+
+        Returns:
+            Parsed CM metadata or None if invalid.
+
+        Example:
+            >>> tp = TransportProtocol()
+            >>> # RTS message
+            >>> info = tp.parse_cm(b'\\x10\\x20\\x00\\x05\\xff\\xf0\\x04\\x00')
+            >>> info['control']
+            'RTS'
+            >>> info['data_pgn']
+            61680
+        """
+        if len(data) < 8:
+            return None
+
+        control = data[0]
+        total_size = int.from_bytes(data[1:3], "little")
+        total_packets = data[3]
+        max_packets = data[4]
+        data_pgn = int.from_bytes(data[5:8], "little")
+
+        cm_types = {
+            self.CM_RTS: "RTS",
+            self.CM_CTS: "CTS",
+            self.CM_EOM_ACK: "EOM_ACK",
+            self.CM_BAM: "BAM",
+            self.CM_ABORT: "ABORT",
+        }
+
+        return {
+            "control": cm_types.get(control, f"Unknown ({control})"),
+            "control_byte": control,
+            "total_size": total_size,
+            "total_packets": total_packets,
+            "max_packets": max_packets,
+            "data_pgn": data_pgn,
+        }
+
+    def parse_dt(self, data: bytes) -> dict[str, Any] | None:
+        """Parse TP.DT (Data Transfer) message.
+
+        TP.DT format:
+        - Byte 0: Sequence number (1-255)
+        - Byte 1-7: Data (7 bytes per packet)
+
+        Args:
+            data: TP.DT message data (8 bytes).
+
+        Returns:
+            Parsed DT metadata or None if invalid.
+
+        Example:
+            >>> tp = TransportProtocol()
+            >>> info = tp.parse_dt(b'\\x01\\x00\\x01\\x02\\x03\\x04\\x05\\x06')
+            >>> info['sequence']
+            1
+            >>> info['data']
+            b'\\x00\\x01\\x02\\x03\\x04\\x05\\x06'
+        """
+        if len(data) < 1:
+            return None
+
+        sequence = data[0]
+        packet_data = data[1:]
+
+        return {
+            "sequence": sequence,
+            "data": packet_data,
+        }
+
+    def start_session(
+        self,
+        source_address: int,
+        dest_address: int,
+        cm_info: dict[str, Any],
+        timestamp: float,
+    ) -> TransportSession | None:
+        """Start transport protocol session from TP.CM.
+
+        Args:
+            source_address: Source address.
+            dest_address: Destination address.
+            cm_info: Parsed TP.CM metadata.
+            timestamp: Session start timestamp.
+
+        Returns:
+            Created session or None if invalid.
+
+        Example:
+            >>> tp = TransportProtocol()
+            >>> cm_info = tp.parse_cm(b'\\x10\\x20\\x00\\x05\\xff\\xf0\\x04\\x00')
+            >>> session = tp.start_session(0, 0xFF, cm_info, 1.0)
+            >>> session.total_size
+            32
+        """
+        control = cm_info.get("control_byte")
+        if control not in (self.CM_RTS, self.CM_BAM):
+            return None
+
+        session = TransportSession(
+            source_address=source_address,
+            dest_address=dest_address,
+            data_pgn=cm_info["data_pgn"],
+            total_size=cm_info["total_size"],
+            total_packets=cm_info["total_packets"],
+            max_packets=cm_info.get("max_packets", 0xFF),
+            started_at=timestamp,
+            last_timestamp=timestamp,
+            is_broadcast=(control == self.CM_BAM),
+        )
+
+        session_key = (source_address, dest_address)
+        self.sessions[session_key] = session
+
+        return session
+
+    def add_packet(
+        self,
+        source_address: int,
+        dest_address: int,
+        dt_info: dict[str, Any],
+        timestamp: float,
+    ) -> bytes | None:
+        """Add TP.DT packet to session.
+
+        Args:
+            source_address: Source address.
+            dest_address: Destination address.
+            dt_info: Parsed TP.DT metadata.
+            timestamp: Packet timestamp.
+
+        Returns:
+            Complete reassembled message if session complete, None otherwise.
+
+        Example:
+            >>> tp = TransportProtocol()
+            >>> cm = tp.parse_cm(b'\\x20\\x0e\\x00\\x02\\xff\\xf0\\x04\\x00')
+            >>> tp.start_session(0, 0xFF, cm, 1.0)
+            <...>
+            >>> dt1 = tp.parse_dt(b'\\x01\\x00\\x01\\x02\\x03\\x04\\x05\\x06')
+            >>> tp.add_packet(0, 0xFF, dt1, 1.1)
+            >>> dt2 = tp.parse_dt(b'\\x02\\x07\\x08\\x09\\x0a\\x0b\\x0c\\x0d')
+            >>> data = tp.add_packet(0, 0xFF, dt2, 1.2)
+            >>> len(data)
+            14
+        """
+        session_key = (source_address, dest_address)
+
+        if session_key not in self.sessions:
+            return None
+
+        session = self.sessions[session_key]
+        sequence = dt_info["sequence"]
+        packet_data = dt_info["data"]
+
+        # Add packet
+        session.packets[sequence] = packet_data
+        session.last_timestamp = timestamp
+
+        # Check if complete
+        if session.is_complete():
+            complete_data = session.reassemble()
+            del self.sessions[session_key]
+            return complete_data
+
+        return None

oscura/automotive/lin/__init__.py

@@ -0,0 +1,47 @@
+"""LIN (Local Interconnect Network) protocol analysis.
+
+This module provides comprehensive LIN protocol analysis capabilities including:
+- LIN 2.x frame parsing with enhanced checksum support
+- Protected ID calculation with parity bits
+- Signal decoding and extraction
+- Diagnostic services (master request/slave response)
+- Schedule table inference from captured traffic
+- LDF (LIN Description File) generation
+
+Key features:
+- Both classic and enhanced checksum validation
+- Diagnostic frame parsing (0x3C, 0x3D)
+- Event-triggered frame handling
+- Signal mapping and decoding
+- Automatic LDF generation from traffic
+
+Example:
+    >>> from oscura.automotive.lin import LINAnalyzer, LINSignal
+    >>> analyzer = LINAnalyzer()
+    >>> # Parse captured LIN frame
+    >>> frame = analyzer.parse_frame(data=b'\\x55\\x80\\x01\\x02\\x03\\xFA', timestamp=1.0)
+    >>> print(f"Frame ID: {frame.frame_id}, Checksum: {frame.checksum_type}")
+    Frame ID: 0, Checksum: enhanced
+    >>> # Add signal definition
+    >>> analyzer.add_signal(LINSignal("Speed", frame_id=0, start_bit=0, bit_length=16))
+    >>> # Generate LDF from captured traffic
+    >>> analyzer.generate_ldf(Path("output.ldf"), baudrate=19200)
+
+References:
+    LIN Specification 2.2A
+    ISO 17987 (LIN standard)
+"""
+
+__all__ = [
+    "LINAnalyzer",
+    "LINFrame",
+    "LINScheduleEntry",
+    "LINSignal",
+]
+
+from oscura.automotive.lin.analyzer import (
+    LINAnalyzer,
+    LINFrame,
+    LINScheduleEntry,
+    LINSignal,
+)