UniteLabs
How-to

Connect & run a method

How to connect to the Tecan FluentControl connector and start a FluentControl method.
Different integration model: Unlike Hamilton STAR/Vantage and Agilent Bravo, which expose instrument commands directly through the SDK's typed deck and labware model, FluentControl is driven through a method defined inside the FluentControl software. The SDK prepares and starts that method; FluentControl handles the actual instrument control.

This guide uses unitelabs-tecan-fluentcontrol version 0.5.1.

There are two ways to run a method:

  • Quick run with run_controller.run() (recommended for preconfigured methods): one command that prepares, runs, injects parameters, handles query dialogs, monitors progress, and cleans up.
  • Low-level runtime_controller flow (needed for the XML execution channel): gives full control over the method lifecycle and lets you stream XML commands into the running method. See Low-level control for details.
Naming convention: FluentControl commands have PascalCase SiLA names such as RunController.Run, and the SDK exposes each one as a snake_case method such as run_controller.run(). This guide uses the SDK form.

Prerequisites

  • A running Tecan FluentControl instrument with the FluentControl software open
  • A named method configured in the FluentControl software
  • A running Tecan FluentControl connector registered in the UniteLabs Platform
  • The UniteLabs SDK installed (see SDK installation)

Connect to the connector

Retrieve the FluentControl service by the connector name registered in the Platform. The name must match exactly.

from unitelabs.sdk import AsyncApiClient

client = AsyncApiClient()
service = await client.get_service_by_name(name="Tecan FluentControl")

The returned service object exposes run_controller, runtime_controller, and execution_channel_controller.

Quick run with RunController

Use run_controller for the simplest path when you do not need to send XML commands at runtime. It performs the whole method lifecycle in one call.

List available methods

get_methods() returns both runnable and maintenance methods registered in FluentControl. Method names are case-sensitive.

methods = await service.run_controller.get_methods()
print(methods)
# ["plate_prep", "dilution_series", "demo"]

Discover parameters

get_parameters() loads the method temporarily, reads its "QueryAtStartup" variables, and returns them as a list of Name and Value pairs. Pass the same keys to run().

parameters = await service.run_controller.get_parameters(method="plate_prep")
print(parameters)
# [{"Name": "plate_count", "Value": ""}, {"Name": "volume", "Value": "100"}]

Run the method

Call run() with the method name, a list of parameters, and auto_close_dialogs. Set it to True to abort a run that stops on an error, or to False to resolve dialogs yourself. Handling dialogs explains both settings, including which dialogs each one closes.

get_parameters() and run() raise InvalidState unless FluentControl is in EditMode or RunModeRunFinished. If a previous session left an XML channel open or a method loaded, close it first, as described in Check and Reset the Channel.

parameters = [
    {"Name": "plate_count", "Value": "4"},
    {"Name": "volume", "Value": "150"},
]

await service.run_controller.run(
    method="plate_prep",
    parameters=parameters,
    auto_close_dialogs=True,
)

For a method without parameters, pass parameters=[].

What Run Controller does

run_controller.run() (RunController.Run) is equivalent to the following low-level sequence, including cleanup:

  1. Attach to or start the FluentControl process: fluent_controller.start()
  2. runtime_controller.prepare_method(method="<name>")
  3. runtime_controller.run_method()
  4. If the state becomes RunModeResetTips: runtime_controller.run_method() again
  5. runtime_controller.set_variable_value(...) for each parameter
  6. If the state becomes RunModeQueryVariables: runtime_controller.close_query_at_startup_dialog(accept_values=True)
  7. For error dialogs when auto_close_dialogs=True: runtime_controller.respond_to_dialog(button_to_press="Abort")
  8. runtime_controller.close_method() when the run finishes or fails

Manage the FluentControl process

run() attaches to a running FluentControl or starts one for you. To control the process yourself, use fluent_controller:

CallWhat it does
get_is_running() / get_is_attached()Whether a FluentControl process is running, and whether the connector is attached
start()Start FluentControl and attach, or attach to a running instance
start_in_simulation_mode() / start_in_integration_mode()Start FluentControl in simulation or system integration mode
start_and_login(username, password, startup_option)Start FluentControl and log a user in. startup_option is None, Simulation or Hidden
shutdown() / force_shutdown()Shut FluentControl down, or force it to
get_runtime()Connect to the runtime of the running process, to access and control methods
subscribe_notifications()Stream the log messages of the running FluentControl process

Next steps

Last updated