Skip to main content

Quick Start

This guide walks through running your first Orca workflow.

Run the Example​

Clone the repository and run the PyLabRobot example:

git clone https://github.com/Cheshire-Labs/orca.git
cd orca
pip install -e .
python ./examples/pylabrobot_example/pylabrobot_example.py

Understanding the Example​

Let's walk through what the example does.

1. Define Labware​

from orca.sdk.labware import PlateTemplate
from pylabrobot.resources.thermo_fisher.plates import Thermo_Nunc_96_well_plate_1300uL_Rb

sample_plate = PlateTemplate("sample_plate", Thermo_Nunc_96_well_plate_1300uL_Rb, None)

PlateTemplate defines a plate type. The second argument is a PyLabRobot plate definition.

2. Create Devices​

from orca.devices.sealer import Sealer
from orca.devices.devices import LiquidHandler
from orca.resource_models.transporter import Transporter
from cheshire_drivers import SimLiquidHandlerDriver, SimTransporterDriver
from pylabrobot.sealing.a4s_backend import A4SBackend

# Real sealer driver (would connect to hardware)
a4s_sealer_driver = A4SBackend(port="/dev/tty.usbserial-0001", timeout=10)
sealer = Sealer("a4s_sealer", a4s_sealer_driver)

# Simulated devices for testing
mock_device = LiquidHandler("liquid_handler", SimLiquidHandlerDriver("ml_star"))
robotic_arm = Transporter("robotic_arm", SimTransporterDriver("robotic_arm"),
                          "examples/pylabrobot_example/teachpoints/teachpoints.json")

Devices wrap drivers. You can use real PyLabRobot backends or simulated drivers.

3. Register Resources​

from orca.sdk.system import ResourceRegistry

resources = ResourceRegistry()
resources.add_resources([sealer, robotic_arm, mock_device])

The ResourceRegistry tracks all devices in your system.

4. Define Actions and Methods​

from orca.sdk.actions import Seal
from orca.sdk.workflow import MethodTemplate

seal_method = MethodTemplate(
    name="Test Method",
    actions=[
        Seal(
            resource=sealer,
            temperature=100,
            duration=60,
            inputs=[sample_plate],
            outputs=[sample_plate]
        ),
    ]
)

Actions are operations on labware. Methods group actions into sequences.

5. Create System Map​

from orca.sdk.system import SystemMap

map = SystemMap(resources)
map.assign_resources({
    "sealer": sealer,
    "mock_device": mock_device,
})

The SystemMap defines where devices are located for transporter routing.

6. Define Thread and Workflow​

from orca.sdk.workflow import ThreadTemplate, WorkflowTemplate

sample_plate_thread = ThreadTemplate(
    sample_plate,
    map.get_location("plate_pad_1"),  # Start location
    map.get_location("plate_pad_2"),  # End location
    [dispense_method, seal_method]    # Methods to execute
)

example_workflow = WorkflowTemplate("example_workflow")
example_workflow.add_thread(sample_plate_thread, True)  # True = starting thread

A thread defines the journey of one piece of labware through methods.

7. Build and Run​

from orca.sdk.system import SdkToSystemBuilder, WorkflowExecutor
from orca.sdk.events import EventBus

event_bus = EventBus()
builder = SdkToSystemBuilder(
    "pylabrobot_example",
    "An example workflow using PylabRobot",
    labwares,
    resources,
    map,
    [seal_method],
    [example_workflow],
    event_bus,
)

system = builder.get_system()

async def run(sim: bool):
    if not sim:
        await system.initialize_all()
    executor = WorkflowExecutor(example_workflow, system)
    await executor.start(sim)

asyncio.run(run(True))  # Run in simulation mode

The SdkToSystemBuilder creates a runnable system. WorkflowExecutor runs the workflow.

What Happens During Execution​

  1. The workflow starts the sample plate thread
  2. For each method in the thread:
    • The transporter picks the plate from its current location
    • The transporter places the plate at the method's device
    • All actions in the method execute
  3. After all methods complete, the transporter moves the plate to its end location

More Examples​

For complete runnable examples, see the examples folder on GitHub:

  • simple_venus_example/ - Venus liquid handler with manual plate transfers
  • precise_flex_example/ - Robotic arm with simulated devices

Next Steps​

  • Architecture - Understand the execution model in depth
  • Devices - Configure your actual hardware
  • Actions - See all available actions