daisylab

Python library for controlling Daisy laboratory instruments over USB serial.

daisylab discovers Daisy hardware on your serial ports, validates the connected instruments against what your code expects, and gives you a clean, per-instrument API for pumps, valves, and motion stages — with background threads handling the serial protocol for you.

Installation

pip install daisylab

Requires Python 3.9+ and pyserial 3.5+.

Quick start

import daisylab

with daisylab.connect() as lab:
    print("Found ports:", lab.ports)
    print("Instrument types:", lab.instruments_list)

    # Declare the instruments on a port, in physical order, by type code.
    group = daisylab.InstrumentGroup([10, 2])   # Peri T + Rotary Valve
    lab.add_group(group)

    pump  = group.inst[0]   # DaisyPeriT
    valve = group.inst[1]   # DaisyRotaryValve

    valve.home()
    pump.run(speed=50.0, volume=10.0, wait=True)   # 50 ml/min, 10 ml
    valve.select_port(3, wait=True)

connect() returns a DaisyInterface (usable as a context manager). Each InstrumentGroup is bound to a serial port in the order you call add_group().

Supported instruments

Instruments are declared by integer type code (the value the firmware reports during roll-call) or by a case-insensitive name substring such as "Peri T" or "gantry".

Codes are assigned by the firmware Instrument ID registry and are never renumbered; a retired model leaves a gap. The registry currently reaches 17 — 15 (Peri T 3-roller), 16 (Piston 100 µL) and 17 (12-port rotary valve, 0.096″ orifice) are defined in firmware but have no class in this library yet, so such a unit enumerates as an unknown instrument. The ID is a uint16_t; 0 and 65535 (unconfigured / safe mode) are reserved and never assigned.

Peristaltic pump speed limits

Peri pumps enforce a per-model maximum motor speed. run(speed, volume) converts the requested flow (ml/min) to RPM using the current calibration and raises ValueError before sending anything if it would exceed the cap:

The cap is calibration-aware: recalibrating the tubing shifts the ml/min ceiling but the motor is always held to its rated RPM.

Recalibrate after upgrading. The rev/s → firmware-speed constant was corrected from an empirical 1.45 to the datasheet value 1.398101 (2**24 / 12 MHz). Every peristaltic previously ran about 3.7% fast, so a calibration measured on an older release now delivers about 3.7% low. Re-run calibrate() (or calibrate_by_tubing()) on each pump.

Piston pump speed limits

The cap is derived from the syringe at the head's 54 strokes/min rating:

The 5 ml build is the exception to the rule, which would give 270,000. Above roughly 6.85 rev/s its dispense stroke stalls the motor at nameplate current, and firmware rejects anything faster — so 200,000 is the achievable rating rather than the nameplate one. run() raises DaisyValueError if exceeded.

Examples

Standalone, runnable scripts live in daisylab/examples/:

• daisy_controller.py — universal interactive controller for any instrument
• z_stage_controller.py — interactive Z-stage controller
• z_stage_peri_t_sequence.py — automated dispense sequence (home → lower → pump → raise)

Each supports a --demo flag that runs against simulated hardware (no serial I/O required):

python daisylab/examples/daisy_controller.py --demo

A sample Jupyter notebook is also included in the package at daisylab/jupyter/sample.ipynb. After installing, you can find it at <site-packages>/daisylab/jupyter/sample.ipynb.

Exceptions

Every error the library raises derives from DaisyError, so a single except daisylab.DaisyError is a complete catch-all for any instrument:

• DaisyTimeoutError — no OK / a BAD reply within the timeout
• DaisyConnectionError — no devices found / connection failure
• DaisyInstrumentMismatchError — software list ≠ hardware roll-call
• DaisyValueError — invalid argument or value (e.g. speed above a pump's MAX_RPM, unknown type code, malformed device response). Also subclasses the built-in ValueError, so existing except ValueError handlers keep working.

Stopping safely

stop_all() halts every instrument across all groups (best-effort — one instrument's failure won't block the others); ports stay open so you can recover. safe_session() wraps a command sequence and stops everything if any exception propagates:

with lab.safe_session():
    pump.run(speed=50, volume=10, wait=True)
    gantry.run(100, 150, wait=True)   # if this raises, the pump is stopped
# the original exception is re-raised after the stop

lab.stop_all()          # or halt everything manually (alias: lab.emergency_stop())
group.stop_all()        # or just one group

Development

git clone https://github.com/ScalablesLab/daisy-python-library
cd daisy-python-library
pip install -e ".[test]"
pytest

The test suite is hardware-free — tests/fakes.py provides a synchronous FakeSerialManager that synthesises device replies, so the real drivers run end to end without any instruments attached.

License

Apache License 2.0 — see LICENSE. Copyright Scalables, LLC.