Monorepos

Last updated on November 19, 2026

A TofuPilot project holds one procedure or many, so a monorepo is the right layout when you want to share instrument drivers, calibration sequences, and finalizer phases across procedures. The patterns below scale from a single procedure on a laptop up to a fleet of related products that ship from the same repo.

Single procedure

When a project covers a single procedure, everything lives next to one procedure .yaml file. Phases, plugs, and the environment all sit in the same folder so you do not have to think about paths.

.env.local
procedure.yaml
test_cell_voltage.py
measure_capacity.py
Keysight34461A.py
ArbinBatteryTester.py

Multiple procedures

When a second product joins the repo, lift the reusable code into shared/ and keep each procedure under procedures/<name>/ with its own .yaml file. Each procedure then references shared code by relative path, so you keep one canonical copy of every driver and helper.

pyproject.toml
.env.local
procedure.yaml

Each procedure resolves Python references against its project root, the folder of its own pyproject.toml, so shared modules are reached either via relative paths (../../shared/phases/save_to_mes) or by adding shared/ to PYTHONPATH from .env.local. The validator warns about a file reached with .. that a deployment of that procedure alone would not ship.

Sharing a plug across procedures

Define each plug once under shared/plugs/ and reference it from every procedure .yaml file that needs it, so a single file holds the canonical driver.

procedures/laptop-battery-functional/procedure.yaml
name: Laptop Battery Functional

plugs:
  - name: Power Supply
    python: ../../shared/plugs/RigolDP832:RigolDP832

main:
  - name: Test Cell Voltage
    python: phases.test_cell_voltage

When the driver changes, every procedure picks up the new version on the next run, so you do not have to remember to bump versions across the repo.

Without a uv workspace at the repository root, this file is not shipped with the deployment and tofupilot validate reports python_outside_root.

Sharing a sequence across procedures

A group of phases that several procedures run, such as an instrument calibration, is a sequence: one YAML file under shared/sequences/, called from each procedure with uses:.

procedures/laptop-battery-functional/procedure.yaml
name: Laptop Battery Functional

main:
  - uses: ../../shared/sequences/instrument_calibration.yaml
    with:
      target_voltage: 12.0
  - name: Test Cell Voltage
    python: phases.test_cell_voltage

A deployment ships the procedure directory, so a sequence file reached with .. only arrives on the station when the repository is a uv workspace whose root encloses both the procedure and the shared folder: a pyproject.toml at the repo root with a [tool.uv.workspace] table listing the procedures as members. A git integration deployment then ships the whole workspace. tofupilot deploy packs the procedure directory only, so it refuses a procedure whose sequence files sit outside it. Without the workspace, the validator reports the uses: file as outside the deployable tree, and the fix is either the workspace or a copy of the sequence under the procedure directory.

A sequence shipped as part of a Python package needs neither: uses: acme_bench:sequences/calibration.yaml reads it from the installed package.

The workspace ships the shared folder, but the operator UI serves images from the procedure's root only. An image kept beside the shared sequence shows the placeholder in a run, and tofupilot validate reports image_outside_root. Keep the images under each procedure's root and let the sequence take their paths from a file input, which the calling procedure writes from its own root.

Deploying each procedure from the same repo

Each TofuPilot procedure maps to its own subdirectory through two settings, set once per procedure with tofupilot procedures update or from the procedure's settings page:

  • Root directory: the path within the repo to the directory holding the procedure's pyproject.toml and procedure.yaml. For the layout above: procedures/laptop-battery-functional.
  • Entry point: which file to run inside that directory, when the default does not fit. A .yaml entry point is the only way to run a procedure file with a custom name (for example battery-functional.yaml instead of procedure.yaml); a .py entry point points OpenHTF procedures at a file other than main.py.
map each procedure to its directory
tofupilot procedures update --id <functional-id> --root-directory procedures/laptop-battery-functional
tofupilot procedures update --id <burnin-id> --root-directory procedures/laptop-battery-burnin

With Git deployments, one push then builds every procedure from its own directory, with no per-procedure checkouts and no renaming.

How is this guide?

On this page