UniteLabs
Reference

Agilent BioTek Synergy H1

Connect an Agilent BioTek Synergy H1 directly over serial, without Gen5, check that it answers, and move the plate carrier from Python.

This page gets you from an unboxed Synergy H1 to a first command from Python. Agilent's manual covers optics, filters, plate types, and safety.

The Agilent Synergy H1 connector talks to the reader directly over its serial interface, and you build and run assays through it. If you want to use the reader through the Gen5 software, use the Gen5 connector instead.

What you need

ItemDetail
InstrumentA Synergy H1, powered on, with the carrier free to move
CableThe reader's USB cable to the GroundControl machine. The reader shows up as a serial port
ConnectorAgilent Synergy H1 from the UniteLabs registry
Vendor softwareNone. Close Gen5 if it's installed, so it doesn't hold the port
MachineWindows, Linux, or macOS running GroundControl
AccessA tenant and the SDK installed. See Setup

Install and configure the connector

  1. In GroundControl, add a connector and pick Agilent Synergy H1 (how to add a connector).
  2. Find the reader's serial port. List the ports with the USB cable unplugged, then plugged in. The new entry is the reader:
    SystemList the portsThe port looks like
    macOSls /dev/cu.*/dev/cu.usbserial-XXXX
    Linuxls /dev/ttyUSB*/dev/ttyUSB0
    WindowsDevice Manager, under Ports (COM & LPT)COM3
  3. Fill in the following fields in the connector configuration:
    FieldValue
    serial_portThe port from step 2
    simulation_modefalse for the real reader. It's true by default, which runs the connector's built-in simulator
    request_timeout300 seconds. Raise it for assays that take longer than 5 minutes per command
  4. Start the connector. It reads which options the reader has, then GroundControl shows the modules DeviceService, HardwareCapabilitiesProvider, CarrierController, ShakerController, AssayConfigurationService, AssayExecutionService, ProbeHeightController, and SimulationController. Readers with incubation option also show TemperatureController.

To switch between the simulator and the real reader, change simulation_mode and restart the connector. Scripts you write against the simulator run unchanged on the real reader.

First successful test

Read the serial number, the firmware, and the reader's status, then extend and retract the plate carrier. The carrier moves. Keep the area in front of the reader clear.

from unitelabs.sdk import AsyncApiClient

client = AsyncApiClient()
reader = await client.get_service_by_name(name="Agilent Synergy H1")

print(await reader.device_service.get_serial_number())
print(await reader.device_service.get_basecode_version())
print(await reader.device_service.read_current_status())

await reader.carrier_controller.extend()
await reader.carrier_controller.retract()

Expected:

  • The serial number prints.
  • The basecode part and version number print.
  • The status prints as a code with its description.
  • The carrier comes out and goes back in.

Known quirks and errors

You seeIt meansDo this
Readings look random, and some commands return errorsThe connector runs in simulation mode, which returns sample data and test errorsSet simulation_mode to false and restart the connector
The connector is still in simulation after you switch modesMode changes apply when the connector startsChange simulation_mode in the configuration and restart the connector
The connector can't open the serial portThe port name is wrong, or the computer has no driver for the reader's USB-serial connectionList the ports with the cable unplugged and plugged in, and use the new entry. If no entry appears, check the cable, then install the USB-serial driver
DeviceIsInitializingError or DeviceIsRefreshingFeaturesErrorThe connector is still reading the reader's optionsWait a few seconds and retry
NakErrorThe reader rejected the commandCall read_current_status() to see why
The reader beeps after an errorIt holds the last error until it's readCall read_current_status() twice. The second call shows any error that needs a self-test; run it with device_service.run_self_test()
TemperatureController isn't listedThe reader has no incubation optionCheck HardwareCapabilitiesProvider for the options the reader has
PlateGeometryNotDefinedErrorAn assay was scheduled before the plate was definedCall define_plate_geometry once after the connector starts
The shake intensity differs from what you expectedshake_rate sets the amplitude of the shakePick the rate by testing it with your plate type
Your assay definition is empty after ShakerController.startStarting the shaker sets up its own short assay, which replaces the current definitionShake before you define the assay, or add a shake event to the assay

More snippets

Read a plate: this example reads absorbance at 450 nm across a 96-well plate. First, define the plate. The reader uses it to find the wells, and it stays defined until the connector restarts. These dimensions are for a standard 96-well plate; for other plates, take them from the plate's data sheet.

await reader.assay_configuration_service.define_plate_geometry(
    rows=8,
    columns=12,
    first_row=11.22,
    last_row=74.34,
    first_column=14.35,
    last_column=113.53,
    external_width=85.59,
    external_length=127.88,
    height=17.72,
)

Then define and run the read. read_plate() clears the assay first, so you can call it again for a re-read.

async def read_plate(wavelength_nm=450):
    config = reader.assay_configuration_service
    await config.clear()
    await config.define_assay_main_details(
        processing_mode="plate mode",
        incubation_protocol="disabled",
        top_filter_probe_aperture="normal",
        plate_range={"FirstRow": 1, "LastRow": 8, "FirstColumn": 1, "LastColumn": 12},
        processing_order={
            "WellProcessingDirection": "by row",
            "InitialRowDirection": "no preference",
            "InitialColumnDirection": "no preference",
        },
        plate_access_mode="eject",
        special_mode="none",
        delay_after_carrier_movement=100,
        light_shutter=False,
        probe_height=12.0,
    )
    await config.add_read_event(read_event_id="R1", kinetic_data_points=1, kinetic_interval=0.0, readsets=1)
    await config.add_absorbance_readset(
        readset_id="Abs1",
        read_event_id="R1",
        readset_core_configuration={
            "Chemistry": "absorbance",
            "Probe": "not used",
            "ReadSpeed": "normal",
            "MeasurementsAveragedPerDataPoint": 8,
            "ColumnReadOffset": 0.0,
        },
        readset_absorbance_specific={
            "SpectralFirstWavelength": 200,
            "SpectralLastWavelength": 201,
            "SpectralWavelengthIncrement": 1,
            "SpectralPerformCalibration": False,
            "SingleWavelength": wavelength_nm,
        },
    )
    await config.set_event_execution_order(event_execution_order=["R1"])
    await config.validate()

    await reader.assay_execution_service.schedule_assay()
    return await reader.assay_execution_service.execute_assay_plate_mode()


await reader.carrier_controller.extend()
input("Place the plate in the carrier, A1 top left, then press Enter")
await reader.carrier_controller.retract()

result = await read_plate()
print(result)

With plate_access_mode="eject", the plate carrier opens with the plate when the read finishes. Use "retain" to keep the plate inside.

The result holds ReadEvents, each with its Readsets. Each readset has a Data list with an entry per well: Row and Col, counted from 1, and the well's Values.

Other assays follow the same order: define the main details, add events and their readsets, set the run order, validate, schedule, and execute. export_assay() returns the definition as JSON and import_assay(...) loads it back, so you can build an assay once and reuse it.

Retry after a read error: check what the reader reports, fix the cause, and read again.

while True:
    try:
        result = await read_plate()
        break
    except Exception as error:
        print(f"Read failed: {error}")
        print(await reader.device_service.read_current_status())
        input("Fix the cause, then press Enter to read again")

Incubate: temperature_controller.start(target_temperature=37, target_gradient=0) returns the setpoint the reader applied, which can be rounded. stop() switches incubation off.

Connector reference

Browse the connected instrument's modules and actions in GroundControl, or list them in Python with print(reader.assay_configuration_service.actions.keys()).

Vendor documentation

Optics, filters, plate types, and safety are in Agilent's Synergy H1 operator's manual.

Last updated