# Installation

This guide will help you install the Saleae MSO API.

## Requirements

- Python 3.11 or higher
- Logic 2.4.20 or newer installed (for the Logic MSO drivers, or udev rules)
- A supported operating system, either:
    - Windows 10, or 11 (x64), or
    - Ubuntu 20.04+ (64-bit)
    - Mac OSX 10.14 (Mohave) or newer
- Enough disk space for your capture files

The remaining package requirement will be installed automatically by `uv` (or `pip`).

We recommend installing a recent version of Logic2 on your system and checking that it can connect with and get
data from your MSO before installing this library. We hope there will be no issues installing this library and
getting your Saleae products operating automatically, but if there are issues then that step will make debugging
them a much smoother and more targeted process.

## Installation Methods

### Saleae Python Package Index

This package is distributed via a private python package index hosted by Saleae. You can install it with `uv` (recommended, see the [uv installation instructions](https://docs.astral.sh/uv/getting-started/installation/) for information), `pip`, `poetry` or any other python package manager. Saleae recommends using both `uv` and a virtual environment. You will need to provide the URL for our index when you install:

```bash
uv add saleae-mso-api --index https://downloads.saleae.com/pypi --index-strategy unsafe-best-match
# or
pip install saleae-mso-api --extra-index-url https://downloads.saleae.com/pypi/
```

### Linux udev Rules

If you have not installed Logic2 before on your Linux system, you will need to install the `udev` rules into the proper place. After installing the package with the above instructions, run:

```bash
# For standard use (will prompt for password when it calls 'sudo')
uv run python -m saleae.mso_api.utils.install_udev

# On pip with virtualenv
source .venv/bin/activate
python -m saleae.mso_api.utils.install_udev
```

This will put the rules into `/etc/udev/rules.d` and reload them with `udevadm`. You will see a new rules file called `99-SaleaeLogic.rules` that contains the following:

```
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="0925", ATTR{idProduct}=="3881", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="21a9", ATTR{idProduct}=="1001", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="21a9", ATTR{idProduct}=="1003", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="21a9", ATTR{idProduct}=="1004", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="21a9", ATTR{idProduct}=="1005", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="21a9", ATTR{idProduct}=="1006", MODE="0666"
SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="21a9", ATTR{idProduct}=="1007", MODE="0666"
```

**For development:** If you need the automation instrumentation udev rules as well, use:

```bash
uv run python -m saleae.mso_api.utils.install_udev --all
```

## Development Setup

If you're planning to contribute to the project, you'll need to install the development dependencies:

```bash
uv sync --all-extras
```

This will install additional packages like:
- ruff (for linting)
- pytest (for testing)
- jupyter-book (for documentation)

## Troubleshooting

### Common Issues

- **ImportError: No module named 'saleae'**: Make sure you've installed the package correctly.
- **ImportError: cannot import name 'X' from 'saleae'**: You might be using an older version of the package. Try updating.

### Getting Help

If you encounter any issues during installation, please send an email to support@saleae.com