Saleae Logic 2 Automation API

Common errors

• ConnectionRefusedError: [WinError 10061] No connection could be made because the target machine actively refused it

  cause The Logic 2 application is not running, or its Automation API is not enabled, preventing the Python library from connecting.
  fix Launch the Saleae Logic 2 application and ensure the 'Automation API' is enabled under `Options -> Automation API`.

• saleae.automation.errors.LalError: The specified device ID could not be found: 'YOUR_DEVICE_ID'

  cause The `device_id` provided in `automation.DeviceConfiguration` does not match any currently connected and recognized Saleae device.
  fix Verify the correct `device_id` from Logic 2's `Options -> Automation API` section. Ensure the device is powered on and properly connected to the computer. You can also use `manager.get_connected_devices()` to list available IDs.

• saleae.automation.errors.LalError: An error occurred in the logic application: Failed to configure device F40105001221. Reason: Digital channel 8 is out of bounds.

  cause The `DeviceConfiguration` parameters (e.g., `digital_channels`, `analog_channels`) specify channels that do not exist or are not available on the connected Saleae device.
  fix Adjust the `digital_channels` or `analog_channels` lists in `automation.DeviceConfiguration` to match the actual capabilities of your Saleae device. Refer to your device's specifications or inspect its configuration in the Logic 2 GUI.

Warnings

• breaking The `logic2-automation` library underwent significant API changes between the v0.x series and the v1.x series. Code written for v0.x is not compatible with v1.x and requires substantial refactoring, particularly around the introduction of the `automation.Manager` context manager for session management.
  Fix: Rewrite automation scripts to use the v1.x API, specifically the `with automation.Manager() as manager:` pattern and new device/capture configuration objects. Refer to the official GitHub README for current examples.
• gotcha The Saleae Logic 2 application must be running and its Automation API feature enabled in the preferences for the Python library to establish a connection. If Logic 2 is not running or the API is disabled, connection attempts will fail.
  Fix: Launch the Logic 2 application and navigate to `Options -> Automation API` to ensure the API is enabled. Restart Logic 2 if changes were made.
• gotcha Device IDs and channel configurations (e.g., digital_channels, analog_channels, channel_grouping) must precisely match the physical Saleae device connected and its capabilities. Mismatches will result in configuration errors.
  Fix: Verify the `device_id` by checking `Options -> Automation API` in Logic 2. Review the device's capabilities and current configuration in Logic 2 to ensure `DeviceConfiguration` parameters (like channel lists) are valid for your specific hardware.

Install

• pip install logic2-automation Install latest version

Imports

• automation

  from saleae import automation

Quickstart

This quickstart connects to the Saleae Logic 2 application, configures a specified device, starts a one-second capture, and then exports the raw digital data. It demonstrates the use of the `Manager` context manager for connection management and includes error handling for common issues.

import os
from saleae import automation
import time

# IMPORTANT: Ensure the Logic 2 application is running and
# the Automation API is enabled in its preferences.
# You can find your device ID in Logic 2 under Options -> Automation API.
# Alternatively, use manager.get_connected_devices() to list available devices.
DEVICE_ID = os.environ.get('SALEAE_DEVICE_ID', 'F40105001221') # Replace with your device ID

try:
    with automation.Manager() as manager:
        print(f"Connected to Logic 2, API version: {manager.get_api_version()}")

        # Add a connected device. Configuration must match device capabilities.
        manager.add_connected_device(
            automation.DeviceConfiguration(
                device_id=DEVICE_ID,
                channel_grouping=automation.ChannelGrouping.GROUP_BY_CABLE,
                digital_channels=[0, 1],
                analog_channels=[0],
            )
        )
        print(f"Device {DEVICE_ID} configured.")

        # Start a 1-second capture at 1MS/s
        capture = manager.start_capture(
            device_id=DEVICE_ID,
            settings=automation.CaptureSettings(
                sample_rate=1_000_000,
                duration_seconds=1.0
            )
        )
        print(f"Capture started. Waiting for completion... Session file: {capture.filepath}")

        # Export raw digital data to a directory
        output_dir = f"raw_capture_digital_{int(time.time())}"
        os.makedirs(output_dir, exist_ok=True)
        capture.export_raw_data_to_directory(
            directory_path=output_dir,
            digital_channels=[0, 1]
        )
        print(f"Raw digital data exported to: {output_dir}")

    print("Automation complete and session manager closed.")

except automation.LalError as e:
    print(f"Logic 2 Automation API Error: {e}")
    print("Please verify Logic 2 is running, API is enabled, and device/channel configs are correct.")
except ConnectionRefusedError:
    print("Error: Connection refused. Is the Logic 2 application running and the Automation API enabled?")
except Exception as e:
    print(f"An unexpected error occurred: {e}")