Developers¶

This section tells you how to build, test, release, and change ForgeFIRM. If you only want to operate the machine, read the Installation and Usage sections instead.

The repositories¶

ForgeFIRM is a set of repositories under the OpenGlow organization on GitHub. Each component has its own repository. The forgefirm repository is the base of the build. Each recipe gets its component from GitHub at a pinned revision. Thus a build needs only two checkouts. For development, every repository is checked out into one base working directory, openglow-forgefirm, as siblings (Build).

How the components connect¶

graph TD
    senders["Grbl senders<br>LightBurn, UGS, cncjs<br>TCP port 23"]
    service["Glowforge web service<br>(optional)"]
    subgraph controllers["Controllers (one at a time)"]
        grbl["grblHAL-glowforge<br>grblHAL core + the ForgeFIRM driver"]
        gfcloud["python3-gfhardware<br>gfcloud, on Glowforge-Utilities"]
    end
    forgectrl["forgectrl<br>machine services, HTTPS 443, HTTP 80"]
    subgraph image["The image (Yocto)"]
        ko["kernel-module-glowforge<br>glowforge.ko: SDMA + EPIT, laser latch, readbacks"]
        cams["Cameras<br>ov5648, video-mux, imx6-mipi-csi2, imx-media, VPU"]
    end
    senders --> grbl
    service --> gfcloud
    grbl --> forgectrl
    gfcloud --> forgectrl
    forgectrl --> ko
    forgectrl --> cams

The controller parses G-code or dispatches the factory actions, turns motion into pulse bytes, and feeds the kernel ring through forgectrl's broker. forgectrl supervises the selected controller, holds the pulse device, runs the cooling engine, the cameras, telemetry, settings, diagnostics, the web control panel, and the A/B updates. The kernel module plays the pulse stream into the stepper drivers and owns the laser latch and the safety readbacks. The full description is under Technical.

At build time, kas assembles the upstream layers (poky, meta-openembedded, meta-freescale, meta-freescale-distro), the BSP layers from meta-openglow, and meta-forgefirm. The component recipes get the source repositories at their pinned revisions (Release flow). One bitbake run makes both images: forgefirm-image, the release image, and forgefirm-image-dev, the bench image.

Licenses¶

The code is free software under MIT and GPL licenses. The text of this site is CC BY-SA 4.0.

Every image carries its own license accounting: the build writes the image's license manifest (every installed package with its license) and copies each package's license texts onto the rootfs, then packs both into /usr/share/forgefirm/licenses.tar.gz and removes the loose tree, so the texts the licenses ask to travel with the software travel with it at the cost of one compressed file. The control panel shows the manifest at GET /licenses, the "Licenses" link at the foot of every panel page, serves the bundle at GET /system/licenses, and the manifest alone at GET /system/licenses/manifest. Keep that step in every image you redistribute.

Every release publishes its source too. The release build writes the source of each recipe of the image, and the pipeline packs it into the release asset forgefirm-source-v<version>.tar.gz: the upstream source, the patches that the recipes apply, the recipes, the ForgeFIRM layers and the kas configuration, with both license manifests and the license texts. The release stops when a recipe that needs source has none (Release flow, "The source bundle").

These are the details that go past a one-word license:

• grblHAL-glowforge is GPL-3.0-or-later. It is derived from the grblHAL Simulator: the platform layer, and the shape of the stream and NVS code. The grblHAL core is copyright Terje Io and contributors. The Simulator platform code is copyright Jens Geisler and Adam Shelly. The Glowforge driver is copyright 514 LLC d/b/a OpenGlow.
• kernel-module-glowforge is GPL-2.0-or-later, copyright 2020-2026 514 LLC d/b/a OpenGlow and copyright 2015-2021 Glowforge, Inc. The SDMA script assembler (tools/sdma_asm.pl and tools/mx51_sdma_set.pm) makes src/sdma.asm.h from asm/sdma.asm at build time. It is by Eli Billauer, copyright 2011, GPL-2.0-or-later, and its headers stay unchanged. Each file under src/ has an SPDX-License-Identifier line.
• python3-gfhardware is MIT, with one component under a different license. gfhardware/src/bayer.c and bayer.h are the Bayer demosaic routines from libdc1394 (Damien Douxchamps, Frederic Devernay; VNG and AHD from the DCRAW of Dave Coffin). They are LGPL-2.1-or-later (LICENSE.LGPL-2.1). The build compiles them into the gfhardware._cam extension module together with the MIT sources. The repository has the full source of both parts and the standard build (setup.py). Thus anyone can change the LGPL component and build or link _cam again. This satisfies the relink condition of the LGPL. Binary packages from this repository, the ForgeFIRM image recipes included, declare MIT & LGPL-2.1-or-later.
• The image installs NXP firmware blobs (VPU, EPDC) from the i.MX6 BSP. NXP distributes them under its firmware EULA. The build configuration accepts it (ACCEPT_FSL_EULA = "1"). The image ships the license text next to the blobs, at /usr/share/licenses/firmware-imx/EULA. Keep it there in each image that you redistribute. The SDMA firmware comes from linux-firmware, which has its own license package.