onefinity-firmware/docs/AUX_W_AXIS.md

W axis (auxcnc) integration

This adds a virtual W axis to the bbctrl controller, driven by the auxcnc ESP32 over USB serial (/dev/ttyUSB0). The ESP owns step-pulse generation, real-time limit-switch monitoring, and the homing dance. The Pi owns units (mm), soft limits, sequencing inside G-code jobs, and a small REST API for jogging / homing from the UI.

How it works

The bbctrl planner (gplan) only understands xyzabc, so adding a true 7th axis would require rebuilding gplan + the AVR firmware. We avoid that by treating W as a synchronous out-of-band axis: W moves run between G-code blocks, not blended with XYZ.

Pipeline:

1. User uploads a G-code file containing W words.
2. FileHandler runs AuxPreprocessor on the upload, rewriting W tokens in place into (MSG,HOOK:aux:<mm>) etc. The original line minus the W word continues to drive XYZ.
3. The planner sees only XYZ + message comments. When it reaches a message line, the message goes through state.add_message which Hooks._on_state_change watches for the HOOK: prefix.
4. Hooks._fire('custom', ...) finds the registered internal handler for the event name (aux, aux_rel, aux_home, aux_setzero).
5. The handler runs in a hook thread, gating Mach.unpause until done. While the handler is busy the machine is in HOLDING - no XYZ motion can resume until W finishes.
6. The handler talks to the ESP over /dev/ttyUSB0 via AuxAxis, blocking on a deterministic reply token ([step] done, [home] done, etc).

MDI commands containing W words are rewritten the same way at the Mach.mdi() boundary so manual jog and macros work too.

G-code surface

G21 G90
G28 W0          ; home W axis
G1 W25 F300     ; move W to 25 mm absolute
G1 X100 W12.5   ; mixed: W moves first, then XYZ (configurable)
G91
G1 W-2.5        ; relative W move
G90
G92 W0          ; set current W as zero (G92-style)

Rules:

• G28 / G28.2 with W only -> homing hook; the bare G28 is NOT emitted to gplan (that would mean home-all).
• G28.2 X0 Y0 W0 -> emit hook, then keep G28.2 X0 Y0 for XY homing.
• A line with both W and XYZ axis words is split into two sequential blocks. Default order: W first, then XYZ. Toggle via the w_first constructor arg.
• Lines inside parens or after ; are passed through verbatim.

Configuration

Per-controller config lives at <ctrl_path>/aux.json (created on first save via the API). Keys:

Key	Default	Notes
enabled	false	Master switch
port	/dev/ttyUSB0	Serial device
baud	115200
steps_per_mm	80.0	Logical steps per mm
dir_sign	1	+1 or -1: maps logical+ to motor+
min_w, max_w	0, 100	Soft limits in mm
home_dir	'-'	Direction toward limit switch
home_position_mm	0.0	mm value assigned at home
home_fast_sps	4000	Fast seek rate
home_slow_sps	400	Slow re-seek rate
home_backoff_steps	200	Backoff after touching limit
home_maxtravel_steps	200000	Hard cap on phase 1 seek
step_max_sps	4000	Cruise rate for STEPS
step_accel_sps2	16000	Trapezoidal ramp accel
step_start_sps	200	Ramp floor
limit_low	true	Switch active low (closed = LOW)

Most of these are pushed to the ESP via HOMECFG on connect and persisted there in NVS.

REST API

Verb	Path	Body	Effect
GET	/api/aux/config	-	Current config
PUT	/api/aux/config/save	{key: val, ...}	Save and re-push
GET	/api/aux/status	-	{enabled, present, homed, pos_mm}
PUT	/api/aux/home	-	Run home cycle (blocks)
PUT	/api/aux/abort	-	Cancel running motion
PUT	/api/aux/jog	{mm: 1.5} or {steps: 200}	Relative move
PUT	/api/aux/move	{mm: 12.5}	Absolute move (mm)
PUT	/api/aux/set-zero	{mm: 0}	Set current pos to mm

Steps-mode jog ignores soft limits (use it to inch the axis to the limit switch when the axis isn't homed yet).

UI

Control view

• A jog row appears under the XYZ jog grid when aux_enabled is true, with three buttons: W-, W+, and a wide Home W. There is intentionally no separate "set zero" or "W origin" button - homing lands the axis at home_position_mm (0 by default), so home and zero are the same point.
• The DRO table shows a W axis row with position, status (OFFLINE / UNHOMED / HOMED), and a single Home button in the actions column (the cog and map-marker columns are placeholders for layout).

Settings view

A "W Axis (auxcnc)" section exposes every aux.json field except enabled (which stays read-only - flipping the W axis on/off requires editingaux.json on the controller, so a fresh install can't surprise the user with hardware that isn't there). Saving PUTs the merged config to /api/aux/config/save, which writes aux.json and pushes HOMECFG to the ESP. A status line shows whether the axis is disabled / offline / connected-unhomed / homed at <pos> mm.

State surface

These are pushed via state.set and visible in the websocket stream:

• aux_enabled - bool, axis is configured + enabled
• aux_present - bool, ESP responding on serial
• aux_homed - bool, has been homed since last ESP reset
• aux_pos - float, current W in mm (4 decimals)

Edge cases

• ESP reboots mid-job: [boot] auxcnc v=N banner -> aux_homed cleared, message added: "W axis controller restarted - re-home before use". Subsequent W moves still run; if you want a hard fail instead, that's a one-line change in _require_present.
• Limit switch closed at boot of HOME: [home] failed reason=already_at_limit -> hook raises -> Mach surfaces error.
• Pause mid-W-move: the hook is blocking, so feed-hold takes effect after the W move completes. For an immediate stop hit estop; the Hooks listener will call aux.abort() which sends ABORT\n to the ESP and the step-pulse loop exits.
• Connection loss: if /dev/ttyUSB0 can't be opened at startup, aux_present=False and any G-code with W will fail-fast at the hook handler with "Aux axis not connected".
• No home enforcement: per design, manual jogs and W moves are allowed even without a successful home. Soft limits still apply unless you use the raw step jog endpoint.

Files added/changed

• src/py/bbctrl/AuxAxis.py (new): serial worker + RPC layer
• src/py/bbctrl/AuxPreprocessor.py (new): G-code rewriter
• src/py/bbctrl/Hooks.py: register_internal(), fix the messages listener so (MSG,HOOK:...) actually fires
• src/py/bbctrl/Ctrl.py: instantiate AuxAxis, register hooks
• src/py/bbctrl/Mach.py: rewrite MDI commands containing W
• src/py/bbctrl/FileHandler.py: rewrite uploads in place
• src/py/bbctrl/Web.py: REST endpoints
• src/py/bbctrl/__init__.py: export AuxAxis
• src/pug/templates/control-view.pug: W jog row + DRO row
• src/js/control-view.js: aux_home / aux_jog / aux_jog_incr handlers
• src/js/axis-vars.js: _compute_aux_axis for W state
• src/svelte-components/src/components/WAxisSettings.svelte: settings panel
• src/svelte-components/src/components/SettingsView.svelte: hosts WAxisSettings
• auxcnc/src/main.cpp: new commands HOME, HOMECFG, WPOS, HOMED?, LIMIT?, ABORT-able STEPS with limit-aware abort, trapezoidal ramps, NVS-persisted config, [boot] banner, deterministic reply tokens