Devices

Orca Framework ships with classes for the common device types in a lab. Each one is a thin wrapper around a driver — the device class is what your workflow talks to; the driver is what talks to the hardware (or simulator).

Built-in device types

Class	Use for	Import
`Shaker`	Plate shakers and incubators	`orca.devices.shaker`
`Sealer`	Heat sealers and de-sealers	`orca.devices.sealer`
`Centrifuge`	Centrifuges (single or multi-plate)	`orca.devices.centrifuge`
`Thermocycler`	Thermocyclers (PCR block + lid)	`orca.devices.thermocycler`
`LiquidHandler`	Deck-modeled liquid handlers (Hamilton STAR, etc.)	`orca.devices.devices`
`LiquidHandlerProtocol`	Deckless / protocol-driven handlers (Bravo, VWorks, remote)	`orca.devices.devices`
`Reader`	Plate readers, imagers	`orca.devices.devices`
`Storage`	Plate stackers, hotels	`orca.devices.devices`
`Waste`	Waste / discard locations	`orca.devices.devices`
`PlateWasher`	Plate washers (BioTek, etc.)	`orca.devices.devices`
`Delidder`	Lid removal stations	`orca.devices.devices`

Vendor-specific concrete classes also exist: Venus (Hamilton Venus) and A4SSealer, both importable from orca.sdk.devices.

HumanTransfer is not a device. It is a Transporter subclass for manual moves with operator prompts; see Transporters.

Import note: orca.sdk.devices re-exports Device, ResourcePool, Transporter, Shaker, Sealer, Centrifuge, Thermocycler, Venus, A4SSealer, and HumanTransfer. The handler, reader, storage, waste, washer, and delidder classes come from orca.devices.devices (and Centrifuge from orca.devices.centrifuge, Thermocycler from orca.devices.thermocycler). Import those directly, as the real examples do.

Creating a device

Most devices take just a name:

shaker = Shaker("shaker")
sealer = Sealer("sealer")

The active device factory (bound at topology-build time) supplies the driver — sim or real, depending on which factory is in scope.

LiquidHandler is the exception: it models the deck (Hamilton carriers or Opentrons slot decks), so it takes a deck layout. You don't declare handoff points; handoff is derived from the topology. Any deck site the external transporter teaches is a transit entry, and the handler's internal gripper relays labware between deck sites automatically. deck_layout names a layout in the deck_layout_store (required for device-sim and live runs, optional for pure simulation):

liquid_handler = LiquidHandler(
    "mlstar_1",
    deck_layout_store=stores.deck_layouts("mlstar_1", seed={"default": deck_config}),
    deck_layout="default",
)

For a handler whose deck Orca does not model (a Bravo running VWorks, or a remote/gateway handler), use LiquidHandlerProtocol(name) instead. It has no deck sites and no internal-gripper relay; the bound driver decides which verbs (well-level vs run_protocol) work.

Device interfaces

Each device class implements an interface (IShaker, ISealer, ICentrifuge, IThermocycler, ILiquidHandler, IReader) that defines the methods your workflow can call. Some method signatures: IShaker.shake(duration, speed), ICentrifuge.centrifuge(g, duration), ISealer.seal(temperature, duration). Use the interface as a typed handle in actions:

@orca.action(device=liquid_handler, inputs=[plate, tips])
async def aspirate_step(ctx: ActionContext):
    lh = ctx.device(ILiquidHandler)   # typed handle
    await lh.pick_up_tips([...])
    await lh.aspirate([...], [...])

TODO: per-device method reference. For now, each interface is documented in the cheshire-drivers source.

Sim vs real drivers

Devices have no hardware-specific code in them. Each device class calls resolve_drivers(kind, name, default_sim) in its constructor, which consults the device factory context in scope to pick the driver: the bound factory's real driver, or the default sim driver when none is bound. Swapping the factory context swaps every device's driver without touching the topology or the device classes.

TODO: full factory-context walkthrough covering binding a real-hardware factory, the pure-sim default, and run-mode selection.

Adding a new device type

If your lab has a device class Orca doesn't know about yet, you'll need:

A driver interface in cheshire-drivers (e.g., IMyDevice).
A driver implementation (real and sim).
An Orca device class wrapping it.

TODO: full walkthrough of adding a new device + driver.

Where to go next

Transporters — moving labware between devices.
Actions — calling device methods from a workflow.

Built-in device types​

Creating a device​

Device interfaces​

Sim vs real drivers​

Adding a new device type​

Where to go next​