Automation API

Manager

class saleae.automation.Manager

Manager is the main class for interacting with the Logic 2 software.

Creating a new instance of the Manager class will attempt to connect to a running instance of the Logic 2 software.

Please review the getting started guide for instructions on preparing the Logic 2 software for API connections.

__init__(*, port, address='127.0.0.1', connect_timeout_seconds=None, grpc_channel_arguments=None, logic2_process=None)

It is recommended that you use Manager.launch() or Manager.connect() instead of using __init__ directly.

Create an instance of the Manager class, and connect to the Logic 2 software.

This library currently assumes the Logic 2 software is running on the same machine, and will attempt to connect to 127.0.0.1. In the future, we’ll add support for supplying an IP address, as well as functions to help launch local copies of the application.

Parameters
  • port (int) – Port number. By default, Logic 2 uses port 10430.

  • address (str) – Address to connect to.

  • connect_timeout_seconds (Optional[float]) – Number of seconds to attempt to connect to gRPC server, after which an exception will be thrown.

  • grpc_channel_arguments (Optional[List[Tuple[str, Any]]]) – A set of arguments to pass through to gRPC.

  • logic2_process (Optional[Popen]) – Process object for Logic2 if launched from Python. The process will be shutdown automatically when Manager.close() is called.

classmethod launch(application_path=None, connect_timeout_seconds=None, grpc_channel_arguments=None, port=None)

Launch the Logic2 application and shut it down when the returned Manager is closed.

Parameters
  • application_path (Union[Path, str, None]) – The path to the Logic2 binary to run. If not specified, a locally installed copy of Logic2 will be searched for.

  • connect_timeout_seconds (Optional[float]) – See __init__

  • grpc_channel_arguments (Optional[List[Tuple[str, Any]]]) – See __init__

  • port (Optional[int]) – Port to use for the gRPC server. If not specified, 10430 will be used.

Return type

Manager

classmethod connect(*, address='127.0.0.1', port=10430, connect_timeout_seconds=None, grpc_channel_arguments=None)

Connect to an existing instance of Logic 2.

Parameters
  • port (int) – Port number. By default, Logic 2 uses port 10430.

  • address (str) – Address to connect to.

  • connect_timeout_seconds (Optional[float]) – See __init__

  • grpc_channel_arguments (Optional[List[Tuple[str, Any]]]) – See __init__

Return type

Manager

get_app_info()

Get information about the connected Logic 2 instance.

Return type

AppInfo

Returns

AppInfo object for the connected Logic 2 instance.

close()

Close connection to Saleae backend, and shut it down if it was created by Manager.

get_devices(*, include_simulation_devices=False)

Returns a list of connected devices. Use this to find the device id of the attached devices.

Parameters

include_simulation_devices (bool) – If True, the return value will also include simulation devices. This can be useful for testing without a physical device.

Return type

List[DeviceDesc]

start_capture(*, device_configuration, device_id=None, capture_configuration=None)

Start a new capture

All capture settings need to be provided. The existing software settings, like selected device or added analyzers, are ignored.

Be sure to catch DeviceError exceptions raised by this function, and handle them accordingly. See the error section of the library documentation.

Parameters
  • device_configuration (DeviceConfiguration) – An instance of LogicDeviceConfiguration, complete with enabled channels, sample rates, and more.

  • device_id (Optional[str]) – The id of device to record with.

  • capture_configuration (Optional[CaptureConfiguration]) – The capture configuration, which selects the capture mode: timer, digital trigger, or manual., defaults to None, indicating manual mode.

Return type

Capture

Returns

Capture instance class. Be sure to call either wait() or stop() before trying to save, export, or close the capture.

load_capture(filepath)

Load a capture.

The returned Capture object will be fully loaded (wait_until_done not required).

Raises:

InvalidFileError

Return type

Capture

Returns

Capture instance class.

LogicDeviceConfiguration

class saleae.automation.LogicDeviceConfiguration

Represents the capture configuration for one of the following devices:

  • Logic 8

  • Logic Pro 8

  • Logic Pro 16

This class is used to define the specific device configuration when starting a capture with start_capture

enabled_analog_channels: List[int]

list of enabled analog channels. Example: [0,1]

enabled_digital_channels: List[int]

list of enabled digital channels. Example: [0,1]

analog_sample_rate: Optional[int] = None

Analog sample rate, Samples per second. This must match a sample rate visible in the software for the given enabled channels. Omit this when no analog channels are used.

digital_sample_rate: Optional[int] = None

Digital sample rate, Samples per second. This must match a sample rate visible in the software for the given enabled channels. Omit this when no analog channels are used.

digital_threshold_volts: Optional[float] = None

Voltage threshold Logic Pro 8 and Logic Pro 16 only Valid options: 1.2, 1.8, and 3.3. leave unspecified or 0 for Logic 8.

glitch_filters: List[GlitchFilterEntry]

Optionally specify a glitch filter for one or more channels. Only applies to digital channels.

__init__(enabled_analog_channels=<factory>, enabled_digital_channels=<factory>, analog_sample_rate=None, digital_sample_rate=None, digital_threshold_volts=None, glitch_filters=<factory>)

Capture

class saleae.automation.Capture

This class represents a single capture in the Logic 2 software.

This class is returned from start_capture() and from load_capture()

In the case of start_capture(), the capture is still in the recording state, and wait() or stop() must be called before any other function can be called.

Be sure to close() when you’re finished! Otherwise, they will remain in the application as tabs, and will continue to consume memory in the background.

__init__(manager, capture_id)

This class cannot be constructed by the user, and is only returned from the Manager class.

add_analyzer(name, *, label=None, settings=None)

Add an analyzer to the capture

Note: analyzers already added to a loaded_capture cannot be accessed from the API at this time.

Parameters
  • name (str) – The name of the Analyzer, as shown in the Logic 2 application add analyzer list. This must match exactly.

  • label (Optional[str]) – The user editable display string for the analyzer. This will be shown in the analyzer data table export, defaults to None

  • settings (Optional[Dict[str, Union[str, int, float, bool]]]) – All settings for the analyzer. The keys and values here must exactly match the Analyzer settings as shown in the UI, defaults to None

Return type

AnalyzerHandle

Returns

Returns an AnalyzerHandle

add_high_level_analyzer(extension_directory, name, *, input_analyzer, settings=None, label=None)

Add a high level analyzer to the capture.

Note: high level analyzers already added to a loaded_capture cannot be accessed from the API at this time.

Parameters
  • extension_directory (str) – The directory of the extension that the HLA is in.

  • name (str) – The name of the HLA, as specifiied in the extension.json of the extension.

  • input_analyzer (AnalyzerHandle) – Handle to analyzer (added via add_analyzer) to use as input to this HLA.

  • settings (Optional[Dict[str, Union[str, float]]]) – All settings for the analyzer. The keys and values here must match the HLA settings as shown in the HLA class.

  • label (Optional[str]) – The user editable display string for the high level analyzer. This will be shown in the analyzer data table export.

Return type

AnalyzerHandle

Returns

Returns an AnalyzerHandle

remove_analyzer(analyzer)

Removes an analyzer from the capture.

Parameters

analyzer (AnalyzerHandle) – AnalyzerHandle returned by add_analyzer()

remove_high_level_analyzer(high_level_analyzer)

Removes a high level analyzer from the capture.

Parameters

high_level_analyzer (AnalyzerHandle) – AnalyzerHandle returned by add_analyzer()

save_capture(filepath)

Saves the capture to a .sal file, which can be loaded later either through the UI or with the load_capture() function.

Parameters

filepath (str) – path to the .sal file. Can be absolute, or relative to the Logic 2 software current working directory.

legacy_export_analyzer(filepath, analyzer, radix)

Exports the specified analyzer using the analyzer plugin export format, and not the data table format.

Use the export_data_table() function to export analyzer results from the data table.

Parameters
  • filepath (str) – file name and path to export to. Should include the file name and extension, typically .csv or .txt.

  • analyzer (AnalyzerHandle) – AnalyzerHandle returned from add_analyzer()

  • radix (RadixType) – Display Radix, from the RadixType enumeration.

export_data_table(filepath, analyzers, *, columns=None, filter=None, iso8601_timestamp=False)

Exports the Analyzer Data Table

We will be adding more options to this in the future, including the query string, specific columns, specific query columns, and more.

Parameters
  • filepath (str) – The specified output file, including extension, .csv.

  • analyzers (List[Union[AnalyzerHandle, DataTableExportConfiguration]]) – A list of AnalyzerHandles that should be included in the export, returned from add_analyzer()

  • columns (Optional[List[str]]) – Columns to include in export.

  • filter (Optional[DataTableFilter]) – Filter to apply to the exported data.

  • iso8601_timestamp (bool) – Use this to output wall clock timestamps, instead of capture relative timestamps. Defaults to False.

export_raw_data_csv(directory, *, analog_channels=None, digital_channels=None, analog_downsample_ratio=1, iso8601_timestamp=False)

Exports raw data to CSV file(s)

This produces exactly the same format as used in the Logic 2 software when using the “Export Raw Data” dialog with the “CSV” option selected.

Note, the directory parameter is a specific folder that must already exist, and should not include a filename.

The export system will produce an analog.csv and/or digital.csv file(s) in that directory.

All selected analog channels will be combined into the analog.csv file, and likewise for digital channels and digital.csv

If no channels are specified, all channels will be exported.

Parameters
  • directory (str) – directory path (not including a filename) to where analog.csv and/or digital.csv will be saved.

  • analog_channels (Optional[List[int]]) – list of analog channels to export, defaults to None

  • digital_channels (Optional[List[int]]) – list of digital channels to export, defaults to None

  • analog_downsample_ratio (int) – optional analog downsample ratio, useful to help reduce export file sizes where extra analog resolution isn’t needed, defaults to 1

  • iso8601_timestamp (bool) – Use this to output wall clock timestamps, instead of capture relative timestamps. Defaults to False.

export_raw_data_binary(directory, *, analog_channels=None, digital_channels=None, analog_downsample_ratio=1)

Exports raw data to binary files

This produces exactly the same format as used in the Logic 2 software when using the “Export Raw Data” dialog with the “binary” option selected.

Documentation for the format can be found here: https://support.saleae.com/faq/technical-faq/binary-export-format-logic-2

Note, the directory parameter is a specific folder that must already exist, and should not include a filename.

The export system will produce one .bin file for each channel exported.

If no channels are specified, all channels will be exported.

Parameters
  • directory (str) – directory path (not including a filename) to where .bin files will be saved

  • analog_channels (Optional[List[int]]) – list of analog channels to export, defaults to None

  • digital_channels (Optional[List[int]]) – list of digital channels to export, defaults to None

  • analog_downsample_ratio (int) – optional analog downsample ratio, useful to help reduce export file sizes where extra analog resolution isn’t needed, defaults to 1

close()

Closes the capture. Once called, do not use this instance.

stop()

Stops the capture. Can be used with any capture mode, but this is recommended for use with ManualCaptureMode.

stop() and wait() should never both be used for a single capture.

Do not call stop() more than once.

stop() should never be called for loaded captures.

If an error occurred during the capture (for example, a USB read timeout, or an out of memory error) that error will be raised by this function.

Be sure to catch DeviceError exceptions raised by this function, and handle them accordingly. See the error section of the library documentation.

wait()

Waits for the capture to complete. This should only be used with TimedCaptureMode or DigitalTriggerCaptureMode.

for TimedCaptureMode, this will wait for the capture duration to complete.

For DigitalTriggerCaptureMode, this will wait for the digital trigger to be found and the capture to complete.

stop() and wait() should never both be used for a single capture.

Do not call wait() more than once.

wait() should never be called for loaded captures.

Be sure to catch DeviceError exceptions raised by this function, and handle them accordingly. See the error section of the library documentation.

CaptureConfiguration

class saleae.automation.CaptureConfiguration

The top-level capture configuration provided to the start_capture function.

buffer_size_megabytes: Optional[int] = None

Capture buffer size (in megabytes)

capture_mode: Union[ManualCaptureMode, TimedCaptureMode, DigitalTriggerCaptureMode]
The capture mode. This can be one of the following:
ManualCaptureMode
(Looping mode in the software. Stop this capture with the stop() function)
TimedCaptureMode
This will record until the specified duration has been captured. Use the wait() function to block until the capture is complete.
DigitalTriggerCaptureMode
This will set the digital trigger and record until the trigger has been found and the post-trigger length has been recorded. Use the wait() function to block until the capture is complete.
__init__(buffer_size_megabytes=None, capture_mode=<factory>)

ManualCaptureMode

class saleae.automation.ManualCaptureMode

When this is used, a capture must be triggered/stopped manually. Note: use the stop() command to stop the capture. The wait() function will return an error.

trim_data_seconds: Optional[float] = None

Seconds of data at end of capture to keep. If unspecified, all data will be kept.

__init__(trim_data_seconds=None)

TimedCaptureMode

class saleae.automation.TimedCaptureMode

This class represents the capture settings when a simple timer mode is used. Note: when using this mode, the wait() function will wait until the specified duration is recorded and the capture has ended.

duration_seconds: float

Stop recording after X seconds

trim_data_seconds: Optional[float] = None

Seconds of data at end of capture to keep. If unspecified, all data will be kept. Note, this retains the latest X seconds. If specified, the final recording length will be approximately trim_data_seconds, retaining the latest data.

__init__(duration_seconds, trim_data_seconds=None)

DigitalTriggerCaptureMode

class saleae.automation.DigitalTriggerCaptureMode

This class represents the Digital Trigger Settings, when using start_capture with a digital trigger. Note: When using this mode, the wait() function will wait until the trigger is found and the post-trigger recording length is complete and the capture has ended.

trigger_type: DigitalTriggerType

Trigger type is RISING, FALLING, PULSE_HIGH, or PULSE_LOW, from the DigitalTriggerType enumeration.

trigger_channel_index: int

Trigger channel where the trigger type is detected.

min_pulse_width_seconds: Optional[float] = None

Minimum pulse width in seconds. Set to zero for no minimum pulse width. PULSE_HIGH or PULSE_LOW only

max_pulse_width_seconds: Optional[float] = None

Maximum pulse width in seconds. PULSE_HIGH or PULSE_LOW only

linked_channels: List[DigitalTriggerLinkedChannel]

Optional list of channels which must be high or low when the trigger channel encounters the trigger type.

trim_data_seconds: Optional[float] = None

Seconds of data at end of capture to keep. If unspecified, all data will be kept.

after_trigger_seconds: Optional[float] = None

Seconds of data to record after triggering

__init__(trigger_type, trigger_channel_index, min_pulse_width_seconds=None, max_pulse_width_seconds=None, linked_channels=<factory>, trim_data_seconds=None, after_trigger_seconds=None)

GlitchFilterEntry

class saleae.automation.GlitchFilterEntry

Represents the glitch filter specifications for a single digital channel

channel_index: int

Digital channel index

pulse_width_seconds: float

Minimum pulse width in seconds. The software will round this to the nearest number of samples.

__init__(channel_index, pulse_width_seconds)

DeviceDesc

class saleae.automation.DeviceDesc

DeviceDesc(device_id: str, device_type: saleae.automation.manager.DeviceType, is_simulation: bool)

device_id: str

Id of the device

device_type: DeviceType

Device type

is_simulation: bool

True if this is a simulation devivce

__init__(device_id, device_type, is_simulation)

DeviceType

class saleae.automation.DeviceType

An enumeration.

LOGIC = 1

Saleae Logic

LOGIC_4 = 2

Saleae Logic 4

LOGIC_8 = 3

Saleae Logic 8

LOGIC_16 = 4

Saleae Logic 16

LOGIC_PRO_8 = 5

Saleae Logic Pro 8

LOGIC_PRO_16 = 6

Saleae Logic Pro 16

Version

class saleae.automation.Version

Version(major: int, minor: int, patch: int)

__init__(major, minor, patch)

AppInfo

class saleae.automation.AppInfo

Logic 2 Application Information

api_version: Version

Version of saleae.proto that the server (Logic 2) is using

app_version: str

Logic 2 application version

app_pid: int

Logic 2 main application PID

__init__(api_version, app_version, app_pid)

RadixType

class saleae.automation.RadixType

An enumeration.

BINARY = 1
DECIMAL = 2
HEXADECIMAL = 3
ASCII = 4

DataTableExportConfiguration

class saleae.automation.DataTableExportConfiguration

DataTableExportConfiguration(analyzer: saleae.automation.capture.AnalyzerHandle, radix: saleae.automation.capture.RadixType)

analyzer: AnalyzerHandle

Analyzer to export

radix: RadixType

Radix type to use for format

__init__(analyzer, radix)

DataTableFilter

class saleae.automation.DataTableFilter

DataTableFilter(columns: List[str], query: str)

columns: List[str]

Columns to search

query: str

Query string

__init__(columns, query)