Synthetic Trigger

Synthetic Trigger#

The synthetic_trigger module provides functionality to apply trigger conditions to existing captures, allowing you to split a single capture into multiple segments based on trigger conditions.

Overview#

This module is particularly useful when you have a long capture and want to extract specific events based on signal characteristics. It allows you to:

  • Define trigger conditions after the capture has been made

  • Split a capture into multiple segments based on those triggers

  • Extract precise time windows around each trigger event

  • Apply holdoff periods between triggers

Functions#

split_capture#

def split_capture(capture: Capture, 
                  trigger: EdgeTrigger, 
                  pre_trigger_seconds: float, 
                  post_trigger_seconds: float) -> List[Capture]

Splits a capture into multiple captures based on a trigger condition.

Parameters:

  • capture: The capture to split

  • trigger: The trigger settings (e.g., EdgeTrigger)

  • pre_trigger_seconds: Time before the trigger to include (can be negative to delay the trigger)

  • post_trigger_seconds: Time after the trigger to include (positive value)

Returns:

  • A list of new captures, each spanning from a detected trigger - pre_trigger_seconds to the detected trigger + post_trigger_seconds

Note: Captures that aren’t long enough to include both pre- and post-trigger data are discarded.

Example:

from saleae.mso_api.capture import Capture
from saleae.mso_api.synthetic_trigger import split_capture
from saleae.mso_api.trigger import EdgeTrigger, EdgeTriggerDirection
from pathlib import Path

# Load a capture
cap_dir = Path("path/to/capture")
cap = Capture.from_dir(cap_dir)

# Define a trigger (rising edge on channel "data")
trigger = EdgeTrigger(
    channel_name="data",
    threshold_volts=0,
    direction=EdgeTriggerDirection.RISING,
    holdoff_seconds=0.001  # 1ms minimum between triggers
)

# Split the capture with 6µs before the trigger and 56µs after
caps = split_capture(cap, trigger, pre_trigger_seconds=-6e-6, post_trigger_seconds=56e-6)

print(f"Found {len(caps)} triggered segments")

find_trigger_indices#

def find_trigger_indices(capture: Capture, trigger: EdgeTrigger) -> List[int]

Finds the indices in the capture where the trigger conditions are met.

Parameters:

  • capture: The capture to analyze

  • trigger: The trigger settings

Returns:

  • A list of indices where the trigger conditions are met

slice_capture#

def slice_capture(capture: Capture, start_idx: int, end_idx: int) -> Capture

Creates a new capture containing only the data between the specified indices.

Parameters:

  • capture: The capture to slice

  • start_idx: Starting index (inclusive)

  • end_idx: Ending index (exclusive)

Returns:

  • A new Capture object containing only the specified range of data

Common Use Cases#

  1. Protocol Analysis: Extract all instances of a specific protocol transaction

  2. Fault Detection: Identify all occurrences of a fault condition in a long capture

  3. Signal Processing: Pre-process data by extracting only relevant segments for further analysis

Error Handling#

The module will raise appropriate errors if:

  • The trigger channel is not found in the capture

  • The capture has no channels

  • The pre-trigger time is after the post-trigger time

  • The capture segments are too short to include the requested time windows

Contents