Getting Started

Getting Started#

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

Prerequisites#

Before using the Saleae MSO API, ensure you have:

  • A Windows or Linux computer (OSX support coming soon)

  • Python 3.11 or higher installed

  • A Saleae Logic device connected to your computer

  • Installed Logic 2.4.20 or newer (so you have the Logic MSO drivers)

We also 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:

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")

Capture 00 in my-captures\00 avg voltage: 0.062 V

Capture 01 in my-captures\01 avg voltage: 0.062 V
Capture 02 in my-captures\02 avg voltage: 0.062 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.

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.

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 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.

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 page for detailed setup instructions

  • Check out the Usage guide for more detailed examples

  • Explore the API Reference for comprehensive documentation

Contents