onefinity-firmware/AGENTS.md

Onefinity firmware — agent guidelines

Branch model

This fork lives on two long-lived branches:

• master — public-facing fork. General-use upgrades on top of upstream OneFinity firmware: V09 UX redesign, Font Awesome 6, faster cold boot, macOS dev/deploy tooling, build & flash docs, SD-card backup, /api/diag/timing, kiosk/tablet polish, and assorted bug-fixes. No A-axis, ATC, hooks, or auxcnc/ESP content. Aim for changes that benefit any Onefinity owner.

• esp-a-axis — bespoke shop branch. Stacks on top of master and adds everything specific to the auxcnc-ESP-driven A axis and the ATC: Hooks (ATC IPC), AuxAxis (ESP serial driver), ExternalAxis (virtual A through gplan), AuxPreprocessor (M100-M103), Z-A coupling interlock, the A-axis UI surface, and the /api/aux/* endpoints.

Upstream:

• upstream → https://github.com/OneFinityCNC/onefinity-firmware.git
• origin → Gitea (https://gitea.home.muehe.org/muehe/onefinity-firmware.git)

origin/pre-split-backup is a tag preserving the pre-split master tip. Keep it indefinitely until further notice.

Where does a change go?

Change	Branch
UI polish, theme, layout that any user benefits from	master
Build / install / boot performance	master
Diagnostics, logging, generic Python / Tornado fixes	master
Anything that touches AuxAxis, ExternalAxis, Hooks, AuxPreprocessor	esp-a-axis
Anything mentioning the auxcnc ESP, /dev/ttyUSB0, the M100-M103 ATC pneumatics, or motor index 4	esp-a-axis
Z-A coupling interlock, ATC tool change sequencing	esp-a-axis
A-axis UI (DRO row, jog tile, settings page, A-axis routes)	esp-a-axis
W → A renames or aux.json migrations	esp-a-axis

When in doubt: ask "would this be useful on a stock Onefinity with no ESP attached?" If yes → master. If no → esp-a-axis.

Workflow

# Day-to-day shop / hardware work (default)
git checkout esp-a-axis
# … do work, commit …
git push origin esp-a-axis

# Generic improvement to master
git checkout master
# … do work, commit …
git push origin master

# After landing on master, replay esp-a-axis on top
git checkout esp-a-axis
git rebase master
git push --force-with-lease origin esp-a-axis

If a change accidentally lands on master but is bespoke (touches the file table above), move it: git reset --hard <prev> on master, cherry-pick onto esp-a-axis, force-push master.

Deploy

• ./deploy.sh local — UI bundle on localhost:8770 (tmux session onefin-local). No controller backend; A-axis row stays hidden.
• ./deploy.sh hardware — rsync to the Pi over SSH, restart bbctrl.service. Use the esp-a-axis branch on the shop Pi.
• ./deploy.sh prod — bundle a release tarball.

See .pi/BUILD.md for the full build / flash / cross-compile flow.

Commit before ending a turn; push after significant changes.