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

Attributes

Name	Type	Description
`manager`
`capture_id`

Methods

__init__(manager: saleae.automation.Manager, capture_id: int)

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

add_analyzer(name: str, *, label: Optional[str] = None, settings: Optional[Dict[str, Union[str, int, float, bool]]] = None) -> AnalyzerHandle

Add an analyzer to the capture

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

name: The name of the Analyzer, as shown in the Logic 2 application add analyzer list. This must match exactly.
label: The user editable display string for the analyzer. This will be shown in the analyzer data table export, defaults to None
settings: All settings for the analyzer. The keys and values here must exactly match the Analyzer settings as shown in the UI, defaults to None
Returns: Returns an AnalyzerHandle

add_high_level_analyzer(extension_directory: str, name: str, *, input_analyzer: AnalyzerHandle, settings: Optional[Dict[str, Union[str, float]]] = None, label: Optional[str] = None) -> AnalyzerHandle

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.

extension_directory: The directory of the extension that the HLA is in.
name: The name of the HLA, as specifiied in the extension.json of the extension.
input_analyzer: Handle to analyzer (added via add_analyzer) to use as input to this HLA.
settings: All settings for the analyzer. The keys and values here must match the HLA settings as shown in the HLA class.
label: The user editable display string for the high level analyzer. This will be shown in the analyzer data table export.
Returns: Returns an AnalyzerHandle

remove_analyzer(analyzer: AnalyzerHandle)

Removes an analyzer from the capture.

analyzer: AnalyzerHandle returned by add_analyzer()

remove_high_level_analyzer(high_level_analyzer: AnalyzerHandle)

Removes a high level analyzer from the capture.

high_level_analyzer: AnalyzerHandle returned by add_analyzer()

save_capture(filepath: str)

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

filepath: path to the .sal file. Can be absolute, or relative to the Logic 2 software current working directory.

legacy_export_analyzer(filepath: str, analyzer: AnalyzerHandle, radix: RadixType)

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.

filepath: file name and path to export to. Should include the file name and extension, typically .csv or .txt.
analyzer: AnalyzerHandle returned from add_analyzer()
radix: Display Radix, from the RadixType enumeration.

export_data_table(filepath: str, analyzers: List[Union[AnalyzerHandle, DataTableExportConfiguration]], *, columns: Optional[List[str]] = None, filter: Optional[DataTableFilter] = None, iso8601_timestamp: bool = 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.

filepath: The specified output file, including extension, .csv.
analyzers: A list of AnalyzerHandles that should be included in the export, returned from add_analyzer()
columns: Columns to include in export.
filter: Filter to apply to the exported data.
iso8601_timestamp: Use this to output wall clock timestamps, instead of capture relative timestamps. Defaults to False.

export_raw_data_csv(directory: str, *, analog_channels: Optional[List[int]] = None, digital_channels: Optional[List[int]] = None, analog_downsample_ratio: int = 1, iso8601_timestamp: bool = 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.

directory: directory path (not including a filename) to where analog.csv and/or digital.csv will be saved.
analog_channels: list of analog channels to export, defaults to None
digital_channels: list of digital channels to export, defaults to None
analog_downsample_ratio: optional analog downsample ratio, useful to help reduce export file sizes where extra analog resolution isn't needed, defaults to 1
iso8601_timestamp: Use this to output wall clock timestamps, instead of capture relative timestamps. Defaults to False.

export_raw_data_binary(directory: str, *, analog_channels: Optional[List[int]] = None, digital_channels: Optional[List[int]] = None, analog_downsample_ratio: int = 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.

directory: directory path (not including a filename) to where .bin files will be saved
analog_channels: list of analog channels to export, defaults to None
digital_channels: list of digital channels to export, defaults to None
analog_downsample_ratio: 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.

AI/LLM users: see llms-automation.txt for machine-readable documentation.