# Toolchange: sequences, sensors, mounted-tool state

Address-verified against the live binary (`CommMgr` methods). Ported in
`pkgs/klipper/payload/klipper/klippy/extras/ff_toolchange.py`; divergences are deliberate and listed at the end.

## Physical model

- 4 docks on the right, X ≈ 297 (250 and 280 are the staging and approach
  waypoints, `x_safe` / `x_approach`), per-dock X/Y from `extruder.json`
  (`x/y_check_pos..3`), station base `x/y/z_station_pos`.
- Lock motor on the carriage grabs/releases the head. Its endstop is registered on
  `manual_stepper gear_stepper`; `MOTOR_GRAB`/`MOTOR_RELEASE` are STOP_ON_ENDSTOP-style
  moves that respond "endstop triggered / not triggered".
- Sensors (`gcode_button`): `extruder_pos1..4` = head present in dock N;
  `extruder_grab(1..4)` = something locked on the carriage. The app also names
  `servo_min`/`servo_max` (lock mechanism end positions), but this printer's
  config declares neither -- see `10-hardware.md` for the family that actually
  exists.
- Invariant checked constantly: a head is EITHER in its dock OR on the carriage
  (E0127-134, E0139-146 cover every disagreement).

## Grab — `doGrabExtruderLatest` @0x7a8190

1. Home gate (abort if not homed, E0160).
2. Dock-must-be-OCCUPIED precheck: 20 × 50 ms polls of `checkInLocation(tool)`;
   failure → E0127+tool, no motion.
3. `SET_VELOCITY_LIMIT ACCEL=8000`; `SET_GCODE_OFFSET X=0 Y=0 MOVE=1 MOVE_SPEED=100`.
4. Approach, once, before the retry loop: `G1 X250 F<fast>` (`x_safe`),
   `G1 Y<dockY>`, `G1 X280` (`x_approach`).
5. Then up to 3 attempts. Each begins by re-engaging the dock —
   `G1 X<dockX> F<slow>` (+`grabOffset` correction from test.json) — which is
   what undoes the previous attempt's back-off. Poll the grab sensor for up to
   1 s; on success `MOTOR_GRAB`, `G1 X<dockX-20> F4800` (the app's literal
   pullback feed, not the calibrated one), `MOTOR_GRAB2`, and leave the loop.
   On failure back off to `G1 X280` and wait. `G1 X250 F1500` is the retreat
   after the loop, not part of an attempt.
6. Verify: dock sensor released AND grab sensor pressed → else E0051+tool
   (`ERR_GRAB_VERIFY_BASE`; the app's own code here was not recovered).
7. Apply per-tool G-code offsets (see `40-offsets.md`).
8. `SET_VELOCITY_LIMIT ACCEL=20000`.

Feedrates: test.json `grabSpeed`/`grabSpeedSlow` × 60, fallbacks 24000/6000.

## Release — `doReleaseExtruderLatest` @0x7aa394

Not symmetric with grab; the details matter:

1. Home gate.
2. Dock-must-be-EMPTY precheck, 20 × 50 ms; failure → E0131+tool, no motion.
3. `ACCEL=8000`; clear X/Y offsets. No ACTIVATE_EXTRUDER anywhere on release.
4. Approach once: `G1 X250 F<fast>`, `G1 Y<dockY>`. **No X280 stage** (grab-only).
5. Up to 3 attempts, each: `G1 X<dockX-10>` (no F, modal feed) → `G1 X<dockX> F<slow>`
   (slow fallback here is **5400**, not 6000) → wait up to 20 × 50 ms for the dock
   sensor to read "seated" → only then `MOTOR_RELEASE` → supervise the lock endstop;
   "ended untriggered" → re-issue MOTOR_RELEASE, max 3 sends per attempt.
6. Success only: retreat `G1 X250 F4800`. On failure the carriage stays at the dock.
7. Verify: in dock AND grab sensor clear → else E0144; all-attempts-exhausted →
   E0135+tool.
8. Unconditional tail (success AND failure): `MOTOR_STOP`, `ACCEL=20000`
   (hence try/finally in the port).

In-process advantage: the app greps response text for "endstop (not) triggered" and
polls 40 × 50 ms; a klippy extra just catches `printer.command_error` from
`MOTOR_RELEASE` synchronously — a strictly stronger signal.

## Mid-print change (`changeExtruderChannel`)

Save state (`SAVE_GCODE_STATE NAME=PAUSE_state`), manage temps, release old → grab
new, prime `G1 E15 F240` / retract with part-fan ooze control, `RESTORE_GCODE_STATE
MOVE=1`, restore `M220`.

## Which tool is mounted

The app persists an imperative index (`now_extruder` in extruder.json), reset to −1 by
homing, and never derives it from sensors — because its grab-sensor read
(`getGrabSensorStatus` @0x76f294) is a plain OR of four bytes: it knows only *that*
something is held, never *which*.

`ff_toolchange.py` derives identity instead: `extruder_pos1..4` are per-tool dock
switches, so **the mounted tool is the one whose dock is empty** (while the grab
sensor is pressed). Exactly-one-empty + held → that tool; all-occupied + held, or
several-empty + held → abort (faulty switch / ambiguous — refusing beats guessing,
since guessing wrong would drop the carried tool into another tool's dock).
Nothing is persisted; the value cannot go stale. `now_extruder` is never written
(see `40-offsets.md` on why writing the JSON is forbidden), and it is no longer
read either: the JSON reader was removed, so `TOOLCHANGE_STATUS` reports only
sensors and Klipper config and has nothing to compare against.

## Deliberate divergences in the port

1. No 4th unsupervised `MOTOR_RELEASE` (the app fires one before checking its own
   failure counter — energising the lock with nobody watching).
2. No `M119` refresh polls — Klipper's `gcode_button` state is event-driven; the
   20 × 50 ms *gating* semantics are kept as wall-clock deadlines.
3. `now_extruder` not written; identity is sensor-derived.
4. Modal-state restore added: the app leaks G90 + last feedrate + accel into whatever
   runs next; the port snapshots and restores absolute/relative mode, feedrate, and
   the pre-sequence accel limit.