Repository navigation
Add KingFisher Flex driver for local BDZ execution #1627
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft
GRiveraDT
wants to merge
4
commits into
PyLabRobot:main
Choose a base branch
from
GRiveraDT:kingfisher-flex-support
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Draft
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
d3226b5
Add KingFisher Flex local BDZ execution over HID
GRiveraDT 98aec14
Share KingFisher HID framing and BDZ container decoding
rickwierenga 773f833
Replace scripted Flex HID transport with unittest mocks
rickwierenga a79b01c
Streamline KingFisher Flex setup and usage documentation
rickwierenga File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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
290
docs/user_guide/thermo_fisher/kingfisher/flex/hello-world.ipynb
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,5 +3,8 @@ | |
| ```{toctree} | ||
| :maxdepth: 1 | ||
|
|
||
| installation | ||
| cli | ||
| presto/hello-world | ||
| flex/hello-world | ||
| ``` | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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?