oscura 0.11.0__py3-none-any.whl → 0.12.0__py3-none-any.whl

oscura/automotive/dtc/data.json

@@ -266,7 +266,12 @@
       "category": "Powertrain",
       "severity": "High",
       "system": "Throttle Control",
-      "possible_causes": ["TPS circuit shorted to voltage", "Faulty TPS sensor", "Wiring harness open", "ECM problem"]
+      "possible_causes": [
+        "TPS circuit shorted to voltage",
+        "Faulty TPS sensor",
+        "Wiring harness open",
+        "ECM problem"
+      ]
     },
     "P0125": {
       "code": "P0125",
@@ -860,7 +865,12 @@
       "category": "Powertrain",
       "severity": "Medium",
       "system": "Emissions Control",
-      "possible_causes": ["EGR valve stuck closed", "EGR passages clogged", "Faulty EGR valve", "Vacuum leak"]
+      "possible_causes": [
+        "EGR valve stuck closed",
+        "EGR passages clogged",
+        "Faulty EGR valve",
+        "Vacuum leak"
+      ]
     },
     "P0401": {
       "code": "P0401",
@@ -881,7 +891,12 @@
       "category": "Powertrain",
       "severity": "Medium",
       "system": "Emissions Control",
-      "possible_causes": ["EGR valve stuck open", "Faulty EGR valve", "EGR vacuum solenoid fault", "ECM problem"]
+      "possible_causes": [
+        "EGR valve stuck open",
+        "Faulty EGR valve",
+        "EGR vacuum solenoid fault",
+        "ECM problem"
+      ]
     },
     "P0403": {
       "code": "P0403",
@@ -943,7 +958,12 @@
       "category": "Powertrain",
       "severity": "Low",
       "system": "Emissions Control",
-      "possible_causes": ["Loose or missing fuel cap", "EVAP system leak", "Faulty purge valve", "Faulty vent valve"]
+      "possible_causes": [
+        "Loose or missing fuel cap",
+        "EVAP system leak",
+        "Faulty purge valve",
+        "Faulty vent valve"
+      ]
     },
     "P0441": {
       "code": "P0441",
@@ -1055,7 +1075,12 @@
       "category": "Powertrain",
       "severity": "Low",
       "system": "Idle Control",
-      "possible_causes": ["Vacuum leak", "IAC valve fault", "Dirty throttle body", "PCV valve problem"]
+      "possible_causes": [
+        "Vacuum leak",
+        "IAC valve fault",
+        "Dirty throttle body",
+        "PCV valve problem"
+      ]
     },
     "P0507": {
       "code": "P0507",
@@ -1063,7 +1088,12 @@
       "category": "Powertrain",
       "severity": "Low",
       "system": "Idle Control",
-      "possible_causes": ["Vacuum leak", "IAC valve stuck open", "PCV valve stuck open", "EVAP purge valve leaking"]
+      "possible_causes": [
+        "Vacuum leak",
+        "IAC valve stuck open",
+        "PCV valve stuck open",
+        "EVAP purge valve leaking"
+      ]
     },
     "P0600": {
       "code": "P0600",
@@ -1097,7 +1127,12 @@
       "category": "Powertrain",
       "severity": "Critical",
       "system": "Engine Control Module",
-      "possible_causes": ["ECM not programmed", "ECM programming incomplete", "Wrong software version", "ECM fault"]
+      "possible_causes": [
+        "ECM not programmed",
+        "ECM programming incomplete",
+        "Wrong software version",
+        "ECM fault"
+      ]
     },
     "P0603": {
       "code": "P0603",
@@ -1170,7 +1205,12 @@
       "category": "Powertrain",
       "severity": "Medium",
       "system": "Charging System",
-      "possible_causes": ["Faulty alternator", "Wiring harness problem", "Poor electrical connection", "ECM fault"]
+      "possible_causes": [
+        "Faulty alternator",
+        "Wiring harness problem",
+        "Poor electrical connection",
+        "ECM fault"
+      ]
     },
     "P0625": {
       "code": "P0625",
@@ -1243,7 +1283,12 @@
       "category": "Powertrain",
       "severity": "High",
       "system": "Transmission",
-      "possible_causes": ["Faulty input speed sensor", "Wiring harness problem", "Sensor reluctor damaged", "TCM fault"]
+      "possible_causes": [
+        "Faulty input speed sensor",
+        "Wiring harness problem",
+        "Sensor reluctor damaged",
+        "TCM fault"
+      ]
     },
     "P0720": {
       "code": "P0720",
@@ -1446,7 +1491,12 @@
       "category": "Chassis",
       "severity": "High",
       "system": "ABS",
-      "possible_causes": ["Faulty valve relay", "Relay circuit problem", "ABS module fault", "Wiring harness issue"]
+      "possible_causes": [
+        "Faulty valve relay",
+        "Relay circuit problem",
+        "ABS module fault",
+        "Wiring harness issue"
+      ]
     },
     "C0161": {
       "code": "C0161",
@@ -2156,7 +2206,12 @@
       "category": "Body",
       "severity": "Low",
       "system": "Lighting System",
-      "possible_causes": ["Burned out bulb", "Wiring harness problem", "Lamp socket corrosion", "BCM fault"]
+      "possible_causes": [
+        "Burned out bulb",
+        "Wiring harness problem",
+        "Lamp socket corrosion",
+        "BCM fault"
+      ]
     },
     "B0601": {
       "code": "B0601",
@@ -2177,7 +2232,12 @@
       "category": "Body",
       "severity": "Low",
       "system": "Lighting System",
-      "possible_causes": ["Burned out turn signal bulb", "Wiring harness problem", "Flasher relay fault", "BCM fault"]
+      "possible_causes": [
+        "Burned out turn signal bulb",
+        "Wiring harness problem",
+        "Flasher relay fault",
+        "BCM fault"
+      ]
     },
     "B0603": {
       "code": "B0603",
@@ -2185,7 +2245,12 @@
       "category": "Body",
       "severity": "Low",
       "system": "Lighting System",
-      "possible_causes": ["Burned out turn signal bulb", "Wiring harness problem", "Flasher relay fault", "BCM fault"]
+      "possible_causes": [
+        "Burned out turn signal bulb",
+        "Wiring harness problem",
+        "Flasher relay fault",
+        "BCM fault"
+      ]
     },
     "B0604": {
       "code": "B0604",
@@ -2297,7 +2362,12 @@
       "category": "Body",
       "severity": "Low",
       "system": "Keyless Entry",
-      "possible_causes": ["Key fob battery weak", "Key fob not synchronized", "BCM fault", "Receiver antenna fault"]
+      "possible_causes": [
+        "Key fob battery weak",
+        "Key fob not synchronized",
+        "BCM fault",
+        "Receiver antenna fault"
+      ]
     },
     "B1300": {
       "code": "B1300",
@@ -2396,7 +2466,12 @@
       "category": "Network",
       "severity": "Critical",
       "system": "CAN Bus",
-      "possible_causes": ["TCM not powered", "CAN bus wiring problem", "TCM internal fault", "CAN bus short circuit"]
+      "possible_causes": [
+        "TCM not powered",
+        "CAN bus wiring problem",
+        "TCM internal fault",
+        "CAN bus short circuit"
+      ]
     },
     "U0102": {
       "code": "U0102",
@@ -2469,7 +2544,12 @@
       "category": "Network",
       "severity": "High",
       "system": "CAN Bus",
-      "possible_causes": ["BCM not powered", "CAN bus wiring problem", "BCM internal fault", "Ground connection issue"]
+      "possible_causes": [
+        "BCM not powered",
+        "CAN bus wiring problem",
+        "BCM internal fault",
+        "Ground connection issue"
+      ]
     },
     "U0141": {
       "code": "U0141",
@@ -2477,7 +2557,12 @@
       "category": "Network",
       "severity": "High",
       "system": "CAN Bus",
-      "possible_causes": ["BCM not powered", "CAN bus wiring problem", "Module internal fault", "Connector problem"]
+      "possible_causes": [
+        "BCM not powered",
+        "CAN bus wiring problem",
+        "Module internal fault",
+        "Connector problem"
+      ]
     },
     "U0151": {
       "code": "U0151",

oscura/core/schemas/device_mapping.json

@@ -149,14 +149,20 @@
           "type": "array",
           "description": "Device IDs to include (whitelist)",
           "items": {
-            "oneOf": [{ "type": "integer" }, { "type": "string", "pattern": "^0[xX][0-9A-Fa-f]+$" }]
+            "oneOf": [
+              { "type": "integer" },
+              { "type": "string", "pattern": "^0[xX][0-9A-Fa-f]+$" }
+            ]
           }
         },
         "exclude_devices": {
           "type": "array",
           "description": "Device IDs to exclude (blacklist)",
           "items": {
-            "oneOf": [{ "type": "integer" }, { "type": "string", "pattern": "^0[xX][0-9A-Fa-f]+$" }]
+            "oneOf": [
+              { "type": "integer" },
+              { "type": "string", "pattern": "^0[xX][0-9A-Fa-f]+$" }
+            ]
           }
         },
         "include_categories": {

oscura/core/schemas/packet_format.json

@@ -118,7 +118,10 @@
               },
               "value": {
                 "description": "Expected constant value for validation",
-                "oneOf": [{ "type": "integer" }, { "type": "array", "items": { "type": "integer" } }]
+                "oneOf": [
+                  { "type": "integer" },
+                  { "type": "array", "items": { "type": "integer" } }
+                ]
               },
               "description": {
                 "type": "string",
@@ -185,7 +188,18 @@
             },
             "type": {
               "type": "string",
-              "enum": ["uint8", "uint16", "uint32", "uint64", "int8", "int16", "int32", "int64", "float32", "float64"],
+              "enum": [
+                "uint8",
+                "uint16",
+                "uint32",
+                "uint64",
+                "int8",
+                "int16",
+                "int32",
+                "int64",
+                "float32",
+                "float64"
+              ],
               "description": "Sample data type"
             },
             "endian": {
@@ -289,7 +303,10 @@
             },
             "expected": {
               "description": "Expected value",
-              "oneOf": [{ "type": "integer" }, { "type": "array", "items": { "type": "integer" } }]
+              "oneOf": [
+                { "type": "integer" },
+                { "type": "array", "items": { "type": "integer" } }
+              ]
             },
             "on_failure": {
               "type": "string",
@@ -362,7 +379,10 @@
             },
             "pattern": {
               "description": "Idle pattern to detect",
-              "oneOf": [{ "type": "string", "enum": ["auto", "zeros", "ones"] }, { "type": "integer" }]
+              "oneOf": [
+                { "type": "string", "enum": ["auto", "zeros", "ones"] },
+                { "type": "integer" }
+              ]
             },
             "min_duration": {
               "type": "integer",

oscura/core/schemas/protocol_definition.json

@@ -241,7 +241,12 @@
         },
         "value": {
           "description": "Expected constant value for validation",
-          "oneOf": [{ "type": "integer" }, { "type": "number" }, { "type": "string" }, { "type": "array" }]
+          "oneOf": [
+            { "type": "integer" },
+            { "type": "number" },
+            { "type": "string" },
+            { "type": "array" }
+          ]
         },
         "condition": {
           "type": "string",
@@ -326,7 +331,12 @@
             },
             "expected": {
               "description": "Expected value",
-              "oneOf": [{ "type": "integer" }, { "type": "number" }, { "type": "string" }, { "type": "array" }]
+              "oneOf": [
+                { "type": "integer" },
+                { "type": "number" },
+                { "type": "string" },
+                { "type": "array" }
+              ]
             },
             "on_mismatch": {
               "type": "string",

oscura/loaders/__init__.py

@@ -41,6 +41,7 @@ _LOADER_REGISTRY: dict[str, tuple[str, str]] = {
     "tdms": ("oscura.loaders.tdms", "load_tdms"),
     "touchstone": ("oscura.loaders.touchstone", "load_touchstone"),
     "chipwhisperer": ("oscura.loaders.chipwhisperer", "load_chipwhisperer"),
+    "binary": ("oscura.loaders.binary", "load_binary_auto"),
 }
 
 
@@ -96,7 +97,7 @@ from oscura.loaders import (
     csv,
     hdf5,
 )
-from oscura.loaders.binary import load_binary
+from oscura.loaders.binary import load_binary, load_binary_auto
 
 # Import configurable binary loading functionality
 from oscura.loaders.configurable import (
@@ -182,6 +183,7 @@ logger = logging.getLogger(__name__)
 SUPPORTED_FORMATS: dict[str, str] = {
     ".wfm": "auto_wfm",  # Auto-detect Tektronix vs Rigol
     ".tss": "tss",  # Tektronix session files
+    ".bin": "binary",  # Raw binary with auto-detection
     ".npz": "numpy",
     ".csv": "csv",
     ".h5": "hdf5",
@@ -655,6 +657,7 @@ __all__ = [
     "load_all_channels",
     "load_auto",
     "load_binary",
+    "load_binary_auto",
     "load_binary_packets",
     "load_lazy",
     "load_packets_streaming",

oscura/loaders/binary.py

@@ -153,4 +153,287 @@ def _load_binary_mmap(
             mm.close()
 
 
-__all__ = ["load_binary"]
+def detect_binary_dtype(
+    path: str | PathLike[str], sample_size: int = 8192
+) -> tuple[str, dict[str, Any]]:
+    """Auto-detect most likely dtype for binary file using intelligent multi-heuristic analysis.
+
+    Performs comprehensive analysis including:
+    - Multi-location sampling (beginning, middle, end)
+    - Byte entropy and distribution analysis
+    - IEEE 754 floating point pattern detection
+    - Value range validation for each dtype
+    - Alignment and padding pattern detection
+    - Statistical confidence scoring
+
+    Designed to handle completely unknown binary formats with no prior knowledge.
+
+    Args:
+        path: Path to binary file.
+        sample_size: Bytes to sample per location (default: 8KB).
+
+    Returns:
+        Tuple of (detected_dtype, confidence_scores).
+        confidence_scores maps each dtype to its normalized confidence (0-1).
+
+    Example:
+        >>> dtype, confidence = detect_binary_dtype("unknown.bin")
+        >>> print(f"Detected: {dtype} (confidence: {confidence[dtype]:.1%})")
+        Detected: uint16 (confidence: 85.3%)
+    """
+    path = Path(path)
+    file_size = path.stat().st_size
+
+    # Sample from multiple locations for robust detection
+    samples_to_check = []
+    with open(path, "rb") as f:
+        # Beginning
+        samples_to_check.append(f.read(min(sample_size, file_size)))
+
+        # Middle (if large enough)
+        if file_size > sample_size * 2:
+            f.seek(file_size // 2)
+            samples_to_check.append(f.read(min(sample_size, file_size - f.tell())))
+
+        # End (if large enough)
+        if file_size > sample_size * 3:
+            f.seek(max(0, file_size - sample_size))
+            samples_to_check.append(f.read())
+
+    sample = b"".join(samples_to_check)
+
+    if len(sample) < 16:
+        return "uint8", {"uint8": 1.0}
+
+    from collections import Counter
+
+    # Byte entropy calculation
+    byte_counts = Counter(sample)
+    total = len(sample)
+    entropy = -sum((count / total) * np.log2(count / total) for count in byte_counts.values())
+    zero_density = sample.count(b"\x00") / len(sample)
+
+    # Score each dtype possibility
+    scores: dict[str, float] = {
+        "uint8": 0.0,
+        "int8": 0.0,
+        "uint16": 0.0,
+        "int16": 0.0,
+        "uint32": 0.0,
+        "int32": 0.0,
+        "float32": 0.0,
+        "float64": 0.0,
+    }
+
+    # Test 1: IEEE 754 floating point validation
+    float32_valid = 0
+    for i in range(0, min(len(sample) - 3, 4096), 4):
+        try:
+            val = np.frombuffer(sample[i : i + 4], dtype=np.float32)[0]
+            if np.isfinite(val) and -1e10 < val < 1e10:
+                float32_valid += 1
+        except Exception:
+            pass
+
+    float64_valid = 0
+    for i in range(0, min(len(sample) - 7, 4096), 8):
+        try:
+            val = np.frombuffer(sample[i : i + 8], dtype=np.float64)[0]
+            if np.isfinite(val) and -1e10 < val < 1e10:
+                float64_valid += 1
+        except Exception:
+            pass
+
+    scores["float32"] = (float32_valid / (min(len(sample), 4096) / 4)) * 3.0
+    scores["float64"] = (float64_valid / (min(len(sample), 4096) / 8)) * 3.0
+
+    # Test 2: Entropy-based scoring
+    if entropy > 7.0:
+        scores["float32"] += 2.0
+        scores["float64"] += 2.0
+    elif entropy > 6.0:
+        scores["int32"] += 1.5
+        scores["uint32"] += 1.5
+    elif entropy > 4.5:
+        scores["int16"] += 2.0
+        scores["uint16"] += 2.0
+    else:
+        scores["int8"] += 2.0
+        scores["uint8"] += 2.0
+
+    # Test 3: Zero density (structured data indicator)
+    if zero_density > 0.6:
+        scores["int16"] += 1.5
+        scores["uint16"] += 1.5
+    elif zero_density > 0.4:
+        scores["int16"] += 1.0
+        scores["uint16"] += 1.0
+
+    # Test 4: Value range reasonableness
+    uint8_reasonable = sum(1 for b in sample[: min(1000, len(sample))] if b < 128) / min(
+        1000, len(sample)
+    )
+    if uint8_reasonable > 0.8:
+        scores["uint8"] += 1.5
+
+    # Find best dtype
+    best_dtype = max(scores.items(), key=lambda x: x[1])[0]
+
+    # Normalize confidence scores
+    max_score = max(scores.values()) if scores.values() else 1.0
+    confidence = {k: v / max_score for k, v in scores.items()} if max_score > 0 else scores
+
+    return best_dtype, confidence
+
+
+def detect_packet_structure(path: str | PathLike[str], sample_size: int = 8192) -> tuple[bool, int]:
+    """Detect if binary file contains structured packet data.
+
+    Looks for repeating header patterns and regular spacing indicating
+    packet boundaries.
+
+    Args:
+        path: Path to binary file.
+        sample_size: Number of bytes to sample for detection.
+
+    Returns:
+        Tuple of (is_packet_data, packet_size_estimate).
+        packet_size_estimate is 0 if not packet data.
+
+    Example:
+        >>> is_packets, size = detect_packet_structure("capture.bin")
+        >>> if is_packets:
+        ...     print(f"Detected packet structure with ~{size} byte packets")
+    """
+    path = Path(path)
+
+    with open(path, "rb") as f:
+        sample = f.read(sample_size)
+
+    if len(sample) < 512:
+        return False, 0
+
+    # Look for sequence numbers (common in packet headers)
+    # Check for patterns like: 00 00, 01 00, 02 00, 03 00 (little-endian sequence)
+    sequence_positions = []
+    for seq_byte in range(10):  # Check first 10 sequence numbers
+        pattern = seq_byte.to_bytes(1, "little") + b"\x00"
+        pos = sample.find(pattern)
+        if pos != -1:
+            sequence_positions.append(pos)
+
+    # If we found multiple sequence numbers at regular intervals = likely packets
+    if len(sequence_positions) >= 3:
+        # Calculate intervals between sequence numbers
+        intervals = [
+            sequence_positions[i + 1] - sequence_positions[i]
+            for i in range(len(sequence_positions) - 1)
+        ]
+
+        # Check if intervals are consistent (within 10% variation)
+        if intervals:
+            avg_interval = sum(intervals) / len(intervals)
+            variation = max(abs(i - avg_interval) for i in intervals) / avg_interval
+
+            if variation < 0.1 and 100 < avg_interval < 10000:
+                # Consistent spacing in reasonable range = packet structure
+                return True, int(avg_interval)
+
+    # Look for repeating byte patterns (common header markers)
+    # Check 4-byte patterns that repeat regularly
+    pattern_positions: dict[bytes, list[int]] = {}
+    for i in range(0, min(1024, len(sample) - 4), 4):
+        pattern = sample[i : i + 4]
+        if pattern not in pattern_positions:
+            pattern_positions[pattern] = []
+        pattern_positions[pattern].append(i)
+
+    # Find patterns that repeat with consistent spacing
+    for pattern, positions in pattern_positions.items():
+        if len(positions) >= 3 and pattern != b"\x00\x00\x00\x00":
+            intervals = [positions[i + 1] - positions[i] for i in range(len(positions) - 1)]
+            if intervals:
+                avg_interval = sum(intervals) / len(intervals)
+                variation = (
+                    max(abs(i - avg_interval) for i in intervals) / avg_interval
+                    if intervals
+                    else 1.0
+                )
+
+                if variation < 0.1 and 100 < avg_interval < 10000:
+                    return True, int(avg_interval)
+
+    return False, 0
+
+
+def load_binary_auto(
+    path: str | PathLike[str],
+    *,
+    sample_rate: float | None = None,
+    max_samples: int = 100_000,
+    channels: int = 1,
+    channel: int = 0,
+) -> WaveformTrace:
+    """Load binary file with automatic dtype detection and intelligent defaults.
+
+    This is a smart wrapper around load_binary() that:
+    - Auto-detects dtype
+    - Limits samples to prevent memory issues
+    - Uses memory-mapped I/O for large files
+    - Detects packet structures
+
+    Designed for use with unknown binary formats where manual
+    configuration is not available.
+
+    Args:
+        path: Path to binary file.
+        sample_rate: Sample rate in Hz. If None, estimates from file.
+        max_samples: Maximum number of samples to load (default: 100K).
+        channels: Number of interleaved channels.
+        channel: Channel index to load.
+
+    Returns:
+        WaveformTrace with loaded data and metadata.
+
+    Example:
+        >>> trace = load_binary_auto("unknown_capture.bin")
+        >>> print(f"Loaded {len(trace.data)} samples, dtype: {trace.metadata.source_file}")
+    """
+    path = Path(path)
+    file_size = path.stat().st_size
+
+    # Detect dtype with confidence scoring
+    dtype, confidence = detect_binary_dtype(path)
+
+    # Detect packet structure (informational)
+    is_packets, packet_size = detect_packet_structure(path)
+
+    # Estimate sample rate if not provided
+    if sample_rate is None:
+        # Common sample rates for oscilloscopes/DAQ
+        sample_rate = 1.0e6  # 1 MS/s default
+
+    # Use mmap for files > 10MB
+    use_mmap = file_size > 10 * 1024 * 1024
+
+    # Calculate potential samples based on detected dtype
+    bytes_per_sample = np.dtype(dtype).itemsize
+    potential_samples = file_size // bytes_per_sample
+
+    # Limit samples for analysis performance
+    count = min(max_samples, potential_samples)
+
+    # Load with detected parameters
+    return load_binary(
+        path,
+        dtype=dtype,
+        sample_rate=sample_rate,
+        channels=channels,
+        channel=channel,
+        offset=0,
+        count=count,
+        mmap_mode=use_mmap,
+    )
+
+
+__all__ = ["detect_binary_dtype", "detect_packet_structure", "load_binary", "load_binary_auto"]