Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions docs/_static/devices.json
Original file line number Diff line number Diff line change
Expand Up @@ -2153,6 +2153,20 @@
"doc_slug": "li_cor/odyssey/hello-world",
"notes": "HTTP scan control and TIFF retrieval; port pending hardware verification."
},
{
"id": "thermo-fisher-kingfisher-flex",
"vendor": "Thermo Fisher",
"name": "KingFisher Flex",
"kind": "magnetic particle processor",
"capabilities": ["magnetic bead processing"],
"status": "wip",
"needs_hardware_testing": true,
Comment on lines +2162 to +2163

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought you tested this on hardware already?

"api": "pylabrobot.thermo_fisher.kingfisher.flex.KingFisherFlex",
"api_version": "v1",
"code_slug": "thermo_fisher/kingfisher/flex",
"doc_slug": "thermo_fisher/kingfisher/flex/hello-world",
"notes": "96DW local BDZ execution tested on macOS/firmware 1.01.0, including 37 C heating, beads, drying and PLR confirmations. Partial tip pickup remains unresolved; broader formats/features and general protocol authoring remain unsupported."
},
{
"id": "thermo-fisher-kingfisher-presto",
"vendor": "Thermo Fisher",
Expand Down
25 changes: 25 additions & 0 deletions docs/api/pylabrobot.thermo_fisher.rst
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,31 @@ KingFisher Presto
ProtocolStep
ProtocolTimeLeft

KingFisher Flex
---------------

.. currentmodule:: pylabrobot.thermo_fisher.kingfisher.flex

.. autosummary::
:toctree: _autosummary
:nosignatures:
:recursive:

KingFisherFlex
FlexError
FlexEvent
FlexRunResult
FlexTranscriptEntry
FlexProtocol
FlexProtocolError
FlexProtocolIssue
FlexCommand
FlexPlate
FlexDispense
FlexTip
FlexPrompt
read_flex_bdz

BindIt protocol files
---------------------

Expand Down
34 changes: 34 additions & 0 deletions docs/user_guide/thermo_fisher/kingfisher/cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Command-line tools

The KingFisher Flex CLI inspects BindIt exports and identifies connected instruments.
See [installation](installation.md) for dependencies and USB setup.

## Inspect a Flex protocol

```console
plr dev kingfisher-flex inspect protocol.bdz
```

Prints JSON with protocol metadata, compatibility issues, and loading/pause prompts.
This command does not access hardware.

## Check multiple protocols

```console
plr dev kingfisher-flex audit /path/to/protocols other-protocol.bdz
```

Checks files and directories without accessing hardware. Directories are scanned
nonrecursively for `.bdz` files. Exits with status 1 if any input is invalid or unsupported.

## Identify a Flex

```console
plr dev kingfisher-flex probe
plr dev kingfisher-flex probe --serial-number SERIAL --transcript transcript.json
```

Opens the instrument, reads its identity, and disconnects. It does not initialize
or run a protocol.

See the [hello-world notebook](flex/hello-world.ipynb) to run protocols from Python.
290 changes: 290 additions & 0 deletions docs/user_guide/thermo_fisher/kingfisher/flex/hello-world.ipynb
Original file line number Diff line number Diff line change
@@ -0,0 +1,290 @@
{
"cells": [
{
"cell_type": "markdown",
"id": "76d09de2",
"metadata": {},
"source": [
"# KingFisher Flex\n",
"\n",
"```{device-card} thermo-fisher-kingfisher-flex\n",
"```\n",
"\n",
"Run BindIt BDZ exports with a matching **96DW head, tip comb and plates**.\n",
"Tested with firmware 1.01.0 on macOS.\n",
"\n",
"**Experimental:** command completion does not verify tip-comb attachment. Inspect\n",
"pickup and clearances.\n",
"\n",
"See [installation](../installation.md) and [command-line tools](../cli.md).\n"
]
},
{
"cell_type": "markdown",
"id": "00b27c3c",
"metadata": {},
"source": [
"## Physical setup\n",
"\n",
"Prepare the 96DW head, matching tips and supported plates according to the instrument\n",
"instructions. Close BindIt before connecting. Run hardware cells individually.\n"
]
},
{
"cell_type": "markdown",
"id": "45ae786f",
"metadata": {},
"source": [
"## Inspect a protocol offline\n",
"\n",
"Set the path to your BindIt export. Reading and preflight do not open USB.\n",
"`compatibility_issues()` lists blockers; `preflight()` raises if any remain.\n",
"`prompts()` shows plate actions and reagent additions. Plate labels are not tray numbers.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4c82c377",
"metadata": {},
"outputs": [],
"source": [
"from pathlib import Path\n",
"from pylabrobot.thermo_fisher.kingfisher.flex import KingFisherFlex, read_flex_bdz\n",
"\n",
"protocol = read_flex_bdz(Path(\"protocol.bdz\"))\n",
"commands = protocol.preflight()\n",
"(protocol.name, protocol.sha256, len(commands), protocol.prompts())"
]
},
{
"cell_type": "markdown",
"id": "51bb761a",
"metadata": {},
"source": [
"## Connect and identify\n",
"\n",
"`setup()` opens USB and reads the identity without moving the instrument.\n",
"Pass `serial_number=\"...\"` to select among multiple instruments.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c03729f7",
"metadata": {},
"outputs": [],
"source": [
"flex = KingFisherFlex()\n",
"await flex.setup()\n",
"(flex.version, flex.serial)"
]
},
{
"cell_type": "markdown",
"id": "b053d5bd",
"metadata": {},
"source": [
"## Initialize\n",
"\n",
"**This moves the instrument**, disables heating, and presents tray 4 at loading\n",
"with tray 1 at processing.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2ab44d80",
"metadata": {},
"outputs": [],
"source": [
"await flex.initialize()\n",
"flex.processing_slot"
]
},
{
"cell_type": "markdown",
"id": "42e2d8b8",
"metadata": {},
"source": [
"## Observe events\n",
"\n",
"Start one event consumer before running. Events include temperature readings,\n",
"plate requests, pauses, confirmations, failures, and run completion. Temperature\n",
"readings describe heater and ambient sensors, not well-liquid temperature.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "8af32021",
"metadata": {},
"outputs": [],
"source": [
"import asyncio\n",
"import logging\n",
"\n",
"logging.basicConfig(level=logging.INFO)\n",
"\n",
"\n",
"async def observe_events():\n",
" async for event in flex.events():\n",
" logging.info(\"%s: %s; prompt=%s\", event.kind, event.text, event.prompt)\n",
"\n",
"\n",
"observer = asyncio.create_task(observe_events())"
]
},
{
"cell_type": "markdown",
"id": "bc0f00d7",
"metadata": {},
"source": [
"## Confirm plate actions and pauses\n",
"\n",
"The input thread lets telemetry continue while you respond. Return exactly `True`\n",
"after completing the action. Pass `confirm_prompt` for loading/unloading and\n",
"`confirm_pause` for protocol pauses. Rejection or callback failure invalidates the session.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "123ebf83",
"metadata": {},
"outputs": [],
"source": [
"async def confirm_action(prompt):\n",
" print(f\"{prompt.action.upper()}: {prompt.label}\")\n",
" print(f\"Loading tray {prompt.loading_slot}; processing tray {prompt.processing_slot}\")\n",
" answer = await asyncio.to_thread(\n",
" input, \"Complete the action, clear your hands, then type CONFIRM: \"\n",
" )\n",
" return answer.strip() == \"CONFIRM\""
]
},
{
"cell_type": "markdown",
"id": "3488faef",
"metadata": {},
"source": [
"## Run a local protocol\n",
"\n",
"This starts motion and may start heating. Complete each action before confirming\n",
"in Python. Reagent prompts include the plate, reagent, and volume per well.\n",
"`operator_timeout=None` allows an indefinite confirmation wait.\n",
"\n",
"To use the instrument's physical Start button, omit both confirmation callbacks.\n",
"Callbacks replace the corresponding instrument pauses; they cannot advance an\n",
"already active onboard pause. Pause text mentioning seconds does not set a timer.\n",
"\n",
"The call returns after execution and finalization. Heating follows the exported\n",
"commands; setting a temperature does not itself wait for target attainment.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5f73c396",
"metadata": {},
"outputs": [],
"source": [
"result = await flex.run_protocol(\n",
" protocol,\n",
" confirm_prompt=confirm_action,\n",
" confirm_pause=confirm_action,\n",
" operator_timeout=None,\n",
")\n",
"result"
]
},
{
"cell_type": "markdown",
"id": "stored-protocols",
"metadata": {},
"source": [
"## List and run onboard protocols\n",
"\n",
"As an alternative to a local BDZ, list the protocols stored on the instrument:\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "list-protocols",
"metadata": {},
"outputs": [],
"source": [
"names = await flex.list_protocols()\n",
"names\n"
]
},
{
"cell_type": "markdown",
"id": "start-stored",
"metadata": {},
"source": [
"Choose an exact name from the inventory. The following call starts motion and\n",
"waits for completion. Internal loading pauses require the physical Start button;\n",
"Python confirmation callbacks are unavailable for onboard runs. Protocol upload\n",
"and remote resume are unsupported. Onboard launch has been tested only through\n",
"the first loading prompt.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "run-stored",
"metadata": {},
"outputs": [],
"source": [
"await flex.start_stored_protocol(\"Your stored protocol\")\n"
]
},
{
"cell_type": "markdown",
"id": "8ff0e980",
"metadata": {},
"source": [
"## Abort an active run\n",
"\n",
"Call `await flex.abort()` from another task while execution is pending. Keep the run\n",
"in an `asyncio.Task` when it needs a supervising task. Canceling a Python task or\n",
"interrupting a notebook cell does not stop the instrument.\n",
"\n",
"After interruption, inspect physical positions, call `stop()`, and reconnect before\n",
"restarting. There is no automatic retry or resume.\n"
]
},
{
"cell_type": "markdown",
"id": "59f31c80",
"metadata": {},
"source": [
"## Disconnect\n",
"\n",
"`stop()` closes USB and ends the event stream. It does not stop motion.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1e56dfff",
"metadata": {},
"outputs": [],
"source": [
"await flex.stop()\n",
"await observer"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
3 changes: 3 additions & 0 deletions docs/user_guide/thermo_fisher/kingfisher/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,8 @@
```{toctree}
:maxdepth: 1

installation
cli
presto/hello-world
flex/hello-world
```
Loading
Loading