From ef78f20eaa9501dc496acfb18b416500bfa9dcc6 Mon Sep 17 00:00:00 2001 From: Henrik Muehe Date: Thu, 30 Apr 2026 19:54:30 +0200 Subject: [PATCH] Docs: README + W axis docs cover macOS build/flash and new UI - README.md (was a one-liner): describe the layout, the macOS quick path including the esbuild platform-pin gotcha, and how to flash with curl or 'make update'. - docs/AUX_W_AXIS.md: document the new Control jog row layout, the Settings 'W Axis (auxcnc)' section, and list the additional UI files touched by this fork. --- README.md | 123 ++++++++++++++++++++++++++++++++++++++++++++- docs/AUX_W_AXIS.md | 30 ++++++++++- 2 files changed, 151 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8988acf..90e6554 100644 --- a/README.md +++ b/README.md @@ -1 +1,122 @@ -#OneFinity CNC Controller Firmware +# OneFinity CNC Controller Firmware (W-axis fork) + +This is the OneFinity / Buildbotics bbctrl firmware with a virtual W +axis driven by an auxcnc ESP32 over USB serial. See +[docs/AUX_W_AXIS.md](docs/AUX_W_AXIS.md) for the design and config. + +## Layout + +``` +src/avr/ AVR firmware (motion controller, AtxMega) +src/boot/ AVR bootloader +src/bbserial/ Linux kernel module for the bbserial driver +src/py/bbctrl/ Python control daemon (Tornado + websockets) +src/js/ Vue.js UI (legacy) +src/svelte-components/ Newer Svelte UI for dialogs and settings +src/pug/ Pug templates compiled into build/http/index.html +src/resources/ Static assets and config templates +scripts/ Install / update / RPi build helpers +docs/ Architecture, dev setup, W-axis docs +``` + +## Build & flash (quick path, macOS or Linux) + +The full build (`make`) requires `avr-gcc`, but the controller and UI +only depend on the Python + web parts. If you're shipping a UI/Python +change you don't need the AVR toolchain. + +### Prerequisites + +- Node.js (any recent LTS) with npm +- Python 3 with setuptools +- `npm install` once at the project root (this is wired into the + `node_modules` Make target, but on a fresh checkout it's clearer to + do it explicitly) + +```bash +npm install +(cd src/svelte-components && npm install) +``` + +#### macOS gotcha: esbuild platform pin + +The Pi build leaves `node_modules/esbuild` pinned to +`linux-arm64`, which won't run on Darwin. If `npm run build` inside +`src/svelte-components` complains about esbuild, reinstall it for the +host: + +```bash +cd src/svelte-components +rm -rf node_modules/esbuild +npm install esbuild@0.14.49 --no-save +``` + +(Use the version that matches `package-lock.json`.) + +### Build the web UI + Python sdist + +```bash +# Build the Svelte components +(cd src/svelte-components && npm run build) + +# Render pug templates and copy assets into build/http +make all # AVR step will fail without avr-gcc; safe to ignore + # if you didn't change anything under src/avr or src/boot + +# Package +./setup.py sdist +ls dist/bbctrl-*.tar.bz2 +``` + +`make pkg` is the canonical target but it tries to build AVR first. On +hosts without avr-gcc, run the steps above directly. + +If `bbctrl-*.tar.bz2` is missing `src/bbserial/bbserial.ko`, copy the +prebuilt `.ko` from a previous official release into `src/bbserial/` +before running `setup.py sdist` (the install script on the controller +just installs the existing module if a newer one isn't shipped). + +### Flash to a controller + +```bash +curl -X PUT -H "Content-Type: multipart/form-data" \ + -F "firmware=@dist/bbctrl-1.6.7.tar.bz2" \ + -F "password=onefinity" \ + http://onefinity.local/api/firmware/update +``` + +…or use the Make target: + +```bash +make update HOST=onefinity.local PASSWORD=onefinity +``` + +The controller stops bbctrl, untars the package, runs +`scripts/install.sh`, and brings the service back up. Total downtime +is ~30-45s. Watch progress at `http:///` (you'll get 404s while +bbctrl restarts, then the new UI). + +### Verify the flash + +```bash +curl -s http://onefinity.local/ | grep -c "OneFinity" +curl -s http://onefinity.local/api/aux/status # if W axis is enabled +``` + +## Build & flash (full path, Debian/Linux) + +For AVR + GPlan rebuilds, see [docs/development.md](docs/development.md). +That path uses qemu + chroot to cross-compile gplan for ARM and needs +the `gcc-avr` / `avr-libc` toolchain. + +## W axis (auxcnc) + +This fork adds a virtual W axis. See +[docs/AUX_W_AXIS.md](docs/AUX_W_AXIS.md) for: + +- G-code surface (`G28 W0`, `G1 W25`, etc.) +- The G-code preprocessor and hook architecture +- aux.json keys +- REST API (`/api/aux/*`) +- UI surface (jog row in Control, settings panel in Settings) +- Edge cases (ESP reboot mid-job, limit closed at home start, …) diff --git a/docs/AUX_W_AXIS.md b/docs/AUX_W_AXIS.md index 5ccd9a0..2948cf2 100644 --- a/docs/AUX_W_AXIS.md +++ b/docs/AUX_W_AXIS.md @@ -100,7 +100,30 @@ persisted there in NVS. Steps-mode jog ignores soft limits (use it to inch the axis to the limit switch when the axis isn't homed yet). -## State surface (UI) +## 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 ` mm`. + +## State surface These are pushed via `state.set` and visible in the websocket stream: @@ -139,6 +162,11 @@ These are pushed via `state.set` and visible in the websocket stream: - `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