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

oscura/__init__.py

@@ -53,7 +53,7 @@ try:
     __version__ = version("oscura")
 except Exception:
     # Fallback for development/testing when package not installed
-    __version__ = "0.6.0"
+    __version__ = "0.7.0"
 
 __author__ = "Oscura Contributors"
 

oscura/automotive/__init__.py

@@ -49,7 +49,7 @@ try:
     __version__ = version("oscura")
 except Exception:
     # Fallback for development/testing when package not installed
-    __version__ = "0.6.0"
+    __version__ = "0.7.0"
 
 __all__ = [
     "CANMessage",

oscura/automotive/dtc/data.json

@@ -266,12 +266,7 @@
       "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",
@@ -865,12 +860,7 @@
       "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",
@@ -891,12 +881,7 @@
       "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",
@@ -958,12 +943,7 @@
       "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",
@@ -1075,12 +1055,7 @@
       "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",
@@ -1088,12 +1063,7 @@
       "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",
@@ -1127,12 +1097,7 @@
       "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",
@@ -1205,12 +1170,7 @@
       "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",
@@ -1283,12 +1243,7 @@
       "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",
@@ -1491,12 +1446,7 @@
       "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",
@@ -2206,12 +2156,7 @@
       "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",
@@ -2232,12 +2177,7 @@
       "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",
@@ -2245,12 +2185,7 @@
       "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",
@@ -2362,12 +2297,7 @@
       "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",
@@ -2466,12 +2396,7 @@
       "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",
@@ -2544,12 +2469,7 @@
       "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",
@@ -2557,12 +2477,7 @@
       "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,20 +149,14 @@
           "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,10 +118,7 @@
               },
               "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",
@@ -188,18 +185,7 @@
             },
             "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": {
@@ -303,10 +289,7 @@
             },
             "expected": {
               "description": "Expected value",
-              "oneOf": [
-                { "type": "integer" },
-                { "type": "array", "items": { "type": "integer" } }
-              ]
+              "oneOf": [{ "type": "integer" }, { "type": "array", "items": { "type": "integer" } }]
             },
             "on_failure": {
               "type": "string",
@@ -379,10 +362,7 @@
             },
             "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,12 +241,7 @@
         },
         "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",
@@ -331,12 +326,7 @@
             },
             "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

@@ -29,6 +29,7 @@ from oscura.core.types import DigitalTrace, IQTrace, WaveformTrace
 _LOADER_REGISTRY: dict[str, tuple[str, str]] = {
     "tektronix": ("oscura.loaders.tektronix", "load_tektronix_wfm"),
     "tek": ("oscura.loaders.tektronix", "load_tektronix_wfm"),
+    "tss": ("oscura.loaders.tss", "load_tss"),
     "rigol": ("oscura.loaders.rigol", "load_rigol_wfm"),
     "numpy": ("oscura.loaders.numpy_loader", "load_npz"),
     "csv": ("oscura.loaders.csv_loader", "load_csv"),
@@ -180,6 +181,7 @@ logger = logging.getLogger(__name__)
 # Supported format extensions mapped to loader names
 SUPPORTED_FORMATS: dict[str, str] = {
     ".wfm": "auto_wfm",  # Auto-detect Tektronix vs Rigol
+    ".tss": "tss",  # Tektronix session files
     ".npz": "numpy",
     ".csv": "csv",
     ".h5": "hdf5",
@@ -392,8 +394,8 @@ def load_all_channels(
             )
         loader_name = SUPPORTED_FORMATS[ext]
 
-    # Currently only supports Tektronix WFM for multi-channel loading
-    if loader_name in ("auto_wfm", "tektronix", "tek"):
+    # Currently only supports Tektronix WFM and TSS for multi-channel loading
+    if loader_name in ("auto_wfm", "tektronix", "tek", "tss"):
         return _load_all_channels_tektronix(path)
     else:
         # For other formats, try loading as single channel
@@ -405,10 +407,10 @@ def load_all_channels(
 def _load_all_channels_tektronix(
     path: Path,
 ) -> dict[str, WaveformTrace | DigitalTrace | IQTrace]:
-    """Load all channels from a Tektronix WFM file.
+    """Load all channels from a Tektronix WFM or TSS file.
 
     Args:
-        path: Path to the Tektronix .wfm file.
+        path: Path to the Tektronix .wfm or .tss file.
 
     Returns:
         Dictionary mapping channel names to traces.
@@ -416,6 +418,12 @@ def _load_all_channels_tektronix(
     Raises:
         LoaderError: If the file cannot be read or parsed.
     """
+    # Check if this is a .tss session file
+    if path.suffix.lower() == ".tss":
+        from oscura.loaders.tss import load_all_channels_tss
+
+        return load_all_channels_tss(path)
+
     wfm = _read_tektronix_file(path)
     channels: dict[str, WaveformTrace | DigitalTrace | IQTrace] = {}
 

oscura/loaders/tss.py

@@ -0,0 +1,456 @@
+"""Tektronix Session File (.tss) Loader.
+
+This module provides loading functionality for Tektronix session files (.tss),
+which are ZIP archives containing multiple waveform captures, instrument
+configuration, measurements, and annotations.
+
+A .tss session file typically contains:
+- Multiple .wfm waveform files (one per channel/capture)
+- session.json: Instrument configuration and setup
+- measurements.json: Stored measurement results (optional)
+- annotations.json: User annotations and markers (optional)
+
+Example:
+    >>> import oscura as osc
+    >>> trace = osc.load("oscilloscope_session.tss")
+    >>> print(f"Channel: {trace.metadata.channel_name}")
+    >>> print(f"Sample rate: {trace.metadata.sample_rate} Hz")
+
+    >>> # Load specific channel
+    >>> trace = osc.load("session.tss", channel="CH2")
+
+    >>> # Load all channels
+    >>> channels = osc.load_all_channels("session.tss")
+    >>> for name, trace in channels.items():
+    ...     print(f"{name}: {len(trace.data)} samples")
+
+References:
+    Tektronix Programming Manual for Session Files
+    TekScope PC Analysis Software Documentation
+"""
+
+from __future__ import annotations
+
+import json
+import tempfile
+import zipfile
+from os import PathLike
+from pathlib import Path
+from typing import Any
+
+from oscura.core.exceptions import FormatError, LoaderError
+from oscura.core.types import DigitalTrace, IQTrace, WaveformTrace
+
+
+def load_tss(
+    path: str | PathLike[str],
+    *,
+    channel: str | int | None = None,
+) -> WaveformTrace | DigitalTrace | IQTrace:
+    """Load a Tektronix session file (.tss).
+
+    Tektronix session files are ZIP archives containing multiple waveform
+    captures along with instrument configuration and analysis results.
+
+    Args:
+        path: Path to the Tektronix .tss session file.
+        channel: Optional channel name or index to load. If None,
+            loads the first waveform found (alphabetically).
+            String names are case-insensitive (e.g., "ch1", "CH1").
+            Integer index is 0-based.
+
+    Returns:
+        WaveformTrace, DigitalTrace, or IQTrace containing the channel data.
+
+    Raises:
+        LoaderError: If the file cannot be loaded or doesn't exist.
+        FormatError: If the file is not a valid Tektronix session.
+
+    Example:
+        >>> # Load first channel (default)
+        >>> trace = load_tss("session.tss")
+
+        >>> # Load specific channel by name
+        >>> trace = load_tss("session.tss", channel="CH2")
+
+        >>> # Load by index
+        >>> trace = load_tss("session.tss", channel=1)  # Second channel
+    """
+    path = Path(path)
+
+    # Validate file
+    _validate_tss_file(path)
+
+    # Load all waveforms and select requested channel
+    waveforms = _load_all_waveforms(path)
+
+    if not waveforms:
+        raise FormatError(
+            "No waveforms found in session file",
+            file_path=str(path),
+            expected="At least one .wfm file in the archive",
+            got="Empty session or no waveform files",
+        )
+
+    # Select channel
+    trace, channel_name = _select_channel(waveforms, channel, path)
+
+    # Enrich metadata with session information
+    try:
+        with zipfile.ZipFile(path, "r") as zf:
+            session_metadata = _parse_session_metadata(zf, path)
+            trace = _enrich_metadata_from_session(trace, session_metadata, str(path))
+    except Exception:
+        # Session metadata is optional, continue with waveform metadata
+        pass
+
+    return trace
+
+
+def load_all_channels_tss(
+    path: Path,
+) -> dict[str, WaveformTrace | DigitalTrace | IQTrace]:
+    """Load all channels from a Tektronix session file.
+
+    Args:
+        path: Path to the .tss session file.
+
+    Returns:
+        Dictionary mapping channel names to traces.
+        Channel names are derived from .wfm filenames (e.g., "ch1", "ch2").
+
+    Raises:
+        LoaderError: If the file cannot be loaded.
+        FormatError: If no waveforms found in session.
+
+    Example:
+        >>> channels = load_all_channels_tss(Path("session.tss"))
+        >>> for name, trace in channels.items():
+        ...     print(f"{name}: {trace.metadata.sample_rate} Hz")
+    """
+    # Validate file
+    _validate_tss_file(path)
+
+    # Load all waveforms
+    waveforms = _load_all_waveforms(path)
+
+    if not waveforms:
+        raise FormatError(
+            "No waveforms found in session file",
+            file_path=str(path),
+            expected="At least one .wfm file",
+            got="Empty archive",
+        )
+
+    # Enrich all traces with session metadata
+    try:
+        with zipfile.ZipFile(path, "r") as zf:
+            session_metadata = _parse_session_metadata(zf, path)
+            for name in waveforms:
+                waveforms[name] = _enrich_metadata_from_session(
+                    waveforms[name], session_metadata, str(path)
+                )
+    except Exception:
+        # Session metadata is optional
+        pass
+
+    return waveforms
+
+
+def _validate_tss_file(path: Path) -> None:
+    """Validate that file exists and is a valid ZIP archive.
+
+    Args:
+        path: Path to validate.
+
+    Raises:
+        LoaderError: If file doesn't exist or can't be read.
+        FormatError: If file is not a ZIP archive.
+    """
+    if not path.exists():
+        raise LoaderError(
+            "File not found",
+            file_path=str(path),
+            fix_hint="Ensure the file path is correct and the file exists.",
+        )
+
+    if not zipfile.is_zipfile(path):
+        raise FormatError(
+            "Not a valid ZIP archive",
+            file_path=str(path),
+            expected="Tektronix session file (.tss) is a ZIP archive",
+            got="File is not a ZIP file",
+        )
+
+    try:
+        with zipfile.ZipFile(path, "r") as zf:
+            # Test archive integrity
+            bad_file = zf.testzip()
+            if bad_file is not None:
+                raise FormatError(
+                    f"Corrupted ZIP archive: {bad_file}",
+                    file_path=str(path),
+                    expected="Valid ZIP archive",
+                    got="Corrupted file detected",
+                )
+    except zipfile.BadZipFile as e:
+        raise FormatError(
+            "Corrupted or invalid ZIP archive",
+            file_path=str(path),
+            details=str(e),
+        ) from e
+
+
+def _parse_session_metadata(zf: zipfile.ZipFile, path: Path) -> dict[str, Any]:
+    """Parse session.json metadata from the archive.
+
+    Args:
+        zf: Open ZipFile object.
+        path: Path to session file (for error messages).
+
+    Returns:
+        Dictionary containing session metadata.
+        Returns empty dict if session.json not found (non-fatal).
+    """
+    # Look for session metadata files
+    metadata_files = [
+        "session.json",
+        "Session.json",
+        "metadata.json",
+        "Metadata.json",
+    ]
+
+    for metadata_file in metadata_files:
+        try:
+            with zf.open(metadata_file) as f:
+                data: dict[str, Any] = json.load(f)
+                return data
+        except KeyError:
+            continue
+        except json.JSONDecodeError as e:
+            # Non-fatal: log warning and continue
+            import warnings
+
+            warnings.warn(
+                f"Failed to parse {metadata_file} in {path.name}: {e}",
+                stacklevel=2,
+            )
+            return {}
+
+    # Session metadata is optional
+    return {}
+
+
+def _extract_waveform_list(zf: zipfile.ZipFile) -> list[str]:
+    """Extract list of .wfm files in the session.
+
+    Args:
+        zf: Open ZipFile object.
+
+    Returns:
+        List of .wfm file paths within the archive.
+        Excludes macOS metadata files (__MACOSX).
+    """
+    return [
+        name
+        for name in zf.namelist()
+        if name.lower().endswith(".wfm") and not name.startswith("__MACOSX")
+    ]
+
+
+def _load_wfm_from_archive(
+    zf: zipfile.ZipFile,
+    wfm_name: str,
+    path: Path,
+) -> WaveformTrace | DigitalTrace | IQTrace:
+    """Extract and load a .wfm file from the archive.
+
+    Args:
+        zf: Open ZipFile object.
+        wfm_name: Name of .wfm file within archive.
+        path: Path to session file (for error messages).
+
+    Returns:
+        Loaded trace from the waveform file.
+
+    Raises:
+        LoaderError: If waveform cannot be loaded.
+    """
+    try:
+        # Extract waveform to temporary file
+        # (load_tektronix_wfm expects file path, not bytes)
+        wfm_bytes = zf.read(wfm_name)
+
+        with tempfile.NamedTemporaryFile(suffix=".wfm", delete=True) as tmp:
+            tmp.write(wfm_bytes)
+            tmp.flush()
+
+            # Use existing Tektronix loader
+            from oscura.loaders.tektronix import load_tektronix_wfm
+
+            trace = load_tektronix_wfm(tmp.name)
+
+            return trace
+
+    except Exception as e:
+        raise LoaderError(
+            f"Failed to load waveform from session: {wfm_name}",
+            file_path=str(path),
+            details=str(e),
+            fix_hint="Waveform file may be corrupted or incompatible.",
+        ) from e
+
+
+def _load_all_waveforms(path: Path) -> dict[str, WaveformTrace | DigitalTrace | IQTrace]:
+    """Load all waveforms from the session file.
+
+    Args:
+        path: Path to .tss session file.
+
+    Returns:
+        Dictionary mapping channel names to traces.
+    """
+    waveforms: dict[str, WaveformTrace | DigitalTrace | IQTrace] = {}
+
+    with zipfile.ZipFile(path, "r") as zf:
+        wfm_files = _extract_waveform_list(zf)
+
+        for wfm_name in sorted(wfm_files):  # Sort for consistent ordering
+            # Derive channel name from filename
+            channel_name = _derive_channel_name(wfm_name)
+
+            # Load waveform
+            trace = _load_wfm_from_archive(zf, wfm_name, path)
+
+            # Store with normalized channel name
+            waveforms[channel_name] = trace
+
+    return waveforms
+
+
+def _derive_channel_name(wfm_filename: str) -> str:
+    """Derive channel name from .wfm filename.
+
+    Args:
+        wfm_filename: Filename like "CH1.wfm", "CH2_Voltage.wfm", etc.
+
+    Returns:
+        Normalized channel name (lowercase, e.g., "ch1", "ch2", "d0").
+
+    Examples:
+        >>> _derive_channel_name("CH1.wfm")
+        'ch1'
+        >>> _derive_channel_name("subdir/CH2_Voltage.wfm")
+        'ch2'
+        >>> _derive_channel_name("D0.wfm")
+        'd0'
+        >>> _derive_channel_name("MATH1.wfm")
+        'math1'
+    """
+    # Get base filename without path
+    basename = Path(wfm_filename).stem  # Remove extension
+
+    # Remove path components if nested
+    basename = basename.split("/")[-1].split("\\")[-1]
+
+    # Extract channel identifier (first part before underscore)
+    channel_id = basename.split("_")[0]
+
+    # Normalize to lowercase
+    return channel_id.lower()
+
+
+def _select_channel(
+    waveforms: dict[str, WaveformTrace | DigitalTrace | IQTrace],
+    channel: str | int | None,
+    path: Path,
+) -> tuple[WaveformTrace | DigitalTrace | IQTrace, str]:
+    """Select specific channel from waveforms dictionary.
+
+    Args:
+        waveforms: Dictionary of channel name to trace.
+        channel: Channel selector (name, index, or None for first).
+        path: Path to session file (for error messages).
+
+    Returns:
+        Tuple of (selected_trace, channel_name).
+
+    Raises:
+        LoaderError: If channel not found or index out of range.
+    """
+    if channel is None:
+        # Default: first channel (alphabetically sorted)
+        channel_name = sorted(waveforms.keys())[0]
+        return waveforms[channel_name], channel_name
+
+    if isinstance(channel, int):
+        # Select by index
+        channel_names = sorted(waveforms.keys())
+        if channel < 0 or channel >= len(channel_names):
+            raise LoaderError(
+                f"Channel index {channel} out of range",
+                file_path=str(path),
+                fix_hint=f"Available channels: {', '.join(channel_names)} (indices 0-{len(channel_names) - 1})",
+            )
+        channel_name = channel_names[channel]
+        return waveforms[channel_name], channel_name
+
+    # Select by name (case-insensitive)
+    channel_lower = channel.lower()
+    for name, trace in waveforms.items():
+        if name.lower() == channel_lower:
+            return trace, name
+
+    # Channel not found
+    available = ", ".join(sorted(waveforms.keys()))
+    raise LoaderError(
+        f"Channel '{channel}' not found in session",
+        file_path=str(path),
+        fix_hint=f"Available channels: {available}",
+    )
+
+
+def _enrich_metadata_from_session(
+    trace: WaveformTrace | DigitalTrace | IQTrace,
+    session_metadata: dict[str, Any],
+    source_file: str,
+) -> WaveformTrace | DigitalTrace | IQTrace:
+    """Enrich waveform metadata with session-level information.
+
+    Args:
+        trace: Original trace from .wfm file.
+        session_metadata: Session metadata from session.json.
+        source_file: Path to .tss file (for source_file metadata).
+
+    Returns:
+        Trace with enriched metadata.
+    """
+    # Create new metadata with session information
+    from dataclasses import replace
+
+    metadata = trace.metadata
+
+    # Update source file to point to .tss instead of temp .wfm
+    metadata = replace(metadata, source_file=source_file)
+
+    # Add trigger info from session if available
+    if "trigger" in session_metadata and metadata.trigger_info is None:
+        metadata = replace(metadata, trigger_info=session_metadata["trigger"])
+
+    # Return trace with updated metadata
+    if isinstance(trace, WaveformTrace):
+        return WaveformTrace(data=trace.data, metadata=metadata)
+    if isinstance(trace, DigitalTrace):
+        return DigitalTrace(data=trace.data, metadata=metadata, edges=trace.edges)
+    # IQTrace
+    return IQTrace(
+        i_data=trace.i_data,
+        q_data=trace.q_data,
+        metadata=metadata,
+    )
+
+
+__all__ = [
+    "load_all_channels_tss",
+    "load_tss",
+]

{oscura-0.6.0.dist-info → oscura-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oscura
-Version: 0.6.0
+Version: 0.7.0
 Summary: Unified hardware reverse engineering framework. Extract all information from any system through signals and data. Unknown protocol discovery, state machine extraction, CRC recovery, security analysis. 16+ protocols, IEEE-compliant measurements.
 Project-URL: Homepage, https://github.com/oscura-re/oscura
 Project-URL: Documentation, https://github.com/oscura-re/oscura/tree/main/docs
@@ -292,7 +292,7 @@ result = osc.auto_decode(trace)
 print(f"Detected {result.protocol}: {len(result.frames)} frames decoded")
 ```
 
-[**6 working examples**](examples/) demonstrating core workflows and analysis patterns.
+**[See demos/README.md](demos/README.md)** for 105+ comprehensive demonstrations organized by skill level.
 
 ---
 
@@ -439,32 +439,50 @@ Built for extensibility:
 
 ## Learn By Doing
 
-### Working Examples
+### Working Demonstrations
 
-Core functionality demonstrated with working code:
+**105+ comprehensive demos** organized into 12 categories covering:
 
-- [Side-Channel Analysis](examples/side_channel_analysis_demo.py) - DPA/CPA attacks, trace analysis
-- [ML Signal Classification](examples/ml_signal_classification_demo.py) - Machine learning for signal identification
-- [Wireshark Dissector Generation](examples/export/wireshark_dissector_demo.py) - Auto-generate protocol dissectors
-- [DBC File Generation](examples/automotive/dbc_generation_example.py) - CAN bus DBC export
-- [LIN Bus Analysis](examples/automotive/lin_analysis_example.py) - LIN protocol decoding
-- [Web Dashboard](examples/web_dashboard_example.py) - Interactive visualization
+- **Data Loading** - All file format loaders (oscilloscopes, logic analyzers, automotive, scientific)
+- **Basic Analysis** - Waveform measurements, digital analysis, spectral analysis, filtering
+- **Protocol Decoding** - UART, SPI, I2C, CAN, LIN, FlexRay, JTAG, SWD, I2S, USB
+- **Advanced Analysis** - Jitter, eye diagrams, power analysis, signal integrity, TDR
+- **Domain Specific** - Automotive diagnostics, EMC compliance, side-channel analysis, IEEE 181 timing
+- **Reverse Engineering** - CRC recovery, state machines, Wireshark dissectors, ML classification
+- **Advanced Features** - Lazy loading, memory management, performance optimization, batch processing
+- **Extensibility** - Custom analyzers, plugins, templates
+- **Integration** - CI/CD, hardware, external tools, web dashboards
+- **Export & Visualization** - All export formats, plotting, reporting
+- **Complete Workflows** - End-to-end production pipelines
+- **Standards Compliance** - IEEE 181/1241/1459/2414, automotive standards
 
-### Run Your First Example
+### Comprehensive Demonstrations
+
+**33+ in-depth demos** organized by skill level and domain:
+
+- **[Getting Started](demos/README.md#beginner-path-2-4-hours)** - File loading, basic measurements, format export (Beginner, 2-4 hours)
+- **[Protocol Decoding](demos/README.md#intermediate-path-6-10-hours)** - UART, SPI, I2C, Manchester, JTAG, USB, PCAP (Intermediate, 6-10 hours)
+- **[Reverse Engineering](demos/README.md#advanced-path-12-20-hours)** - CRC recovery, state machines, Wireshark dissectors, automotive protocols (Advanced, 12-20 hours)
+- **[Standards Compliance](demos/README.md#advanced-path-12-20-hours)** - IEEE 181/1241/1459/2414, CISPR 32, IEC 61000 (Advanced/Expert)
+- **[Complete Workflows](demos/README.md#expert-path-20-40-hours)** - End-to-end production pipelines with ML inference (Expert, 20-40 hours)
+
+**Categories**: Waveform Analysis | File I/O | Custom DAQ | Serial Protocols | Protocol Decoding | UDP Analysis | Protocol Inference | Automotive | Timing | Mixed Signal | Spectral | Jitter | Power | Signal Integrity | EMC | Signal RE | Advanced Inference | Complete Workflows
+
+[**See full demo catalog with learning paths**](demos/README.md)
+
+### Run Your First Demo
 
 ```bash
 # Install development dependencies
 ./scripts/setup.sh
 
-# Side-channel analysis demo
-python examples/side_channel_analysis_demo.py
+# Run your first demo
+python demos/00_getting_started/00_hello_world.py
 
-# ML signal classification
-python examples/ml_signal_classification_demo.py
+# Or try a specific topic
+python demos/05_domain_specific/05_side_channel_basics.py
 ```
 
-[**Browse all examples**](examples/)
-
 ---
 
 ## Command-Line Interface
@@ -556,7 +574,7 @@ python3 .claude/hooks/validate_all.py # Must show 5/5 passing
 | **Real-World Validation**      | Test on your captures, report issues                               | Ensure reliability across use cases             |
 | **Documentation & Case Studies** | Tutorials, sanitized RE workflows, academic papers using Oscura    | Lower entry barrier, demonstrate capabilities   |
 
-[**Contributing Guide**](CONTRIBUTING.md) | [Architecture Documentation](docs/architecture/)
+[**Contributing Guide**](CONTRIBUTING.md) | [Architecture Documentation](docs/developer-guide/architecture.md)
 
 ### Community
 
@@ -584,7 +602,7 @@ python3 .claude/hooks/validate_all.py # Must show 5/5 passing
 
 ### Development
 
-- [Architecture](docs/architecture/) - Design principles and patterns
+- [Architecture](docs/developer-guide/architecture.md) - Design principles and patterns
 - [Testing Guide](docs/testing/) - Test suite architecture
 - [CHANGELOG](CHANGELOG.md) - Version history and migration guides
 

{oscura-0.6.0.dist-info → oscura-0.7.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-oscura/__init__.py,sha256=sZMIZXUx6o16YS0E_1XC19L0dIduZHJgTFa5960TenQ,19022
+oscura/__init__.py,sha256=cB_SbWzKA60qDD2BQHesVvh_GOgWI7XOGfOOwd42YyY,19022
 oscura/__main__.py,sha256=l1rnaD-tpI1W3cp1VHGhSdq9NDqw6Gxjf_gnqXf-zzE,11786
 oscura/convenience.py,sha256=tAABQMwgKjftSNUJLlYnchAwVSO-no0rBfSZteXfZnI,16361
 oscura/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -159,7 +159,7 @@ oscura/api/server/templates/reports.html,sha256=18xoAZPIg7eQANs9k-tmGzVs_-tmS5m6
 oscura/api/server/templates/session_detail.html,sha256=32HnJ0o8ptlZEHQVO1c96j6PoxS0856kPjW2MVn0D8o,3693
 oscura/api/server/templates/sessions.html,sha256=kVcpLOlXAx0PizP7Vc1NlhsYg5swTj77fKCZxoTTCYU,3146
 oscura/api/server/templates/waveforms.html,sha256=5XfpHkgRpmV0MeFb9pBkVDa63phT8zGWnrmA0UlUwZE,2269
-oscura/automotive/__init__.py,sha256=MhHsef7rFKAn_0souQIh2BQPcIlKnBzBOryTr5oww-I,2767
+oscura/automotive/__init__.py,sha256=PCTYjEm5mVPrBiOmYyhPul9utHa955ASz-Oq7h_nYy8,2767
 oscura/automotive/visualization.py,sha256=LD6Gia3kDqoB_jQkOeVmyRVLv1BPuTUVj6lJMVtbQWg,10664
 oscura/automotive/can/__init__.py,sha256=ZYxC8tMMi9Drm9adkH5yklypBTfIbf3D7BYA2SUp9fE,1491
 oscura/automotive/can/analysis.py,sha256=0z6MycxuJGusqDQhYEpHnGRmDw3OMf5yDbS8zI6GJO0,11251
@@ -177,7 +177,7 @@ oscura/automotive/dbc/__init__.py,sha256=HZlM2WAaaglpX4C9tJVkF7uZiaHW4iUPQAbhfJY
 oscura/automotive/dbc/generator.py,sha256=Dxg6fFHYNxtqExKxf0S63MeZsHriisA6R-Ii7WwsfPY,6724
 oscura/automotive/dbc/parser.py,sha256=C5SL1bfJFZp0CYsw-ff8ysJ_57Us9dBoHZ1t6LVLGbo,4421
 oscura/automotive/dtc/__init__.py,sha256=09CgvnClJTQIvzgDOQ22CbcjGAg_zOhPlbm1-k-gl30,895
-oscura/automotive/dtc/data.json,sha256=OrymnbjQkVMdJlIeQ6MUDIihkd9Kea-YvAizZwOZWcc,80011
+oscura/automotive/dtc/data.json,sha256=5pddTolfBJjwimwp5epiMjUqSngZ1dur9LQlcHfdjrA,79331
 oscura/automotive/dtc/database.py,sha256=Ee1Jd4CbP5T4LON0Y2PdOkgdISHa8jf8c6znb0S_L00,9582
 oscura/automotive/flexray/__init__.py,sha256=2RuW8TR4M3tSDEfcj-pJQpGGSxGaw5GdyGSvjMnU8Lk,938
 oscura/automotive/flexray/analyzer.py,sha256=UG3e9tJSHGV7aR3WKwfVCrNDSVlT7ZgFm7vgCcw0qOo,16727
@@ -284,9 +284,9 @@ oscura/core/plugins/registry.py,sha256=XNtq0rBuppC1Z5V5RH74afW-LBnWSLc33lCE6BDZK
 oscura/core/plugins/versioning.py,sha256=d18sXMbgeWy_dVNaM7JWvCVIF6VgpnjIbjP8gdFfgSs,10785
 oscura/core/schemas/__init__.py,sha256=W33kQp0A8v9qZevqjm3T-1Fjrnou5cz0WCAbLRkwbgY,4327
 oscura/core/schemas/bus_configuration.json,sha256=gpcDsg04760KCaLeIDuWvP6RzRUcPZuQplJbe7xpc8E,9562
-oscura/core/schemas/device_mapping.json,sha256=sYOcc2zSe0rmMQN_vtg3Y5XeeDMktAO1ar8vAWl-E1M,5499
-oscura/core/schemas/packet_format.json,sha256=y2KavMGeOUlmjDq7AW_85bfTk3nHlGPuistpuVDdlAk,12893
-oscura/core/schemas/protocol_definition.json,sha256=VPHkgY4fAI-hUiRBtiqZvDNUGjp6_7O4xdi1z36IhCI,11256
+oscura/core/schemas/device_mapping.json,sha256=I87-MWnXldVWIXRC1H-WgzNLszymRdnaxwE3B1z8qys,5415
+oscura/core/schemas/packet_format.json,sha256=NVa4RtwSye9QgD1pBi67nuCDRsVljudCpBBGjmZsMqk,12567
+oscura/core/schemas/protocol_definition.json,sha256=lThVXTWzh7GxN-XNb3h8Bh20l1NZUigivWBb04xvogs,11116
 oscura/correlation/__init__.py,sha256=4H5lCJqBBG3_10oIPsdIOyCij8FlKtMxLp3SAYvSsRg,1537
 oscura/correlation/multi_protocol.py,sha256=X3sTdAc6etsY_9GIbXISCeNMNWM8imkGzHn-UhK7rcw,28288
 oscura/discovery/__init__.py,sha256=ytYa_s4PfKxRRopOdUGsmzUIDPevH25ze_VytBEX2Cw,1232
@@ -376,7 +376,7 @@ oscura/jupyter/exploratory/unknown.py,sha256=KaxpoP9tW9E7Ld16_3VaXaKszfcU2uw62Id
 oscura/jupyter/ui/__init__.py,sha256=XQJh89b_xRe1CB8jssjIdbVgQeLCplFzSkCiXQYKXFU,935
 oscura/jupyter/ui/formatters.py,sha256=roXZhaNLgypb30T6EGF805cDkrqsAh_RQ978iGLtlAU,13580
 oscura/jupyter/ui/progressive_display.py,sha256=Ew-xXek_f6-XkR0CZymyzYbYkbXn8qCZS6Usk2n86dQ,11993
-oscura/loaders/__init__.py,sha256=6XL9e9V3c5sE4tNyNVE4NNEvk9g16lA8nGfyewbtfzs,19927
+oscura/loaders/__init__.py,sha256=f1yakezyiv6IjrsK_L7H1jFCwQUAGNCvjv5DIKHDgzo,20237
 oscura/loaders/binary.py,sha256=USQTTdWjbrn3b-Ly4v-E5eLhga6kM73QlNKxnLm1YUw,5062
 oscura/loaders/chipwhisperer.py,sha256=gkxgakx0YXxJ4dKKkSmlOZYa-VKdWFldAbz3PPAvWyw,12756
 oscura/loaders/configurable.py,sha256=QyyqN_hMBKafx1wyMCcQrykRFY_TfWFU8XLYXztjnFY,44483
@@ -394,6 +394,7 @@ oscura/loaders/sigrok.py,sha256=BliW7KuLIKpyRkupaZTGlSczVoHWbK0-HBs2n4r5oVM,1302
 oscura/loaders/tdms.py,sha256=J1qDLiQMDs_7ayR04g9hsP39hs7LkYy7jJEc57BUPzw,11114
 oscura/loaders/tektronix.py,sha256=V-ns3yCqsXSkeZ1zNXbOZZuViMzYagsiiHr12WeKc4s,26189
 oscura/loaders/touchstone.py,sha256=Cj4KlQQMcSEZuf5M0hg3lFvXvnuPZkcLa8-X-qKEObA,8898
+oscura/loaders/tss.py,sha256=c0xL2h0x09u765qFAxOKpFE8ggOGpc9DwUyRi6r41Y0,13874
 oscura/loaders/validation.py,sha256=JA_vVYQJB4gC9KFKa2lsGV5D-_agmIjP9kE_dXpv4Wk,17835
 oscura/loaders/vcd.py,sha256=y1mFZXTEqJEFfvMf3MYgGk5e16qG7mNlyAQgVLZNwfU,17722
 oscura/loaders/wav.py,sha256=xv6eELWMYflP7OormysAe6-yAiYNzWMInzC6cuUZZmo,9391
@@ -583,8 +584,8 @@ oscura/workflows/batch/logging.py,sha256=6YkTrOA2OSiRjYHmtRn-lL2wyNpya0sggVkgxsz
 oscura/workflows/batch/metrics.py,sha256=InbxaZmFQrANpp_RCcx5F3va55UaiQjhFJ-_SEKAS20,17322
 oscura/workflows/legacy/__init__.py,sha256=PqHw8AIWfP4-1lJEjCDC4c_O8GXYOcWodK9ciOnGJaU,409
 oscura/workflows/legacy/dag.py,sha256=tEhiWmOSdcEYKmrwYUETC0P5yN-_Cy9fEysPwTDVZ3A,12337
-oscura-0.6.0.dist-info/METADATA,sha256=CtuxIm7lD1gUhOP9qjFRhIm4WhucoiUSjCxtzOHqLNE,32904
-oscura-0.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-oscura-0.6.0.dist-info/entry_points.txt,sha256=QLBxd-iTjBQ5HidaVSkLBwvUsqxSG1ZTJ6i-0juu960,48
-oscura-0.6.0.dist-info/licenses/LICENSE,sha256=p1_oEK-oqWDXMFSv5mKbyYkgW-CPbCnFUvdICu490aY,1077
-oscura-0.6.0.dist-info/RECORD,,
+oscura-0.7.0.dist-info/METADATA,sha256=s6BHYA3LswuBulGUa6yeH-08oWJKWE-gwZkp9n19aIw,34518
+oscura-0.7.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+oscura-0.7.0.dist-info/entry_points.txt,sha256=QLBxd-iTjBQ5HidaVSkLBwvUsqxSG1ZTJ6i-0juu960,48
+oscura-0.7.0.dist-info/licenses/LICENSE,sha256=p1_oEK-oqWDXMFSv5mKbyYkgW-CPbCnFUvdICu490aY,1077
+oscura-0.7.0.dist-info/RECORD,,