{"id":9904,"library":"logic2-automation","title":"Saleae Logic 2 Automation API","description":"The `logic2-automation` library provides a Pythonic interface for controlling the Saleae Logic 2 application via its Automation API. It enables users to programmatically connect to Saleae devices, configure captures, start/stop data acquisition, add analyzers, and export data. The current version is 1.0.11, and releases are generally made on an as-needed basis to support new features or fix bugs.","status":"active","version":"1.0.11","language":"en","source_language":"en","source_url":"https://github.com/saleae/logic2-automation","tags":["hardware","test","logic-analyzer","saleae","automation","data-acquisition"],"install":[{"cmd":"pip install logic2-automation","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for communication with the Logic 2 Automation API.","package":"websocket-client"}],"imports":[{"symbol":"automation","correct":"from saleae import automation"}],"quickstart":{"code":"import os\nfrom saleae import automation\nimport time\n\n# IMPORTANT: Ensure the Logic 2 application is running and\n# the Automation API is enabled in its preferences.\n# You can find your device ID in Logic 2 under Options -> Automation API.\n# Alternatively, use manager.get_connected_devices() to list available devices.\nDEVICE_ID = os.environ.get('SALEAE_DEVICE_ID', 'F40105001221') # Replace with your device ID\n\ntry:\n    with automation.Manager() as manager:\n        print(f\"Connected to Logic 2, API version: {manager.get_api_version()}\")\n\n        # Add a connected device. Configuration must match device capabilities.\n        manager.add_connected_device(\n            automation.DeviceConfiguration(\n                device_id=DEVICE_ID,\n                channel_grouping=automation.ChannelGrouping.GROUP_BY_CABLE,\n                digital_channels=[0, 1],\n                analog_channels=[0],\n            )\n        )\n        print(f\"Device {DEVICE_ID} configured.\")\n\n        # Start a 1-second capture at 1MS/s\n        capture = manager.start_capture(\n            device_id=DEVICE_ID,\n            settings=automation.CaptureSettings(\n                sample_rate=1_000_000,\n                duration_seconds=1.0\n            )\n        )\n        print(f\"Capture started. Waiting for completion... Session file: {capture.filepath}\")\n\n        # Export raw digital data to a directory\n        output_dir = f\"raw_capture_digital_{int(time.time())}\"\n        os.makedirs(output_dir, exist_ok=True)\n        capture.export_raw_data_to_directory(\n            directory_path=output_dir,\n            digital_channels=[0, 1]\n        )\n        print(f\"Raw digital data exported to: {output_dir}\")\n\n    print(\"Automation complete and session manager closed.\")\n\nexcept automation.LalError as e:\n    print(f\"Logic 2 Automation API Error: {e}\")\n    print(\"Please verify Logic 2 is running, API is enabled, and device/channel configs are correct.\")\nexcept ConnectionRefusedError:\n    print(\"Error: Connection refused. Is the Logic 2 application running and the Automation API enabled?\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Launch the Saleae Logic 2 application and ensure the 'Automation API' is enabled under `Options -> Automation API`.","cause":"The Logic 2 application is not running, or its Automation API is not enabled, preventing the Python library from connecting.","error":"ConnectionRefusedError: [WinError 10061] No connection could be made because the target machine actively refused it"},{"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.","cause":"The `device_id` provided in `automation.DeviceConfiguration` does not match any currently connected and recognized Saleae device.","error":"saleae.automation.errors.LalError: The specified device ID could not be found: 'YOUR_DEVICE_ID'"},{"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.","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.","error":"saleae.automation.errors.LalError: An error occurred in the logic application: Failed to configure device F40105001221. Reason: Digital channel 8 is out of bounds."}]}