Connect & run a method
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_controllerflow (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.
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:
- Attach to or start the FluentControl process:
fluent_controller.start() runtime_controller.prepare_method(method="<name>")runtime_controller.run_method()- If the state becomes
RunModeResetTips:runtime_controller.run_method()again runtime_controller.set_variable_value(...)for each parameter- If the state becomes
RunModeQueryVariables:runtime_controller.close_query_at_startup_dialog(accept_values=True) - For error dialogs when
auto_close_dialogs=True:runtime_controller.respond_to_dialog(button_to_press="Abort") 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:
| Call | What 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
- To stream XML commands into a running method, see Low-level control.
- To handle dialogs, warnings, and query prompts manually, see Handling dialogs.
- For a complete end-to-end script, see Full workflow example.
Last updated