Metadata-Version: 2.3
Name: vortran-lbl
Version: 1.0.0
Summary: A Python project to control a Vortran Stradus laser
Keywords: laser,vortran,stradus,control
Author: Arun Persaud, Sean Vo
Author-email: Arun Persaud <apersaud@lbl.gov>, Sean Vo <svo2@lbl.gov>
License: Copyright (c) 2026, The Regents of the University of California,
         through Lawrence Berkeley National Laboratory (subject to receipt of
         any required approvals from the U.S. Dept. of Energy). All rights
         reserved.
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are
         met:
         
         (1) Redistributions of source code must retain the above copyright
         notice, this list of conditions and the following disclaimer.
         
         (2) Redistributions in binary form must reproduce the above copyright
         notice, this list of conditions and the following disclaimer in the
         documentation and/or other materials provided with the distribution.
         
         (3) Neither the name of the University of California, Lawrence
         Berkeley National Laboratory, U.S. Dept. of Energy, nor the names of
         its contributors may be used to endorse or promote products derived
         from this software without specific prior written permission.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
         "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
         LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
         A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
         OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
         SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
         LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
         DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
         THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
         (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
         
         You are under no obligation whatsoever to provide any bug fixes,
         patches, or upgrades to the features, functionality or performance of
         the source code ("Enhancements") to anyone; however, if you choose to
         make your Enhancements available either publicly, or directly to
         Lawrence Berkeley National Laboratory, without imposing a separate
         written license agreement for such Enhancements, then you hereby grant
         the following license: a non-exclusive, royalty-free perpetual license
         to install, use, modify, prepare derivative works, incorporate into
         other computer software, distribute, and sublicense such enhancements
         or derivative works thereof, in binary and source code form.
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Dist: pyusb
Requires-Dist: libusb
Requires-Dist: pytest>=7.0 ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/FSIBT/Stradus
Project-URL: Repository, https://github.com/FSIBT/Stradus
Project-URL: Issues, https://github.com/FSIBT/Stradus/issues
Provides-Extra: test
Description-Content-Type: text/markdown

# Stradus SDK for Vortran lasers

Note: Python library for controlling Vortran Stradus lasers,
maintained by Lawrence Berkeley National Laboratory.

## Installation

If you don't have python already on your system you can install it using [uv](https://docs.astral.sh/uv/#installation).

Install the package from PyPI:

    uv pip install vortran-lbl

You can also first clone this git repository and then install the
package using uv directly from the cloned git repository:

    uv pip install -e .

## Use

The code below shows how to use the package

```python
import vortran_lbl as vortran

lasers = vortran.get_lasers()

laser = lasers[0]

is_open = laser.open_connection()

laser.enable_power_control_mode()
laser.power = 50

base_temp = laser.base_plate_temperature

laser.on()
time.sleep(1)
laser.off()
```

## Logging Configuration

The vortran_lbl library uses Python's standard logging module. By default, no log messages are shown. To see log output, configure logging in your application:

### Basic Logging Setup

```python
import logging
import vortran_lbl as vortran

# Show INFO level and above (device discovery, connections)
logging.basicConfig(level=logging.INFO)

# Or show DEBUG level for detailed USB communication
logging.basicConfig(level=logging.DEBUG)

lasers = vortran.get_lasers()  # Will now show log messages
```

### Advanced Logging Configuration

```python
import logging
import vortran_lbl as vortran

# Configure specific logger levels
logging.getLogger('vortran_lbl.usb').setLevel(logging.INFO)      # USB device discovery
logging.getLogger('vortran_lbl.laser').setLevel(logging.DEBUG)   # Laser operations
logging.getLogger('vortran_lbl.usb_connection').setLevel(logging.WARNING)  # Only errors

# Custom formatter
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
handler = logging.StreamHandler()
handler.setFormatter(formatter)

logger = logging.getLogger('vortran_lbl')
logger.addHandler(handler)
logger.setLevel(logging.DEBUG)
```

### Log Levels

- **DEBUG**: Detailed USB communication, retry attempts
- **INFO**: Device discovery, connection status
- **WARNING**: Parse errors, failed operations with retries
- **ERROR**: Connection failures, USB communication errors

## Configuration

### USB Library Configuration (Windows only)

The library automatically finds libusb in this order:

1. **Custom path** via `VORTRAN_LIBUSB_PATH` environment variable
2. **libusb package** installed via pip (`pip install libusb`)
3. **Default relative paths** in your project directory

#### Setting Custom Path

**Linux/macOS (bash):**
```bash
export VORTRAN_LIBUSB_PATH="/path/to/your/libusb-1.0.dll"
```

**Windows (PowerShell):**
```powershell
$env:VORTRAN_LIBUSB_PATH = "C:\path\to\your\libusb-1.0.dll"
```

**Windows (Command Prompt):**
```cmd
set VORTRAN_LIBUSB_PATH=C:\path\to\your\libusb-1.0.dll
```

#### Default Paths

If no custom path is set and libusb package is not installed, the library looks for:
- 32-bit: `USB/libusb/x86/libusb-1.0.dll`
- 64-bit: `USB/libusb/x64/libusb-1.0.dll`

#### Recommended Setup

For easiest setup, simply install the libusb package:
```bash
pip install libusb
```

## Development

### Running Tests

Install test dependencies:
```bash
uv pip install -e ".[test]"
```

Run tests:
```bash
pytest
```

Run tests with coverage:
```bash
pytest --cov=src/vortran_lbl --cov-report=term-missing
```

### Contributing

If you want to contribute, please install and use `pre-commit`:

```bash
uv pip install pre-commit
pre-commit install
```

