watch_print
Destructive
Start background monitoring of an in-progress 3D print: poll printer state, capture webcam snapshots, detect stalls, and auto-stop at a set completion percentage.
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.
5. **Hardware stop** -- the print carries a hardware plan (pauses
written in for nuts, magnets or bearings) and a stop is a few
minutes away, the printer has stopped for the parts, or it went
past a stop without stopping: ``outcome: "hardware_stop"`` with a
``hardware`` block saying what goes in. Tell the person; at the
stop itself, resume only on their word that every piece is in
(``resume_print(hardware_confirmed=true)``). Then watch again.
**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%.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "watch_print"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No | Maximum seconds to monitor (default 7200 = 2 hours). Default: 7200. | |
| printer_name | No | Target printer. Omit for the default printer. | |
| save_to_disk | No | 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). Default: false. | |
| max_snapshots | No | Return after this many snapshots (default 5). Default: 5. | |
| poll_interval | No | Seconds between state polls (default 15). Default: 15. | |
| stall_timeout | No | Seconds of zero progress before declaring stall (default 600 = 10 min). Set to 0 to disable stall detection. Default: 600. | |
| cancel_at_percent | No | 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%. Default: 0.0. | |
| snapshot_interval | No | Seconds between snapshot captures (default 60). Default: 60. |