bug: Robot analysis shows outdated results when the protocol has an external dependency

[SyntaxColoring]

This is a centralized issue to discuss something that several people have reported here on GitHub. Internally, we're tracking this as AUTH-56.

Overview

It's possible to write a Python protocol that opens a file on the robot's filesystem and changes its behavior depending on the contents. This is often done with CSV files, as in this Opentrons Support article. Equivalently, you could have the Python protocol make a network request, for example to pull data from Google Sheets or a LIMS.

Since robot software v7.0.0, there's a problem where, if you update just the external file, and you re-run your protocol, you won't see the changes you just made.

Specifically, symptoms include:

• The Opentrons App showing an outdated deck map, labware, pipettes, etc.
• The Opentrons App showing an outdated run log.
• The Opentrons App continuing to show protocol errors like "missing file my_csv.csv" even after you correct the problem.

The problem is limited to protocol analysis. If you manage to actually run the protocol, the robot will use the latest data when actually moving around.

Workarounds

Replace the external dependency with runtime parameters

v7.3.0 adds runtime parameters. Runtime parameters give you an operator-friendly way to change variables in a protocol. The feature is currently not powerful enough to replace the full generality of things like CSV files (there is no free text input). But for simpler cases, like inputting a single integer for a sample count, it's the better solution.

"Change" the protocol

To see the latest changes in your external dependencies, you can trick the robot into thinking it's an entirely new protocol and doing a fresh protocol analysis.

Some ways to do this:

• Rename your .py file, like my_protocol_1.py, my_protocol_2.py, etc., and upload it again.
• Or add a dummy runtime parameter to your .py file, and change the value to something unique (like an incrementing integer, or the current date and time) whenever you need to see the latest changes.
• Or edit your .py file's contents, for example by adding an extraneous # comment somewhere, and upload it again.

HTTP API

If you're not using the Opentrons App, and are instead controlling the run yourself with the robot's HTTP API, you have an additional option: you can DELETE the protocol and POST it again.

Underlying cause

v7.0.0 (technically, PR #12193) added a protocol cache to the robot. If you upload a protocol that "exactly matches" one that's already on the robot, the robot will reuse the original copy instead of storing a new one. This includes reusing the original copy's analysis. This can make things much faster for people who repeatedly upload the same long protocol. It also makes the Flex's touchscreen more useful because it won't get filled up with a bunch of redundant copies.

Unfortunately, this has turned out to interact poorly with protocols that change depending on external resources like CSV files. As long as your protocol source files—the .py file and any custom labware .json files—are the same as they were before, the system will treat it as "the same protocol" and skip re-analyzing it. For most protocols, this is a safe optimization, but for protocols that depend on external resources, it will show stale and confusing results.

[pkMyt1]

I have seen this as well. Very annoying. I have to reset the run cache and reboot the robot every I do a new run. It is not practical to rewrite and rename the protocol for each run when all that changes is the number of samples and the labels.

[SyntaxColoring]

v7.3.0 just released with the new feature of runtime parameters, which gives you some more options. You can use them directly to outright replace some uses of external dependencies. Or you can use them as a trick to trigger a fresh protocol analysis, as a perhaps more convenient alternative to renaming the .py file. See the updated "Workarounds" section.