lightbox-sdk 1.0.1

Python SDK to control Lightbox Pro over USB serial

Lightbox SDK

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

Install

pip install lightbox-sdk

Or install from source in editable mode:

cd python
pip install -e .

Quick start

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:

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:

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:

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

Run an experiment

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

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

    print("Done!")

Error handling

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