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.
This commit is contained in:
123
README.md
123
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://<host>/` (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, …)
|
||||
|
||||
@@ -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 `<pos> 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
|
||||
|
||||
Reference in New Issue
Block a user