vh/forgefirm
1
0
Fork 0
mirror of https://github.com/openglow-org/forgefirm.git synced 2026-09-27 16:51:12 -07:00
Code Issues Packages Projects Releases Wiki Activity

Retire BRINGUP.md and CAMPAIGN-LOG.md

Browse Source 
Every fact in the two documents is now on the documentation site, which
is the single source of truth. This repository carries no project
documentation any more: it is the build and release base plus the
acceptance tool, the bench tools and the fixture firmware.

BRINGUP.md was the runbook, the hardware facts bank and the open-work
list. CAMPAIGN-LOG.md was the dated record of how each result was
obtained. What replaces them: the site for present state, and the
commit message for the record of what a change did and how it was
proven, so the change and its record stay together. Local open work is
the developer's own file at the tree root and is not tracked here.

README.md becomes an index card: what this is, build, test, and where
the documentation is.

The release pipeline tags the documentation. Firmware on a machine
needs the documentation that agrees with it, so release.sh now tags the
forgefirm-docs checkout with the same v<version> as the release, and
prints the command that pushes the tag with the release. The checkout
must exist and be clean, which is a new gate before the signature.
FORGEFIRM_DOCS_DIR names the checkout (default: the sibling one) and
FORGEFIRM_DOCS_SKIP releases without a tag, loudly, and is never the
default. The tag is made at staging and pushed with the release, never
before: a documentation tag for a release that never shipped is worse
than no tag.

No catalog consequence. release.sh is host-side and is in no image.
The commission.py change is one sentence of a test description, not
behavior. accel_crash_probe.py and the kas header lose pointers to the
retired files.

Checks: bash -n and sh -n on release.sh, and the tracked trees carry no
reference to either retired file.
This commit is contained in:
ScottW514
2026-09-08 13:29:43 -04:00
parent 81df43e7a4
commit e36a322ec5
8 changed files with 512 additions and 11250 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+80 -64
View File
@@ -1,87 +1,103 @@
# OpenGlow/ForgeFIRM Firmware for Glowforge
# OpenGlow / ForgeFIRM firmware for Glowforge
> # ⚠️ BETA
> ### BETA
>
> **ForgeFIRM is in beta.** Every release below 0.1.0 is a beta release.
> Expect problems, and expect frequent updates. Upgrade whenever a newer
> release is available, and report what you find on the
> [community forum](https://community.openglow.org).
Open-source firmware for Glowforge brand CNC lasers. ForgeFIRM replaces the
cloud-dependent factory software on the **stock control board** - no hardware
modification - and gives the machine a local controller, a local web control
panel, and a standard Grbl interface.
Open firmware for Glowforge brand CNC lasers. ForgeFIRM replaces the
cloud-dependent factory software on the **stock control board**, with no
hardware modification, and gives the machine a local controller, a local web
control panel, and a standard Grbl interface. The factory cloud experience
stays available as an option.
* [Latest Release](https://github.com/openglow-org/forgefirm/releases)
* [Installation Instructions](https://docs.forgefirm.org/install/)
* [Build Instructions](https://docs.forgefirm.org/developers/building/)
* [Connecting LightBurn](https://docs.forgefirm.org/usage/lightburn/)
* [How motion and the laser are driven](https://docs.forgefirm.org/technical/forgefirm/)
* [How cooling and airflow work](https://docs.forgefirm.org/technical/forgefirm/cooling-engine/)
* [The cameras and the video stream](https://docs.forgefirm.org/usage/cameras/)
* [How the laser safing works](https://docs.forgefirm.org/safety/)
* [How a release is tested before being accepted](https://docs.forgefirm.org/developers/acceptance/)
* [Community Support](https://community.openglow.org)
This repository is the **base of the build and of the release**: the
`meta-forgefirm` Yocto layer, the kas configuration, the image recipes, the
install and release scripts, the acceptance tool (`forgetest/`), the bench
tools (`scripts/bench/`), the bench actuator firmware (`fixture/`), and the
release artifacts (`releases/`).
## Start here
**<https://docs.forgefirm.org/>** is the documentation, and the source of
truth for every fact about the machine and the firmware.
| | |
|---|---|
| Read this first | [Safety](https://docs.forgefirm.org/safety/) |
| Put it on a machine | [Installation](https://docs.forgefirm.org/install/) |
| Use it | [Usage](https://docs.forgefirm.org/usage/), [LightBurn](https://docs.forgefirm.org/usage/lightburn/) |
| How the machine works | [Technical](https://docs.forgefirm.org/technical/machine/) |
| How ForgeFIRM works with it | [ForgeFIRM internals](https://docs.forgefirm.org/technical/forgefirm/) |
| Build, test, release | [Developers](https://docs.forgefirm.org/developers/) |
| Downloads | [Releases](https://github.com/openglow-org/forgefirm/releases) |
| Questions | [Community forum](https://community.openglow.org) |
## What it does
**Two controller modes, selected in the web panel and switchable while the
machine is idle:**
Two controller modes, selected in the web panel and switchable while the
machine is idle. **GRBL mode** runs grblHAL on the machine, speaking Grbl 1.1
over TCP port 23, so LightBurn, UGS and cncjs drive the laser directly; motion
runs on the board's own hardware step engine, fed live by a local planner.
**Cloud mode** signs in to the Glowforge web service as itself, so the phone
and web apps work as they always did; it is optional and off by default.
Around both sits a local web control panel: status and position, coolant and
fan telemetry, safety-switch states, a live camera stream, settings, hardware
diagnostics, firmware updates and boot-slot management.
* **GRBL mode**: [grblHAL](https://github.com/grblHAL) runs on the machine and
speaks Grbl 1.1 over TCP port 23, so LightBurn, UGS, cncjs, etc... drive the
laser directly. Motion runs on the board's own hardware step engine (SDMA +
EPIT), fed live by a local planner. M3/M4 dynamic laser power, coolant-flow
verification, over-temp holds, and an operator button press to arm the laser
for each job.
* **Cloud mode**: The machine signs in to the Glowforge web service with its
own identity, names its software as ForgeFIRM, and uses the service the way
a stock machine does, so the phone and web apps work as they always did.
Optional, and off by default. GRBL mode jogs and cuts without it; the one
GRBL-mode function that still reaches the Glowforge service is
camera-referenced homing (below), until limit-switch homing lands.
* A **web control panel**: Machine status and position, coolant
and fan telemetry, safety-switch states, live camera stream, machine settings, hardware diagnostics, firmware updates, and boot-slot management.
* **Camera-referenced homing**: `$H` from any sender runs the factory-style
camera homing cycle through the Glowforge service (a Glowforge account and a
live service session are required for `$H`; everything else in GRBL mode
runs without them).
The control board is common to the Basic, the Plus and the Pro, and one image
covers every model. The 5 MP camera is hardware validated; the 8 MP camera of
an "HD" machine has a complete path that has never run on one
([Cameras](https://docs.forgefirm.org/technical/machine/cameras/)).
## Hardware
## Build
The control board is common to Glowforge Basic, Plus, and Pro. The 5 MP
(OV5648) camera modules are fully supported and hardware-validated. The 8 MP
(OV8856) modules found in "HD" units have a complete capture path - the kernel
patches, device tree and sensor-aware capture profile they need are all in the
build, but it has never run on an 8 MP machine, so treat it as untested.
```sh
kas build kas/forgefirm-glowforge.yml
```
[Build](https://docs.forgefirm.org/developers/building/) covers the host
setup, the two images, the source variant and the debug kernel.
[Release flow](https://docs.forgefirm.org/developers/release-flow/) covers the
pins, the push order and the signing pipeline.
## Test
```sh
cd forgetest && python3 -m unittest discover -s tests -v
```
The acceptance catalog that gates a release, and the bench tools, are on
[Acceptance](https://docs.forgefirm.org/developers/acceptance/) and
[The bench](https://docs.forgefirm.org/developers/bench/).
## Contributing
[AGENTS.md](AGENTS.md) carries the rules for this repository and for the
project: safety ordering, proof before done, the push order, and the writing
rules. They apply to human contributors too, and
[Contribute](https://docs.forgefirm.org/developers/contributing/) is the same
set on the site.
## What this costs
ForgeFIRM is free in both senses: free as in beer, free as in speech. All of
it is public and released under MIT and GPL licenses. Read it, build it,
change it, use it, pass it on.
The work happens in public, including the parts that don't work yet, which
are written up with more candor than flatters anyone.
No paid tier. No license key, no subscription, no activation, no Pro edition,
no feature parked behind a paywall. Nothing is held back for a rainy day,
mostly because there's no plan for a rainy day.
If someone offers to sell you this firmware, the licenses allow it and
nobody's calling it theft. Just note that you'd be paying for something
that's given away. Get it from the source. Same price everywhere, and here
you get to read what you're running.
Nothing. ForgeFIRM is free in both senses, under MIT and GPL licenses. There
is no paid tier, no license key, no subscription and no Pro edition. If
someone offers to sell it to you, the licenses allow it, but what you take
home is their build rather than this one: get it from the source.
## Safety
**These machines contain a CO₂ laser: it burns, blinds, and starts
fires.** Never defeat the lid switches or interlock. Never leave a
running job unattended. Keep a fire extinguisher within reach. Read [this](https://docs.forgefirm.org/safety/) before you cut
your first job, and read this [regulatory and legal](https://docs.forgefirm.org/install/#regulatory-and-legal) section before installing. [This](https://docs.forgefirm.org/technical/machine/safing-chain/) page describes the hardware safety chain and the software gates ForgeFIRM stacks on it.
**These machines contain a CO2 laser: it burns, blinds, and starts fires.**
Never defeat the lid switches or the interlock. Never leave a running job
unattended. Keep a fire extinguisher within reach. Read
[Safety](https://docs.forgefirm.org/safety/) before you cut your first job,
and [Regulatory and legal](https://docs.forgefirm.org/install/#regulatory-and-legal)
before you install.
**THIS IS EXPERIMENTAL SOFTWARE
Use of this software
could seriously maim or kill you or others, and could void your warranty.
Use it at your own risk.**
**This is experimental software. Use of it could seriously maim or kill you or
others, and it may void your warranty. Use it at your own risk.**
This project is not affiliated with or endorsed by Glowforge.