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
- 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
- get_app_info()
Get information about the connected Logic 2 instance.
- Return type
- 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
- Returns
Capture instance class. Be sure to call either wait() or stop() before trying to save, export, or close the capture.
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 Nonesettings (
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 Nonedigital_channels (
Optional[List[int]]) – list of digital channels to export, defaults to Noneanalog_downsample_ratio (
int) – optional analog downsample ratio, useful to help reduce export file sizes where extra analog resolution isn’t needed, defaults to 1iso8601_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 savedanalog_channels (
Optional[List[int]]) – list of analog channels to export, defaults to Nonedigital_channels (
Optional[List[int]]) – list of digital channels to export, defaults to Noneanalog_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)TimedCaptureModeThis will record until the specified duration has been captured. Use the wait() function to block until the capture is complete.DigitalTriggerCaptureModeThis 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)