### Basic Capture Example

Source: https://docs.saleae.com/mso-api/v0.5.0/getting_started

Demonstrates how to initialize the MSO object, configure a capture with analog channels and sample rate, trigger multiple captures, save them to disk, and calculate the average voltage of a captured analog signal.

```python
from pathlib import Path
import numpy as np
from saleae import mso_api

mso = mso_api.MSO()

capture_config = mso_api.CaptureConfig(
    enabled_channels=[mso_api.AnalogChannel(channel=0, name="clock")],
    analog_settings=mso_api.AnalogSettings(sample_rate=100e6),
    capture_settings=mso_api.TimedCapture(capture_length_seconds=0.1),
)

for n in range(3):
    save_dir = Path('my-captures') / f'{n:02d}'
    capture = mso.capture(capture_config, save_dir=save_dir)
    avg_voltage = np.mean(capture.analog_data["clock"].voltages)
    print(f"Capture {n:02d} in {save_dir} avg voltage: {avg_voltage:.3f} V")

```

--------------------------------

### API Documentation for Saleae MSO

Source: https://docs.saleae.com/mso-api/v0.5.0/getting_started

Provides an overview of key API components for Saleae MSO captures, including CaptureConfig, MSO, and Capture objects. Details on configuration, triggering, and data handling are referenced.

```APIDOC
MSO:
  capture():
    Triggers a capture using the configured CaptureConfig.
    Returns: A Capture object providing access to the captured data.

CaptureConfig:
  Controls capture parameters such as channels, sample rates, trigger conditions, and duration.
  Note: The API adjusts to the closest supported sample rate if the requested rate is not supported by the device.

Capture:
  Uses numpy.memmap() for efficient handling of large capture files.
  Objects are persisted on disk by default and can be recreated from their directory locations.
  Methods:
    delete(): Deletes the underlying data files for the capture.
```

--------------------------------

### MSO API Reference - MSO Class

Source: https://docs.saleae.com/mso-api/v0.5.0/getting_started

Provides details on the MSO class, which serves as the primary interface for interacting with Saleae Logic MSO hardware. It covers initialization methods for connecting to devices.

```APIDOC
MSO:
  __init__(serial_number: str = None)
    Initializes the MSO object to connect to a Saleae Logic MSO device.
    If no serial_number is provided, it connects to the first available device.
    Parameters:
      serial_number: The serial number of the specific Logic MSO device to connect to (optional).
    
  capture(capture_config: CaptureConfig, save_dir: Path = None) -> Capture
    Configures and triggers a capture using the provided CaptureConfig.
    Parameters:
      capture_config: An instance of CaptureConfig specifying capture settings.
      save_dir: A directory path to save the capture data (optional).
    Returns:
      A Capture object containing the captured data.

  (See MSO API Reference for more details: https://docs.saleae.com/mso-api/v0.5.0/api/mso.html)
```

--------------------------------

### Install Saleae Development Dependencies

Source: https://docs.saleae.com/mso-api/v0.5.0/installation

Installs development dependencies for the Saleae project, including linters, testing frameworks, and documentation tools.

```bash
pip install ruff pytest jupyter-book
```

--------------------------------

### Install Saleae MSO API with pip

Source: https://docs.saleae.com/mso-api/v0.5.0/index

Installs the saleae-mso-api package using pip, the standard Python package installer.

```bash
pip install saleae-mso-api --index-url https://pypi.saleae.com/simple/
```

--------------------------------

### Install udev rules on Linux

Source: https://docs.saleae.com/mso-api/v0.5.0/installation

Installs the necessary udev rules for Saleae MSO API on Linux systems. This is required if Logic2 has not been previously installed.

```bash
sudo udevadm control --reload-rules && sudo udevadm trigger
```

--------------------------------

### Install Saleae MSO API with uv

Source: https://docs.saleae.com/mso-api/v0.5.0/index

Installs the saleae-mso-api package using the uv package manager, recommended for its efficiency.

```bash
uv pip install saleae-mso-api --index-url https://pypi.saleae.com/simple/
```

--------------------------------

### Clone Repository and Setup Virtual Environment

Source: https://docs.saleae.com/mso-api/v0.5.0/contributing

Clones the Saleae MSO API repository and sets up a virtual environment using 'uv'. This is part of the initial development setup.

```bash
cd
source .venv\Scripts\activate
```

--------------------------------

### Install Playwright for PDF Generation

Source: https://docs.saleae.com/mso-api/v0.5.0/contributing

Installs the Playwright library, which is required for the first-time setup of the PDF generator for the documentation.

```python
playwright
```

--------------------------------

### Install uv Package Manager

Source: https://docs.saleae.com/mso-api/v0.5.0/contributing

Installs the 'uv' package manager using a PowerShell command. This is a prerequisite for setting up the development environment.

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Install Saleae MSO API using pip

Source: https://docs.saleae.com/mso-api/v0.5.0/installation

Installs the Saleae MSO API package from Saleae's private Python Package Index using pip. Requires specifying the index URL.

```python
pip install --index-url https://pypi.saleae.com/simple saleae-mso-api
```

--------------------------------

### Install Saleae udev Rules on Linux

Source: https://docs.saleae.com/mso-api/v0.5.0/installation

Installs the necessary udev rules for Saleae automation instrumentation on Linux systems. This command ensures that Saleae devices are properly recognized and accessible.

```python
uv run python -m saleae.mso_api.utils.install_udev --all
```

--------------------------------

### Install Saleae MSO API using uv

Source: https://docs.saleae.com/mso-api/v0.5.0/installation

Installs the Saleae MSO API package from Saleae's private Python Package Index using uv. uv is recommended for managing Python packages and virtual environments.

```python
uv pip install --index-url https://pypi.saleae.com/simple saleae-mso-api
```

--------------------------------

### Install Package in Development Mode

Source: https://docs.saleae.com/mso-api/v0.5.0/contributing

Installs the Saleae MSO API package in development mode, including development dependencies, within the activated virtual environment.

```bash
uv pip install -e .[dev]
```

--------------------------------

### Initiating an Analog Capture with Saleae MSO API

Source: https://docs.saleae.com/mso-api/v0.5.0/usage

This snippet demonstrates how to initialize the MSO API, configure an analog capture with a specified sample rate and capture duration, execute the capture, and calculate the average voltage of a channel. It saves the captured data to a specified directory.

```python
from pathlib import Path
import numpy as np
from saleae import mso_api

mso = mso_api.MSO()

capture_config = mso_api.CaptureConfig(
    enabled_channels=[mso_api.AnalogChannel(channel=0, name="clock")],
    analog_settings=mso_api.AnalogSettings(sample_rate=100e6),
    capture_settings=mso_api.TimedCapture(capture_length_seconds=0.1),
)

save_dir = Path('my-capture')
capture = mso.capture(capture_config, save_dir)
avg_voltage = np.mean(capture.analog_data["clock"].voltages)
print(f"Captured into {save_dir} avg voltage: {avg_voltage:.3f} V")

```

--------------------------------

### Linux udev Rules for Saleae Devices

Source: https://docs.saleae.com/mso-api/v0.5.0/installation

These udev rules grant the necessary permissions for Saleae devices to be accessed by users. They are typically placed in `/etc/udev/rules.d/99-SaleaeLogic.rules` and reloaded using `udevadm`.

```bash
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="0925", ATTR{idProduct}=="3881", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="21a9", ATTR{idProduct}=="1001", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="21a9", ATTR{idProduct}=="1003", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="21a9", ATTR{idProduct}=="1004", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="21a9", ATTR{idProduct}=="1005", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="21a9", ATTR{idProduct}=="1006", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="21a9", ATTR{idProduct}=="1007", MODE="0666"
```

--------------------------------

### Run Pytest Suite

Source: https://docs.saleae.com/mso-api/v0.5.0/contributing

Executes the test suite using pytest. This requires specific hardware setup, including a Siglent function generator and the MSO connected via USB.

```bash
uv run pytest tests
```

```bash
.venv\Scripts\activate
pytest tests
```

--------------------------------

### Example: Timed Capture Configuration

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture_config

Configures a timed capture for 100ms, enabling two analog channels and four digital channels with specified settings.

```python
frompathlibimport Path
fromsaleaeimport mso_api
fromsaleae.mso_api.part_numberimport MsoPodPartNumber as PN


# Capture 100ms of data in a timed capture on 2 analog channels and 4 digital ones
config1 = mso_api.CaptureConfig(
    enabled_channels=[
        mso_api.AnalogChannel(channel=0, name="clock", center_voltage=2.0, voltage_range=5.0),
        mso_api.AnalogChannel(channel=1, name="data", center_voltage=2.0, voltage_range=5.0),
        mso_api.DigitalChannel(port=0, channel=0, name="MISO", threshold_volts=1.5),
        mso_api.DigitalChannel(port=0, channel=1, name="MOSI"),
        mso_api.DigitalChannel(port=0, channel=2, name="CLK"),
        mso_api.DigitalChannel(port=0, channel=3, name="CS")
    ],
    analog_settings=mso_api.AnalogSettings(
        downsample_mode=mso_api.DownsampleMode.AVERAGE,
        sample_rate=100e6
    ),
    capture_settings=mso_api.TimedCapture(capture_length_seconds=0.1)
)
```

--------------------------------

### Initiating a Mixed-Signal Capture with Saleae MSO API

Source: https://docs.saleae.com/mso-api/v0.5.0/usage

This snippet shows how to configure and initiate a mixed-signal capture using the Saleae MSO API. It includes both analog and digital channels, sets the sample rate, capture duration, and saves the data to a directory.

```python
from pathlib import Path
from saleae import mso_api

mso = mso_api.MSO()

capture_config = mso_api.CaptureConfig(
    enabled_channels=[
        mso_api.AnalogChannel(channel=0, name="clock"),
        mso_api.DigitalChannel(port=0, channel=0, name="MOSI", threshold_volts=1.6),
    ],
    analog_settings=mso_api.AnalogSettings(sample_rate=100e6),
    capture_settings=mso_api.TimedCapture(capture_length_seconds=0.1),
)

save_dir = Path('my-capture')
capture = mso.capture(capture_config, save_dir)

```

--------------------------------

### Example: Analog Triggered Capture Configuration

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture_config

Sets up an analog triggered capture on the rising edge of an analog channel, configuring probe attenuation and pre/post trigger times.

```python
fromsaleaeimport mso_api

# Trigger a capture on the rising edge of an analog channel at full sample rate (default)
config2 = mso_api.CaptureConfig(
    enabled_channels=[
        # signals directly connected via coax must be set to 1x attenuation mode
        mso_api.AnalogChannel(
            channel=0, name="clock",
            probe_attenuation=mso_api.ProbeAttenuation.PROBE_1X
        ),
        mso_api.AnalogChannel(
            channel=1, name="signal",
            probe_attenuation=mso_api.ProbeAttenuation.PROBE_1X
        ),
    ],
    capture_settings=mso_api.AnalogTriggered(
        # specify by channel_name, or channel_index, both work
        trigger=mso_api.EdgeTrigger(
            channel_name="clock", threshold_volts=1.6,
            direction=mso_api.EdgeTriggerDirection.RISING
        ),
        # capture 1/2 millisecond of data on either side of the trigger
        pre_trigger_seconds=0.5e-3,
        post_trigger_seconds=0.5e-3,
    )
)
```

--------------------------------

### Loading a Previously Saved Capture with Saleae MSO API

Source: https://docs.saleae.com/mso-api/v0.5.0/usage

This snippet demonstrates how to load a previously saved capture from a directory containing binary export files. It prints information about the loaded capture, such as channel names, sample rate, and duration.

```python
from pathlib import Path

from saleae import mso_api

# Specify the directory containing the capture files
cap_dir = Path("../tests/data/capture1")

# Load the capture
cap = mso_api.Capture.from_dir(cap_dir)

# Print information about the capture
print(f"Channels: {cap.analog_channel_names}")
print(f"Sample rate: {cap.analog_sample_rate} Hz")
print(f"Duration: {cap.analog_stop_time-cap.analog_start_time:.6f} seconds")

```

--------------------------------

### Example Edge Trigger Usage

Source: https://docs.saleae.com/mso-api/v0.5.0/api/trigger

Demonstrates how to create an EdgeTrigger object to detect rising edges on channel 1 at a voltage threshold of 0V.

```python
from saleae import mso_api


# Create a trigger for rising edges on channel 1 at 0V
trigger = mso_api.EdgeTrigger(
    channel_index=1,
    threshold_volts=0,
    direction=mso_api.EdgeTriggerDirection.RISING
)
```

--------------------------------

### Python Example: Validating and Converting Capture Configurations

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture_config

This Python snippet demonstrates how to iterate through a list of capture configurations, validate them, and convert them into a dictionary format. It uses a hypothetical `config.to_dict` method and a `PN.MsoPod_4ch_200Mhz_12b_1000Ms` constant.

```python
for n, config in enumerate([config1, config2], start=1):
    _ = config.to_dict(Path("my-capture-save-dir"), PN.MsoPod_4ch_200Mhz_12b_1000Ms)
    print(f"configuration #{n} is valid")
```

--------------------------------

### Process Triggered Capture Segments

Source: https://docs.saleae.com/mso-api/v0.5.0/usage

Illustrates how to iterate through the segments generated by `split_capture` and access their data. This includes retrieving duration, sample counts, and analyzing analog channel data such as minimum and maximum voltage values.

```python
# Process each triggered segment
for i, segment in enumerate(caps[:5]):  # Process just the first 5 segments as an example
    print(f"Segment {i}:")
    print(f"  Duration: {segment.analog_stop_time-segment.analog_start_time:.9f} seconds")
    print(f"  Samples: {segment.num_analog_samples}")
    
    # You can perform analysis on each segment
    for ch_name, ch_data in segment.analog_data.items():
        print(f"    {ch_name} min: {ch_data.voltages.min():.3f}V, max: {ch_data.voltages.max():.3f}V")
```

--------------------------------

### Define Edge Triggers

Source: https://docs.saleae.com/mso-api/v0.5.0/usage

Demonstrates how to create EdgeTrigger objects for specific signal events. Supports defining triggers by channel index or name, setting voltage thresholds, edge direction (rising/falling), and configuring holdoff periods.

```python
from saleae.mso_api import EdgeTrigger, EdgeTriggerDirection

# Create a trigger for rising edges on channel 1 (channel_index 0) at 0V
trigger = EdgeTrigger(
    channel_index=0,
    threshold_volts=0,
    direction=EdgeTriggerDirection.RISING
)

# Create a trigger for falling edges on the "clock" channel at 1.65V with a 1ms holdoff
trigger_with_holdoff = EdgeTrigger(
    channel_name="clock",
    threshold_volts=1.65,
    direction=EdgeTriggerDirection.FALLING,
    holdoff_seconds=0.001
)
```

--------------------------------

### Build HTML Documentation

Source: https://docs.saleae.com/mso-api/v0.5.0/contributing

Command to build the HTML version of the project's documentation. The output will be located in the `docs/_build/html` directory.

```bash
make html
```

--------------------------------

### Slice Capture by Index Range

Source: https://docs.saleae.com/mso-api/v0.5.0/api/synthetic_trigger

Creates a new capture containing only the data between the specified start and end indices. The start index is inclusive, and the end index is exclusive.

```python
defslice_capture(capture: Capture, start_idx: int, end_idx: int) -> Capture
```

--------------------------------

### Build PDF Documentation

Source: https://docs.saleae.com/mso-api/v0.5.0/contributing

Command to build the PDF version of the project's documentation. This option is used in conjunction with building the HTML documentation.

```bash
make pdf
```

--------------------------------

### Basic Capture and Data Analysis with Saleae MSO API

Source: https://docs.saleae.com/mso-api/v0.5.0/index

Demonstrates configuring and executing timed captures using the Saleae MSO API. It sets up analog channels, specifies analog and capture settings, performs multiple captures, and calculates the average voltage for a captured analog channel.

```python
from pathlib import Path
import numpy as np
from saleae import mso_api

mso = mso_api.MSO()

capture_config = mso_api.CaptureConfig(
    enabled_channels=[mso_api.AnalogChannel(channel=0, name="clock")],
    analog_settings=mso_api.AnalogSettings(sample_rate=100e6),
    capture_settings=mso_api.TimedCapture(capture_length_seconds=0.1),
)

for n in range(3):
    save_dir = Path('my-captures') / f'{n:02d}'
    capture = mso.capture(capture_config, save_dir=save_dir)
    avg_voltage = np.mean(capture.analog_data["clock"].voltages)
    print(f"Capture {n:02d} in {save_dir} avg voltage: {avg_voltage:.3f} V")

```

--------------------------------

### Re-load Capture from Directory

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture

Demonstrates how to create a Capture instance from a saved capture directory. This method re-loads both the configuration and data files associated with the capture. It requires the `Path` object from the `pathlib` module and the `Capture` class from `saleae.mso_api`.

```python
from pathlib import Path
from saleae.mso_api import Capture

capture = Capture.from_dir(Path("../my-capture"))
print(f"Re-loaded capture with channels: {capture.analog_channel_names}")
```

--------------------------------

### Perform Capture and Access Data

Source: https://docs.saleae.com/mso-api/v0.5.0/api/mso

Demonstrates how to initiate a capture with specified configuration and save directory, and then access the captured analog data and sample rate.

```python
from pathlib import Path

# Perform the capture
save_dir = Path("my-capture")
capture = mso.capture(config, save_dir=save_dir)

# Access the captured data and inspect the actual (effective) capture settings
print(f"Captured {capture.analog_data['clock'].num_samples} samples at a "
      f"{capture.config.analog_settings.sample_rate/1e6:.1f} MHz sample rate")
```

--------------------------------

### Saleae MSO API Modules Overview

Source: https://docs.saleae.com/mso-api/v0.5.0/api/index

Overview of the main modules available in the Saleae MSO API. Each module provides specific functionalities for interacting with the MSO device and its data.

```APIDOC
MSO:
  Manages interaction with the Logic MSO device.

Capture Configuration:
  The configuration objects to control capturing from the device.

Capture:
  The main object returned by a capture operation.

Trigger:
  Classes for defining trigger conditions.

Plot:
  Simple debug plotting of captures.

Synthetic Trigger:
  Tools for applying triggers to existing captures.

Binary Files:
  Utilities for working with binary data files.
```

--------------------------------

### MSO API v0.5.0 - Capture Configuration Documentation

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture_config

API documentation for the Saleae MSO API v0.5.0, covering capture configuration details. This includes an overview, class definitions for various capture-related objects, and enumerations for specific settings.

```APIDOC
Project: /websites/saleae_mso-api_v0_5_0

# Overview
Provides details on how to configure captures for the Saleae MSO.

# Classes
## CaptureConfig
Represents the overall configuration for a capture.

## AnalogChannel
Defines settings for an analog channel.

## DigitalChannel
Defines settings for a digital channel.

## AnalogSettings
Contains specific settings for analog channels, such as voltage range and probe attenuation.

## TimedCapture
Configuration for a timed capture.

## AnalogTriggered
Configuration for an analog-triggered capture.

# Enums
## ProbeAttenuation
Enum for probe attenuation settings.
- `x1`
- `x10`
- `x100`

## DownsampleMode
Enum for downsampling modes.
- `average`
- `skip`
- `decimate`

# Example Capture Configurations
Demonstrates how to set up various capture scenarios.
```

--------------------------------

### Apply Synthetic Triggers to Split Captures

Source: https://docs.saleae.com/mso-api/v0.5.0/usage

Shows how to use the `split_capture` function to divide a long capture into multiple segments based on a defined trigger. This is useful for isolating specific events within a large dataset. Requires loading a capture file and specifying pre/post trigger times.

```python
from pathlib import Path

from saleae import mso_api
from saleae.mso_api.synthetic_trigger import split_capture

# Load a capture
cap_dir = Path(r"C:\\Users\\clark\\OneDrive\\Documents\\01-projects\\api-first-user\\01-data")
cap = mso_api.Capture.from_dir(cap_dir)

# Set up a new trigger to split on
trigger = mso_api.EdgeTrigger(channel_index=0, threshold_volts=0, direction=EdgeTriggerDirection.RISING)

# Split the capture
caps = split_capture(cap, trigger, pre_trigger_seconds=-6e-6, post_trigger_seconds=56e-6)
print(f"Number of triggered segments: {len(caps)}")
# Output: Number of triggered segments: 13810
```

--------------------------------

### Accessing Digital Data

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture

Explains how to access digital data, which is stored as an initial state and transition times. It highlights helper methods `state_at_idx` and `state_at_time` for retrieving digital states.

```python
def state_at_idx(self, idx: int) -> bool:
    """
    Returns the state of the digital channel just before the given transition_time index
    """
    ...

def state_at_time(self, time: float) -> bool:
    """
    Returns the state of the digital channel at the given time
    """
    ...
```

--------------------------------

### Saleae MSO API v0.5.0 - Capture Configuration Reference

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture_config

API documentation for the CaptureConfig, AnalogChannel, DigitalChannel, AnalogSettings, and TimedCapture classes within the Saleae MSO API v0.5.0.

```APIDOC
CaptureConfig:
  __init__(enabled_channels: list[ChannelConfig], analog_settings: Optional[AnalogSettings] = None, capture_settings: Optional[CaptureSettings] = None)
    enabled_channels: List of analog and digital channels to capture.
    analog_settings: Optional analog capture settings (defaults to device maximum sample rate and DROP mode).
    capture_settings: Optional capture settings (defaults to 1ms timed capture).
  to_dict(output_dir: Path, mso_part_number: MsoPodPartNumber) -> Dict[str, Any]
    Converts configuration to device format that the capture binary understands.
  to_dir(output_dir: Path, mso_part_number: MsoPodPartNumber) -> Path
    Writes a full configuration to several files in a given directory.
  from_dir(dir_path: Path) -> CaptureConfig
    Reads a configuration from a given directory.

AnalogChannel:
  __init__(channel: int, name: Optional[str] = None, center_voltage: float = 0.0, voltage_range: float = 10.0, probe_attenuation: ProbeAttenuation = ProbeAttenuation.PROBE_10X, coupling: Coupling = Coupling.DC, bandwidth_mhz: BandwidthLimit = BandwidthLimit.MHz_350)
    channel: The channel number (0-based index).
    name: Optional descriptive name for the channel (defaults to “CH_volts”).
    center_voltage: Center voltage for the channel (default: 0.0V).
    voltage_range: Voltage range for the channel (default: 10.0V).
    probe_attenuation: Probe attenuation setting (default: 1x).
    coupling: Coupling type (default: DC).
    bandwidth_mhz: Bandwidth limit (default: 350MHz).

DigitalChannel:
  __init__(channel: int, name: Optional[str] = None, port: Optional[int] = None, threshold_volts: Optional[float] = None, minimum_pulse_width_samples: Optional[int] = None)
    channel: The channel number (0-based index).
    name: Optional descriptive name for the channel (defaults to “P_CH_logic”).
    port: The port number for the digital channel (required).
    threshold_volts: Voltage threshold for digital signal detection (default: None, uses global threshold).
    minimum_pulse_width_samples: Minimum pulse width in samples to filter out noise (default: None).
    Note: Digital channels require a port number. All digital channels on the same port share the same voltage threshold.

AnalogSettings:
  __init__(downsample_mode: DownsampleMode = DownsampleMode.AVERAGE, sample_rate: float = 1_600_000_000)
    downsample_mode: How to handle downsampling (default: AVERAGE).
    sample_rate: The sample rate in Hz (default: 1.6GS/s).

TimedCapture:
  __init__(capture_length_seconds: float)
    capture_length_seconds: How long to capture in seconds.
```

--------------------------------

### Capture Class Methods

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture

Details class methods for creating Capture objects. `from_dir` reconstructs a capture from saved files, while `from_config` creates a capture using a specified configuration and save path.

```APIDOC
Capture Class Methods:
  * from_dir: Create a Capture from a directory containing .bin files
    Signature: from_dir(cls, dir_path: Path) -> "Capture"
    Description: Call this method on previously saved capture directories to re-create the exact `Capture` object that existed when the capture was first returned, including the `CaptureConfig` object used to generate the capture in the first place.

  * from_config: Create a Capture from a CaptureConfig and a save path
    Signature: from_config(cls, config: CaptureConfig, dir_path: Path) -> "Capture"
    Description: Call this when your previously saved capture doesn’t have any .json files detailing the capture config in it. This may be the case if your capture came from a Logic2 export.
```

--------------------------------

### Create Triggered Capture Configuration

Source: https://docs.saleae.com/mso-api/v0.5.0/api/trigger

Defines a capture configuration with analog channels, sample rate, and edge trigger settings. This includes specifying the channel for triggering, the threshold voltage, and pre/post trigger durations.

```python
config = mso_api.CaptureConfig(
    enabled_channels=[mso_api.AnalogChannel(channel=0, name="data")],
    analog_settings=mso_api.AnalogSettings(sample_rate=100e6),
    capture_settings=mso_api.AnalogTriggered(
        trigger=mso_api.EdgeTrigger(channel_name="data", threshold_volts=0),
        pre_trigger_seconds=0.0005,
        post_trigger_seconds=0.0005,
        timeout_seconds=1.0
    )
)
```

--------------------------------

### Accessing Analog Data

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture

Demonstrates how to access continuous analog data using NumPy indexing on the `voltages` attribute of analog data objects.

```python
# Get voltage data for channel 1 (channel_index 0)
ch1_volts = cap.analog_data["CH0_volts"].voltages

# Get a specific sample
sample_index = 1000
voltage_at_sample = cap.analog_data["CH0_volts"].voltages[sample_index]
```

--------------------------------

### Capture Class Overview

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture

The Capture class represents an individual capture from a Logic MSO device. It allows loading capture data from binary files using np.memmap for efficient memory usage, accessing channel data and metadata, and querying capture information such as channels and time range.

```APIDOC
Capture:
  Represents an individual capture from a Saleae Logic MSO device.

  Methods:
    load_capture(file_path: str, **kwargs):
      Loads capture data from a specified binary file path.
      Uses np.memmap for memory-efficient loading.
      Parameters:
        file_path: The path to the binary capture file.
        **kwargs: Additional keyword arguments for np.memmap.
      Returns:
        An instance of the Capture class.

    get_analog_data(channel_name: str):
      Retrieves analog data for a specified channel.
      Parameters:
        channel_name: The name of the analog channel.
      Returns:
        A numpy array containing the analog data.

    get_digital_data(channel_name: str):
      Retrieves digital data for a specified channel.
      Parameters:
        channel_name: The name of the digital channel.
      Returns:
        A numpy array containing the digital data.

    get_channels():
      Returns a list of all channels in the capture.

    get_time_range():
      Returns the start and end time of the capture.

  Usage:
    # Load a capture
    capture = Capture.load_capture("path/to/your/capture.logicdata")

    # Get analog data from channel 'LA'
    analog_data = capture.get_analog_data("LA")

    # Get digital data from channel 'D0'
    digital_data = capture.get_digital_data("D0")

    # Get all channel names
    channels = capture.get_channels()

    # Get capture time range
    start_time, end_time = capture.get_time_range()

```

--------------------------------

### MSO Class Initialization

Source: https://docs.saleae.com/mso-api/v0.5.0/api/mso

Initializes the MSO class, which serves as the primary interface for Saleae Logic MSO devices. It allows connection to a specific device via its serial number or the first available device.

```APIDOC
class MSO:
    __init__(self, serial_number: Optional[str] = None)

Parameters:
  serial_number: Optional serial number to connect to a specific device. If not provided, connects to the first available device.

Properties:
  part_number: The Saleae Part Number for the attached MSO. Supplies information like maximum sample rates and buffer sizes.
```

--------------------------------

### Ruff for Code Formatting and Linting

Source: https://docs.saleae.com/mso-api/v0.5.0/contributing

Utilizes ruff for code linting and formatting. Commands are provided to auto-format code before committing and to perform linting checks.

```bash
ruff format .
```

```bash
ruff check .
```

--------------------------------

### MSO Capture Method

Source: https://docs.saleae.com/mso-api/v0.5.0/api/mso

Captures data from the Saleae MSO device based on the provided configuration. It handles directory creation, saving configuration and results, executing the capture, and loading the data into a Capture object.

```APIDOC
def capture(self, capture_config: mso_api.CaptureConfig, save_dir: pathlib.Path, timeout_secs: Optional[float] = None) -> mso_api.Capture

Captures data from the device according to the specified configuration.

Parameters:
  capture_config: Configuration for the capture (channels, sample rate, etc.)
  save_dir: Directory to save capture data
  timeout_secs: Optional timeout for the capture operation

Returns:
  A Capture object containing the captured data

Note:
  1. Create the save directory if it doesn’t exist
  2. Save the record options to record_options.json
  3. Execute the capture command
  4. Save the record result to record_result.json
  5. Load the captured data into a Capture object
```

```python
from pathlib import Path
from saleae.mso_api import MSO, CaptureConfig, AnalogChannel, AnalogSettings, TimedCapture

# Initialize the MSO
mso = MSO()

# Configure the capture
config = CaptureConfig(
    enabled_channels=[AnalogChannel(channel=0, name="clock")],
    analog_settings=AnalogSettings(sample_rate=100e6),
    capture_settings=TimedCapture(capture_length_seconds=0.1),
)

# Example of how to call the capture method would go here, 
# but is omitted as the prompt only provided the definition and configuration setup.
```

--------------------------------

### AnalogTriggered Capture Configuration

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture_config

Defines settings for a capture triggered by an analog signal threshold. Includes trigger details, pre/post trigger capture times, and timeout settings.

```python
fromsaleae.mso_api.capture_config import AnalogTriggered, EdgeTrigger

@dataclass
class AnalogTriggered(CaptureSettings):
    trigger: EdgeTrigger
    pre_trigger_seconds: float = 0.0005
    post_trigger_seconds: float = 0.0005
    timeout_seconds: float = 1.0
```

--------------------------------

### Capture Configuration Classes and Enums

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture_config

Defines the structure for configuring capture operations, including channel settings, analog parameters, and capture modes. This module provides the necessary objects to set up a capture on the Saleae Logic MSO device.

```APIDOC
CaptureConfig:
  Description: Represents the overall configuration for a capture operation.
  Attributes:
    digital_channels: List of DigitalChannel objects to capture.
    analog_channels: List of AnalogChannel objects to capture.
    timed_capture: TimedCapture object for timed capture settings.
    analog_triggered: AnalogTriggered object for analog triggered capture settings.

AnalogChannel:
  Description: Configuration for an analog channel.
  Attributes:
    enabled: Boolean indicating if the channel is enabled.
    name: String name of the analog channel.
    settings: AnalogSettings object for channel-specific settings.

DigitalChannel:
  Description: Configuration for a digital channel.
  Attributes:
    enabled: Boolean indicating if the channel is enabled.
    name: String name of the digital channel.

AnalogSettings:
  Description: Settings specific to an analog channel.
  Attributes:
    probe_attenuation: ProbeAttenuation enum value for probe attenuation.
    downsample_mode: DownsampleMode enum value for downsampling.
    sample_rate: Integer sample rate for the channel.

TimedCapture:
  Description: Configuration for a timed capture.
  Attributes:
    duration_ms: Integer duration of the capture in milliseconds.

AnalogTriggered:
  Description: Configuration for an analog triggered capture.
  Attributes:
    trigger_channel: String name of the channel to trigger on.
    trigger_level: Float trigger level.
    trigger_edge: String indicating the trigger edge ('rising' or 'falling').

ProbeAttenuation:
  Description: Enum for probe attenuation settings.
  Values:
    ATTN_1X: 1x attenuation.
    ATTN_10X: 10x attenuation.
    ATTN_100X: 100x attenuation.

DownsampleMode:
  Description: Enum for downsampling modes.
  Values:
    NONE: No downsampling.
    ODD_EVEN: Downsample by taking odd and even samples.
    AVERAGE: Downsample by averaging samples.
```

--------------------------------

### SmartCableNotReadyError Exception

Source: https://docs.saleae.com/mso-api/v0.5.0/api/mso

Details the SmartCableNotReadyError, raised when a smart cable is not ready or not connected. Explains common causes, solutions, and attributes.

```apidoc
SmartCableNotReadyError:

```python
classSmartCableNotReadyError(MsoApiError):
    def __init__(self, command: str, stdout: str):
        self.command = command
        self.stdout = stdout
        super().__init__(f"Smart cable was not connected or initialized in time. {command} failed, stdout was: {stdout}")
```

Exception raised when a smart cable is not ready or not connected. This typically occurs when:
  * The smart cable is not properly connected to the MSO device
  * The smart cable has not been initialized in time for the capture operation
  * There are communication issues with the smart cable hardware

**Attributes:**
  * `command`: The command that failed
  * `stdout`: The stdout output from the command

**Common Solutions:**
  * Ensure the smart cable is properly connected to the MSO device
  * Try unplugging and replugging the smart cable
  * Verify that the smart cable is being detected by the system by opening Logic2 and attempting to capture data from it
```

--------------------------------

### SaleaeFile Class Documentation

Source: https://docs.saleae.com/mso-api/v0.5.0/api/binary_files

Represents the parsed contents of a Saleae binary file. This class holds information about the file's version, type, and the actual parsed data. It is part of the binary_files module.

```APIDOC
SaleaeFile:
  Attributes:
    version: The file format version (0 or 1).
    type: Internal Enum representing the file type (e.g., Filetype_DigitalExport, _AnalogExport, _WaveformAdcExport).
    contents: The parsed contents of the file (e.g., AnalogExport_V0, DigitalExport_V1).
```

--------------------------------

### AnalogChannel Configuration

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture_config

Represents the configuration for a single analog channel, including its number, name, voltage settings, probe attenuation, coupling, and bandwidth.

```python
from dataclasses import dataclass
from typing import Optional

# Assuming ProbeAttenuation and Coupling enums are defined elsewhere

@dataclass
class AnalogChannel:
    channel: int
    name: Optional[str] = None
    center_voltage: float = 0.0
    voltage_range: float = 10.0
    probe_attenuation: ProbeAttenuation = ProbeAttenuation.PROBE_10X
    coupling: Coupling = Coupling.DC
    bandwidth_mhz: BandwidthLimit = BandwidthLimit.MHz_350
```

--------------------------------

### DigitalChannel Configuration

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture_config

Represents the configuration for a single digital channel, including its number, name, port, voltage threshold, and minimum pulse width.

```python
from dataclasses import dataclass
from typing import Optional

# Assuming ChannelConfig and BandwidthLimit enums are defined elsewhere

@dataclass
class DigitalChannel(ChannelConfig):
    channel: int
    name: Optional[str] = None
    port: Optional[int] = None
    threshold_volts: Optional[float] = None
    minimum_pulse_width_samples: Optional[int] = None
```

--------------------------------

### CaptureConfig Data Structure

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture_config

Defines the main configuration object for captures, including enabled channels and optional analog/capture settings. It supports methods for converting configuration to device format and reading/writing from directories.

```python
from dataclasses import dataclass
from typing import List, Optional, Dict, Any
from pathlib import Path

# Assuming ChannelConfig, AnalogSettings, CaptureSettings, MsoPodPartNumber are defined elsewhere

@dataclass
class CaptureConfig:
    enabled_channels: List[ChannelConfig]
    analog_settings: Optional[AnalogSettings] = None
    capture_settings: Optional[CaptureSettings] = None

    def to_dict(self, output_dir: Path, mso_part_number: MsoPodPartNumber) -> Dict[str, Any]:
        # Implementation details for converting configuration to device format
        pass

    def to_dir(self, output_dir: Path, mso_part_number: MsoPodPartNumber) -> Path:
        # Implementation details for writing configuration to files
        pass

    @classmethod
    def from_dir(cls, dir_path: Path) -> "CaptureConfig":
        # Implementation details for reading configuration from files
        pass
```

--------------------------------

### Plot Capture Utility

Source: https://docs.saleae.com/mso-api/v0.5.0/api/plot

Demonstrates how to load a capture and plot it using the Saleae MSO API's plot utility. Includes optional parameters for saving the plot, setting time windows, adding a title, and including markers for specific events.

```python
from pathlib import Path
from saleae import mso_api
from saleae.mso_api.utils.plot import plot_capture, PlotMarker

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

# Optional: Create markers for important events
markers = [
    PlotMarker(time=0.001),
    PlotMarker(time=0.002)
]

# Plot the capture
plot_capture(
    capture=capture,
    save_to=Path("debug_plot.png"),
    start_time=0.000,  # Optional: Start time in seconds
    stop_time=0.005,   # Optional: Stop time in seconds
    title="My Capture", # Optional: Plot title
    markers=markers    # Optional: List of markers
)

```

--------------------------------

### AnalogSettings Configuration

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture_config

Configures analog capture settings, including the downsample mode and sample rate.

```python
from dataclasses import dataclass

# Assuming DownsampleMode enum is defined elsewhere

@dataclass
class AnalogSettings:
    downsample_mode: DownsampleMode = DownsampleMode.AVERAGE
    sample_rate: float = 1_600_000_000
```

--------------------------------

### Capture Class Properties

Source: https://docs.saleae.com/mso-api/v0.5.0/api/capture

Provides access to various properties of the Capture object, such as start/stop times, sample rates, channel names, and the number of samples for analog data.

```APIDOC
Capture Properties:
  * analog_start_time: The start time of the capture in MSO-relative seconds
  * analog_sample_rate: The sample rate that analog traces were taken at in Hz
  * analog_channel_names: Returns a list of analog channel names in the capture
  * analog_time_series: Returns the time array for analog data
  * analog_stop_time: Returns the end time of the capture in seconds
  * num_analog_samples: Returns the number of analog samples in the capture
```

--------------------------------

### MsoCommandError Exception

Source: https://docs.saleae.com/mso-api/v0.5.0/api/mso

Details the MsoCommandError, raised when device commands fail. Explains attributes and provides context for when this error occurs.

```apidoc
MsoCommandError:

```python
classMsoCommandError(MsoApiError):
    def __init__(self, command: str, stdout: str):
        self.command = command
        self.stdout = stdout
        super().__init__(f"Command {command} failed, stdout was: {stdout}")
```

Exception raised when device commands otherwise fail.
**Attributes:**
  * `command`: The command that failed
  * `stdout`: The stdout output from the command
```