Skip to content

protocol-designer

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

protocol-designer

README.md

Opentrons Protocol Designer

Overview

Protocol Designer is a tool for scientists and technicians to create protocols for their OT-2 personal pipetting robot without having to write any code. It provides visual feedback including liquid tracking and tip tracking to allow users to see exactly what their protocol will do at each step. The protocols are saved to Opentrons JSON Protocol files, which can be uploaded to the Opentrons Desktop App to run on a robot.

Protocol Designer is optimized for Chrome browser. Other browsers are not fully supported.

Build setup for development

# from the repo root

# install all dependencies
make setup

cd protocol-designer/

# run the development server
make dev

Opentrons Dependencies

Protocol Designer uses the Components Library for many React components.

It uses shared-data for data about labware and pipettes and for JSON schema definitions.

Some important directories

  • shared-data/protocol/schemas/{schemaVersionNumber}.json - contains the JSON schema definitions for all versions of Opentrons JSON Protocols
  • protocol-designer/src/step-generation/ - a set of functions for creating commands for Opentrons JSON Protocols. Designed to be agnostic of the specifics of Protocol Designer so that it can eventually be split out as its own library
  • protocol-designer/src/steplist - contains Redux actions, reducers, and selectors that make up the bulk of the logic for the behavior of Step Forms and the protocol Timeline.
  • protocol-designer/src/ui - Redux actions, reducers, and selectors that are purely concerned with UI and not with the "domain layer" of the protocol itself

Environment variables

Feature flags

We have an evolving set of feature flags for development, to avoid introducing regressions when we add new features that aren't fully ready to be "live" on edge. You can either set them through the UI, or through environment variables that are baked in at build time.

The environment variables start with OT_PD_. See the code for the current list. Use them like:

OT_PD_COOL_FLAG=1 OT_PD_SWAG_FLAG=1 make dev

OT_PD_VERSION

This version string is saved protocol files, to the designer-application.application-version field (and to designer-application.applicationVersion for future compatibility).

OT_PD_BUILD_DATE

Used for analytics segmentation. Also saved in protocol file at designer-application._internalAppBuildDate to help with bug reporting.

OT_PD_COMMIT_HASH

Used for analytics segmentation. In Travis CI, this is fed by $TRAVIS_COMMIT.

OT_PD_MIXPANEL_ID

Used for Mixpanel in prod. Should be provided in the CI build.

OT_PD_MIXPANEL_DEV_ID

Used for Mixpanel in dev (eg via a sandbox URL). Should be provided in the CI build.

OT_PD_SHOW_GATE

If truthy, uses the GateModal component in development. The GateModal component is always used in production.

Sentry (error reporting + sourcemaps)

Protocol Designer uses Sentry in two places:

  1. Runtime error reporting (in the browser) via @sentry/react.
  2. Build-time sourcemap uploading (optional) via @sentry/vite-plugin.

Runtime error reporting (browser)

PD will only initialize Sentry if a DSN is provided and the user has opted in.

  • OT_PD_SENTRY_DSN: production/staging DSN.
  • OT_PD_SENTRY_DEV_DSN: development DSN fallback.

Local sourcemap upload (opt-in)

By default, local builds do not upload sourcemaps. To opt in locally, set the Sentry plugin credentials:

SENTRY_AUTH_TOKEN=... \
SENTRY_ORG=... \
SENTRY_PROJECT=... \
make -C protocol-designer build

Notes:

  • The plugin is always enabled (to annotate React component names for better Sentry breadcrumbs), but it only uploads sourcemaps when the SENTRY_* env vars are present.
  • Local sourcemaps are uploaded under the Sentry release name local-dev so they don’t collide with real releases.
  • The runtime SDK is configured to report release=local-dev when local upload is enabled, so local events can resolve the uploaded sourcemaps.

CI sourcemap upload (releases)

CI uploads sourcemaps via the Vite plugin on tagged staging/production releases. See the workflow at .github/workflows/pd-test-build-deploy.yaml.

  • Sourcemaps are uploaded from protocol-designer/dist.
  • Upload only runs for tagged staging or production releases.
  • The release name comes from the tag version (e.g. protocol-designer@8.8.0 → 8.8.0).

Implementation notes:

  • CI enables the upload by setting OT_PD_SENTRY_PLUGIN_UPLOAD=true for eligible tagged builds.
  • CI sets SENTRY_RELEASE to the tag version so runtime events match the uploaded sourcemaps.

Protocol schema versioning on import and save, and how protocol versioning is exposed to users

This info is current as of 2021/07/01:

Our protocol executor (in robot server) doesn't support older versions of JSON protocols (v1 and v2 will not execute). Users with v1/v2 PD protocols need to upload them into PD and save them again so that they can run them on a recent version of Run App + robot.

PD supports importing of all PD JSON protocols, back to schema v1. It has machinery to transform v1 to v2, v2 to v3, and so on. We internally call these "migrations", but to the user it's just exposed in an "Update Protocol" modal that users see upon importing an older protocol into PD.

Regardless of version upon import, PD will save the lowest schema version depending on features of the protocol. Right now PD saves version 3, 4, or 5. PD chooses the lowest possible version given the features used by the protocol. It doesn't matter what version was imported, only what features it has when you go to save it.

  • A protocol that uses Air Gap will be saved as v5.
  • A protocol with modules (and no air gap) will be saved as v4.
  • A protocol with no modules and no air gap will be saved as v3.

We chose to make PD save the oldest workable version (of 3/4/5) because users are resistant to upgrading their robots. With this ability to export the oldest workable version, users who are not taking advantage of newer features don't need to upgrade. For example, if I wasn't using modules in my protocol, and I'm still not using modules, I as a user don't want to have to upgrade my robot to run my existing protocol that I'm working on in PD.

However, it becomes unmaintainable to support saving older versions indefinitely -- eg sometime soon we'll drop support for PD saving v3 (and maybe also drop saving v4). Users would still be able to import any old versions back to v1, but only save newer ones.

Users never have to think about protocol version numbers directly. But we do make them aware in some ways that protocols are tied to updates:

  • Upon importing an older protocol into PD, we make them aware of "PD is upgrading your protocol, please check it to make sure nothing has broken".
  • In Run App, upon uploading a newer protocol to an older robot version, users may see a message like "you have to upgrade your robot to run this protocol" (if they have a schema newer than their run app / robot server version)
  • Upon exporting from PD, we also have a message like "you may have to upgrade your robot" when a user is taking advantage of certain new features for the first time. PD can't tell what version their robot is, so we can't be more specific, currently.