# 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, …)