---
jupytext:
  formats: md:myst
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.11.5
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

# Getting Started

This guide will help you get started with the Saleae MSO API.

## Prerequisites

Before starting, please follow the [Installation](installation.md) guide to set up your environment with the necessary requirements and dependencies.

We recommend opening up Logic2 and testing that your Logic MSO can perform basic functions on your machine before diving into automation.

## Basic Usage

Here's a simple example of how to capture an analog signal:

```{code-cell} 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")
```

As you can see there's 4 basic things happening in this example:

 - Initializing the `MSO()` object
 - Configuring the capture by building a `CaptureConfig()` object
 - Triggering one or more captures with that configuration
 - Digesting the data from those captures (however you want)

Let's dive into each one a little bit below.

## Initializing the `MSO()` object

The `MSO()` object is your main interface to the Logic MSO hardware. You can initialize it with no arguments to connect to the first available device, or provide a serial number to connect to a specific device.

For more details on the `MSO` class and its capabilities, see the [MSO API Reference](api/mso.md).

## Configuring a capture

The `CaptureConfig` object controls all aspects of how a capture will be performed - which channels to capture from, sample rates, trigger conditions, and capture duration. You can configure analog channels, digital channels, or both for mixed-signal captures.

Not all sample rates will be supported by all devices, so the API will make the capture at the closest supported sampling rate
to the one in the configuration. Each capture object is returned with a configuration object which accurately represents the configuration
the device used to make the capture, including the exact sample rate.

For more details on configuring captures, see the [Capture Configuration Reference](api/capture_config.md).

## Triggering a capture with that configuration

Once you have an `MSO` object and a `CaptureConfig`, you can trigger a capture using the `capture()` method. Capture files are saved to disk
directly by the underlying MSO communications binary, and can be absolutely enormous depending on their length and sample rate. Top line Logic MSO
devices can take >6GB single captures (2 bytes per sample with a tiny header in each file).
See [MSO API Reference](api/mso.md) for more information.

The method returns a `Capture` object that provides access to the captured data. `Capture` objects use `numpy.memmap()` as their underlying storage
mechanism so huge captures don't necessarily have to be stored in memory for certain operations to work on them. `Capture` objects are also persisted on disk by
default, and are really easy to re-create quickly from their folder locations. Learn more about `Capture` objects in [Capture API Reference](api/capture.md).

## Digesting the data

Here's where the fun begins!

If you're using huge capture files, be mindful of what operations might cause them to be loaded into memory vs. operated on in-place. If you are only
storing computation results from your captures, use `capture.delete()` to delete the underlying data files, or just `rm` the entire directory after calling
`del` on your capture.

If you have an interesting use case we'd love to hear about it - send us a message on the support site!

## Next Steps

- See the [Installation](installation.md) page for detailed setup instructions
- Check out the [Usage](usage.md) guide for more detailed examples
- Explore the [API Reference](api/index.md) for comprehensive documentation