Quick Start

This guide walks through running your first Orca workflow.

Run the Example

Clone the repository and run the PyLabRobot example:

git clone --branch v1.0.0 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 path 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 at v1.0.0:

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

Next Steps

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