Agilent BioTek Synergy H1
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
| Item | Detail |
|---|---|
| Instrument | A Synergy H1, powered on, with the carrier free to move |
| Cable | The reader's USB cable to the GroundControl machine. The reader shows up as a serial port |
| Connector | Agilent Synergy H1 from the UniteLabs registry |
| Vendor software | None. Close Gen5 if it's installed, so it doesn't hold the port |
| Machine | Windows, Linux, or macOS running GroundControl |
| Access | A tenant and the SDK installed. See Setup |
Install and configure the connector
- In GroundControl, add a connector and pick Agilent Synergy H1 (how to add a connector).
- Find the reader's serial port. List the ports with the USB cable unplugged, then plugged in. The
new entry is the reader:
System List the ports The port looks like macOS ls /dev/cu.*/dev/cu.usbserial-XXXXLinux ls /dev/ttyUSB*/dev/ttyUSB0Windows Device Manager, under Ports (COM & LPT) COM3 - Fill in the following fields in the connector configuration:
Field Value serial_portThe port from step 2 simulation_modefalsefor the real reader. It'strueby default, which runs the connector's built-in simulatorrequest_timeout300seconds. Raise it for assays that take longer than 5 minutes per command - Start the connector. It reads which options the reader has, then GroundControl shows the modules
DeviceService,HardwareCapabilitiesProvider,CarrierController,ShakerController,AssayConfigurationService,AssayExecutionService,ProbeHeightController, andSimulationController. Readers with incubation option also showTemperatureController.
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 see | It means | Do this |
|---|---|---|
| Readings look random, and some commands return errors | The connector runs in simulation mode, which returns sample data and test errors | Set simulation_mode to false and restart the connector |
| The connector is still in simulation after you switch modes | Mode changes apply when the connector starts | Change simulation_mode in the configuration and restart the connector |
| The connector can't open the serial port | The port name is wrong, or the computer has no driver for the reader's USB-serial connection | List 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 DeviceIsRefreshingFeaturesError | The connector is still reading the reader's options | Wait a few seconds and retry |
NakError | The reader rejected the command | Call read_current_status() to see why |
| The reader beeps after an error | It holds the last error until it's read | Call 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 listed | The reader has no incubation option | Check HardwareCapabilitiesProvider for the options the reader has |
PlateGeometryNotDefinedError | An assay was scheduled before the plate was defined | Call define_plate_geometry once after the connector starts |
| The shake intensity differs from what you expected | shake_rate sets the amplitude of the shake | Pick the rate by testing it with your plate type |
Your assay definition is empty after ShakerController.start | Starting the shaker sets up its own short assay, which replaces the current definition | Shake 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