Procedures

This section collects step-by-step procedures for operating, calibrating, and maintaining a Science Jubilee machine.

Unlike the Examples section (which focuses on copy-paste scripts and workflows), procedures combine:

• Physical steps (what to do on or around the machine),
• Controller steps (Duet / G-code changes), and
• Python steps (how to use the Science Jubilee library)

into one canonical “do it this way every time” recipe.

When to use a procedure

Use a procedure when you need to:

• Perform a repeatable, safety-critical task (e.g., calibrating tool offsets, parking positions, or probe locations)
• Change machine configuration (e.g., editing Toffsets.g, config.g, or similar)
• Follow a multi-part workflow that involves both hardware and software (e.g., installing a new tool with camera alignment)

If you just want to see what the library can do or copy a minimal script, start in the Examples section instead.

WARNING

Always read a procedure all the way through before making permanent changes (like editing .g files) or moving hardware near the bed.

How procedure pages are structured

Every procedure page follows a consistent format so you can scan and execute it carefully:

1. Overview What the procedure accomplishes and why it matters (for example, “calibrate XY offsets between tools and the z-probe using a USB microscope”).

2. Pre-Conditions A checklist of what must already be true, such as:

   • Machine powered on and homed
   • No active offsets for the tool
   • Specific hardware installed (camera, probe, tool, plate)

3. Steps Numbered or titled sections that walk through the task in order, combining:

   • Python snippets using Machine, Tool, and other classes
   • G-code commands to send via Duet Web Control
   • Physical actions on the machine (mounting tools, placing cameras, etc.)

   For example, in Calibrating XY Tool Offsets with Camera Alignment, the steps include connecting to the machine, preparing the tool, launching a camera feed, centering the z-probe, centering the tool, and computing offsets.

4. Important Notes Call-outs about safety, common failure modes, or subtle details (e.g., “clear existing tool offsets before starting” or camera index troubleshooting).

5. Related Concepts Links to class docs and other procedures that are often used together:

   • Tool and Machine
   • Related procedures like Setting Tool Parking Positions

Procedures may also include VitePress callouts like ::: tip, ::: warning, and ::: danger for quick visual scanning.

Procedure catalog

Calibration & alignment

These procedures help you align tools and references so multi-tool workflows behave consistently.

• Calibrating XY Tool Offsets with Camera Alignment Use a USB microscope and live video feed to align the z-probe and tool tip, then compute and persist XY offsets in Toffsets.g.

• Setting Tool Parking Positions Define safe and repeatable parking locations for tools and update the relevant Duet configuration files.

Machine setup & maintenance

Foundation procedures for keeping a Jubilee healthy and predictable.

• Initial Machine Setup & Homing Procedure Verify axes directions, limits, and homing behavior on a new or recently serviced machine.

• Deck & Labware Verification Confirm that physical labware placement matches deck_config definitions and coordinate systems.

Troubleshooting & recovery

Procedures for “something went wrong” scenarios.

• Recovering from Interrupted Runs What to check if the machine stops mid-run (e.g., emergency stop or connection loss) and how to safely resume or reset.

• Re-establishing Safe Z After Collision Steps for inspecting hardware, re-homing, and re-calibrating Z-related offsets after a suspected crash.

(Additional procedures will appear here as they are added to the knowledge base.)

Conventions in procedure docs

Across all procedures, we follow consistent conventions:

• Explicit module imports

  from science_jubilee.machine import Machine
  from science_jubilee.tools import Tool

• Clear distinction between Python and G-code

  • Python blocks are marked with ```python
  • Controller commands (for Duet / console) use ```gcode

• Measured changes, not magic constants

  Where offsets or coordinates are computed (e.g., XY offset from camera alignment), the procedure shows how to measure and calculate them, not just paste hard-coded numbers.

• Persistent vs. temporary changes are labeled

  If a step modifies configuration files like Toffsets.g or config.g, the doc explicitly states that the change is permanent and machine-wide.

TIP

If you create a new procedure, use the XY tool offset calibration page as a template: start with Overview and Pre-Conditions, then break the main workflow into numbered steps with small, testable code snippets.