Skip to content

Connect an Opentrons robot

FlaskTrack can use an Instrument Agent inside the laboratory network to collect run information from an Opentrons Robot Server and submit it through the normal instrument ingestion pipeline.

Network architecture

The recommended topology is:

Opentrons Flex or OT-2
        ↑
        │ laboratory network
        │
FlaskTrack Instrument Agent
        │
        │ outbound HTTPS
        ↓
FlaskTrack

The FlaskTrack cloud server does not need direct access to the private robot IP address.

Before you begin

You need:

  • an Opentrons instrument reachable from the agent host;
  • an Instrument Agent installed on that host or another machine on the same accessible network;
  • an Opentrons instrument record in FlaskTrack;
  • an Opentrons connector assigned to that agent;
  • a parser profile compatible with the Opentrons artifact captured by your FlaskTrack deployment.

1. Add the robot as an instrument

Create the physical instrument in FlaskTrack.

Example:

Name:         Opentrons Flex 01
Type:         Liquid handler
Manufacturer: Opentrons
Model:        Flex
Location:     Automation Lab

2. Install or select an Instrument Agent

The agent must be able to reach the Robot Server over the local laboratory network.

From the agent machine, first verify normal network connectivity according to your laboratory's network policy.

Then run:

flasktrack-agent doctor --config ./agent.json

after the Opentrons connector has been assigned.

3. Create the connector

Create an instrument connector with:

Instrument:       Opentrons Flex 01
Instrument Agent: Automation Lab Agent
Connector type:   Opentrons
Direction:        Inbound
Base URL:         http://ROBOT-ADDRESS:31950
Polling interval: 30
Enabled:          Yes

The Base URL is evaluated by the agent running inside the laboratory network.

Use the actual robot hostname or IP address reachable from that machine.

Opentrons-specific settings

The current agent recognizes settings such as:

{
  "opentrons_version": "*",
  "opentrons_page_length": 50,
  "vendor_timeout_seconds": 20
}

opentrons_version controls the Robot Server API version header used by the connector.

What the agent retrieves

For supported runs, the agent queries Robot Server information including:

GET /health
GET /runs
GET /runs/{run_id}
GET /runs/{run_id}/commands

Terminal run states such as successful, failed, or stopped runs can be captured and converted into an immutable JSON source artifact for FlaskTrack ingestion.

The captured artifact can include:

  • robot health information;
  • run identity and status;
  • protocol association;
  • pipettes;
  • labware;
  • liquids;
  • run errors;
  • ordered command information;
  • completion timestamps.

Duplicate protection

The agent creates a stable idempotency identity from the connector, Opentrons run ID, and terminal state. Already-known terminal runs are not continuously resubmitted on every polling pass.

FlaskTrack still performs server-side idempotency checking when the artifact arrives.

Verify the connector

Run:

flasktrack-agent doctor --config ./agent.json

A healthy Opentrons connector should report that the Robot Server is reachable.

For a full processing test:

  1. execute a test protocol on the robot;
  2. allow it to reach a terminal state;
  3. wait for the configured polling interval or run flasktrack-agent once;
  4. open Instrument Ingestions in FlaskTrack;
  5. open the resulting run;
  6. verify labware/position identity and observations against the source run;
  7. complete required mappings;
  8. submit for review.

Robot Server unavailable

If doctor reports that the Robot Server cannot be reached:

  • confirm the robot is powered and reachable from the agent machine;
  • confirm the Base URL and port;
  • confirm local firewall rules;
  • confirm the agent machine is on the correct network or VLAN;
  • confirm your laboratory permits the agent host to reach Robot Server;
  • do not expose the Robot Server directly to the public internet merely to make FlaskTrack SaaS connectivity work.

Parser compatibility

The Opentrons connector collects source run information. A parser still determines how that source payload becomes FlaskTrack positions and observations.

If ingestions arrive successfully but fail during parsing, investigate the parser profile and ingestion details rather than the local robot connection.