watch_print
Monitor a 3D print in progress with periodic snapshots and stall detection. Auto-cancel at a specified completion percentage for test prints.
Instructions
Start background monitoring of an in-progress print.
Launches a background thread that polls the printer state every
*poll_interval* seconds and captures webcam snapshots every
*snapshot_interval* seconds. Returns immediately with a
``watch_id`` that can be used with ``watch_print_status`` and
``stop_watch_print``.
The watcher finishes automatically when:
1. **Print terminal state** -- completed, failed, cancelled, or offline.
2. **Snapshot batch ready** -- *max_snapshots* images collected.
3. **Timeout** -- the print has not finished within *timeout* seconds.
4. **cancel_at_percent** -- if set (> 0), auto-cancels when completion
reaches or exceeds this percentage. Use this for test prints,
calibration runs, or any case where you want to stop at a specific
progress point without writing a polling script.
**Camera ground-truth**: each captured snapshot is hashed and compared to
the previous frame. If the camera shows the print bed changing but
telemetry reports zero progress, the snapshot is flagged with
``telemetry_mismatch: true`` so agents can detect broken monitoring
scripts and fall back to visual inspection.
Args:
printer_name: Target printer. Omit for the default printer.
snapshot_interval: Seconds between snapshot captures (default 60).
max_snapshots: Return after this many snapshots (default 5).
timeout: Maximum seconds to monitor (default 7200 = 2 hours).
poll_interval: Seconds between state polls (default 15).
stall_timeout: Seconds of zero progress before declaring stall
(default 600 = 10 min). Set to 0 to disable stall detection.
save_to_disk: Save snapshots as JPEG files to
``~/.kiln/timelapses/<watch_id>/`` and persist metadata to the
database. Use ``list_snapshots`` to query saved frames after
the print completes (default False).
cancel_at_percent: Auto-cancel when completion >= this value.
Set to 0 (default) to disable. Example: ``cancel_at_percent=50``
cancels the print as soon as it reaches 50%.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No | ||
| printer_name | No | ||
| save_to_disk | No | ||
| max_snapshots | No | ||
| poll_interval | No | ||
| stall_timeout | No | ||
| cancel_at_percent | No | ||
| snapshot_interval | No |