78 lines
2.9 KiB
Markdown
78 lines
2.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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.
|