Z-A coupling: drop active jog/MDI auto-coordination, keep refuse-only check

The active rewriter for jogs/MDI didn't help anyway because the
continuous-jog buttons send rate-based /api/jog commands to the AVR
and bypass the planner+MDI path entirely. Rather than build out
continuous-jog coupling on the ESP firmware or fake it with browser
ticks, simplify back to:

  * Runtime check (Planner.__encode + ExternalAxis motion entry
    points) refuses any move that would worsen the Z-A gap. Already
    improvement-aware so X/Y jogs and Z-up/A-down recoveries pass.
  * File preprocessor (AuxPreprocessor) injects pre-position A
    moves into uploaded gcode so well-formed programs run without
    operator intervention.

Operator workflow: jog freely down to the safe band; if you need to
go deeper, lower A first (aux jog mm) or use a step-jog MDI like
'G91 G0 Z-10 A-10' that includes the A delta. Programs do the right
thing on their own.

scripts/rc.local

@@ -28,4 +28,4 @@ plymouth quit
 
 # Start X in /home/pi
 cd /home/pi
-sudo -u pi startx
+sudo -u pi startx -- -nocursor

scripts/rc.local.fast

@@ -34,7 +34,9 @@ plymouth quit 2>/dev/null || true
 # late-boot units (bbctrl logrotate, etc.) don't block on it. Output
 # is redirected so the journal doesn't fill up with X warnings.
 cd /home/pi
-nohup sudo -u pi startx >/var/log/onefin-x.log 2>&1 &
+# `-- -nocursor` hides the X pointer; this is a touchscreen kiosk and
+# the mouse cursor only gets in the way.
+nohup sudo -u pi startx -- -nocursor >/var/log/onefin-x.log 2>&1 &
 disown
 
 exit 0

scripts/setup_rpi.sh

@@ -75,7 +75,7 @@ sed -i 's/^PARTUUID=.*\//\/dev\/mmcblk0p2 \//' /etc/fstab
 
 # Enable browser in xorg
 sed -i 's/allowed_users=console/allowed_users=anybody/' /etc/X11/Xwrapper.config
-echo "sudo -u pi startx" >> /etc/rc.local
+echo "sudo -u pi startx -- -nocursor" >> /etc/rc.local
 cp /mnt/host/xinitrc /home/pi/.xinitrc
 cp /mnt/host/ratpoisonrc /home/pi/.ratpoisonrc
 cp /mnt/host/xorg.conf /etc/X11/

src/js/a-axis-view.js

@@ -1,16 +1,16 @@
 "use strict";
 
-// V09 W-axis page \u2014 mounts the existing WAxisSettings Svelte component
+// V09 A-axis page — mounts the AAxisSettings Svelte component
 // inside the settings shell so it gets a real top-level rail entry
 // instead of being a soft-link anchor inside Display & Units.
 
 module.exports = {
-    template: "#w-axis-view-template",
+    template: "#a-axis-view-template",
 
     attached: function () {
         this.svelteComponent = SvelteComponents.createComponent(
-            "WAxisSettings",
-            document.getElementById("w-axis-mount")
+            "AAxisSettings",
+            document.getElementById("a-axis-mount")
         );
     },
 

src/js/app.js

@@ -369,7 +369,7 @@ module.exports = new Vue({
     ready: function() {
         window.onhashchange = () => this.parse_hash();
 
-        // Embedded Svelte subviews (W axis settings, etc.) signal
+        // Embedded Svelte subviews (A axis settings, etc.) signal
         // unsaved changes via this event. The master Save button
         // highlights when modified is true.
         window.addEventListener("onefin:dirty", () => {
@@ -391,7 +391,7 @@ module.exports = new Vue({
             "admin-general", "admin-network",
             "motor", "tool", "io", "macros",
             "help", "cheat-sheet",
-            "w-axis",
+            "a-axis",
         ];
         const initialHead = (location.hash || "").replace(/^#/, "").split(":")[0];
         if (settingsFamily.indexOf(initialHead) === -1) {
@@ -627,7 +627,7 @@ module.exports = new Vue({
                 "admin-general", "admin-network",
                 "motor", "tool", "io", "macros",
                 "help", "cheat-sheet",
-                "w-axis",
+                "a-axis",
             ];
 
             if (head == "control") {
@@ -690,7 +690,7 @@ module.exports = new Vue({
             try {
                 await api.put("config/save", this.config);
                 // Notify any embedded Svelte subviews that own their
-                // own persistence (W axis -> aux.json, etc.) that
+                // own persistence (A axis -> aux.json, etc.) that
                 // the user just hit the master Save button. They
                 // listen for `onefin:save-all` and PUT their state.
                 try {

src/js/axis-vars.js

@@ -56,7 +56,12 @@ module.exports = {
             const abs = this.state[`${axis}p`] || 0;
             const off = this.state[`offset_${axis}`];
             const motor_id = this._get_motor_id(axis);
-            const motor = motor_id == -1 ? {} : this.config.motors[motor_id];
+            // motor_id may be 4 for the synthetic external-axis motor;
+            // there is no entry for it in config.motors so guard with
+            // an empty object to avoid undefined property access.
+            const motor = (motor_id == -1
+                ? {}
+                : (this.config.motors[motor_id] || {}));
             const enabled = this._check_is_enabled(axis);
             const homingMode = motor["homing-mode"];
             const homed = this.state[`${motor_id}homed`];
@@ -198,6 +203,17 @@ module.exports = {
                 }
             }
 
+            // Synthetic external motor (index 4) used by ExternalAxis
+            // to expose the auxcnc ESP stepper as a virtual axis.
+            // Its `Nan` lives in state, not config.
+            const axes = { x: 0, y: 1, z: 2, a: 3, b: 4, c: 5 };
+            const wanted = axes[axis];
+            const extAn = this.state && this.state["4an"];
+            if (typeof wanted === "number" && typeof extAn === "number"
+                && extAn === wanted) {
+                return 4;
+            }
+
             return -1;
         },
 
@@ -226,14 +242,25 @@ module.exports = {
                     }
                 }
             }
+            // Synthetic external motor (index 4) - the auxcnc ESP
+            // stepper exposed as A via ExternalAxis.
+            if (typeof wanted === "number") {
+                const extAn = this.state["4an"];
+                const extMe = this.state["4me"];
+                if (typeof extAn === "number" && extAn === wanted
+                    && extMe) {
+                    return true;
+                }
+            }
             return false;
         },
 
         _compute_aux_axis: function() {
-            // Virtual W axis driven by the auxcnc ESP32. Position, homed
-            // flag and presence come from the bbctrl AuxAxis driver via
-            // state.aux_*. No motor mapping, no soft-limit warnings on
-            // toolpath bounds (auxcnc enforces its own).
+            // Auxiliary axis driven by the auxcnc ESP32 (typically
+            // exposed to gplan as A). Position, homed flag and
+            // presence come from the bbctrl AuxAxis driver via
+            // state.aux_*. No motor mapping, no soft-limit warnings
+            // on toolpath bounds (auxcnc enforces its own).
             const enabled = !!this.state.aux_enabled;
             const present = !!this.state.aux_present;
             const homed   = !!this.state.aux_homed;
@@ -243,12 +270,12 @@ module.exports = {
             let state = present ? "UNHOMED" : "OFFLINE";
             let icon  = present ? "question-circle" : "plug";
             let title = present
-                ? "Click the home button to home W axis."
+                ? "Click the home button to home the auxiliary axis."
                 : "Aux controller not connected on /dev/ttyUSB0.";
             if (homed) {
                 state = "HOMED";
                 icon  = "check-circle";
-                title = "W axis successfully homed.";
+                title = "Auxiliary axis successfully homed.";
             } else if (!present) {
                 klass += " error";
             }
@@ -269,7 +296,7 @@ module.exports = {
                 title: title,
                 ticon: "check-circle",
                 tstate: "OK",
-                toolmsg: "W axis is not constrained by tool path bounds.",
+                toolmsg: "Auxiliary axis is not constrained by tool path bounds.",
                 tklass: `${homed ? "homed" : "unhomed"} axis-w`,
                 isAux: true,
             };

src/js/control-view.js

@@ -251,28 +251,74 @@ module.exports = {
 
     aux_home: function () {
       api.put("aux/home").catch(function (err) {
-        console.error("W home failed:", err);
+        console.error("Aux home failed:", err);
       });
     },
 
-    // Home every enabled axis at once (legacy Onefinity behavior).
-    // The XYZ home is fired first via the standard /api/home endpoint,
-    // then the W axis is homed if it is enabled. The two cycles run
-    // in parallel — W is on the auxcnc ESP and doesn't share motors
-    // with the AVR — so the user sees one click homing everything.
-    home_all: function () {
+    // Home every enabled axis (legacy Onefinity "Home All"). Sequence:
+    //   1. Z, X, Y (and A/B/C if enabled)  via /api/home on the AVR
+    //   2. Auxiliary axis                  via /api/aux/home on the ESP
+    //      ONLY when the auxcnc axis is not integrated as a virtual
+    //      machine axis. With the gplan A-axis integration (synthetic
+    //      motor 4 enabled), Mach.home() already homes the external
+    //      axis as part of the xyzabc pass - calling aux/home
+    //      afterwards would home it a second time.
+    // /api/home returns as soon as the request is queued, not when
+    // homing completes, so we have to watch state.cycle:
+    //   - first wait for it to *leave* 'idle' (cycle began),
+    //   - then wait for it to come *back* to 'idle' (cycle ended).
+    // Only then do we fire the auxiliary home, so the gantry and the
+    // auxcnc ESP never move at the same time.
+    home_all: async function () {
       this.ask_home = false;
-      api.put("home");
-      if (this.w && this.w.enabled) {
-        api.put("aux/home").catch(function (err) {
-          console.error("W home failed:", err);
-        });
+      try {
+        await api.put("home");
+      } catch (e) {
+        console.error("Home all (XYZ) failed:", e);
+        return;
       }
+      if (!this.w || !this.w.enabled) return;
+
+      // When the synthetic external motor (index 4) is enabled,
+      // the auxcnc axis is mapped onto a real machine axis letter
+      // (e.g. A) and was already homed by /api/home above.
+      if (this.state && this.state["4me"]) return;
+
+      const wait = (ms) => new Promise(r => setTimeout(r, ms));
+      const cycleNow = () => (this.state && this.state.cycle) || "idle";
+
+      // Phase 1: wait up to 5s for the homing cycle to actually start.
+      // If the request was rejected upstream (e.g. estopped) cycle
+      // never leaves idle and we bail rather than home A in isolation.
+      const startedAt = Date.now();
+      while (Date.now() - startedAt < 5000) {
+        if (cycleNow() != "idle") break;
+        await wait(100);
+      }
+      if (cycleNow() == "idle") {
+        console.warn("home_all: main homing cycle never started; skipping aux");
+        return;
+      }
+
+      // Phase 2: wait up to 2 minutes for the gantry to finish.
+      const settledAt = Date.now();
+      while (Date.now() - settledAt < 120000) {
+        if (cycleNow() == "idle") break;
+        await wait(200);
+      }
+      if (cycleNow() != "idle") {
+        console.warn("home_all: gantry homing did not complete in time");
+        return;
+      }
+
+      api.put("aux/home").catch(function (err) {
+        console.error("Aux home failed:", err);
+      });
     },
 
     aux_jog: function (delta_mm) {
       api.put("aux/jog", { mm: delta_mm }).catch(function (err) {
-        console.error("W jog failed:", err);
+        console.error("Aux jog failed:", err);
       });
     },
 

src/js/program-mixin.js

@@ -79,17 +79,28 @@ module.exports = {
 
     // True only while a loaded G-code program is actually being
     // executed (running, paused/holding, or stopping). Excludes
-    // jogging, homing, MDI commands and other one-off motion that
-    // also leave state.cycle != 'idle' but should not bring up the
-    // "Now Running" panel on the Control tab.
+    // jogging, homing, probing, MDI commands and other one-off
+    // motion that also leave state.xx == "RUNNING" but must not
+    // swap the jog grid out for the "Now Running" panel.
+    //
+    // Distinguishing signal is state.cycle:
+    //   - "idle"    : nothing happening
+    //   - "jogging" : user-initiated jog
+    //   - "homing"  : home cycle
+    //   - "probing" : probe cycle
+    //   - "mdi"     : single MDI command
+    //   - "running" : an actual loaded program is being run
+    // Only "running" (combined with a selected file) is what we want.
     is_program_executing: function () {
-      const xx = this.state && this.state.xx;
-      if (xx == "RUNNING" || xx == "HOLDING" || xx == "STOPPING") {
-        // Only count it as a program run if a file is selected.
-        // Otherwise an MDI submission also reads xx=RUNNING.
-        return !!(this.state && this.state.selected);
-      }
-      return false;
+      if (!this.state) return false;
+      const xx = this.state.xx;
+      const cycle = this.state.cycle;
+      const isExecState = xx == "RUNNING" || xx == "HOLDING" || xx == "STOPPING";
+      if (!isExecState) return false;
+      // The cycle string narrows it to a real program run; anything
+      // else (jogging / homing / probing / mdi) is a one-off.
+      if (cycle && cycle != "running" && cycle != "idle") return false;
+      return !!this.state.selected;
     },
 
     is_paused: function () {
@@ -553,23 +564,43 @@ module.exports = {
     override_feed:  function () { api.put(`override/feed/${this.feed_override}`); },
     override_speed: function () { api.put(`override/speed/${this.speed_override}`); },
 
-    run_macro: function (id) {
+    run_macro: async function (id) {
       if (this.state.macros[id].file_name == "default") {
         this.showNoGcodeMessage = true;
-      } else {
-        if (this.state.macros[id].file_name != this.state.selected) {
-          this.state.selected = this.state.macros[id].file_name;
+        return;
       }
+      const file_name = this.state.macros[id].file_name;
       try {
+        // Selecting a file on the server is a side effect of
+        // GET /api/file/<name>. The macro button used to mutate
+        // state.selected client-side and immediately call start, which
+        // raced the file fetch: if the server hadn't seen the new
+        // selection yet, mach.start() ran whichever file was selected
+        // last. Do it explicitly and await so start always sees the
+        // right file.
+        if (file_name != this.state.selected) {
+          this.state.selected = file_name;
+          // GET /api/file/<name> returns gcode text (not JSON), so use
+          // fetch directly. The server's FileHandler.get sets
+          // state.selected as a side effect; we await the response
+          // before starting so mach.start() reads the right file.
+          const resp = await fetch(
+            `/api/file/${encodeURIComponent(file_name)}`,
+            { cache: "no-cache" }
+          );
+          if (!resp.ok) {
+            throw new Error(`file fetch failed: ${resp.status}`);
+          }
+          await resp.text();
+        }
         this.load();
         if (this.state.macros[id].alert == true) {
           this.macrosLoading = true;
         } else {
-            setImmediate(() => this.start_pause());
+          await this.start_pause();
         }
       } catch (error) {
-          console.warn("Error running program: ", error);
-        }
+        console.warn("Error running macro: ", error);
       }
     },
   },

src/js/settings-shell-view.js

@@ -24,7 +24,7 @@ module.exports = {
     "io-view":                 require("./io-view"),
     "macros-view":             require("./macros"),
     "help-view":               require("./help-view"),
-    "w-axis-view":             require("./w-axis-view"),
+    "a-axis-view":             require("./a-axis-view"),
     "cheat-sheet-view": {
       template: "#cheat-sheet-view-template",
       data: function () {
@@ -57,9 +57,9 @@ module.exports = {
         { sub: "motor", motor: 1, href: "#motor:1", icon: "fa-arrows-up-down-left-right", label: "Motor 1" },
         { sub: "motor", motor: 2, href: "#motor:2", icon: "fa-arrows-up-down-left-right", label: "Motor 2" },
         { sub: "motor", motor: 3, href: "#motor:3", icon: "fa-arrows-up-down-left-right", label: "Motor 3" },
-        // W axis is auxiliary (auxcnc ESP32). It mounts the existing
-        // WAxisSettings Svelte component on its own page.
-        { sub: "w-axis", href: "#w-axis", icon: "fa-arrows-up-down", label: "W Axis" },
+        // Auxiliary axis (auxcnc ESP32 - exposed to gplan as A).
+        // Mounts the AAxisSettings Svelte component on its own page.
+        { sub: "a-axis", href: "#a-axis", icon: "fa-arrows-up-down", label: "A Axis" },
         { section: " " },
         { sub: "help",           href: "#help",           icon: "fa-circle-question", label: "Help" },
       ],
@@ -137,7 +137,7 @@ module.exports = {
         // layout, which under tablet mode pulls the fixed header out
         // of view.
         if (location.hash !== item.href) location.hash = item.href;
-        this._w_axis_focus = (item.sub === "w-axis");
+        this._a_axis_focus = (item.sub === "a-axis");
         const reset = () => {
           // Force any inadvertent ancestor scroll back to 0 before
           // we move .settings-content explicitly.
@@ -160,7 +160,7 @@ module.exports = {
           requestAnimationFrame(reset);
         }, 320);
       } else {
-        this._w_axis_focus = false;
+        this._a_axis_focus = false;
         if (location.hash !== item.href) location.hash = item.href;
         // Reset .app-body scroll so each route starts at the top.
         const body = document.querySelector(".app-body");

src/pug/templates/a-axis-view.pug

@@ -0,0 +1,4 @@
+script#a-axis-view-template(type="text/x-template")
+  #a-axis-page
+    h1 A Axis (auxcnc)
+    #a-axis-mount

src/pug/templates/control-view.pug

@@ -92,17 +92,21 @@ script#control-view-template(type="text/x-template")
             .fa.fa-arrow-down.ico(style="transform: rotate(-45deg)")
           button.jbtn(@click="jog_fn(0, 0, -1, 0)") Z−
 
-          // Row 4 — W axis (auxcnc) when enabled.
-          //   W-  |  W+  |  Probe XYZ  |  Probe Z
-          // "Home W" lives in the DRO table's actions column on the
-          // right, so it doesn't need a tile here.
-          template(v-if="w.enabled")
-            button.jbtn(@click="aux_jog_incr(-1)", :disabled="!w.enabled")
+          // Row 4 — A axis (the auxcnc-driven external axis) when enabled.
+          //   A-  |  A+  |  Probe XYZ  |  Probe Z
+          // "Home A" lives in the DRO table's actions column on the
+          // right, so it doesn't need a tile here. The legacy w.enabled
+          // gate is kept so older installs (where the auxcnc axis still
+          // appears as W via the side-channel) keep working.
+          template(v-if="w.enabled || a.enabled")
+            button.jbtn(@click="aux_jog_incr(-1)",
+              :disabled="!(w.enabled || a.enabled)")
               .fa.fa-arrow-down.ico
-              span.lbl W−
-            button.jbtn(@click="aux_jog_incr(+1)", :disabled="!w.enabled")
+              span.lbl A−
+            button.jbtn(@click="aux_jog_incr(+1)",
+              :disabled="!(w.enabled || a.enabled)")
               .fa.fa-arrow-up.ico
-              span.lbl W+
+              span.lbl A+
             button.jbtn(@click="showProbeDialog('xyz')",
               :class="{'load-on': !state['pw']}")
               .fa.fa-bullseye.ico
@@ -211,13 +215,11 @@ script#control-view-template(type="text/x-template")
             div Position
             div Absolute
             div Offset
-            div State
-            div Toolpath
             .actions-cell
               // Master Home All. Each row's Actions cell has a per-axis
               // home button; this header-level button homes every
               // enabled axis (legacy Onefinity behavior). Auto-includes
-              // the W axis when it is enabled.
+              // the auxiliary A axis when it is enabled.
               button.icon-btn(:disabled="!is_idle",
                 title="Home all axes.", @click="home_all()")
                 .fa.fa-house-chimney
@@ -226,56 +228,47 @@ script#control-view-template(type="text/x-template")
           each axis in 'xyzabc'
             .dro-row(:class=`${axis}.klass + ' ' + ${axis}.tklass`,
               v-if=`${axis}.enabled`,
-              :title=`${axis}.title`)
+              :title=`${axis}.toolmsg ? (${axis}.title + ' — ' + ${axis}.toolmsg) : ${axis}.title`)
               .dro-axis(:class=`'axis-' + '${axis}'`)= axis.toUpperCase()
               .dro-pos: unit-value(:value=`${axis}.pos`, precision=4)
               .dro-sec: unit-value(:value=`${axis}.abs`, precision=3)
               .dro-sec: unit-value(:value=`${axis}.off`, precision=3)
-              .dro-state
-                span.chip(:class=`${axis}.tklass.indexOf('error') !== -1 ? 'chip-red' : (${axis}.homed ? 'chip-green' : 'chip-amber')`)
-                  .fa(:class=`'fa-' + ${axis}.icon`)
-                  |  {{#{axis}.state}}
-              .dro-toolpath
-                span.chip(:class=`${axis}.tklass.indexOf('error') !== -1 ? 'chip-red' : (${axis}.tklass.indexOf('warn') !== -1 ? 'chip-amber' : 'chip-green')`,
-                  @click=`showToolpathMessageDialog('${axis}')`)
-                  .fa(:class=`'fa-' + ${axis}.ticon`)
-                  |  {{#{axis}.tstate}}
               .actions-cell
                 button.icon-btn(:disabled="!can_set_axis",
                   :title=`'Set ${axis.toUpperCase()} axis position.'`,
                   @click=`show_set_position('${axis}')`)
                   .fa.fa-gear
-                button.icon-btn(:disabled="!can_set_axis",
-                  :title=`'Zero ${axis.toUpperCase()} axis offset.'`,
+                button.icon-btn(:class=`${axis}.tklass.indexOf('error') !== -1 ? 'state-red' : (${axis}.tklass.indexOf('warn') !== -1 ? 'state-amber' : 'state-green')`,
+                  :disabled="!can_set_axis",
+                  :title=`${axis}.toolmsg || ('Zero ${axis.toUpperCase()} axis offset.')`,
                   @click=`zero('${axis}')`)
                   .fa.fa-location-dot
-                button.icon-btn(:disabled="!is_idle",
-                  :title=`'Home ${axis.toUpperCase()} axis.'`,
+                button.icon-btn(:class=`${axis}.klass.indexOf('error') !== -1 ? 'state-red' : (${axis}.homed ? 'state-green' : 'state-amber')`,
+                  :disabled="!is_idle",
+                  :title=`${axis}.title`,
                   @click=`home('${axis}')`)
                   .fa.fa-home
 
-          // W axis (auxiliary) — no offset, no set-zero / no set-position
-          .dro-row(:class="w.klass + ' ' + w.tklass", v-if="w.enabled",
+          // Legacy auxiliary-axis row - shown only when the auxcnc stepper is
+          // *not* exposed as a virtual A axis. After v2 the standard
+          // A row above renders this axis natively (with full offset
+          // + set-position support); this row only appears on legacy
+          // installs that haven't migrated yet.
+          .dro-row(:class="w.klass + ' ' + w.tklass",
+            v-if="w.enabled && !a.enabled",
             :title="w.title")
             .dro-axis.axis-w W
             .dro-pos: unit-value(:value="w.pos", precision=4)
             .dro-sec: unit-value(:value="w.abs", precision=3)
             .dro-sec —
-            .dro-state
-              span.chip(:class="w.homed ? 'chip-green' : 'chip-amber'")
-                .fa(:class="'fa-' + w.icon")
-                |  {{w.state}}
-            .dro-toolpath
-              span.chip.chip-green
-                .fa(:class="'fa-' + w.ticon")
-                |  {{w.tstate}}
             .actions-cell
               button.icon-btn(disabled, style="visibility:hidden")
                 .fa.fa-gear
               button.icon-btn(disabled, style="visibility:hidden")
                 .fa.fa-location-dot
-              button.icon-btn(:disabled="!w.enabled",
-                title="Home W axis.", @click="aux_home()")
+              button.icon-btn(:class="w.homed ? 'state-green' : 'state-amber'",
+                :disabled="!w.enabled",
+                title="Home auxiliary axis.", @click="aux_home()")
                 .fa.fa-home
 
         // ----- Status strip -----

src/pug/templates/settings-shell.pug

@@ -46,7 +46,7 @@ script#settings-shell-view-template(type="text/x-template")
         :index="index", :config="config", :template="template", :state="state")
       io-view(v-if="sub === 'io' && config_ready",
         :index="index", :config="config", :template="template", :state="state")
-      w-axis-view(v-if="sub === 'w-axis' && config_ready",
+      a-axis-view(v-if="sub === 'a-axis' && config_ready",
         :index="index", :config="config", :template="template", :state="state")
       macros-view(v-if="sub === 'macros' && config_ready",
         :index="index", :config="config", :template="template", :state="state")

src/pug/templates/w-axis-view.pug

@@ -1,4 +0,0 @@
-script#w-axis-view-template(type="text/x-template")
-  #w-axis-page
-    h1 W Axis (auxcnc)
-    #w-axis-mount

src/py/bbctrl/AuxAxis.py

@@ -33,11 +33,27 @@ DEFAULTS = {
     'enabled':           False,
     'port':              '/dev/ttyUSB0',
     'baud':              115200,
-    'steps_per_mm':      80.0,    # logical steps per mm of W travel
+    'steps_per_mm':      80.0,    # logical steps per mm of axis travel
     'dir_sign':          1,       # +1 or -1: maps logical+ to motor+ steps
-    'min_w':             0.0,     # soft limit min (mm)
-    'max_w':             100.0,   # soft limit max (mm)
-    'max_feed_mm_min':   600.0,   # informational; rate caps are on the ESP
+    # Logical axis letter exposed to gplan. The auxcnc ESP stepper
+    # is presented to the planner as this axis (default 'a' = standard
+    # 4th axis). gcode uses A for moves; the host ExternalAxis layer
+    # forks A motion to the ESP transparently.
+    'axis_letter':       'a',
+    'min_mm':            0.0,     # soft limit min (mm), exposed as 4tn
+    'max_mm':            100.0,   # soft limit max (mm), exposed as 4tm
+    # Per-axis kinematic limits used to populate the planner's config.
+    # Units match the bbctrl/onefinity per-motor convention so the
+    # values are directly comparable to motors 0-3:
+    #   max_velocity_m_per_min   m/min   (planner sees * 1000 = mm/min)
+    #   max_accel_km_per_min2    km/min2 (planner sees * 1e6 = mm/min2)
+    #   max_jerk_km_per_min3     km/min3 (planner sees * 1e6 = mm/min3)
+    'max_velocity_m_per_min':   6.0,
+    'max_accel_km_per_min2':  100.0,
+    'max_jerk_km_per_min3':   500.0,
+    # Informational only - rate caps that actually clamp the move
+    # are on the ESP via step_max_sps below.
+    'max_feed_mm_min':   600.0,
     'home_dir':          '-',     # which direction is "toward limit" (host's view)
     'home_position_mm':  0.0,     # mm value to assign at home
     # ESP-side homing rates (steps/sec). Pushed via HOMECFG on connect.
@@ -50,10 +66,34 @@ DEFAULTS = {
     'home_slow_sps':     250,     # ≈  10 mm/s
     'home_backoff_steps': 400,    # ≈  16 mm
     'home_maxtravel_steps': 200000,
+    # If HOME starts with the limit switch already tripped the ESP
+    # first moves this many steps away from the limit and then
+    # rechecks. If the switch is still active afterward, HOME hard-
+    # fails (refuses to set zero blindly when we may already be past
+    # the home position). Default ≈ 10 mm @ 25 steps/mm. Set to 0 to
+    # disable the preclear move (HOME then fails immediately if the
+    # switch reads active at start, matching the original behaviour).
+    'home_preclear_mm':  10.0,
     'step_max_sps':      4000,    # ≈ 160 mm/s normal-move cap
     'step_accel_sps2':   12000,
     'step_start_sps':    200,
     'limit_low':         True,
+    # ------------------------------------------------------------------
+    # Z-A coupling interlock
+    # ------------------------------------------------------------------
+    # The auxiliary A axis carries a tool that physically hangs below
+    # the Z-axis spindle nose. Beyond a certain Z descent the two
+    # collide unless A drops with Z. The constraint, in machine coords,
+    # is:
+    #     A_machine - Z_machine <= K
+    # where K = (A_home_mm - z_home_mm) + couple_z_clearance_mm.
+    # When enabled this is enforced everywhere motion can be
+    # initiated (planner, MDI, jog, file load) and the AuxPreprocessor
+    # injects pre-position A moves before Z descends past the safe
+    # band.
+    'couple_z_enabled':       True,
+    'couple_z_clearance_mm':  22.0,   # Z drop allowed before A must follow
+    'z_home_mm':              0.0,    # Z's machine position when homed
 }
 
 
@@ -104,23 +144,61 @@ class AuxAxis(object):
     def _config_path(self):
         return self.ctrl.get_path(filename='aux.json')
 
+    # Legacy aux.json fields that have been renamed for clarity.
+    # Loaded values are migrated up on every load/save so existing
+    # installs keep working without operator intervention.
+    _LEGACY_FIELD_MAP = {
+        'min_w': 'min_mm',
+        'max_w': 'max_mm',
+    }
+
+    def _migrate_legacy_fields(self, cfg):
+        """In-place rename of legacy keys in `cfg` (dict). Returns
+        True if anything was migrated, so callers can decide whether
+        to persist the upgraded form.
+        """
+        migrated = False
+        for old, new in self._LEGACY_FIELD_MAP.items():
+            if old in cfg:
+                if new not in cfg:
+                    cfg[new] = cfg[old]
+                del cfg[old]
+                migrated = True
+        return migrated
+
     def _load_config(self):
         path = self._config_path()
         if os.path.exists(path):
             try:
                 with open(path) as f:
                     user = json.load(f)
+                migrated = self._migrate_legacy_fields(user)
                 # Be permissive; ignore unknown keys.
                 for k, v in user.items():
                     if k in self._cfg:
                         self._cfg[k] = v
                 self.log.info('Loaded aux config from %s' % path)
+                if migrated:
+                    # Persist the upgraded form so future restarts
+                    # see the new field names directly.
+                    try:
+                        self.save_config(self._cfg)
+                        self.log.info(
+                            'Migrated aux.json legacy fields '
+                            '(min_w/max_w -> min_mm/max_mm)')
+                    except Exception:
+                        self.log.warning(
+                            'Could not persist aux.json migration')
             except Exception:
                 self.log.error('Failed to read aux.json: %s'
                                % traceback.format_exc())
 
     def save_config(self, cfg):
         merged = dict(DEFAULTS)
+        # Accept legacy keys from callers that may still send the
+        # old names (older UI bundles, hand-edited POSTs).
+        cfg = dict(cfg)
+        self._migrate_legacy_fields(cfg)
         for k, v in cfg.items():
             if k in DEFAULTS:
                 merged[k] = v
@@ -157,6 +235,11 @@ class AuxAxis(object):
     def position_mm(self):
         return self._steps_to_mm(self._pos_steps)
 
+    def set_state_observer(self, fn):
+        """Register a callback invoked after every _publish_state.
+        Used by ExternalAxis to mirror the homed flag into State."""
+        self._state_observer = fn
+
     def home(self):
         """Run the homing cycle on the ESP. Blocks until done. Raises on
         failure. Updates aux_homed and aux_pos.
@@ -230,6 +313,55 @@ class AuxAxis(object):
         except Exception as e:
             self.log.warning('ABORT send failed: %s' % e)
 
+    # ---------------------------------------------------------- ATC commands
+    #
+    # The auxcnc firmware drives an AMB 1050 FME-W DI tool changer via
+    # three pneumatic valves on relays 1-3. The ESP runs the timed
+    # sequences itself; the host just kicks them off and waits for the
+    # terminal reply.
+
+    def atc_droptool(self, timeout=30.0):
+        """Eject the current tool. Opens the collet (V1), oscillates the
+        ejector (V2), then re-clamps with a bleed cycle. Blocks until
+        the ESP reports done. Raises on failure."""
+        self._require_present()
+        line = self._rpc('DROPTOOL', topic='droptool', timeout=timeout)
+        if line.startswith('done'):
+            return
+        reason = line.split('reason=', 1)[1] if 'reason=' in line else line
+        raise AuxAxisError('DROPTOOL failed: %s' % reason)
+
+    def atc_grabtool(self, timeout=30.0):
+        """Pick up a tool that's already been seated by the operator.
+        Opens V1 (releases the collet), waits for the operator to insert
+        the holder, then re-clamps with a bleed cycle. Blocks."""
+        self._require_present()
+        line = self._rpc('GRABTOOL', topic='grabtool', timeout=timeout)
+        if line.startswith('done'):
+            return
+        reason = line.split('reason=', 1)[1] if 'reason=' in line else line
+        raise AuxAxisError('GRABTOOL failed: %s' % reason)
+
+    def atc_release(self, timeout=5.0):
+        """Manually open the collet (release-only, no clamp). Use
+        atc_clamp() afterwards once the new holder is in place."""
+        self._require_present()
+        line = self._rpc('RELEASE', topic='release', timeout=timeout)
+        if line.startswith('done'):
+            return
+        reason = line.split('reason=', 1)[1] if 'reason=' in line else line
+        raise AuxAxisError('RELEASE failed: %s' % reason)
+
+    def atc_clamp(self, timeout=10.0):
+        """Manually clamp the collet (run a full bleed cycle). Pairs
+        with atc_release() for two-step manual tool changes."""
+        self._require_present()
+        line = self._rpc('CLAMP', topic='clamp', timeout=timeout)
+        if line.startswith('done'):
+            return
+        reason = line.split('reason=', 1)[1] if 'reason=' in line else line
+        raise AuxAxisError('CLAMP failed: %s' % reason)
+
     def close(self):
         self._stop.set()
         try:
@@ -247,13 +379,13 @@ class AuxAxis(object):
             raise AuxAxisError('Aux axis not connected')
 
     def _check_limits(self, target_mm):
-        lo = float(self._cfg['min_w'])
-        hi = float(self._cfg['max_w'])
+        lo = float(self._cfg['min_mm'])
+        hi = float(self._cfg['max_mm'])
         if hi <= lo:
             return  # no limits
         if target_mm < lo - 1e-6 or target_mm > hi + 1e-6:
             raise AuxAxisError(
-                'W=%.3f out of soft limits [%.3f, %.3f]' % (target_mm, lo, hi))
+                'A=%.3f out of soft limits [%.3f, %.3f]' % (target_mm, lo, hi))
 
     def _mm_to_steps(self, mm):
         spm = float(self._cfg['steps_per_mm'])
@@ -286,6 +418,64 @@ class AuxAxis(object):
             raise AuxAxisError('W move aborted by limit switch')
         raise AuxAxisError('W move aborted: %s' % line)
 
+    def _do_line(self, signed_steps, length_mm,
+                 max_accel_mm_min2, max_jerk_mm_min3,
+                 entry_vel_mm_min, exit_vel_mm_min,
+                 times_min, ignore_limits=False, timeout=300.0):
+        """Run a 7-segment jerk-limited S-curve on the ESP that mirrors
+        gplan/buildbotics' planner output exactly.
+
+        Parameters are in the same units the AVR/gplan use:
+          - length_mm:       absolute travel in mm (>= 0)
+          - max_accel:       mm/min^2
+          - max_jerk:        mm/min^3
+          - entry/exit_vel:  mm/min
+          - times_min:       7-tuple of section durations in minutes
+
+        ignore_limits sets safe=0 on the ESP - used for jog/move
+        endpoints that may run before homing.
+
+        Blocks until the ESP reports done or aborted. Updates the
+        position mirror and re-publishes state on every reply.
+        """
+        if signed_steps == 0 or length_mm <= 0:
+            return
+        if not any(times_min):
+            raise AuxAxisError('LINE rejected: all section times are zero')
+        # Build the LINE command. Float formatting matches the AVR's
+        # printf precision (6 sig figs) - that's well above what the
+        # ESP needs given it integrates into a few thousand 4 ms
+        # segments per move.
+        parts = [
+            'LINE',
+            'steps=%d' % int(signed_steps),
+            'length=%.6f' % float(length_mm),
+            'max_accel=%.6f' % float(max_accel_mm_min2),
+            'max_jerk=%.6f' % float(max_jerk_mm_min3),
+            'entry_vel=%.6f' % float(entry_vel_mm_min),
+            'exit_vel=%.6f' % float(exit_vel_mm_min),
+        ]
+        for i, t in enumerate(times_min):
+            if t and t > 0:
+                parts.append('t%d=%.9f' % (i, float(t)))
+        if ignore_limits:
+            parts.append('safe=0')
+        cmd = ' '.join(parts)
+        line = self._rpc(cmd, topic='line', timeout=timeout)
+        # line: "done pos=P emitted=N" or "aborted pos=P emitted=N reason=..."
+        if line.startswith('done'):
+            self._pos_steps = self._parse_kv_int(line, 'pos', self._pos_steps)
+            self._publish_state()
+            return
+        # aborted
+        self._pos_steps = self._parse_kv_int(line, 'pos', self._pos_steps)
+        self._publish_state()
+        reason = self._parse_kv_str(line, 'reason')
+        if reason == 'limit':
+            self._homed = False
+            raise AuxAxisError('W move aborted by limit switch')
+        raise AuxAxisError('W move aborted: %s' % line)
+
     # ------------------------------------------------------------ serial I/O
 
     def _open(self):
@@ -318,8 +508,14 @@ class AuxAxis(object):
     def _push_homecfg(self):
         c = self._cfg
         zero_steps = self._mm_to_steps(c['home_position_mm'])
+        # preclear: how far (in steps) the ESP backs off if HOME is
+        # invoked while the limit switch is already tripped. Computed
+        # from home_preclear_mm so the operator configures it in mm.
+        spm = float(c.get('steps_per_mm', 1.0)) or 1.0
+        preclear_steps = int(round(abs(float(c['home_preclear_mm'])) * spm))
         cmd = ('HOMECFG dir=%s fast=%d slow=%d backoff=%d maxtravel=%d '
-               'zero=%d accel=%d step_max=%d step_start=%d limit_low=%d') % (
+               'zero=%d accel=%d step_max=%d step_start=%d limit_low=%d '
+               'preclear=%d') % (
             c['home_dir'],
             int(c['home_fast_sps']),
             int(c['home_slow_sps']),
@@ -330,6 +526,7 @@ class AuxAxis(object):
             int(c['step_max_sps']),
             int(c['step_start_sps']),
             1 if c['limit_low'] else 0,
+            preclear_steps,
         )
         self._rpc(cmd, topic='homecfg', timeout=3.0)
 
@@ -339,6 +536,23 @@ class AuxAxis(object):
             self._pos_steps = int(r.strip())
         except Exception:
             pass
+        # Force the host to start unhomed regardless of what the ESP
+        # remembers from a prior session. The ESP's homed flag survives
+        # bbctrl restarts (since the ESP itself wasn't power-cycled),
+        # but the host's planner offsets and DRO position get reset to
+        # zero on bbctrl boot. Trusting the ESP's homed flag would mean
+        # the user thinks A is homed at the wrong work-coord origin
+        # (offset_a=0 but ESP physically at home_position_mm). Sending
+        # UNHOME forces the user to re-home explicitly, which sets up
+        # the offset and gplan state correctly via the homing path in
+        # Mach.home.
+        try:
+            self._rpc('UNHOME', topic='ok', timeout=2.0)
+            self._homed = False
+        except Exception:
+            # Fall back to whatever HOMED? says - but treat any
+            # missing UNHOME support as "trust ESP's flag" so we
+            # don't break older firmware.
             try:
                 r = self._rpc('HOMED?', topic='homed', timeout=2.0)
                 self._homed = (r.strip() == '1')
@@ -380,7 +594,7 @@ class AuxAxis(object):
             self._present = True
             self._publish_state()
             self.ctrl.state.add_message(
-                'W axis controller restarted - re-home before use')
+                'Auxiliary axis controller restarted - re-home before use')
             return
 
         # Topic dispatch: "[topic] body..."
@@ -482,3 +696,11 @@ class AuxAxis(object):
         except Exception:
             # During very early startup, state may not be ready.
             pass
+        # Notify the external-axis layer so it can mirror state
+        # (e.g. homed flag) into the synthetic motor vars.
+        observer = getattr(self, '_state_observer', None)
+        if observer is not None:
+            try:
+                observer()
+            except Exception:
+                pass

src/py/bbctrl/AuxPreprocessor.py

@@ -1,25 +1,33 @@
 ################################################################################
 #
-# AuxPreprocessor - rewrite W-axis G-code into hook calls
+# AuxPreprocessor - rewrite ATC M-codes into hook calls
 #
-# The bbctrl planner only understands xyzabc. We expose a virtual W axis by
-# rewriting the G-code file *before* it is fed to gplan, replacing each W
-# move with a (MSG,HOOK:aux:...) line that the host's hook handler turns
-# into a STEPS or HOME command on the ESP.
+# History
+# -------
+# v1: rewrote W tokens into (MSG,HOOK:aux:N) lines because the bbctrl
+#     planner only understood XYZABC and the W axis was driven via a
+#     side-channel.
+# v2: W is now exposed to gplan as a virtual A axis (see ExternalAxis),
+#     so gplan handles W motion natively. The preprocessor no longer
+#     touches W tokens. ATC pneumatics still go through the hook
+#     channel because they're events, not motion.
 #
-# Rules:
-#   - Mixed-axis blocks (W together with XYZABC) are split into two
-#     sequential blocks. By default the W move runs first; configurable.
-#   - G90/G91/G20/G21 modal state is tracked so we can convert relative-W
-#     and inch-W into the absolute mm value the hook handler expects.
-#   - G28 W0 / G28.2 W0 -> HOOK:aux_home
-#   - G92 Wx           -> HOOK:aux_setzero:<mm>
-#   - G53 + W not specially handled (W only knows machine coords)
-#   - Lines inside parentheses or after `;` are passed through.
+# What this still does
+# --------------------
+# Maps four user-defined M-codes onto pneumatic-tool-changer events:
+#
+#   M100  DROPTOOL  -> (MSG,HOOK:droptool:)
+#   M101  GRABTOOL  -> (MSG,HOOK:grabtool:)
+#   M102  RELEASE   -> (MSG,HOOK:release:)
+#   M103  CLAMP     -> (MSG,HOOK:clamp:)
+#
+# M100-M103 are in LinuxCNC/Buildbotics' user-defined range, so the
+# planner won't error if the codes leak through unrewritten - it just
+# won't *do* anything. We strip them out and emit the matching hook
+# line in their place.
 #
 # The preprocessor is intentionally conservative: anything it doesn't
-# understand involving W is left alone with a warning, so motion lands in
-# gplan which will complain loudly rather than silently misbehaving.
+# understand is left alone.
 #
 ################################################################################
 
@@ -29,18 +37,39 @@ import shutil
 import tempfile
 
 
-# Match a word like "W12.5" or "W-3" or "w0". Also matches inside the same
-# line as XYZ words. We pull W out specifically.
-_W_TOKEN_RE = re.compile(r'(?<![A-Za-z_0-9])[Ww]\s*([-+]?\d*\.?\d+)')
-
-# Detect any axis-bearing word (so we can tell mixed-axis lines apart).
-_AXIS_WORD_RE = re.compile(r'(?<![A-Za-z_0-9])[XYZABCxyzabc]\s*[-+]?\d*\.?\d+')
-
-# Strip line comments so we don't get fooled by "(W axis)".
+# Strip line comments so we don't get fooled by "(M100 not really)".
 _PAREN_COMMENT_RE = re.compile(r'\([^)]*\)')
 
-# Modal G-code groups we care about.
-_MODAL_RE = re.compile(r'(?<![A-Za-z_0-9])[Gg]\s*0*(\d+(?:\.\d+)?)')
+# ATC pneumatics M-codes mapped onto hook events.
+_ATC_M_CODES = {
+    100: 'droptool',
+    101: 'grabtool',
+    102: 'release',
+    103: 'clamp',
+}
+_ATC_M_RE = re.compile(
+    r'(?<![A-Za-z_0-9])[Mm]\s*0*(' +
+    '|'.join(str(n) for n in _ATC_M_CODES) +
+    r')(?![\w.])'
+)
+
+# Detect a W axis token. We no longer rewrite W to A automatically;
+# instead we warn so the user knows their old gcode needs migration.
+# (The W support was removed when the axis was integrated as a real
+# A axis through gplan.)
+_W_TOKEN_RE = re.compile(r'(?<![A-Za-z_0-9])[Ww]\s*[-+]?\d*\.?\d+')
+
+# Match a single axis word (letter + optional whitespace + signed decimal)
+# for Z, A, X, Y. Used to extract modal targets while preserving the
+# original line for emission. We deliberately ignore I/J/K/R (arc params)
+# because they're not endpoints.
+_AXIS_TOKEN_RES = {
+    'z': re.compile(r'(?<![A-Za-z_0-9])[Zz]\s*([-+]?\d*\.?\d+)'),
+    'a': re.compile(r'(?<![A-Za-z_0-9])[Aa]\s*([-+]?\d*\.?\d+)'),
+    'x': re.compile(r'(?<![A-Za-z_0-9])[Xx]\s*([-+]?\d*\.?\d+)'),
+    'y': re.compile(r'(?<![A-Za-z_0-9])[Yy]\s*([-+]?\d*\.?\d+)'),
+}
+_G_CODE_RE = re.compile(r'(?<![A-Za-z_0-9])[Gg]\s*0*(\d+(?:\.\d+)?)')
 
 
 class AuxPreprocessorError(Exception):
@@ -48,79 +77,240 @@ class AuxPreprocessorError(Exception):
 
 
 class AuxPreprocessor(object):
-    def __init__(self, log=None, w_first=True):
+    def __init__(self, log=None, coupling=None):
+        """`coupling`, when supplied, enables Z-A coupling injection.
+        Expected shape:
+            {
+              'enabled':       bool,
+              'clearance_mm':  float,   # max (A_wc - Z_wc)
+              'a_initial_wc':  float,   # A's work-coord position at
+                                        # file start (typically 0 if
+                                        # operator zeroed at home)
+              'z_initial_wc':  float,   # Z's work-coord position at
+                                        # file start (typically 0)
+            }
+        Pass None to disable injection (preprocessor still rewrites
+        ATC M-codes)."""
         self.log = log
-        # If True, on a mixed-axis line (e.g. G1 X10 W5), emit the W move
-        # first, then the XYZ move. Set False to invert.
-        self.w_first = w_first
+        self._w_warned = False
+        self._coupling = coupling if (coupling and
+                                       coupling.get('enabled')) else None
+        # Modal state used while scanning the file.
+        if self._coupling is not None:
+            self._a_wc = float(coupling.get('a_initial_wc', 0.0))
+            self._z_wc = float(coupling.get('z_initial_wc', 0.0))
+            self._K = float(coupling.get('clearance_mm', 0.0))
+        else:
+            self._a_wc = 0.0
+            self._z_wc = 0.0
+            self._K = 0.0
+        self._g91_warned = False
+        # Distance mode: True for absolute (G90), False for incremental
+        # (G91). Per RS274 the modal default at start is G90.
+        self._g90 = True
 
     def _info(self, msg):
-        if self.log:
-            self.log.info(msg)
+        if self.log: self.log.info(msg)
 
     def _warn(self, msg):
-        if self.log:
-            self.log.warning(msg)
+        if self.log: self.log.warning(msg)
 
     # ------------------------------------------------------------------ scan
 
     @staticmethod
-    def file_uses_w(path):
-        """Quick check: does this file contain any W-axis word? Used to skip
-        preprocessing entirely for files that don't care about W."""
+    def file_uses_aux(path, coupling=None):
+        """Quick check: does this file contain anything the preprocessor
+        would rewrite? Returns True for ATC M-codes always, and for
+        any Z/A move if coupling is enabled (we have to scan to know
+        whether injection is needed, so any motion file qualifies)."""
+        couple_active = bool(coupling and coupling.get('enabled'))
         try:
             with open(path, 'r', encoding='utf-8', errors='replace') as f:
                 for line in f:
                     code = _PAREN_COMMENT_RE.sub('', line)
                     code = code.split(';', 1)[0]
-                    if _W_TOKEN_RE.search(code):
+                    if _ATC_M_RE.search(code):
+                        return True
+                    if couple_active:
+                        if _AXIS_TOKEN_RES['z'].search(code) or \
+                                _AXIS_TOKEN_RES['a'].search(code):
                             return True
         except Exception:
             pass
         return False
 
-    # ------------------------------------------------------------------ core
+    # Backwards-compat alias.
+    file_uses_w = file_uses_aux
 
-    def _strip_w(self, line):
-        """Return (line_without_w, w_value_str_or_None). Only first W kept."""
-        m = _W_TOKEN_RE.search(line)
-        if m is None:
-            return line, None
-        # Remove just the matched W<num> token, preserving surrounding spaces.
-        rewritten = line[:m.start()] + line[m.end():]
-        return rewritten, m.group(1)
+    # ------------------------------------------------------------------ Z-A coupling
+    #
+    # Track modal Z and A targets across the file. Whenever a line
+    # would put A above Z by more than `clearance_mm` (i.e. A_wc -
+    # Z_wc > K), we inject `G0 A<safe>` immediately before it so A is
+    # already at the safe position when Z descends. The injected move
+    # uses G0 (rapid) so it's quick.
+    #
+    # Endpoint-only check: gplan plans line endpoints. As long as
+    # (target_A_wc - target_Z_wc) <= K, the trajectory stays safe
+    # because Z's *minimum* during a single line is its endpoint (Z
+    # moves monotonically along a single line block in absolute
+    # mode) and A is held at the pre-positioned value during the move.
 
-    def _has_other_axis(self, code_no_w):
-        return _AXIS_WORD_RE.search(code_no_w) is not None
-
-    def _detect_modals(self, code, modal):
-        """Update modal dict in-place from G-codes on this line."""
-        for mm in _MODAL_RE.finditer(code):
+    def _extract_g_codes(self, code):
+        """Return the set of G-codes referenced on `code`. Numeric
+        only, e.g. {0, 1, 90, 17}. Used to track modal state."""
+        out = set()
+        for m in _G_CODE_RE.finditer(code):
             try:
-                g = float(mm.group(1))
-            except ValueError:
-                continue
-            if g == 90: modal['abs'] = True
-            elif g == 91: modal['abs'] = False
-            elif g == 20: modal['inch'] = True
-            elif g == 21: modal['inch'] = False
-            # G28 / G28.2 / G92 are detected case-by-case below.
+                out.add(int(float(m.group(1))))
+            except Exception:
+                pass
+        return out
 
-    @staticmethod
-    def _is_g28_like(code):
-        # Match G28 or G28.2 (homing).
-        return bool(re.search(r'(?<![A-Za-z_0-9])[Gg]\s*0*28(?:\.2)?(?![\w.])', code))
+    def _extract_axis(self, axis, code):
+        """Return the last value of `axis` token on `code`, or None."""
+        rx = _AXIS_TOKEN_RES.get(axis)
+        if rx is None:
+            return None
+        last = None
+        for m in rx.finditer(code):
+            try:
+                last = float(m.group(1))
+            except Exception:
+                pass
+        return last
 
-    @staticmethod
-    def _is_g92(code):
-        return bool(re.search(r'(?<![A-Za-z_0-9])[Gg]\s*0*92(?![\w.])', code))
+    def _maybe_inject_a_down(self, code, fout):
+        """Inspect `code` (with comments stripped) for an upcoming Z
+        descent; emit a `G0 A<safe>` line on `fout` if needed and
+        update self._a_wc accordingly. Returns True if anything was
+        injected.
+
+        On a violation that cannot be fixed by lowering A (e.g. the
+        operator wrote `G0 A0` while Z is too deep), raise
+        AuxPreprocessorError so the file load surfaces the problem -
+        per the rule we agreed: error, don't silently insert a Z-up.
+        """
+        if self._coupling is None:
+            return False
+
+        # Distance mode tracking.
+        gs = self._extract_g_codes(code)
+        if 90 in gs: self._g90 = True
+        if 91 in gs:
+            if self._g90 and not self._g91_warned:
+                self._warn(
+                    'AuxPreprocessor: G91 (incremental mode) detected; '
+                    'Z-A coupling injection is disabled for the rest of '
+                    'the file. The runtime check still applies.')
+                self._g91_warned = True
+            self._g90 = False
+
+        # G92 sets coordinate offsets. The new modal value of an
+        # axis is whatever value follows on the same word (e.g.
+        # G92 A0 sets A_wc = 0). Apply that and skip injection.
+        if 92 in gs:
+            new_a = self._extract_axis('a', code)
+            new_z = self._extract_axis('z', code)
+            if new_a is not None: self._a_wc = new_a
+            if new_z is not None: self._z_wc = new_z
+            return False
+
+        # In incremental mode we can still track approximately, but
+        # the user has been warned; skip injection.
+        if not self._g90:
+            return False
+
+        new_z_target = self._extract_axis('z', code)
+        new_a_target = self._extract_axis('a', code)
+        if new_z_target is None and new_a_target is None:
+            return False
+
+        # Modal values after the line executes.
+        a_after = new_a_target if new_a_target is not None else self._a_wc
+        z_after = new_z_target if new_z_target is not None else self._z_wc
+
+        eps = 1e-4
+        if a_after - z_after <= self._K + eps:
+            # Move is safe as authored. Update modal state.
+            self._a_wc = a_after
+            self._z_wc = z_after
+            return False
+
+        # Violation. Two cases:
+        #
+        #   (a) The line lowers Z (z_after < self._z_wc) and A is
+        #       held or moved upward, so A needs to drop to keep up.
+        #       We can fix this by pre-positioning A at z_after + K
+        #       BEFORE the line - at which point gplan's plan for the
+        #       line is safe at every point along it.
+        #
+        #   (b) The line raises A above the safe band while Z is
+        #       held (z_after >= self._z_wc) - i.e. the operator
+        #       wrote `G0 A0` while Z is parked deep. Auto-injecting
+        #       a Z-up here is unsafe (Z could swing into a fixture
+        #       or the part) so we error out and let the operator
+        #       author the lift.
+
+        safe_a = z_after + self._K
+
+        # If the line itself targets an A above the safe band, the
+        # endpoint violates the rule no matter what we pre-position.
+        # Refuse rather than emit something that runs the gantry into
+        # the tool.
+        if new_a_target is not None and new_a_target > safe_a + eps:
+            raise AuxPreprocessorError(
+                'Z-A coupling violation: line targets A=%.3f at '
+                'Z=%.3f, but max A allowed is %.3f (clearance %.3f). '
+                'Lower the A target or add a Z-up move first.' % (
+                    new_a_target, z_after, safe_a, self._K))
+
+        # If the line raises A above the current safe band but Z
+        # isn't dropping with it (no Z target on the line, or Z stays
+        # put), the violation is the operator's A-up, not a Z-down.
+        # Refuse rather than insert a Z-up (which could swing through
+        # a fixture or part).
+        if (new_a_target is not None and
+                new_a_target > self._a_wc + eps and
+                new_z_target is None):
+            raise AuxPreprocessorError(
+                'Z-A coupling violation at line raising A to %.3f '
+                'while Z is at %.3f (max A allowed is %.3f given '
+                'clearance %.3f). Add a Z-up move first.' % (
+                    new_a_target, z_after, safe_a, self._K))
+
+        # Case (a): pre-position A.
+        # Don't move A *up* as part of pre-position - if the safe
+        # value is above where A already is, we'd lift A into a
+        # potential collision elsewhere. In practice safe_a < a_wc
+        # whenever we get here (otherwise no violation), but assert
+        # to be sure.
+        if safe_a > self._a_wc + eps:
+            raise AuxPreprocessorError(
+                'Z-A coupling: cannot fix line by lowering A '
+                '(safe A = %.3f > current A = %.3f).' % (
+                    safe_a, self._a_wc))
+        fout.write('(injected by AuxPreprocessor: Z-A coupling)\n')
+        fout.write('G0 A%.4f\n' % safe_a)
+        self._a_wc = safe_a
+        # Don't update z_wc yet - the original line will do that
+        # when it runs. But our modal copy must reflect the post-line
+        # value so subsequent injections compute correctly.
+        self._z_wc = z_after
+        # If the original line also moved A, our pre-positioning
+        # supersedes it (we overwrite a_wc above with safe_a then
+        # the original line's A target may push it back up). Update
+        # a_wc to the line's authored A value so further checks see
+        # the post-line state.
+        if new_a_target is not None:
+            self._a_wc = new_a_target
+        return True
 
     # ------------------------------------------------------------------ run
 
     def process(self, src_path, dst_path):
-        """Read src_path, write rewritten G-code to dst_path. Returns True
-        if any rewrite happened."""
-        modal = {'abs': True, 'inch': False}  # G90 G21 are common defaults
+        """Read src_path, write rewritten G-code to dst_path. Returns
+        True if any rewrite happened."""
         rewrote_any = False
 
         with open(src_path, 'r', encoding='utf-8', errors='replace') as fin, \
@@ -135,90 +325,63 @@ class AuxPreprocessor(object):
                     fout.write(raw)
                     continue
 
-                # Update modal from G-codes on this line first (so absolute
-                # vs incremental matches what the planner sees for XYZ).
-                self._detect_modals(code, modal)
-
-                if not _W_TOKEN_RE.search(code):
-                    fout.write(raw)
-                    continue
+                # Warn (once) if the file still uses W tokens. The
+                # standard way is now G1 A<value>; old files must be
+                # migrated by hand.
+                if (not self._w_warned) and _W_TOKEN_RE.search(code):
+                    self._warn('Found W axis token in gcode; W is no '
+                               'longer recognized by bbctrl. Use A '
+                               'instead. (warning suppressed for '
+                               'subsequent W tokens in this file)')
+                    self._w_warned = True
 
+                # Z-A coupling injection BEFORE the line is emitted.
+                if self._maybe_inject_a_down(code, fout):
                     rewrote_any = True
 
-                # G28[.2] W... -> aux_home (W value is ignored except as
-                # a flag that W is being homed).
-                if self._is_g28_like(code):
-                    code_no_w, _ = self._strip_w(line)
-                    fout.write('(MSG,HOOK:aux_home:)\n')
-                    # Only keep the residual line if other axes were also
-                    # present (e.g. G28.2 X0 Y0 W0 still homes X+Y). A bare
-                    # "G28" without axis args means "home all" in gcode
-                    # which we explicitly DON'T want to trigger from a
-                    # W-only home command.
-                    rest_code = _PAREN_COMMENT_RE.sub('', code_no_w)
-                    rest_code = rest_code.split(';', 1)[0]
-                    if self._has_other_axis(rest_code):
-                        fout.write(code_no_w + '\n')
+                # ATC M-codes (M100-M103). Each ATC M-code on the line
+                # is replaced with its (MSG,HOOK:<event>:) line and
+                # stripped from the residual.
+                atc_matches = list(_ATC_M_RE.finditer(line))
+                if atc_matches:
+                    rewrote_any = True
+                    for m in atc_matches:
+                        try: num = int(m.group(1))
+                        except ValueError: continue
+                        event = _ATC_M_CODES.get(num)
+                        if event:
+                            fout.write('(MSG,HOOK:%s:)\n' % event)
+                    line = _ATC_M_RE.sub('', line)
+                    code = _PAREN_COMMENT_RE.sub('', line)
+                    code = code.split(';', 1)[0]
+                    if not code.strip():
+                        # Nothing meaningful left; preserve any trailing
+                        # comment text but skip empty lines.
+                        rest = line.rstrip()
+                        if rest:
+                            fout.write(rest + '\n')
+                        continue
+                    # Other gcode remains on the line - emit it.
+                    fout.write(line + '\n')
                     continue
 
-                # G92 W... -> set W zero (or other value) without motion.
-                if self._is_g92(code):
-                    line_no_w, w_val = self._strip_w(line)
-                    target_mm = self._w_to_mm(w_val, modal, set_pos=True)
-                    fout.write('(MSG,HOOK:aux_setzero:%g)\n' % target_mm)
-                    rest_code = _PAREN_COMMENT_RE.sub('', line_no_w)
-                    rest_code = rest_code.split(';', 1)[0]
-                    if self._has_other_axis(rest_code):
-                        fout.write(line_no_w + '\n')
-                    continue
-
-                # Plain motion: G0/G1 etc with W word.
-                line_no_w, w_val = self._strip_w(line)
-                target_mm = self._w_to_mm(w_val, modal, set_pos=False)
-                # Distinguish absolute vs relative: encode both, the hook
-                # handler will pick the right operation.
-                if modal['abs']:
-                    hook_line = '(MSG,HOOK:aux:%g)' % target_mm
-                else:
-                    hook_line = '(MSG,HOOK:aux_rel:%g)' % target_mm
-
-                rest_code = _PAREN_COMMENT_RE.sub('', line_no_w)
-                rest_code = rest_code.split(';', 1)[0]
-                has_xyz = self._has_other_axis(rest_code)
-
-                if not has_xyz:
-                    # Pure W move; drop the (now-empty) original line.
-                    fout.write(hook_line + '\n')
-                    continue
-
-                # Mixed-axis: split. Default order is W first.
-                if self.w_first:
-                    fout.write(hook_line + '\n')
-                    fout.write(line_no_w + '\n')
-                else:
-                    fout.write(line_no_w + '\n')
-                    fout.write(hook_line + '\n')
+                # No rewrite needed.
+                fout.write(raw)
 
         return rewrote_any
 
-    # ------------------------------------------------------------ unit conv
 
-    def _w_to_mm(self, w_str, modal, set_pos):
-        try:
-            v = float(w_str)
-        except (TypeError, ValueError):
-            raise AuxPreprocessorError('Invalid W value: %r' % w_str)
-        if modal['inch']:
-            v *= 25.4
-        return v
+def preprocess_file(src_path, log=None, coupling=None, **_unused):
+    """Convenience: rewrite src_path in place if it contains ATC
+    M-codes or needs Z-A coupling injection. Returns True if the
+    file was rewritten.
 
-
-def preprocess_file(src_path, log=None, w_first=True):
-    """Convenience: rewrite src_path in place if it uses W.
-    Returns True if the file was rewritten."""
-    if not AuxPreprocessor.file_uses_w(src_path):
+    `coupling` is an optional dict (see AuxPreprocessor.__init__).
+    Extra keyword args are accepted for backwards compat (the old
+    w_first arg is no longer used)."""
+    if not AuxPreprocessor.file_uses_aux(src_path, coupling=coupling):
         return False
-    pre = AuxPreprocessor(log=log, w_first=w_first)
+    pre = AuxPreprocessor(log=log, coupling=coupling)
     fd, tmp = tempfile.mkstemp(prefix='auxpre_', suffix='.nc',
                                dir=os.path.dirname(src_path) or None)
     os.close(fd)

src/py/bbctrl/Config.py

@@ -216,6 +216,32 @@ class Config(object):
                 defaults = json.load(f)
                 config['selected-tool-settings'] = defaults['selected-tool-settings'];
 
+        # Auxiliary axis nomenclature: rename W -> A in macro names and
+        # filenames. The auxcnc-driven stepper has been integrated into
+        # gplan as A since the option-b migration; old configs may
+        # still carry W Down/W Up macro entries pointing at
+        # w_down.nc/w_up.nc which were renamed on disk to a_down.nc /
+        # a_up.nc. Migrate idempotently on every load so a stale
+        # in-memory copy can never reintroduce the old names.
+        macros = config.get('macros') if isinstance(config, dict) else None
+        if isinstance(macros, list):
+            renames = {
+                'w_down.nc': 'a_down.nc',
+                'w_up.nc':   'a_up.nc',
+            }
+            display_renames = {
+                'W Down': 'A Down',
+                'W Up':   'A Up',
+            }
+            for m in macros:
+                if not isinstance(m, dict): continue
+                fn = m.get('file_name')
+                if isinstance(fn, str) and fn in renames:
+                    m['file_name'] = renames[fn]
+                nm = m.get('name')
+                if isinstance(nm, str) and nm in display_renames:
+                    m['name'] = display_renames[nm]
+
         config['version'] = self.version.split('b')[0]
         config['full_version'] = self.version
 

src/py/bbctrl/Ctrl.py

@@ -75,6 +75,19 @@ class Ctrl(object):
                 self.hooks = bbctrl.Hooks(self)
             with Trace.span('ctrl.aux'):
                 self.aux = bbctrl.AuxAxis(self)
+            with Trace.span('ctrl.ext_axis'):
+                # ExternalAxis exposes the auxcnc ESP stepper as a
+                # virtual A axis that gplan handles natively. Created
+                # unconditionally so State sees the synthetic motor
+                # vars even when aux is disabled (kept inert in that
+                # case via ext_axis.enabled).
+                axis_letter = self.aux._cfg.get('axis_letter', 'a')
+                self.ext_axis = bbctrl.ExternalAxis(
+                    self, self.aux, axis_letter=axis_letter)
+                # Hook AuxAxis post-publish callback so homed flag
+                # mirrors into State after homing.
+                self.aux.set_state_observer(
+                    self.ext_axis.refresh_homed)
             self._register_aux_hooks()
 
             with Trace.span('ctrl.mach.connect'):
@@ -133,38 +146,51 @@ class Ctrl(object):
 
 
     def _register_aux_hooks(self):
-        """Wire up the auxcnc HOOK: events to AuxAxis methods."""
+        """Wire up auxcnc HOOK: events to AuxAxis methods.
+
+        v2: motion hooks (aux/aux_rel/aux_home/aux_setzero) are
+        retired now that the W axis is integrated through gplan as
+        a virtual A axis (see ExternalAxis). Only the ATC pneumatic
+        hooks remain - those are events, not motion.
+
+        For backwards compatibility with files that still contain
+        (MSG,HOOK:aux_home:) (e.g. older preprocessed gcode), keep
+        an aux_home alias that routes to the standard ext_axis homing
+        path."""
         log = self.log.get('AuxAxis')
 
-        def _hook_move(ctx):
-            data = (ctx.get('data') or '').strip()
-            if not data:
-                raise Exception('aux hook missing target')
-            self.aux.move_abs_mm(float(data))
-
-        def _hook_move_rel(ctx):
-            data = (ctx.get('data') or '').strip()
-            if not data:
-                raise Exception('aux_rel hook missing delta')
-            self.aux.move_rel_mm(float(data))
-
-        def _hook_home(ctx):
+        def _hook_aux_home(ctx):
+            # Legacy: route to the standard external-axis homing.
+            if self.ext_axis is not None and self.ext_axis.enabled:
+                self.ext_axis.home()
+            else:
                 self.aux.home()
 
-        def _hook_setzero(ctx):
-            data = (ctx.get('data') or '').strip()
-            mm = float(data) if data else 0.0
-            self.aux.set_position_mm(mm)
+        def _hook_droptool(ctx):  self.aux.atc_droptool()
+        def _hook_grabtool(ctx):  self.aux.atc_grabtool()
+        def _hook_release(ctx):   self.aux.atc_release()
+        def _hook_clamp(ctx):     self.aux.atc_clamp()
 
-        self.hooks.register_internal('aux',         _hook_move,
-                                     block_unpause=True, auto_resume=True)
-        self.hooks.register_internal('aux_rel',     _hook_move_rel,
-                                     block_unpause=True, auto_resume=True)
-        self.hooks.register_internal('aux_home',    _hook_home,
+        # Legacy alias for older gcode that used aux_home.
+        self.hooks.register_internal('aux_home',    _hook_aux_home,
                                      block_unpause=True, auto_resume=True,
                                      timeout=180)
-        self.hooks.register_internal('aux_setzero', _hook_setzero,
-                                     block_unpause=True, auto_resume=True)
+
+        # ATC pneumatics. block_unpause + auto_resume so a program
+        # using M100/M101/M102/M103 pauses at the right point and
+        # resumes once the sequence is done.
+        self.hooks.register_internal('droptool',    _hook_droptool,
+                                     block_unpause=True, auto_resume=True,
+                                     timeout=60)
+        self.hooks.register_internal('grabtool',    _hook_grabtool,
+                                     block_unpause=True, auto_resume=True,
+                                     timeout=60)
+        self.hooks.register_internal('release',     _hook_release,
+                                     block_unpause=True, auto_resume=True,
+                                     timeout=10)
+        self.hooks.register_internal('clamp',       _hook_clamp,
+                                     block_unpause=True, auto_resume=True,
+                                     timeout=15)
         log.info('Aux hooks registered')
 
 
@@ -173,5 +199,7 @@ class Ctrl(object):
         self.ioloop.close()
         self.avr.close()
         self.mach.planner.close()
+        try: self.ext_axis.close()
+        except Exception: pass
         try: self.aux.close()
         except Exception: pass

src/py/bbctrl/ExternalAxis.py

@@ -0,0 +1,677 @@
+################################################################################
+#
+# ExternalAxis - bridges a logical motorless axis to step generation on
+# the auxcnc ESP, so the Buildbotics planner can drive a stepper that
+# isn't on the AVR.
+#
+# Architecture
+# ------------
+# The bbctrl planner (camotics gplan) handles parsing, units, modal
+# state, soft limits, accel ramping and S-curve timing for axes
+# X, Y, Z, A, B, C. The AVR has 4 motor channels (0-3) and only
+# generates step pulses for axes that have a motor mapped to them.
+# An axis with no mapped motor is fully accepted by the AVR - it
+# updates its internal `ex.position[axis]` and reports `<axis>p` to
+# the host, but no stepper turns.
+#
+# We exploit that: the W stepper is exposed to gplan as A, but no
+# AVR motor maps to A. The planner does all the gcode-level work
+# correctly (G90/G91, soft limits, accel, units, modal feed rate);
+# we intercept the resulting `Cmd.line` blocks in `Planner.__encode`,
+# strip A out, and forward the A delta to the auxcnc ESP as STEPS.
+#
+# To make gplan and State *believe* A is enabled we register a
+# synthetic motor (index 4) into State.vars, populated from
+# aux.json, with `4an=3` (axis A), `4me=1` (enabled), and the
+# usual velocity/accel/jerk/soft-limit vars. State.find_motor and
+# the snapshot projection are extended to walk index 4. Motor-4
+# vars never leave the host (they're not in the AVR's schema) so
+# the AVR is undisturbed.
+#
+# v1 coupling: serialize. If a line has any A delta we wait for
+# the ESP to finish before letting subsequent commands flow. This
+# matches the behaviour of the previous hook-based approach (no
+# XYZ+A blending) but with all the planner's correctness guarantees.
+#
+# v2 could match ESP move duration to the gplan trapezoid time and
+# allow concurrent motion; out of scope for v1.
+#
+################################################################################
+
+import threading
+
+try:
+    from queue import Queue
+except ImportError:
+    from Queue import Queue  # py2 just in case
+
+
+# Synthetic motor index used to expose the external axis to State.
+# The AVR has motors 0..3; we use 4 as a host-only sentinel.
+EXTERNAL_MOTOR_INDEX = 4
+
+# Axis letters in their canonical order; 'a' is index 3.
+_AXIS_LETTERS = 'xyzabc'
+
+
+class ExternalAxisError(Exception):
+    pass
+
+
+class ExternalAxis(object):
+    """Bridge between Planner line blocks and AuxAxis serial RPCs.
+
+    Owns no thread; runs RPC calls inline on whatever thread invokes
+    execute_to_mm / home / abort. The Planner runs `__encode` on its
+    own thread which is allowed to block on planner I/O, so blocking
+    inside the interceptor is fine.
+
+    Position tracking: gplan emits absolute targets in mm; the ESP
+    counts steps relative to home_zero. We mirror the last commanded
+    mm position so subsequent line blocks compute the correct delta.
+    `_pos_mm` is also published as `<axis>p` so DRO updates."""
+
+    def __init__(self, ctrl, aux, axis_letter='a'):
+        self.ctrl = ctrl
+        self.aux = aux
+        self.log = ctrl.log.get('ExternalAxis')
+
+        self.axis_letter = (axis_letter or 'a').lower()[:1]
+        if self.axis_letter not in _AXIS_LETTERS:
+            raise ExternalAxisError(
+                'Invalid external axis letter: %r' % axis_letter)
+        # Index in 'xyzabc' (0..5)
+        self.axis_index = _AXIS_LETTERS.index(self.axis_letter)
+
+        self._busy = threading.Event()
+        # Last absolute mm we committed; None until first move /
+        # homing event syncs us up.
+        self._pos_mm = None
+
+        # Single-slot worker queue: __encode posts (target_mm,) tuples
+        # here; the worker thread runs the ESP RPC. Capacity is
+        # intentionally bounded - if it fills it means motion is
+        # outpacing the ESP and we should backpressure the planner.
+        self._work_q = Queue(maxsize=64)
+        self._stop = threading.Event()
+        self._worker = threading.Thread(
+            target=self._worker_loop,
+            name='ExternalAxis-worker', daemon=True)
+        self._worker.start()
+
+        # Push synthetic motor vars into State so the planner sees
+        # this axis as enabled with proper limits/velocity/accel.
+        self._publish_synthetic_motor()
+        # Also seed <axis>p so the DRO has something to render.
+        self.ctrl.state.set(self.axis_letter + 'p', 0.0)
+
+    # -------------------------------------------------------------- enabled
+
+    @property
+    def enabled(self):
+        try:
+            return bool(self.aux is not None
+                        and self.aux.enabled
+                        and self.aux.present)
+        except Exception:
+            return False
+
+    # -------------------------------------------------------- configuration
+
+    @property
+    def steps_per_mm(self):
+        try:
+            return float(self.aux._cfg.get('steps_per_mm', 25.0))
+        except Exception:
+            return 25.0
+
+    @property
+    def dir_sign(self):
+        try:
+            v = int(self.aux._cfg.get('dir_sign', 1))
+            return -1 if v < 0 else 1
+        except Exception:
+            return 1
+
+    @property
+    def home_position_mm(self):
+        try:
+            return float(self.aux._cfg.get('home_position_mm', 0.0))
+        except Exception:
+            return 0.0
+
+    # ------------------------------------------------------- soft limits
+
+    def _soft_limits(self):
+        """Return (min_mm, max_mm) in machine coords, or (None, None)
+        if soft limits are disabled (max <= min)."""
+        try:
+            lo = float(self.aux._cfg.get('min_mm', 0.0))
+            hi = float(self.aux._cfg.get('max_mm', 0.0))
+        except Exception:
+            return (None, None)
+        if hi <= lo:
+            return (None, None)
+        return (lo, hi)
+
+    def _check_soft_limit(self, target_abs_mm):
+        """Raise ExternalAxisError if target_abs_mm is outside the
+        configured soft limits. Skips the check when the axis isn't
+        homed (matching the standard bbctrl convention that soft
+        limits are gated by homing state) - that lets the user jog
+        away from a stuck position before homing without false
+        rejections.
+
+        Called by both planner-driven motion (enqueue_target_mm) and
+        UI motion (execute_to_mm), so this is the single source of
+        truth regardless of which path triggered the move."""
+        # Honour the homing gate.
+        try:
+            homed = bool(self.aux._homed)
+        except Exception:
+            homed = False
+        if not homed:
+            return
+        lo, hi = self._soft_limits()
+        if lo is None:
+            return
+        # Use a tiny epsilon so floating-point round-trip targets
+        # right at the boundary aren't rejected.
+        eps = 1e-4
+        target = float(target_abs_mm)
+        if target < lo - eps or target > hi + eps:
+            raise ExternalAxisError(
+                '%s axis target %.4f mm is outside soft limits '
+                '[%.3f, %.3f] mm' % (
+                    self.axis_letter.upper(), target, lo, hi))
+
+    # ----------------------------------------------- Z-A coupling
+    #
+    # The auxiliary tool hangs below the Z spindle. Beyond a small
+    # Z descent the two collide unless A drops with Z. The
+    # constraint, in machine coords, is
+    #
+    #     A_machine - Z_machine <= K
+    #     K = (A_home_mm - z_home_mm) + couple_z_clearance_mm
+    #
+    # Enforced before any motion (planner blocks, MDI, jogs). The
+    # AuxPreprocessor injects pre-position A moves into uploaded
+    # files so well-formed gcode runs without having to think about
+    # this. Disabled when couple_z_enabled is false.
+
+    @property
+    def couple_z_enabled(self):
+        try:
+            return bool(self.aux._cfg.get('couple_z_enabled', False))
+        except Exception:
+            return False
+
+    @property
+    def couple_K(self):
+        """Limit constant K (machine-coord units): the maximum value
+        of (A_machine - Z_machine) before the tool collides. Returns
+        None if the rule isn't applicable (coupling disabled or
+        config missing)."""
+        try:
+            cfg = self.aux._cfg
+            clearance = float(cfg.get('couple_z_clearance_mm', 0.0))
+            a_home    = float(cfg.get('home_position_mm', 0.0))
+            z_home    = float(cfg.get('z_home_mm', 0.0))
+            return (a_home - z_home) + clearance
+        except Exception:
+            return None
+
+    @property
+    def couple_clearance_mm(self):
+        """Raw clearance from config: how far Z may travel below its
+        home before A has to start dropping with it. Used by the
+        AuxPreprocessor to inject pre-position A moves into uploaded
+        gcode."""
+        try:
+            return float(self.aux._cfg.get('couple_z_clearance_mm', 0.0))
+        except Exception:
+            return 0.0
+
+    def _z_machine_now(self):
+        """Read Z's current machine position from State, or None if
+        Z isn't homed/reported yet. The AVR reports absolute machine
+        positions in <axis>p; the work-coord display is computed by
+        the UI as zp - offset_z, but here we want machine directly."""
+        try:
+            st = self.ctrl.state
+            zp = st.get('zp', None)
+            if zp is None:
+                return None
+            return float(zp)
+        except Exception:
+            return None
+
+    def _a_machine_now(self):
+        """A's current machine position. ExternalAxis tracks this
+        directly in self._pos_mm (mm in machine coords - we don't
+        apply G92 to A internally; offset_a is informational)."""
+        try:
+            if self._pos_mm is not None:
+                return float(self._pos_mm)
+            # Fall back to whatever the ESP last reported.
+            return float(self.aux.position_mm)
+        except Exception:
+            return None
+
+    def coupling_for_preprocessor(self):
+        """Return the dict the AuxPreprocessor wants for in-file
+        injection, or None when coupling is off. We assume the
+        operator authors gcode in a frame where the at-home position
+        is A_wc=0, Z_wc=0 - which matches our home-zeroed setup.
+        Files that use a different convention will fall through to
+        the runtime check."""
+        if not self.couple_z_enabled:
+            return None
+        return {
+            'enabled':       True,
+            'clearance_mm':  self.couple_clearance_mm,
+            'a_initial_wc':  0.0,
+            'z_initial_wc':  0.0,
+        }
+
+    def check_coupling(self, target_a_machine=None, target_z_machine=None):
+        """Validate that a proposed motion respects the Z-A coupling.
+
+        Each argument is a target *machine* mm position; pass None to
+        keep the current value of that axis.
+
+        Improvement-aware: a move is rejected only when it *worsens*
+        an already-violating state (or moves a healthy state into
+        violation). Pure XY jogs that touch neither Z nor A are not
+        passed through here; jogs that hold Z or A at their current
+        value (gplan emits the unchanged value in `target`) pass
+        because (a-z) doesn't change. Z-up moves while in violation
+        also pass because they reduce (a-z) toward the bound.
+
+        Raises ExternalAxisError on violation. Skipped when coupling
+        is disabled, the aux axis isn't homed, or current positions
+        aren't yet known.
+        """
+        if not self.couple_z_enabled:
+            return
+        try:
+            homed = bool(self.aux._homed)
+        except Exception:
+            homed = False
+        if not homed:
+            return
+        K = self.couple_K
+        if K is None:
+            return
+        a_now = self._a_machine_now()
+        z_now = self._z_machine_now()
+        if a_now is None or z_now is None:
+            return
+        a_after = (float(target_a_machine)
+                   if target_a_machine is not None else a_now)
+        z_after = (float(target_z_machine)
+                   if target_z_machine is not None else z_now)
+        eps = 1e-4
+        gap_after  = a_after - z_after
+        gap_before = a_now   - z_now
+        # Only refuse when (a) the resulting state would violate the
+        # constraint AND (b) the move makes things at least as bad
+        # as the current state. This lets the operator escape an
+        # already-violating state by moving in the right direction
+        # (Z up, A down).
+        if gap_after > K + eps and gap_after > gap_before - eps:
+            raise ExternalAxisError(
+                'Z-A coupling violation: A=%.3f mm and Z=%.3f mm '
+                '(machine) would put A above Z by %.3f mm; max '
+                'allowed is %.3f mm. Drop A or raise Z first.' % (
+                    a_after, z_after, gap_after, K))
+
+    # ----------------------------------------------------------- conversion
+
+    def mm_to_steps_delta(self, delta_mm):
+        return int(round(float(delta_mm) * self.steps_per_mm * self.dir_sign))
+
+    def steps_to_mm(self, steps):
+        return (float(steps) / self.steps_per_mm) * self.dir_sign
+
+    # ---------------------------------------------------- synthetic motor
+
+    def _publish_synthetic_motor(self):
+        """Write motor-4 vars into State so find_motor('a') and
+        get_axis_vector('vm') see A as a real axis. The AVR never
+        sees these (motor index 4 is not in its var schema)."""
+        cfg = self.aux._cfg if self.aux is not None else {}
+        st = self.ctrl.state
+        i = str(EXTERNAL_MOTOR_INDEX)
+
+        # Axis assignment: 'an' is the 0-based axis index in xyzabc.
+        st.set(i + 'an', self.axis_index)
+        # Motor enabled.
+        st.set(i + 'me', 1 if (self.aux and self.aux.enabled) else 0)
+        # Homed flag - cleared until aux reports homed.
+        try:
+            homed = bool(self.aux._homed)
+        except Exception:
+            homed = False
+        st.set(i + 'h', 1 if homed else 0)
+
+        # Velocity / accel / jerk: the planner reads these via
+        # state.get_axis_vector('<code>', SCALE) which multiplies the
+        # stored raw value by SCALE. The bbctrl convention (matching
+        # what motors 0-3 store) is:
+        #   vm: stored in m/min, planner expects mm/min  (scale 1000)
+        #   am: stored in km/min^2, planner expects mm/min^2 (scale 1e6)
+        #   jm: stored in km/min^3, planner expects mm/min^3 (scale 1e6)
+        # Onefinity defaults for XY are vm=10, am=750, jm=1000. We
+        # follow the same convention; aux.json exposes the values in
+        # those user-facing units so they're directly comparable.
+        st.set(i + 'vm', float(cfg.get('max_velocity_m_per_min',  6.0)))
+        st.set(i + 'am', float(cfg.get('max_accel_km_per_min2', 100.0)))
+        st.set(i + 'jm', float(cfg.get('max_jerk_km_per_min3',  500.0)))
+
+        # Soft limits in machine units (mm). State.get_soft_limit_vector
+        # returns these directly, no scaling.
+        st.set(i + 'tn', float(cfg.get('min_mm', 0.0)))
+        st.set(i + 'tm', float(cfg.get('max_mm', 0.0)))
+
+        # home_position / home_travel are exposed as callbacks for
+        # motors 0..3 (see State.__init__). Register the same lazy
+        # callbacks for motor 4 so gplan's resolver lookup
+        # (_<axis>_home_position / _<axis>_home_travel) returns the
+        # right values for the external axis.
+        st.set_callback(
+            i + 'home_position', lambda name: self.home_position_mm)
+        st.set_callback(
+            i + 'home_travel',
+            lambda name: float(self.aux._cfg.get('max_mm', 0.0))
+                       - self.home_position_mm)
+
+        # Misc fields that other code paths might query. Defaults
+        # mirror what the AVR pushes for motors 0-3.
+        st.set(i + 'sa', 1.8)
+        st.set(i + 'mi', 16)
+        st.set(i + 'tr', 4.0)
+        st.set(i + 'sp', 200)
+        st.set(i + 'ic', 0.0)
+        st.set(i + 'dc', 0.0)
+        st.set(i + 'rv', False)
+        st.set(i + 'tc', 1)
+        st.set(i + 'lb', 5)
+        st.set(i + 'ho', 0)
+        st.set(i + 'os', 0)
+        st.set(i + 'oa', False)
+        st.set(i + 'lm', 8)
+        st.set(i + 'lv', 0.1)
+        st.set(i + 'sv', 1.688)
+        st.set(i + 'tv', 1.997)
+        st.set(i + 'lw', 2)   # min-switch
+        st.set(i + 'xw', 2)   # max-switch
+        st.set(i + 'ls', 0)
+        st.set(i + 'xs', 0)
+        st.set(i + 'df', 0)
+
+    def refresh_homed(self):
+        """Called when AuxAxis updates its homed flag. Mirrors into
+        State so is_axis_homed('a') returns the right answer.
+
+        Updates several places at once because different layers read
+        the homed state via different keys:
+          - synthetic motor flag: 4h    (used by snapshot -> a_h)
+          - axis-level flag:      a_homed (used by State.is_axis_homed
+                                           and gplan _a_homed resolver)"""
+        try:
+            homed = bool(self.aux._homed)
+        except Exception:
+            homed = False
+        st = self.ctrl.state
+        st.set(str(EXTERNAL_MOTOR_INDEX) + 'h', 1 if homed else 0)
+        st.set(self.axis_letter + '_homed', bool(homed))
+
+    # ----------------------------------------------------------- line split
+
+    def split_target(self, target):
+        """Pop the external axis out of a target dict and return
+        (target_without_ext, ext_mm_or_None). Both case variants
+        accepted defensively."""
+        if not target:
+            return target, None
+        ax = self.axis_letter
+        new_target = dict(target)
+        ext_mm = new_target.pop(ax, None)
+        if ext_mm is None:
+            ext_mm = new_target.pop(ax.upper(), None)
+        return new_target, ext_mm
+
+    # -------------------------------------------------------- execution API
+
+    def is_busy(self):
+        return self._busy.is_set()
+
+    def execute_to_mm(self, ext_mm):
+        """Synchronously run an external move. Blocks until the ESP
+        reports done. Used by the legacy /api/aux/move and /api/aux/jog
+        endpoints which may want to wait. Most planner-driven motion
+        goes through enqueue_target_mm instead, which is non-blocking.
+
+        Soft limits are enforced here (not just in gplan) because the
+        UI jog/move endpoints don't go through the planner.
+
+        Updates state.<axis>p immediately on completion. For the
+        planner-driven path that goes through enqueue_target_mm, the
+        AVR's own ap reports drive state.<axis>p instead."""
+        if not self.enabled:
+            raise ExternalAxisError(
+                'External axis %r not available (aux disabled or '
+                'not connected)' % self.axis_letter)
+
+        self._check_soft_limit(ext_mm)
+        # Coupling: A is in machine coords directly (we don't apply
+        # a G92 offset to A), so target_a_machine == ext_mm.
+        self.check_coupling(target_a_machine=ext_mm)
+        steps, abs_mm = self._compute_move(ext_mm)
+        if steps == 0:
+            self._pos_mm = abs_mm
+            self.ctrl.state.set(self.axis_letter + 'p', self._pos_mm)
+            return
+
+        self._busy.set()
+        try:
+            self.aux._do_steps(steps, ignore_limits=True)
+            self._pos_mm = abs_mm
+            self.ctrl.state.set(self.axis_letter + 'p', self._pos_mm)
+        finally:
+            self._busy.clear()
+
+    def enqueue_target_mm(self, ext_mm):
+        """Legacy non-blocking variant: post a fixed-rate STEPS move
+        to the worker queue. No longer used by Planner.__encode (which
+        uses enqueue_line for full S-curve mirroring), but kept for
+        UI jog endpoints that don't have planner timing data.
+
+        Soft limits are enforced here (defense in depth on top of
+        gplan)."""
+        if not self.enabled:
+            raise ExternalAxisError(
+                'External axis %r not available' % self.axis_letter)
+        self._check_soft_limit(ext_mm)
+        self.check_coupling(target_a_machine=ext_mm)
+        steps, abs_mm = self._compute_move(ext_mm)
+        # Internal mirror only - drives subsequent delta computation.
+        # state.<axis>p is left to the AVR's status reports.
+        self._pos_mm = abs_mm
+        if steps == 0:
+            return
+        self._work_q.put(('move', steps))
+
+    def enqueue_line(self, ext_mm, max_accel_mm_min2, max_jerk_mm_min3,
+                     entry_vel_mm_min, exit_vel_mm_min, times_ms):
+        """Post a full S-curve LINE block to the ESP worker. Mirrors
+        gplan's planned trajectory exactly (same 7-segment math, same
+        unit system) so the ESP's move duration matches what the AVR
+        would have produced for an A motor.
+
+        Called by Planner.__encode for every line block that touches
+        the external axis.
+
+        Parameters:
+          ext_mm:           absolute target in mm (gplan target['a'])
+          max_accel_mm_min2:from block['max-accel']
+          max_jerk_mm_min3: from block['max-jerk']
+          entry_vel_mm_min: from block['entry-vel'] (typically 0 for
+                            the first block, exit_vel of the prior
+                            block otherwise)
+          exit_vel_mm_min:  from block['exit-vel']
+          times_ms:         7-tuple of section durations in ms
+                            (block['times'] - the same units gplan uses)
+        """
+        if not self.enabled:
+            raise ExternalAxisError(
+                'External axis %r not available' % self.axis_letter)
+        self._check_soft_limit(ext_mm)
+        self.check_coupling(target_a_machine=ext_mm)
+        steps, abs_mm = self._compute_move(ext_mm)
+        delta_mm = abs(abs_mm - (self._pos_mm if self._pos_mm is not None
+                                 else 0.0))
+        # Update internal mirror; AVR drives state.<axis>p.
+        self._pos_mm = abs_mm
+        if steps == 0 or delta_mm <= 0:
+            return
+        # ms -> minutes (the unit gplan/AVR/ESP use internally for
+        # SCurve math).
+        times_min = tuple((t / 60000.0) if t else 0.0 for t in times_ms)
+        self._work_q.put(('line', steps, delta_mm,
+                          float(max_accel_mm_min2),
+                          float(max_jerk_mm_min3),
+                          float(entry_vel_mm_min),
+                          float(exit_vel_mm_min),
+                          times_min))
+
+    def _compute_move(self, ext_mm):
+        """Return (signed_steps, absolute_mm) for a target in mm.
+        Caches first-time position from the ESP."""
+        if self._pos_mm is None:
+            self._pos_mm = self._read_esp_position_mm()
+        delta_mm = float(ext_mm) - self._pos_mm
+        return self.mm_to_steps_delta(delta_mm), float(ext_mm)
+
+    def _worker_loop(self):
+        """Background thread that drains the work queue. RPCs to the
+        ESP are slow (multi-second moves) and must not run on the
+        ioloop thread. We serialize ESP commands here so multiple
+        line-block enqueues for the external axis are processed in
+        the order the planner emitted them."""
+        while not self._stop.is_set():
+            try:
+                op = self._work_q.get(timeout=0.5)
+            except Exception:
+                continue
+            if op is None:
+                continue
+            kind = op[0]
+            try:
+                self._busy.set()
+                if kind == 'move':
+                    steps = op[1]
+                    self.aux._do_steps(steps, ignore_limits=True)
+                elif kind == 'line':
+                    (_, steps, length_mm,
+                     max_accel, max_jerk,
+                     entry_vel, exit_vel,
+                     times_min) = op
+                    self.aux._do_line(
+                        steps, length_mm, max_accel, max_jerk,
+                        entry_vel, exit_vel, times_min,
+                        ignore_limits=True)
+                elif kind == 'home':
+                    self.aux.home()
+                    # _pos_mm and DRO updated by the caller's enqueue.
+            except Exception as e:
+                self.log.error('External axis worker failed on %s: %s'
+                               % (kind, e))
+            finally:
+                self._busy.clear()
+                self._work_q.task_done()
+
+    def wait_idle(self, timeout=None):
+        """Block until the worker queue is empty. Used by callers
+        that need post-motion state to be settled (e.g. homing,
+        stop/abort handlers)."""
+        try:
+            # Queue.join blocks until task_done has been called for
+            # every item put. It does not honour a timeout, so we
+            # poll instead when one is requested.
+            if timeout is None:
+                self._work_q.join()
+                return True
+            import time
+            deadline = time.time() + float(timeout)
+            while time.time() < deadline:
+                if self._work_q.unfinished_tasks == 0:
+                    return True
+                time.sleep(0.05)
+            return False
+        except Exception:
+            return False
+
+    def close(self):
+        self._stop.set()
+        try:
+            self._work_q.put(None, block=False)
+        except Exception:
+            pass
+
+    def home(self):
+        """Run the ESP homing cycle and sync our recorded position
+        to the configured home_position_mm. Blocks; called from
+        Mach.home (which already runs synchronously per axis)."""
+        if not self.enabled:
+            raise ExternalAxisError(
+                'External axis %r not available' % self.axis_letter)
+        # Drain pending moves so we don't home into stale work.
+        self.wait_idle(timeout=30.0)
+        self._busy.set()
+        try:
+            self.aux.home()
+            self._pos_mm = self.home_position_mm
+            self.ctrl.state.set(self.axis_letter + 'p', self._pos_mm)
+            self.refresh_homed()
+        finally:
+            self._busy.clear()
+
+    def abort(self):
+        """Cancel the ESP move and drop pending queued work.
+        Caller (estop / stop handler) is responsible for the
+        planner-side cleanup."""
+        try:
+            if self.aux is not None:
+                self.aux.abort()
+        finally:
+            self._busy.clear()
+        # Drain any pending ops so resume after an abort doesn't
+        # replay stale targets.
+        try:
+            while True:
+                self._work_q.get_nowait()
+                self._work_q.task_done()
+        except Exception:
+            pass
+
+    # ------------------------------------------------------- ESP introspection
+
+    def _read_esp_position_mm(self):
+        """Convert AuxAxis._pos_steps mirror to mm. Falls back to 0."""
+        try:
+            steps = int(self.aux._pos_steps)
+        except Exception:
+            steps = 0
+        return self.steps_to_mm(steps)
+
+    # ---------------------------------------------------------- DRO update
+
+    def sync_dro(self):
+        """Push the current position to State as <axis>p so the DRO
+        reflects what we believe gplan/ESP agreed on. Called after
+        moves; also safe to call from external code."""
+        if self._pos_mm is None:
+            return
+        self.ctrl.state.set(self.axis_letter + 'p', self._pos_mm)

src/py/bbctrl/FileHandler.py

@@ -99,18 +99,26 @@ class FileHandler(bbctrl.APIHandler):
 
             del (self.uploadFile)
 
-            # If the uploaded G-code uses the virtual W axis, rewrite the
-            # file in place so the planner sees (MSG,HOOK:aux:*) lines
-            # instead of W tokens it can't parse.
+            # If the uploaded G-code uses ATC M-codes (M100..M103),
+            # rewrite them into (MSG,HOOK:droptool:) etc so the hook
+            # layer can dispatch them at runtime. The planner accepts
+            # M100-M103 in user-defined range but doesn't *do* anything
+            # with them. Motion in A goes through gplan unchanged - the
+            # auxcnc stepper is exposed as a virtual A axis (see
+            # ExternalAxis).
             try:
                 from bbctrl.AuxPreprocessor import preprocess_file
                 log = self.get_log('AuxPreprocessor')
-                if preprocess_file(filename.decode('utf8'), log=log):
-                    log.info('Rewrote W-axis tokens in %s' %
-                             self.uploadFilename)
+                ext = getattr(self.get_ctrl(), 'ext_axis', None)
+                coupling = (ext.coupling_for_preprocessor()
+                            if ext is not None else None)
+                if preprocess_file(filename.decode('utf8'),
+                                    log=log, coupling=coupling):
+                    log.info('Rewrote upload (ATC / Z-A coupling) in %s'
+                             % self.uploadFilename)
             except Exception:
                 self.get_log('AuxPreprocessor').exception(
-                    'W-axis preprocess failed; uploading unchanged')
+                    'Aux preprocess failed; uploading unchanged')
 
             self.get_ctrl().preplanner.invalidate(self.uploadFilename)
             self.get_ctrl().state.add_file(self.uploadFilename)

src/py/bbctrl/Hooks.py

@@ -201,7 +201,15 @@ class Hooks:
                     # Cancel any running hook on estop. The hook thread
                     # cannot be killed from Python, but we can ask the
                     # AuxAxis to send ABORT to the ESP so its in-flight
-                    # motion stops.
+                    # motion stops. Also drain the external-axis
+                    # worker queue so resume after clear doesn't replay
+                    # stale moves.
+                    try:
+                        ext = getattr(self.ctrl, 'ext_axis', None)
+                        if ext is not None:
+                            ext.abort()
+                    except Exception:
+                        pass
                     if self._hook_busy:
                         self.log.warning('E-stop: cancelling hook "%s"' %
                                          self._hook_busy_event)
@@ -249,6 +257,23 @@ class Hooks:
 
     # -- Hook execution --
 
+    def dispatch_hook_message(self, text):
+        """Direct entry point for HOOK:<event>:<data> messages emitted
+        by the planner via (MSG,HOOK:...) comments. Bypasses the
+        state.messages list (which the UI also reads), so callers can
+        suppress popup display without losing the hook dispatch.
+
+        Returns True if the text matched a HOOK: line and was
+        dispatched, False otherwise."""
+        if not isinstance(text, str) or not text.startswith('HOOK:'):
+            return False
+        parts = text[5:].split(':', 1)
+        event = parts[0]
+        data = parts[1] if len(parts) > 1 else ''
+        self._fire('custom', {'event': event, 'data': data},
+                   custom_name=event)
+        return True
+
     def register_internal(self, name, fn, block_unpause=True,
                           auto_resume=True, timeout=120):
         """Register an in-process handler for HOOK:<name> events.

src/py/bbctrl/Mach.py

@@ -95,6 +95,10 @@ class Mach(Comm):
         self.planner = bbctrl.Planner(ctrl)
         self.unpausing = False
         self.stopping = False
+        # Guard against overlapping deferred-external-homing threads
+        # if the user clicks Home (All) again while the previous run
+        # is still waiting for the AVR cycle to finish.
+        self._ext_home_thread = None
 
         ctrl.state.set('cycle', 'idle')
 
@@ -256,9 +260,12 @@ class Mach(Comm):
             if   cmd[0] == '$':  self._query_var(cmd)
             elif cmd[0] == '\\': super().queue_command(cmd[1:])
             else:
-                # Rewrite W-axis tokens in MDI input the same way the
-                # FileHandler rewrites uploaded files.
-                cmd = self._rewrite_w_mdi(cmd)
+                # Rewrite ATC M-codes in MDI input the same way the
+                # FileHandler rewrites uploaded files. Motion (X/Y/Z/A)
+                # is left unchanged: the planner handles it natively
+                # now that the auxcnc stepper is exposed as a virtual
+                # A axis (see ExternalAxis).
+                cmd = self._rewrite_aux_mdi(cmd)
                 self._begin_cycle('mdi')
                 self.planner.mdi(cmd, with_limits)
                 super().resume()
@@ -266,12 +273,12 @@ class Mach(Comm):
             self.mlog.info("Exception during MDI: %s" % err)
             pass
 
-    def _rewrite_w_mdi(self, cmd):
-        """Apply the W-axis preprocessor to a single MDI line. Returns
-        possibly-multi-line G-code with HOOK: comments inserted."""
+    def _rewrite_aux_mdi(self, cmd):
+        """Apply the ATC M-code preprocessor to a single MDI line.
+        Returns possibly-multi-line G-code with HOOK: comments inserted."""
         try:
-            from bbctrl.AuxPreprocessor import AuxPreprocessor, _W_TOKEN_RE
-            if not _W_TOKEN_RE.search(cmd):
+            from bbctrl.AuxPreprocessor import AuxPreprocessor, _ATC_M_RE
+            if not _ATC_M_RE.search(cmd):
                 return cmd
             import io, tempfile, os
             # AuxPreprocessor.process is file-based; route through
@@ -292,7 +299,7 @@ class Mach(Comm):
                 except OSError: pass
             return rewritten
         except Exception as e:
-            self.mlog.warning('W-axis MDI rewrite failed: %s' % e)
+            self.mlog.warning('Aux MDI rewrite failed: %s' % e)
             return cmd
 
     def set(self, code, value):
@@ -300,6 +307,17 @@ class Mach(Comm):
 
 
     def jog(self, axes):
+        # Strip the external axis from the jog request before sending
+        # to the AVR. v1 doesn't support continuous-rate jogging on
+        # the ESP-driven axis - users jog A via /api/aux/jog (relative
+        # mm steps) instead. Sending A to the AVR is harmless (no
+        # motor maps to it) but cleaner to strip.
+        ext = getattr(self.ctrl, 'ext_axis', None)
+        if ext is not None and isinstance(axes, dict):
+            axes = {k: v for k, v in axes.items()
+                    if k.lower() != ext.axis_letter}
+            if not axes:
+                return
         self._begin_cycle('jogging')
         self.planner.position_change()
         super().queue_command(Cmd.jog(axes))
@@ -313,10 +331,52 @@ class Mach(Comm):
             axes = 'zxybc' if is_rotary_active else 'zxyabc' # TODO This should be configurable
         else: axes = '%c' % axis
 
+        # Collect external axes here and process them *after* every
+        # AVR axis above has finished its homing cycle. Without this,
+        # the AVR is still running Z/X/Y homing G-code in the
+        # planner queue while ext.home() synchronously drives the ESP
+        # to home A in parallel - which is unsafe (the gantry and W
+        # axis can move at the same time) and visually confusing.
+        # We defer external homing to a background thread that
+        # polls cycle until the AVR cycle completes.
+        external_pending = []
+
         for axis in axes:
             enabled = state.is_axis_enabled(axis)
             mode = state.axis_homing_mode(axis)
 
+            # External axes (e.g. the auxcnc-driven A axis) home via
+            # their own ESP-side homing routine; the standard
+            # G28.2 / G38.6 / latch sequence doesn't apply.
+            #
+            # After homing we want a deterministic outcome regardless
+            # of where the user was before:
+            #   physical position = home_position_mm   (e.g. 134 mm)
+            #   work-coord origin = home position      (user A = 0)
+            #   work offset       = home_position_mm   (so abs - off = 0)
+            #
+            # ext.home() blocks on the ESP and updates state.ap to
+            # home_position_mm. We then need to tell the AVR (so its
+            # ex.position[A] matches physical reality) and gplan
+            # (so trajectory planning sees abs at home).
+            #
+            # We deliberately avoid G28.3 here: gplan's G28.3 keeps the
+            # current user-coord position fixed and adjusts the offset
+            # to match the new abs, which means re-homing after a move
+            # accumulates offset (134 -> 268 -> ...). Using G92 a0
+            # *after* syncing abs gives the desired "user A = 0 here"
+            # outcome with offset = home_position every time.
+            ext = getattr(self.ctrl, 'ext_axis', None)
+            if ext is not None and ext.enabled \
+                    and ext.axis_letter == axis.lower():
+                if 1 < len(axes) and not enabled:
+                    continue
+                # Defer until AVR axes are done. We capture the axis
+                # letter and ext reference; the actual homing runs
+                # in _run_external_homing below.
+                external_pending.append((axis, ext))
+                continue
+
             # If this is not a request to home a specific axis and the
             # axis is disabled or in manual homing mode, don't show any
             # warnings
@@ -347,8 +407,138 @@ class Mach(Comm):
             self.planner.mdi(gcode, False)
             super().resume()
 
+        # Kick off the deferred external-axis homing on a background
+        # thread so we don't block the HTTP handler (which is on the
+        # IOLoop) waiting for the AVR cycle to finish.
+        if external_pending:
+            prev = self._ext_home_thread
+            if prev is not None and prev.is_alive():
+                self.mlog.info(
+                    'External homing already in progress; ignoring '
+                    'duplicate request')
+            else:
+                import threading
+                t = threading.Thread(
+                    target=self._run_external_homing,
+                    args=(list(external_pending),),
+                    name='ext-home-deferred',
+                    daemon=True)
+                self._ext_home_thread = t
+                t.start()
 
-    def unhome(self, axis): self.mdi('G28.2 %c0' % axis)
+    def _run_external_homing(self, pending):
+        """Background worker: wait for the AVR cycle to drop to idle
+        (meaning all queued AVR-side homing is done), then run each
+        deferred external-axis home in order.
+
+        We split the work between two threads:
+          - this background thread blocks on the ESP serial RPC
+            (ext.home(), which can take 5-10 seconds while the
+            carriage seeks the limit and backs off twice);
+          - small bookkeeping operations that touch gplan, the AVR
+            command queue, or shared State are scheduled back onto
+            the IOLoop via ctrl.ioloop.add_callback() so we don't
+            race with the rest of the controller.
+        """
+        import time
+        # Wait up to 5 minutes for the AVR cycle to leave 'homing'.
+        # Long enough for any reasonable Onefinity full-travel home
+        # (Y axis at slow rate covers ~800 mm).
+        deadline = time.time() + 300.0
+        while time.time() < deadline:
+            cycle = self._get_cycle()
+            # 'homing' is the AVR's homing cycle; we wait for it to
+            # return to idle. If the user estopped or the cycle was
+            # aborted, cycle goes to idle too - we still proceed and
+            # the external home will fail-soft if conditions are wrong.
+            if cycle == 'idle':
+                break
+            time.sleep(0.1)
+        else:
+            self.mlog.error(
+                'External axis homing aborted: AVR cycle did not '
+                'return to idle within timeout')
+            return
+
+        for axis, ext in pending:
+            self.mlog.info('Homing external %s axis via auxcnc' %
+                           axis.upper())
+            # Begin the cycle on the IOLoop so cycle-state writes go
+            # through the same thread that all other state writes do.
+            self.ctrl.ioloop.add_callback(self._begin_cycle, 'homing')
+            try:
+                # ext.home() runs on this background thread - it
+                # blocks on serial I/O and is fully thread-safe (the
+                # AuxAxis driver has its own RPC lock).
+                ext.home()
+                home_mm = ext.home_position_mm
+                # All of the post-home bookkeeping touches gplan and
+                # the AVR command queue, both of which run on the
+                # IOLoop. Schedule it there in a single callback so
+                # the steps run in order without intervening events.
+                self.ctrl.ioloop.add_callback(
+                    self._finish_external_home, axis, home_mm)
+            except Exception as e:
+                self.mlog.error(
+                    'External axis homing failed: %s' % e)
+                # Cycle reset must also happen on the IOLoop. Without
+                # this the UI stays locked at 'homing' since the AVR
+                # never moved (no state change to drive _update's
+                # cycle-end path).
+                self.ctrl.ioloop.add_callback(
+                    self._abort_external_home_cycle)
+
+    def _finish_external_home(self, axis, home_mm):
+        """IOLoop-side completion of an external axis home.
+        Synchronizes AVR position, refreshes the planner, and emits
+        a G92 to set the user-coord origin at the home position.
+        """
+        try:
+            # 1) Update AVR: no motor steps, just position sync.
+            super().queue_command(Cmd.set_axis(axis, home_mm))
+            # 2) Force planner to resync abs from State on the next
+            #    planner call (which is the MDI below).
+            self.planner.position_change()
+            # 3) G92 <axis>0: with abs already at home_mm, sets
+            #    user-coord A = 0 and offset = home_mm. Use
+            #    planner.mdi (not Mach.mdi) so we don't flip cycle
+            #    to 'mdi' inside the 'homing' cycle.
+            self.planner.mdi('G92 %c0' % axis, False)
+            super().resume()
+        except Exception:
+            self.mlog.exception(
+                'Post-home bookkeeping failed for external axis')
+            self._abort_external_home_cycle()
+
+    def _abort_external_home_cycle(self):
+        """Reset cycle to idle from the IOLoop after a failed
+        external axis home. The AVR never moved so _update's normal
+        cycle-end path won't fire; do it explicitly here.
+        """
+        if self._get_cycle() == 'homing':
+            try:
+                self._set_cycle('idle')
+            except Exception:
+                self.mlog.exception(
+                    'Failed to reset cycle to idle after external '
+                    'homing error')
+
+
+    def unhome(self, axis):
+        # External axes don't have AVR-side homed state to clear; the
+        # ESP holds its own homed flag. We don't have an explicit
+        # "unhome" verb on the ESP, but a stale homed flag is harmless
+        # because the next absolute move will fail-soft via
+        # ExternalAxis._pos_mm sync. Still mirror the cleared flag
+        # into State for the UI.
+        ext = getattr(self.ctrl, 'ext_axis', None)
+        if ext is not None and ext.enabled \
+                and chr(axis).lower() == ext.axis_letter:
+            from bbctrl.ExternalAxis import EXTERNAL_MOTOR_INDEX
+            self.ctrl.state.set('%dh' % EXTERNAL_MOTOR_INDEX, 0)
+            self.ctrl.state.set(ext.axis_letter + '_homed', False)
+            return
+        self.mdi('G28.2 %c0' % axis)
     def estop(self): super().estop()
 
 
@@ -375,6 +565,12 @@ class Mach(Comm):
     def stop(self):
         if self._get_state() != 'jogging': self.stopping = True
         super().i2c_command(Cmd.STOP)
+        # Drain the external-axis worker queue so post-stop resumption
+        # doesn't replay queued moves that the user wanted cancelled.
+        ext = getattr(self.ctrl, 'ext_axis', None)
+        if ext is not None:
+            try: ext.abort()
+            except Exception: pass
         
     def pause(self): super().pause()
 

src/py/bbctrl/Planner.py

@@ -196,12 +196,23 @@ class Planner():
 
 
     def _add_message(self, text):
-        self.ctrl.state.add_message(text)
-
         line = self.ctrl.state.get('line', 0)
         if 0 <= line: where = '%s:%d' % (self.where, line)
         else: where = self.where
 
+        # HOOK:<event>:<data> messages are an internal IPC channel
+        # between the gcode preprocessor and Hooks; bypass the user
+        # message list so they don't surface as popups, and dispatch
+        # the hook directly. Routing through state.messages would
+        # only deliver it after the 0.25s state-change debounce, by
+        # which point we'd have to keep it visible to ensure Hooks
+        # could see it.
+        hooks = getattr(self.ctrl, 'hooks', None)
+        if hooks is not None and hooks.dispatch_hook_message(text):
+            self.log.info('HOOK msg: %s' % text, where = where)
+            return
+
+        self.ctrl.state.add_message(text)
         self.log.message(text, where = where)
 
 
@@ -259,6 +270,54 @@ class Planner():
         if type != 'set': self.log.info('Cmd:' + log_json(block))
 
         if type == 'line':
+            # Z-A coupling check: every line block that touches Z (or
+            # A) is validated against the projected (A,Z) machine
+            # pair. The ExternalAxis check is improvement-aware: it
+            # only refuses moves that worsen an existing violation
+            # or push a healthy state into one. So pure-XY jogs and
+            # recovery moves (Z up, A down) are not rejected even
+            # when (A-Z) is currently above the bound.
+            ext_check = getattr(self.ctrl, 'ext_axis', None)
+            if ext_check is not None:
+                from bbctrl.ExternalAxis import ExternalAxisError
+                target = block.get('target') or {}
+                z_target = target.get('z')
+                if z_target is None: z_target = target.get('Z')
+                a_letter = ext_check.axis_letter
+                a_target = target.get(a_letter)
+                if a_target is None:
+                    a_target = target.get(a_letter.upper())
+                if z_target is not None or a_target is not None:
+                    try:
+                        ext_check.check_coupling(
+                            target_a_machine=a_target,
+                            target_z_machine=z_target)
+                    except ExternalAxisError as e:
+                        # Convert the raw error into a clean abort:
+                        # surface the message to the operator, stop
+                        # the cycle, and skip this block. Returning
+                        # None drops the block from the AVR queue;
+                        # mach.stop() halts further planner output
+                        # so the rest of an offending program can't
+                        # leak through. The planner stays usable
+                        # for new MDI / jog commands.
+                        self.log.warning('Z-A coupling refused: %s' % e)
+                        try:
+                            self.ctrl.state.add_message(
+                                'Z-A coupling refused move: ' + str(e))
+                        except Exception: pass
+                        try:
+                            self.ctrl.mach.stop()
+                        except Exception: pass
+                        return None
+
+            ext = self._external_axis_for_line(block)
+            if ext is not None:
+                # Side effect: enqueue the ESP move on the external-
+                # axis worker. The AVR still receives the full target
+                # (including A) so ex.position[A] tracks gplan; no
+                # motor steps for A because no motor maps to it.
+                self._dispatch_external_line(block, ext)
             self._enqueue_line_time(block)
             return Cmd.line(block['target'], block['exit-vel'],
                             block['max-accel'], block['max-jerk'],
@@ -289,8 +348,17 @@ class Planner():
 
                 if name[2:] == '_homed':
                     motor = self.ctrl.state.find_motor(name[1])
-                    if motor is not None:
+                    # Synthetic external motor (index 4) doesn't exist
+                    # on the AVR; mirror the homed flag in State only.
+                    from bbctrl.ExternalAxis import EXTERNAL_MOTOR_INDEX
+                    if motor is not None and motor < EXTERNAL_MOTOR_INDEX:
                         return Cmd.set_sync('%dh' % motor, value)
+                    if motor == EXTERNAL_MOTOR_INDEX:
+                        # Update synthetic motor flag and the<axis>_homed
+                        # projection consumed by the DRO.
+                        self.cmdq.enqueue(
+                            id, self.ctrl.state.set,
+                            '%dh' % EXTERNAL_MOTOR_INDEX, value)
 
             return
 
@@ -339,6 +407,68 @@ class Planner():
             self.planner.set_logger(None)
 
 
+    # ----------------------------------------------- external-axis routing
+    #
+    # When an axis is exposed to gplan via a synthetic motor (no AVR
+    # channel), we need to fork its motion off to the ESP at line
+    # encode time and let the rest of the line proceed to the AVR.
+    # The split is done here rather than in gplan because gplan
+    # treats all six axes uniformly and just emits target dicts; we
+    # don't want to teach it about the ESP.
+
+    def _external_axis_for_line(self, block):
+        """Return the ExternalAxis instance for whichever axis in
+        block['target'] is external, or None."""
+        ext = getattr(self.ctrl, 'ext_axis', None)
+        if ext is None or not ext.enabled:
+            return None
+        target = block.get('target') or {}
+        if ext.axis_letter in target or ext.axis_letter.upper() in target:
+            return ext
+        return None
+
+    def _dispatch_external_line(self, block, ext):
+        """Side-effect: enqueue the ESP move on the external-axis
+        worker thread (non-blocking). Returns the block (possibly
+        unchanged) for the AVR.
+
+        We do NOT strip the external axis target from the AVR line.
+        The AVR's exec_move_to_target updates ex.position[axis] for
+        every axis in the target dict regardless of motor mapping,
+        and reports it back via the `p` indexed var. Leaving A in
+        the target keeps state.ap in sync with gplan's idea of A
+        (otherwise the AVR's stale ex.position[A] would clobber
+        ExternalAxis's state.ap=N update on the next status report).
+
+        The AVR doesn't step any motor for the external axis (no
+        motor maps to it) - so leaving A in the target is
+        physically a no-op for the steppers, while keeping the
+        host-side state coherent.
+
+        We pass the full S-curve parameters to the ESP so its move
+        duration matches the AVR's exactly. The ESP runs the same
+        7-segment jerk-limited trajectory the AVR would have run
+        if A had been a real motor."""
+        target = block.get('target') or {}
+        # Read the external target (case-insensitive) without modifying
+        # the dict so the AVR still sees A.
+        ext_mm = target.get(ext.axis_letter)
+        if ext_mm is None:
+            ext_mm = target.get(ext.axis_letter.upper())
+        try:
+            ext.enqueue_line(
+                ext_mm,
+                block.get('max-accel', 0.0),
+                block.get('max-jerk',  0.0),
+                block.get('entry-vel', 0.0),
+                block.get('exit-vel',  0.0),
+                block.get('times',     [0]*7),
+            )
+        except Exception as e:
+            self.log.error('External axis enqueue failed: %s' % e)
+            raise
+        return block
+
     def reset(self, *args, **kwargs):
         stop = kwargs.get('stop', True)
         if stop:
@@ -352,6 +482,16 @@ class Planner():
         self.cmdq.clear()
         self.reset_times()
 
+        # Drain the external-axis worker queue and force the next
+        # move to re-sync position from the ESP (since State.reset
+        # below will zero <axis>p which makes ext._pos_mm stale).
+        ext = getattr(self.ctrl, 'ext_axis', None)
+        if ext is not None:
+            try: ext.abort()
+            except Exception: pass
+            try: ext._pos_mm = None
+            except Exception: pass
+
         resetState = kwargs.get('resetState', True)
         if resetState:
             self.ctrl.state.reset()
@@ -369,6 +509,22 @@ class Planner():
         self.where = path
         path = self.ctrl.get_path('upload', path)
         self.log.info('GCode:' + path)
+        # Rewrite ATC M-codes (M100..M103) before gplan sees them.
+        # preprocess_file is a no-op when no rewriting is needed and
+        # idempotent when run twice on the same file, so this is
+        # safe on every load. W tokens are no longer rewritten - the
+        # auxcnc stepper is now exposed as a virtual A axis and gcode
+        # should use A directly.
+        try:
+            from bbctrl.AuxPreprocessor import preprocess_file
+            ext = getattr(self.ctrl, 'ext_axis', None)
+            coupling = (ext.coupling_for_preprocessor()
+                        if ext is not None else None)
+            if preprocess_file(path, log=self.log, coupling=coupling):
+                self.log.info('Rewrote (ATC / Z-A coupling) in %s' % path)
+        except Exception:
+            self.log.exception('Aux preprocess at load failed; '
+                               'attempting to load file unchanged')
         self._sync_position()
         self.planner.load(path, self.get_config(False, True))
         self.reset_times()

src/py/bbctrl/State.py

@@ -107,8 +107,14 @@ class State(object):
 
 
     def reset(self):
-        # Unhome all motors
-        for i in range(4): self.set('%dhomed' % i, False)
+        # Unhome all motors (real AVR motors 0..3 and the synthetic
+        # external-axis motor at index 4 used by ExternalAxis).
+        # Both <motor>homed and <motor>h are cleared - they're set
+        # by different code paths (gplan emits homed via _<axis>_homed
+        # set blocks, AVR reports h directly).
+        for i in range(5):
+            self.set('%dhomed' % i, False)
+            self.set('%dh' % i, 0)
 
         # Zero offsets and positions
         for axis in 'xyzabc':
@@ -280,8 +286,11 @@ class State(object):
         axis_motors = {axis: self.find_motor(axis) for axis in 'xyzabc'}
         axis_vars = {}
 
+        # NOTE: motor index '4' is a host-only synthetic motor used
+        # by ExternalAxis to expose the auxcnc ESP-driven stepper as
+        # an additional axis. Real AVR motors are 0..3.
         for name, value in vars.items():
-            if name[0] in '0123':
+            if name[0] in '01234':
                 motor = int(name[0])
 
                 for axis in 'xyzabc':
@@ -330,6 +339,9 @@ class State(object):
     def get_axis_vector(self, name, scale = 1):
         v = {}
 
+        # 0..3 are AVR motor channels. 4 is the host-side synthetic
+        # motor used by ExternalAxis. find_motor returns the right
+        # index regardless of whether the axis is physical or external.
         for axis in 'xyzabc':
             motor = self.find_motor(axis)
 
@@ -351,7 +363,10 @@ class State(object):
 
 
     def find_motor(self, axis):
-        for motor in range(4):
+        # Walk 0..4: 0..3 are real AVR motors, 4 is the synthetic
+        # host-side motor used to expose the auxcnc ESP stepper as
+        # an external axis.
+        for motor in range(5):
             if not ('%dan' % motor) in self.vars: continue
             motor_axis = 'xyzabc'[self.vars['%dan' % motor]]
             if motor_axis == axis.lower() and self.vars.get('%dme' % motor, 0):

src/py/bbctrl/Web.py

@@ -812,8 +812,12 @@ class AuxStatusHandler(bbctrl.APIHandler):
 
 class AuxHomeHandler(bbctrl.APIHandler):
     def put_ok(self):
-        # Run synchronously via the AuxAxis' own RPC; this blocks the
-        # request. Fine because the UI shows a spinner.
+        # Run synchronously. Route through ExternalAxis so the
+        # synthetic motor's homed flag and DRO update.
+        ext = getattr(self.get_ctrl(), 'ext_axis', None)
+        if ext is not None and ext.enabled:
+            ext.home()
+        else:
             self.get_ctrl().aux.home()
 
 
@@ -824,12 +828,22 @@ class AuxAbortHandler(bbctrl.APIHandler):
 
 class AuxJogHandler(bbctrl.APIHandler):
     """Body: {"mm": 1.5}  for relative-mm move,
-             {"steps": 200} for raw step move (bypasses soft limits)."""
+             {"steps": 200} for raw step move (bypasses soft limits).
+
+    Note: with the gplan-integrated W axis, jog-by-mm goes through
+    ExternalAxis so the DRO updates and gplan's idea of A's position
+    stays in sync. jog-by-steps still bypasses everything for the
+    homing/setup workflow where the axis isn't homed yet."""
     def put_ok(self):
         body = self.json or {}
         aux = self.get_ctrl().aux
+        ext = getattr(self.get_ctrl(), 'ext_axis', None)
         if 'mm' in body:
-            aux.move_rel_mm(float(body['mm']))
+            delta_mm = float(body['mm'])
+            if ext is not None and ext.enabled and ext._pos_mm is not None:
+                ext.execute_to_mm(ext._pos_mm + delta_mm)
+            else:
+                aux.move_rel_mm(delta_mm)
         elif 'steps' in body:
             aux.jog_steps(int(body['steps']))
         else:
@@ -842,6 +856,10 @@ class AuxMoveHandler(bbctrl.APIHandler):
         body = self.json or {}
         if 'mm' not in body:
             raise HTTPError(400, 'mm required')
+        ext = getattr(self.get_ctrl(), 'ext_axis', None)
+        if ext is not None and ext.enabled:
+            ext.execute_to_mm(float(body['mm']))
+        else:
             self.get_ctrl().aux.move_abs_mm(float(body['mm']))
 
 

src/py/bbctrl/__init__.py

@@ -68,6 +68,7 @@ from bbctrl.IOLoop import IOLoop
 from bbctrl.MonitorTemp import MonitorTemp
 from bbctrl.Hooks import Hooks
 from bbctrl.AuxAxis import AuxAxis
+from bbctrl.ExternalAxis import ExternalAxis
 import bbctrl.Cmd as Cmd
 import bbctrl.v4l2 as v4l2
 import bbctrl.Log as log

src/stylus/style.styl

@@ -1396,7 +1396,7 @@ tt.save
 
 .control-page .dro-head, .control-page .dro-row
   display grid
-  grid-template-columns 84px 1.4fr 1fr 1fr 170px 170px 280px
+  grid-template-columns 84px 1.4fr 1fr 1fr 280px
   column-gap 0.75rem
   align-items center
   padding 14px 22px
@@ -1529,6 +1529,39 @@ tt.save
     opacity 0.45
     cursor not-allowed
 
+  // State-tinted variants used on home + zero buttons in DRO rows
+  // to communicate per-axis homing / toolpath fit at a glance,
+  // replacing the explicit HOMED / OK chips that used to live in
+  // their own columns.
+  &.state-green
+    background #dcfce7
+    border-color #86efac
+    color #166534
+
+    &:hover:not([disabled])
+      background #bbf7d0
+
+  &.state-amber
+    background #fef3c7
+    border-color #fcd34d
+    color #92400e
+
+    &:hover:not([disabled])
+      background #fde68a
+
+  &.state-red
+    background #fee2e2
+    border-color #fca5a5
+    color #991b1b
+
+    &:hover:not([disabled])
+      background #fecaca
+
+  &[disabled].state-green,
+  &[disabled].state-amber,
+  &[disabled].state-red
+    opacity 0.7
+
 .actions-cell
   display flex
   justify-content flex-end
@@ -2380,7 +2413,7 @@ html.kiosk-mode
     gap 6px
 
   .control-page .dro-head, .control-page .dro-row
-    grid-template-columns 56px 1fr 0.85fr 0.85fr 90px 90px 1fr
+    grid-template-columns 56px 1fr 0.85fr 0.85fr 1fr
     column-gap 0.4rem
     padding 6px 10px
 

src/svelte-components/src/components/AAxisSettings.svelte

@@ -4,18 +4,24 @@
     import * as api from "$lib/api";
 
     // Mirrors the DEFAULTS in src/py/bbctrl/AuxAxis.py. The "enabled"
-    // flag is read-only here; toggling the W axis on/off is done via
-    // aux.json on disk, so adding/removing the hardware doesn't have a
-    // surprise UI that bricks bring-up.
+    // flag is read-only here; toggling the auxiliary A axis on/off
+    // is done via aux.json on disk, so adding/removing the hardware
+    // doesn't have a surprise UI that bricks bring-up. Legacy aux.json
+    // files using min_w/max_w are migrated up to min_mm/max_mm by
+    // AuxAxis._migrate_legacy_fields on load.
     type AuxConfig = {
         enabled: boolean;
         port: string;
         baud: number;
         steps_per_mm: number;
         dir_sign: number;
-        min_w: number;
-        max_w: number;
+        axis_letter: string;
+        min_mm: number;
+        max_mm: number;
         max_feed_mm_min: number;
+        max_velocity_m_per_min: number;
+        max_accel_km_per_min2: number;
+        max_jerk_km_per_min3: number;
         home_dir: string;
         home_position_mm: number;
         home_fast_sps: number;
@@ -26,6 +32,9 @@
         step_accel_sps2: number;
         step_start_sps: number;
         limit_low: boolean;
+        couple_z_enabled: boolean;
+        couple_z_clearance_mm: number;
+        z_home_mm: number;
     };
 
     let cfg: AuxConfig | null = null;
@@ -69,9 +78,9 @@
         }
     }
 
-    // Mark the root config as modified whenever a W axis field is
-    // edited, so the master Save button highlights and the user knows
-    // there are unsaved changes.
+    // Mark the root config as modified whenever an auxiliary axis
+    // field is edited, so the master Save button highlights and
+    // the user knows there are unsaved changes.
     function markDirty() {
         try {
             const root = (window as any).$root || (window as any).Vue?.root;
@@ -82,9 +91,9 @@
     }
 </script>
 
-<div class="w-axis-settings">
+<div class="a-axis-settings">
     {#if !cfg}
-        <p class="tip">Loading W axis configuration...</p>
+        <p class="tip">Loading A axis configuration...</p>
     {:else}
         <div class="status">
             {#if status}
@@ -105,7 +114,7 @@
 
         <div class="pure-form pure-form-aligned" on:input={markDirty} on:change={markDirty}>
             <fieldset>
-                <div class="pure-control-group" title="Enable the auxcnc W axis. Edit aux.json to toggle.">
+                <div class="pure-control-group" title="Enable the auxiliary axis (auxcnc-driven A). Edit aux.json to toggle.">
                     <label for="enabled">enabled</label>
                     <input id="enabled" type="checkbox" checked={cfg.enabled} disabled />
                     <label for="" class="units">(edit aux.json)</label>
@@ -124,13 +133,13 @@
 
             <h3>Mechanics</h3>
             <fieldset>
-                <div class="pure-control-group" title="Logical steps per mm of W travel.">
+                <div class="pure-control-group" title="Logical steps per mm of axis travel.">
                     <label for="steps_per_mm">steps per mm</label>
                     <input id="steps_per_mm" type="number" bind:value={cfg.steps_per_mm} step="any" />
                     <label for="" class="units">steps/mm</label>
                 </div>
 
-                <div class="pure-control-group" title="Direction sign: +1 or -1. Flip if W+ moves the wrong way.">
+                <div class="pure-control-group" title="Direction sign: +1 or -1. Flip if A+ moves the wrong way.">
                     <label for="dir_sign">direction sign</label>
                     <select id="dir_sign" bind:value={cfg.dir_sign}>
                         <option value={1}>+1</option>
@@ -138,19 +147,78 @@
                     </select>
                 </div>
 
-                <div class="pure-control-group" title="Soft-limit minimum W in mm.">
-                    <label for="min_w">soft min</label>
-                    <input id="min_w" type="number" bind:value={cfg.min_w} step="any" />
+                <div class="pure-control-group" title="gcode axis letter exposed to the planner. Default 'a' (the standard 4th axis).">
+                    <label for="axis_letter">axis letter</label>
+                    <select id="axis_letter" bind:value={cfg.axis_letter}>
+                        <option value="a">A</option>
+                        <option value="b">B</option>
+                        <option value="c">C</option>
+                    </select>
+                </div>
+
+                <div class="pure-control-group" title="Soft-limit minimum in mm.">
+                    <label for="min_mm">soft min</label>
+                    <input id="min_mm" type="number" bind:value={cfg.min_mm} step="any" />
                     <label for="" class="units">mm</label>
                 </div>
 
-                <div class="pure-control-group" title="Soft-limit maximum W in mm.">
-                    <label for="max_w">soft max</label>
-                    <input id="max_w" type="number" bind:value={cfg.max_w} step="any" />
+                <div class="pure-control-group" title="Soft-limit maximum in mm.">
+                    <label for="max_mm">soft max</label>
+                    <input id="max_mm" type="number" bind:value={cfg.max_mm} step="any" />
+                    <label for="" class="units">mm</label>
+                </div>
+            </fieldset>
+
+            <h3>Z-A Coupling</h3>
+            <p class="tip">
+                The auxiliary tool hangs below the Z spindle. Beyond a small
+                Z descent the two collide unless A drops with Z. The rule
+                in machine coordinates is
+                <code>A &minus; Z &le; (A_home &minus; Z_home) + clearance</code>.
+                When enabled, the planner refuses moves that would violate
+                it and the gcode preprocessor injects pre-position A moves
+                into uploaded files.
+            </p>
+            <fieldset>
+                <div class="pure-control-group" title="Master switch for the Z-A interlock. When off, no checks are performed.">
+                    <label for="couple_z_enabled">enable coupling</label>
+                    <input id="couple_z_enabled" type="checkbox" bind:checked={cfg.couple_z_enabled} />
+                </div>
+
+                <div class="pure-control-group" title="How far Z may descend below its home position before A must move with it.">
+                    <label for="couple_z_clearance_mm">Z clearance</label>
+                    <input id="couple_z_clearance_mm" type="number" bind:value={cfg.couple_z_clearance_mm} step="any" />
                     <label for="" class="units">mm</label>
                 </div>
 
-                <div class="pure-control-group" title="Informational max feed; rate caps live on the ESP.">
+                <div class="pure-control-group" title="Z's machine position when homed. Almost always 0.">
+                    <label for="z_home_mm">Z home position</label>
+                    <input id="z_home_mm" type="number" bind:value={cfg.z_home_mm} step="any" />
+                    <label for="" class="units">mm</label>
+                </div>
+            </fieldset>
+
+            <h3>Planner Limits</h3>
+            <fieldset>
+                <div class="pure-control-group" title="Maximum velocity used by gplan trajectory planning.">
+                    <label for="max_velocity_m_per_min">max velocity</label>
+                    <input id="max_velocity_m_per_min" type="number" bind:value={cfg.max_velocity_m_per_min} step="any" />
+                    <label for="" class="units">m/min</label>
+                </div>
+
+                <div class="pure-control-group" title="Maximum acceleration used by gplan trajectory planning.">
+                    <label for="max_accel_km_per_min2">max acceleration</label>
+                    <input id="max_accel_km_per_min2" type="number" bind:value={cfg.max_accel_km_per_min2} step="any" />
+                    <label for="" class="units">km/min²</label>
+                </div>
+
+                <div class="pure-control-group" title="Maximum jerk used by gplan trajectory planning.">
+                    <label for="max_jerk_km_per_min3">max jerk</label>
+                    <input id="max_jerk_km_per_min3" type="number" bind:value={cfg.max_jerk_km_per_min3} step="any" />
+                    <label for="" class="units">km/min³</label>
+                </div>
+
+                <div class="pure-control-group" title="Informational max feed; rate caps live on the ESP via step_max_sps.">
                     <label for="max_feed_mm_min">max feed</label>
                     <input id="max_feed_mm_min" type="number" bind:value={cfg.max_feed_mm_min} step="any" />
                     <label for="" class="units">mm/min</label>
@@ -162,12 +230,12 @@
                 <div class="pure-control-group" title="Direction the axis moves when looking for the home limit switch.">
                     <label for="home_dir">home direction</label>
                     <select id="home_dir" bind:value={cfg.home_dir}>
-                        <option value="-">- (toward W-)</option>
-                        <option value="+">+ (toward W+)</option>
+                        <option value="-">- (toward A-)</option>
+                        <option value="+">+ (toward A+)</option>
                     </select>
                 </div>
 
-                <div class="pure-control-group" title="W position assigned when homing completes.">
+                <div class="pure-control-group" title="Axis position assigned when homing completes.">
                     <label for="home_position_mm">home position</label>
                     <input id="home_position_mm" type="number" bind:value={cfg.home_position_mm} step="any" />
                     <label for="" class="units">mm</label>
@@ -229,7 +297,7 @@
                 master <strong>Save</strong> button at the bottom of the
                 settings rail. Homing rates and the limit polarity are
                 pushed to the ESP immediately; any running motion is
-                unaffected. Re-home the W axis after changing direction,
+                unaffected. Re-home the auxiliary axis after changing direction,
                 sign, or step settings.
             </div>
         </div>
@@ -237,7 +305,7 @@
 </div>
 
 <style lang="scss">
-    .w-axis-settings {
+    .a-axis-settings {
         .status {
             margin-bottom: 1em;
             font-size: 90%;

src/svelte-components/src/components/SettingsView.svelte

@@ -2,10 +2,10 @@
     import configTemplate from "../../../resources/config-template.json";
     import ScreenRotationDialog from "$dialogs/ScreenRotationDialog.svelte";
     import ConfigTemplatedInput from "./ConfigTemplatedInput.svelte";
-    // WAxisSettings is mounted directly by the V09 settings shell at
-    // #w-axis instead of being embedded here — see
-    // src/pug/templates/w-axis-view.pug.
-    // import WAxisSettings from "./WAxisSettings.svelte";
+    // AAxisSettings is mounted directly by the V09 settings shell at
+    // #a-axis instead of being embedded here — see
+    // src/pug/templates/a-axis-view.pug.
+    // import AAxisSettings from "./AAxisSettings.svelte";
     import SetTimeDialog from "$dialogs/SetTimeDialog.svelte";
     import Button, { Label } from "@smui/button";
 
@@ -99,7 +99,7 @@
         </fieldset>
 
         <!-- W Axis (auxcnc) is now its own routed page in the V09
-             settings shell (#w-axis). Keep the SettingsView free of
+             settings shell (#a-axis). Keep the SettingsView free of
              that section so we don't render it twice. -->
 
         <h2 id="sec-path-accuracy" data-sec="gcode">Path Accuracy</h2>

src/svelte-components/src/main.ts

@@ -6,7 +6,7 @@ matchAll.shim();
 import AdminNetworkView from "$components/AdminNetworkView.svelte";
 import SettingsView from "$components/SettingsView.svelte";
 import HelpView from "$components/HelpView.svelte";
-import WAxisSettings from "$components/WAxisSettings.svelte";
+import AAxisSettings from "$components/AAxisSettings.svelte";
 import DialogHost, { showDialog } from "$dialogs/DialogHost.svelte";
 import { handleConfigUpdate, setDisplayUnits } from "$lib/ConfigStore";
 import { handleControllerStateUpdate } from "$lib/ControllerState";
@@ -23,8 +23,8 @@ export function createComponent(component: string, target: HTMLElement, props: R
         case "HelpView":
             return new HelpView({ target, props });
 
-        case "WAxisSettings":
-            return new WAxisSettings({ target, props });
+        case "AAxisSettings":
+            return new AAxisSettings({ target, props });
 
         case "DialogHost":
             return new DialogHost({ target, props });