Venus Integration

The Venus device allows Orca to execute Hamilton Venus protocols (.hsl files) on Hamilton liquid handlers.

Use the Venus driver when you have existing Venus protocols you want to incorporate into Orca workflows.

Requirements

• Hamilton Venus software installed
• Windows operating system
• HxRun.exe executable (typically at C:\Program Files (x86)\HAMILTON\Bin\HxRun.exe)

Setup

from orca.devices.venus import Venus

ml_star = Venus("ml_star")

The simplest setup just requires a name. Venus uses sensible defaults for paths.

Full Configuration

from orca.devices.venus import Venus

venus = Venus(
    name="ml_star",
    init_protocol="init.hsl",             # Run on initialization
    picked_protocol="picked.hsl",          # Run after labware picked
    placed_protocol="placed.hsl",          # Run after labware placed
    prepare_pick_protocol="prep_pick.hsl", # Run before picking
    prepare_place_protocol="prep_place.hsl", # Run before placing
    exe_path=r"C:\Program Files (x86)\HAMILTON\Bin\HxRun.exe",
    methods_folder=r"C:\Program Files (x86)\HAMILTON\Methods",
    sim=False
)

Constructor Parameters

Parameter	Description	Default
name	Device name	Required
init_protocol	Protocol to run on initialization	None
picked_protocol	Protocol after labware picked from Venus	None
placed_protocol	Protocol after labware placed on Venus	None
prepare_pick_protocol	Protocol before picking labware	None
prepare_place_protocol	Protocol before placing labware	None
exe_path	Path to HxRun.exe	C:\Program Files (x86)\HAMILTON\Bin\HxRun.exe
methods_folder	Base folder for method paths	C:\Program Files (x86)\HAMILTON\Methods
sim	Enable simulation mode	False

Running Protocols

Use the RunProtocol action to execute Venus methods:

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

example_method = MethodTemplate(
    "example_method",
    actions=[
        RunProtocol(
            resource=ml_star,
            protocol_filepath="Cheshire Labs\\VariableAccessTesting.hsl",
            parameters={
                "strParam": "string value",
                "intParam": 123,
                "fltParam": 1.003
            },
            inputs=[sample_plate],
            outputs=[sample_plate]
        )
    ]
)

Protocol Path Resolution

The protocol_filepath is resolved relative to methods_folder:

• If protocol_filepath is "Cheshire Labs\\MyProtocol.hsl"
• And methods_folder is "C:\Program Files (x86)\HAMILTON\Methods"
• Venus looks for "C:\Program Files (x86)\HAMILTON\Methods\Cheshire Labs\MyProtocol.hsl"

Passing Parameters

Parameters are passed to Venus protocols via a JSON file at %TEMP%\CheshireLabs\Orca\actionConfig.json. Your Venus protocol can read this file to access the parameters.

Supported parameter types:

• Strings: "strParam": "value"
• Integers: "intParam": 123
• Floats: "fltParam": 1.003

Multi-Plate Operations

For operations involving multiple plates (transfers, cherrypicking), list all plates in inputs and outputs:

transfer_method = MethodTemplate(
    "transfer_method",
    actions=[
        RunProtocol(
            resource=ml_star,
            protocol_filepath="Cheshire Labs\\SimplePlateStamp.hsl",
            parameters={
                "numOfPlates": 1,
                "waterVol": 30,
                "dyeVol": 10,
                "wait": 1,
                "tipEjectPos": 2,
                "clld": 1
            },
            inputs=[source_plate, dest_plate],
            outputs=[source_plate, dest_plate]
        )
    ]
)

Pick/Place Coordination

Venus coordinates labware transfers with transporters through hook protocols:

1. Prepare for place - Runs prepare_place_protocol before transporter places labware
2. Notify placed - Runs placed_protocol after labware is placed
3. Prepare for pick - Runs prepare_pick_protocol before transporter picks labware
4. Notify picked - Runs picked_protocol after labware is picked

Use these to manage plate grippers, lids, or deck state during transfers.

Venus Workflow Example

import asyncio
from orca.devices.venus import Venus
from orca.driver_management.drivers.human_transfer import HumanTransfer
from orca.sdk.labware import PlateTemplate
from orca.sdk.system import ResourceRegistry, SystemMap, SdkToSystemBuilder, WorkflowExecutor
from orca.sdk.workflow import MethodTemplate, WorkflowTemplate, ThreadTemplate, SharedMethodTemplate
from orca.sdk.events import EventBus
from orca.sdk.actions import RunProtocol
from pylabrobot.resources.thermo_fisher.plates import Thermo_Nunc_96_well_plate_1300uL_Rb

# Labware
source_plate = PlateTemplate("source_plate", Thermo_Nunc_96_well_plate_1300uL_Rb, None)
dest_plate = PlateTemplate("dest_plate", Thermo_Nunc_96_well_plate_1300uL_Rb, None)

# Devices
ml_star = Venus("ml_star")
human_transfer = HumanTransfer("human_transfer", "teachpoints/teachpoints.json")

# Resources
resources = ResourceRegistry()
resources.add_resources([ml_star, human_transfer])

# System map
system_map = SystemMap(resources)
system_map.assign_resources({"ml_star_position_1": ml_star})

# Methods
transfer_method = MethodTemplate(
    "transfer",
    actions=[
        RunProtocol(
            ml_star,
            "Cheshire Labs\\SimplePlateStamp.hsl",
            {"waterVol": 30, "dyeVol": 10},
            [source_plate, dest_plate],
            [source_plate, dest_plate]
        )
    ]
)

# Threads
source_thread = ThreadTemplate(
    source_plate,
    system_map.get_location("plate_pad_1"),
    system_map.get_location("plate_pad_2"),
    [transfer_method]
)

dest_thread = ThreadTemplate(
    dest_plate,
    system_map.get_location("plate_pad_3"),
    system_map.get_location("plate_pad_4"),
    [SharedMethodTemplate()]
)

# Workflow
workflow = WorkflowTemplate("venus_workflow")
workflow.add_thread(source_thread, is_start=True)
workflow.add_thread(dest_thread)
workflow.set_spawn_point(dest_thread, source_thread, transfer_method, join=True)

# Build and run
builder = SdkToSystemBuilder(
    "Venus Example", "Venus workflow with multi-plate transfer",
    [source_plate, dest_plate], resources, system_map,
    [transfer_method], [workflow], EventBus()
)
system = builder.get_system()

async def run():
    await system.initialize_all()
    executor = WorkflowExecutor(workflow, system)
    await executor.start(sim=False)

asyncio.run(run())

Next Steps

• Actions - All action types including RunProtocol
• Workflows - Spawn points and join for multi-plate operations
• PyLabRobot - Alternative Hamilton control via PLR