Metadata-Version: 2.4
Name: lightbox-sdk
Version: 1.0.1
Summary: Python SDK to control Lightbox Pro over USB serial
Author: GormleyLab
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pyserial>=3.5

# Lightbox SDK

> **Version 1.0.1** — Python SDK for controlling the Lightbox Pro over USB serial.

## Install

```bash
pip install lightbox-sdk
```

Or install from source in editable mode:

```bash
cd python
pip install -e .
```

## Quick start

```python
from lightbox_sdk import Lightbox

with Lightbox() as lb:                    # auto-detect port
    lb.ping()                              # verify connection
    lb.set_pixel(0, 255, 0, 0)            # LED 0 → red
    lb.set_leds([(0, 0, 0, 80)] * 96)    # all LEDs → dim white
    lb.off()                               # all off
```

Explicit port:

```python
with Lightbox("COM4") as lb:
    print(lb.version())       # "1.0.0"
    print(lb.status())        # "idle"
```

## Well positions

LEDs are in a 96-well plate grid (rows A–H, columns 1–12) matching the ANSI microplate standard layout. Use `well()` to address by name:

```python
from lightbox_sdk import Lightbox, well, well_row, well_column

with Lightbox() as lb:
    lb.set_pixel(well("A1"), 255, 0, 0)       # well A1 → red
    lb.set_pixel(well("D6"), 0, 0, 200)       # well D6 → blue

    for idx in well_row("A"):                  # all 12 wells in row A
        lb.set_pixel(idx, 0, 80, 0)

    for idx in well_column(6):                 # all 8 wells in column 6
        lb.set_pixel(idx, 80, 0, 80)
```

For numeric loops (e.g. animations), `xy(col, row)` is also available:

```python
from lightbox_sdk import xy
idx = xy(5, 3)   # column 5 (="6"), row 3 (="D") → same as well("D6")
```

## Run an experiment

```python
with Lightbox() as lb:
    lb.run_experiment_json("experiment.json")

    while lb.status() == "running":
        time.sleep(0.5)

    print("Done!")
```

## Error handling

```python
from lightbox_sdk import Lightbox, LightboxError, LightboxTimeout, LightboxConnectionError

try:
    with Lightbox("COM4") as lb:
        lb.ping()
except LightboxConnectionError:
    print("Cannot connect")
except LightboxTimeout:
    print("Device not responding")
except LightboxError as e:
    print(f"Device error: {e}")
```

## Package layout

```
lightbox_sdk/
├── __init__.py           # Public exports, version
├── client.py             # Lightbox class, connection, commands
└── constants.py          # LED_COUNT, well(), xy(), helpers
```
