LinuxCNC Machine Retrofit

This lab guides students through the deployment and configuration of an open-source computer numerical control (CNC) controller using LinuxCNC to retrofit automated machine tools. Students configure real-time Linux operating system environments utilizing Preempt-RT or RTAI kernels on x86-64 desktop platforms or ARM single-board computers, measure and evaluate system latency and timing jitter, and interface the host controller with physical machine hardware through Ethernet FPGA motion control boards or general-purpose input/output pins. Working within LinuxCNC's Hardware Abstraction Layer (HAL), students map motor drive step generation, configure spindle controls and industrial field I/O signals, and verify graphical operator interfaces. Through this process, students develop practical competencies in real-time operating systems, industrial motion control architectures, hardware-in-the-loop signal interfacing, and the complete electronic retrofit of legacy machine tools.

LinuxCNC CNC retrofit computer numerical control real-time operating system RTOS Preempt-RT RTAI motion control hardware abstraction layer HAL latency testing jitter measurement Mesa FPGA industrial automation Raspberry Pi machine tool GPIO interfacing pulse generation

Uploaded by demo on 2026-09-03 · ready · Electronics · Original source ↗

Files: README.md · getting-linuxcnc.adoc · system-requirements.adoc · updating-linuxcnc.adoc

Readiness checks

  • complete 2026-09-04 00:07 🛡 Cybersecurity: Review before networking · 5 findings 17 searches · 18 pages
    view · PDF

Latest report — 2026-09-04 00:07

Readiness: LinuxCNC Machine Retrofit

Verdict: Ready with caveats · 2026-09-03 · est. parts cost $260–$460 (Raspberry Pi host plus one Mesa Ethernet card; the x86 desktop host path was not priced) Cybersecurity — software & network: Review before networking

This is the cold check for this lab — it establishes the baseline, so every line below carries its current price and availability for the next comparison. The lab is sourceable today: seven of its eight bill-of-materials lines are commodity computer hardware available cheaply from many sellers, and the Raspberry Pi 4 Model B carries a manufacturer commitment to stay in production until at least January 2034. The caveats are in the specialty item and in the paperwork. Mesa Electronics still sells Ethernet motion-control cards across the range the lab names, but the 7I92 / 7I92H / 7I92M the handout gives as an example now list at US$0.00 — no orderable price — with the 7I92T series at US$109.00 as the evident replacement, and Mesa publishes no stock figures at all, so lead time is unverified. Separately, the Raspberry Pi image checksum recorded in the lab materials no longer matches the checksum the project currently publishes, which will make a careful instructor think their download is corrupt.

Action required

Part Problem Recommended action
Mesa 7I92 / 7I92H / 7I92M Listed at US$0.00 on Mesa's store — no orderable price shown, while the newer 7I92T series is priced normally Order the 7I92TF / 7I92TH / 7I92TM at US$109.00 instead, matching the trailing connector letter to the existing wiring, and update the handout's example part numbers. Confirm stock and lead time with Mesa directly before a class order.

Cybersecurity — software & network

Review before networking — A high-severity privilege-escalation flaw affects the exact LinuxCNC version the lab pins and a fixed release is already published, and two documented host operating systems plus the RTAI kernel line are past end of life.

Component Version How known Support status
LinuxCNC (linuxcnc-uspace) 2.9.8 inferred (Stated in the lab documentation (getting-linuxcnc.adoc / updating-linuxcnc.adoc) and matched by the published image linuxcnc_2.9.8-amd64.hybrid.iso; no project manifest fetched this run pins it.) —
LinuxCNC APT install path (apt-get install linuxcnc-uspace) not determined unpinned (The fetched install script (fetched/01-linuxcnc-install.sh) runs 'apt-get install linuxcnc-uspace' with no version constraint; extraction this run returned linuxcnc-uspace, linuxcnc-doc-[lang] and linuxcnc-dev, none pinned.) —
LinuxCNC repository setup script (linuxcnc-install.sh) not determined unpinned (Unversioned; fetched fresh from https://www.linuxcnc.org/linuxcnc-install.sh (2001 bytes this run). It installs archive signing keys from hkp://keyserver.ubuntu.com and writes HTTPS deb/deb-src lines with signed-by keyrings.) —
Debian GNU/Linux 13 (Trixie) 13 inferred (Listed as a supported host variant in the lab documentation (system-requirements.adoc) and the target of the current LinuxCNC ISO.) supported until 2028-08-09
Debian GNU/Linux 12 (Bookworm) 12 inferred (Listed as a supported host variant in the lab documentation and carried as an APT suite in the recorded sources.list lines.) extended/LTS support only until 2028-06-30
Debian GNU/Linux 11 (Bullseye) 11 inferred (Listed as a supported host variant in the lab documentation and carried as an APT suite in the recorded sources.list lines.) unsupported since 2024-08-14
Debian GNU/Linux 10 (Buster) 10 inferred (Named in the recorded APT sources.list line 'deb http://linuxcnc.org buster base'; the LinuxCNC repository still carries a buster suite.) unsupported since 2022-09-10
Ubuntu 20.04 LTS (Focal Fossa) 20.04 inferred (Documentation names 'Ubuntu 20.04 (Focal Fossa) or newer' as a supported host.) extended/LTS support only until 2030-04-23
Preempt-RT real-time kernel (linux-image-rt-amd64) 6.1 inferred (The APT meta-package is unpinned; 6.1.0-10-rt-amd64 is the example kernel version stated in the documentation, so the 6.1 line was checked.) supported until 2027-12-31
RTAI real-time kernel (5.4.258-rtai) 5.4.258-rtai inferred (Release named in the documentation and supplied by the LinuxCNC 2.9-rt repositories; the upstream 5.4 kernel line it is built on was checked.) unsupported since 2025-12-03
Media flashing and download utilities (balenaEtcher, Rufus, Raspberry Pi Imager, Infra Recorder, zsync) not determined not determined (The lab materials name these tools and their download pages but state no version for any of them; zsync is installed unpinned via apt.) —
Renderer and graphics runtime (OpenGL 3.3 core profile, Mesa llvmpipe, libgpiod) not determined not determined (System runtime libraries supplied by the host distribution; the documentation states a required OpenGL feature level but no library versions.) —
Component Finding Severity Fix available?
LinuxCNC (linuxcnc-uspace) The exact version this lab documents, 2.9.8, is affected: the rtapi_app helper in linuxcnc-uspace is installed with root privileges and loads a code module whose name the user supplies, and it does not check that name properly, so anyone who can log in at the controller can take over the machine as root. — DEBIAN-CVE-2026-58302 high Yes — update to 2.9.10, the release linuxcnc.org currently publishes; the advisory affects LinuxCNC before 2.9.9, and the fixed Debian package is 1:2.9.4-2+deb13u1.
Debian GNU/Linux 11 (Bullseye) and 10 (Buster) Two of the host systems the lab still offers as install targets are past end of life — Debian 11 Bullseye's extended support ran out on 2026-08-31 and Debian 10 Buster's on 2024-06-30 — so a machine built on either stops receiving security fixes, and the LinuxCNC repository still serves both suites, so nothing stops an instructor from doing it. posture No — requires platform migration: build on Debian 13 Trixie, which is supported to 2028-08-09 and is what the project's current ISO installs. See https://endoflife.date/debian
LinuxCNC APT install path (apt-get install linuxcnc-uspace) The documented install script pins no version — it runs 'apt-get install linuxcnc-uspace' — so the version each student machine ends up running is whatever the repository serves that day and cannot be known in advance, while the offline path documented alongside it pins 2.9.8, the last release the advisory above affects. posture Mitigation only — record the installed version at setup ('apt list --installed linuxcnc-uspace') and require 2.9.9 or newer before the machine is used; prefer the apt path over the pinned 2.9.8 offline .deb and ISO.
mqtt-publisher HAL component LinuxCNC ships an mqtt-publisher component that sends the machine's internal state to an external message broker on the standard MQTT ports 1883 or 8883, and the lab materials record no authentication, encryption or broker hardening for it — port 1883 carries traffic in the clear. posture Mitigation only — leave mqtt-publisher out of the HAL configuration unless it is needed; if it is used, keep the controller and broker on an isolated network segment and require broker authentication and TLS on 8883 rather than plain 1883.
RTAI real-time kernel (5.4.258-rtai) The RTAI path pins a kernel built on the Linux 5.4 line, which reached end of life on 2025-12-03, so that kernel no longer receives upstream security fixes; the documentation also notes RTAI cannot be used with Mesa Ethernet cards at all. posture No — requires platform migration: use the Preempt-RT path (the 6.1 line, supported to 2027-12-31), which is also the only option for the Mesa Ethernet card this lab specifies. See https://endoflife.date/linux

What this means for your lab

The most concrete problem is on the controller itself rather than on the network: the LinuxCNC version this lab documents, 2.9.8, contains a flaw that lets anyone who can log in at that machine gain full administrator control of it. Updating to 2.9.10 fixes that, and it is a straightforward apt update. Beyond that, treat a retrofitted CNC controller as an appliance, not a classroom PC. Two of the operating systems the handout still lists as options, Debian 11 and Debian 10, no longer get security fixes, so build on Debian 13 instead. LinuxCNC can optionally publish live machine state to a message broker over the network, and nothing in the lab materials sets up a password or encryption for that, so anyone on the same network could read what the machine is doing if that feature is switched on — leave it off unless you need it. Nothing checked this run showed a remote login service, a web interface or a default password on the controller, and the documentation deliberately steers installers away from setting a root password. Put the controller and its Mesa card on their own isolated network segment, keep it off the campus network unless your IT group has agreed to it, and confirm the LinuxCNC version on each machine before students use it.

Not checked

  • LinuxCNC 2.9.10 (confirmation that the fix is present): A lookup of 2.9.10 this run still matched the same advisory, because the Debian advisory's fixed version carries an epoch (1:2.9.4-2+deb13u1) that a bare upstream version string does not compare against cleanly. The advisory text itself states the flaw affects releases before 2.9.9, so 2.9.10 should carry the fix — but that was not independently confirmed this run.
  • balenaEtcher, Rufus, Raspberry Pi Imager, Infra Recorder: no version is stated anywhere in the lab materials, so there is no exact version to check against an advisory database
  • zsync: installed unpinned via apt; no exact version to check
  • OpenGL 3.3 core profile, Mesa llvmpipe, libgpiod: system runtime libraries supplied by the host distribution and left unversioned in the documentation
  • Raspberry Pi custom image builder (rpi-img-builder-lcnc): the repository is live but the images it builds are assembled at build time from whatever the chosen distribution serves; no manifest pins a version to check

Parts

Part Spec/Package Status Stock Price Source
Host Compute Platform (Raspberry Pi 4 Model B, 4 GB) Raspberry Pi form factor, 85.00 mm x 56.00 mm, 0 °C ~ 50 °C, 5 V DC via USB-C ≥ 3 A readily available — Active; 4 GB variant not pinned by the evidence (see note) 983 $55.00 DigiKey, SC0193(13) "RASPBERRY PI 4 DUAL RAM VARIANT"
Host Compute Platform — retail alternative 4 GB starter kit readily available — $61.05 Vilros, "Raspberry Pi 4 Model B Vilros Basic Starter Kit / 4GB"
Host Compute Platform — x86-64 desktop / industrial PC path Any 64-bit PC ≥ 1.2 GHz passing the LinuxCNC latency test; laptops excluded not checked — — not priced — commodity COTS, no comparable single product to price
System Random-Access Memory (RAM) 4 GB DDR4-2133 unbuffered DIMM (x86 host path only; on-SoC on the Pi) readily available — $14.00 Memory.NET, Crucial CT4G4DFS8213
Mass Storage Medium (internal SSD/HDD ≥ 8 GB) 120 GB 2.5" SATA SSD readily available — $13.99 – $59.99 eBay (Kingston SSDNow V300) to Newegg (Gigastone, new retail)
Boot / Installation Medium (USB flash drive) 16 GB, USB 2.0/3.0, Type-A readily available — $10.99 Walmart, 16 GB 2-pack (SanDisk singles from $7.85)
Boot / Installation Medium (MicroSD card) 32 GB UHS-I / Class 10, 11 mm x 15 mm readily available — $14.95 Adorama, SanDisk Extreme SDSQXVF-032G-GN6MA
Boot / Installation Medium (blank DVD-R, optional) DVD-R / DVD+R, 4.7 GB, 120 mm readily available — shrinking category — $7.20 Walmart, Maxell 4.7 GB 16X
Visual Display & Graphics Adapter Monitor ≥ 1024 x 768 with HDMI; GPU must do OpenGL 3.3 core or fall back to llvmpipe readily available — $59.99 Best Buy, AOC 22" 22b30hm2 FHD
Machine Interface Hardware — Mesa 7I76E Industrial PCB, screw terminals, RJ45; 5 V DC logic, 24 V DC field I/O readily available — current not published US$219.00 Mesa Electronics store
Machine Interface Hardware — Mesa 7I96 / 7I96S as above readily available — 7I96 reachable only via store search, not the category listing not published US$119.00 / US$149.00 Mesa Electronics store
Machine Interface Hardware — Mesa 7I92 / 7I92H / 7I92M as above no orderable price — all three list at US$0.00 not published US$0.00 Mesa Electronics store — see Substitutes

Note on the Raspberry Pi: DigiKey stocks the board under packaging variants of the base part number SC0193 — SC0193(13) is described only as "RASPBERRY PI 4 DUAL RAM VARIANT" with no capacity stated, while SC0193(11) at the same $55.00 is described as the 2 GB board. PiShop's product page for the 4 GB board also cites SC0193 and specifies 4 GB LPDDR4-3200. The evidence therefore does not establish which orderable variant carries 4 GB — confirm "4GB" on the order line. The snapshot's floor is 512 MB with 4 GB recommended, so a 2 GB board would still run, just below the recommendation. Mesa cards are single-source and Mesa's storefront publishes no stock quantities on any page fetched for this report, so every Mesa row above is priced but not stock-verified.

Substitutes

For part Substitute Differences Verified Judgment
Mesa 7I92 / 7I92H / 7I92M Mesa 7I92TF / 7I92TH / 7I92TM — US$109.00 Same vendor, same product family, and the same store description ("a low cost, general purpose, FPGA based programmable..."), differing only in the trailing connector-code letter F/H/M — exactly as the superseded 7I92/H/M did. Price US$109.00 against no listed price for the original. verified: vendor, product family and current catalog price (Mesa store search page fetched this run). not verified: connector type, pinout, I/O count, field-I/O voltage rating, physical footprint and FPGA bitfile compatibility — Mesa's listing carries no parametrics and no datasheet was fetched. What the F/H/M letters encode is assumed, not evidenced. Acceptable as the like-for-like replacement — match the connector letter to the existing wiring before ordering.
Mesa 7I92 / 7I92H / 7I92M Mesa 7I96 — US$119.00 or 7I96S — US$149.00 A different card, described by Mesa as an Ethernet-connected motion-control card rather than a general-purpose FPGA card. Not a footprint hard stop, because the snapshot's own substitution latitude reads "Mesa 7i76E, 7i92, 7i96, or equivalent Ethernet-connected driver card" — the lab explicitly permits changing card within Mesa's Ethernet range. verified: that the snapshot permits substitution across Mesa's Ethernet range (snapshot, "Substitution latitude"); current catalog prices (Mesa store search page fetched this run). not verified: I/O count, terminal layout, step/dir channel count, field-voltage rating, enclosure fit and HAL driver/bitfile compatibility — none appear in the evidence. Acceptable per the lab's stated latitude, but treat it as a rewiring job, not a swap.

Verify any substitute against its datasheet — and, for the Mesa cards, against your machine's existing I/O wiring — before ordering.

Other dependencies

  • Live hybrid ISO linuxcnc_2.9.8-amd64.hybrid.iso — still published. The project's ISO directory lists it at 4.0G, dated 2026-01-04, so the URL in the handout still resolves.
  • A newer release is out. The same index lists linuxcnc_2.9.10-amd64.hybrid.iso (3.9G, 2026-07-13), and the downloads page now leads with "LinuxCNC 2.9.10 Debian 13 Trixie PREEMPT-RT ISO (Download this then update to 2.9.10 with Synaptic or apt. 2.9.10 .iso image is WIP)". A pre-release linuxcnc_2.10.pre1-amd64.hybrid.iso (3.1G, 2026-01-11) is also on the server, matching the handout's note about a 2.10 upgrade path.
  • Raspberry Pi image checksum no longer matches — fix the handout. The lab materials record the arm64 Pi image with MD5 4547e8a72433efb033f0a5cf166a5cd2. The downloads page currently publishes the Pi 4/5 SD card image with "MD5SUM 705b7f3c2f7b385f6cb094d05e01070e", the current file being image_2026-01-21-raspios-lcnc-2.9.8-trixie-arm64.zip (1.7G). An instructor who verifies the download against the recorded value will get a mismatch and may wrongly conclude the file is corrupt. The amd64 ISO's recorded MD5/SHA256 were not verified — that needs a 4 GB download and hash.
  • Offline Debian packages — linuxcnc-uspace_2.9.8_amd64.deb (25M, 2026-03-27) is present in the ISO directory, alongside linuxcnc-uspace_2.9.8_amd64_probe2.deb. The linuxcnc-uspace_2.9.8_arm64.deb the handout names does not appear there; treat it as not located rather than gone — it may be served from the package repository instead.
  • Package repository https://linuxcnc.org/dists/ — live, and every suite the handout's sources.list lines use is present and recently rebuilt: buster/ (2026-06-27), bullseye/ (2026-07-02), bookworm/ (2026-07-10), trixie/ (2026-07-11).
  • Installer script https://www.linuxcnc.org/linuxcnc-install.sh — live, 2001 bytes.
  • Raspberry Pi image builder https://github.com/rodw-au/rpi-img-builder-lcnc — live and maintained. Worth knowing before you try it: its README names the supported builder host systems as Debian Bookworm (testing), Ubuntu Jammy Jellyfish (recommended) and Ubuntu Noble Numbat (recommended) — so the machine you build the image on has its own requirements.
  • Mesa Modbus driver documentation — live, but the driver is on a deprecation path. The page's own opening note reads: "The Mesa Modbus framework (modcompile and mesa_modbus) is superseded by the hm2_modbus driver and mesambccc-compiled MBCCB files. It remains available throughout the 2.9 series, but new configurations are encouraged to migrate." The lab names mesa_modbus as one of the HAL interfaces its card must use, so a configuration built on it today will need rework at 2.10.
  • HAL GPIO driver documentation — live.
  • Hardware Requirements wiki page — live, but obsolete by its own admission, and it fails over HTTPS. Its first line reads: "This information was current when LinuxCNC was called EMC2 and when Ubuntu 8.04 was new. ie some time around 2008. It should be viewed as currently unreliable". Its figures ("at least 256MB of RAM", "later Pentium II or III, 400MHz or higher", "Currently an x86 PC is required") contradict the lab's own current requirements. The HTTPS form of the URL presents a certificate that could not be validated, so it is reachable only over plain HTTP. Drop this link in favour of system-requirements.adoc.
  • Windows zsync port https://www.assembla.com/spaces/zsync-windows/documents — effectively dead as a public download. The page returns only "Granting access, please wait..." — an access wall, not a document listing. Windows users following this link get nothing.
  • balenaEtcher download page — live.
  • Rufus https://rufus.ie/ — reachable, but the page is script-rendered and no readable text could be extracted, so its current download was not confirmed this run.
  • Raspberry Pi Imager https://www.raspberrypi.com/software/ — not confirmed this run; the fetch was blocked, which for this domain most likely means bot protection rather than a dead link.
  • Infra Recorder https://infrarecorder.org/ — not reachable this run, and the host was seen presenting a TLS certificate issued for a different domain, so an instructor clicking through may face a browser security warning ahead of a binary download. balenaEtcher and Rufus cover the same job.
  • Fabrication — none. The lab package contains no PCB, CAD or custom fabrication files; the build is commercial off-the-shelf hardware wired to existing machine actuators.

Watch list

  • Mesa 7I92 family — the plain 7I92/H/M already show no orderable price. Expect them to disappear from the store entirely; the handout's example part numbers should move to the 7I92T series or the 7I96S now.
  • Mesa 7I96 — still priced at US$119.00 but reachable only through store search, not the Ethernet card category listing. That is the usual shape of a part being wound down in favour of the 7I96S; check it again next cycle.
  • Mesa stock and lead time generally — a single-source vendor publishing no stock figures is the biggest sourcing unknown in this lab. Nothing in a catalog page tells you whether a card ships this week.
  • The DVD-R install path — the ISO has grown release over release (2.9.1 3.4G → 2.9.4 3.5G → 2.9.8 4.0G) and a single-layer DVD-R holds about 4.38 GiB. The current images still fit, but not for many more releases — and neither a Raspberry Pi nor most current desktops have an optical drive at all. Plan on USB.
  • Recorded checksums — they drifted once already. Any handout that pins an MD5 against a moving "latest image" link will drift again at the next image rebuild.
  • The 4 GB Raspberry Pi variant — DigiKey's variant descriptions do not state capacity consistently. If the 2 GB and 4 GB boards keep sharing a base part number, ordering the wrong one stays easy.
  • Debian 11 and 10 as documented targets — both are already past end of life and the LinuxCNC repository still serves suites for them, so the handout can still be followed onto an unsupported platform.
Snapshot What the lab depended on when it was uploaded — the baseline the readiness checks research against.

This lab documents the hardware infrastructure, real-time operating system environments, and software packages required to deploy and upgrade LinuxCNC (version 2.9.x / 2.10.x) for retrofitting computer numerical control (CNC) machinery. The system operates as a real-time host controller driving machine axes, spindles, and peripheral I/O either directly via hardware interface cards (e.g., Mesa FPGA cards or host GPIO) or through software pulse generation. The host computational hardware operates from standard AC mains (100–240 V AC, 50/60 Hz for desktop PCs) or standard low-voltage DC rails (5 V DC via USB-C for single-board computers such as the Raspberry Pi 4/5). Peripheral motion interface hardware and field I/O typically interface via Ethernet or serial buses and operate on 5 V DC logic and 24 V DC industrial control rails.

Bill of Materials

  • Host Compute Platform (Desktop / Industrial PC or SBC)

    • Identity: Generic x86-64 desktop/industrial computer or Raspberry Pi 4 / Raspberry Pi 5 single-board computer (SBC). Processor must be at least 1.2 GHz 64-bit x86 architecture or ARM Cortex-A72/A76 (Raspberry Pi 4 or better). Laptops are explicitly flagged as unsuitable for real-time software step generation due to power-management latency spikes. 32-bit x86 platforms are deprecated/unsupported.
    • Quantity: 1
    • Footprint/package: Standard desktop ATX/Micro-ATX/Mini-ITX chassis or Raspberry Pi Form Factor.
    • Electrical constraints: Standard AC mains (100–240 V AC) for PC power supply, or 5 V DC (minimum 3.0 A for RPi 4, 5.0 A for RPi 5 via USB-C).
    • Substitution latitude: Any 64-bit PC or supported ARM SBC capable of passing the LinuxCNC Latency Test (jitter low enough for the target machine's step rates).
    • Control status: Host platform; power switch operated by user.
    • Sourcing plan: retail shopping search: "x86-64 desktop PC 1.2 GHz" or retail shopping search: "Raspberry Pi 4 Model B 4GB".

  • System Random-Access Memory (RAM)

    • Identity: System RAM matching host platform (DDR3, DDR4, DDR5, or LPDDR4). Minimum capacity: 512 MB; recommended capacity: 4 GB or greater when running GUI environments (AXIS, QtVCP, QtPlasmaC, Gremlin).
    • Quantity: 1 module or integrated SoC memory bank (minimum 512 MB, recommended 4 GB).
    • Footprint/package: DIMM, SO-DIMM, or on-board BGA.
    • Electrical constraints: Supplied by motherboard memory bus (typically 1.1 V to 1.5 V DC).
    • Substitution latitude: Any compatible memory module supported by host motherboard/SoC meeting the 512 MB floor / 4 GB recommendation.
    • Control status: Set-once internal hardware.
    • Sourcing plan: retail shopping search: "4GB DDR4 desktop RAM module".

  • Mass Storage Medium (Permanent Installation)

    • Identity: Internal Solid-State Drive (SSD) or Hard Disk Drive (HDD). Minimum capacity: 8 GB. (Not required if operating exclusively via Live CD / Live USB).
    • Quantity: 1
    • Footprint/package: 2.5-inch SATA, M.2 2280 NVMe/SATA, or 3.5-inch SATA drive.
    • Electrical constraints: Host powered (+5 V / +12 V DC SATA or +3.3 V DC M.2).
    • Substitution latitude: Any internal mass storage device with ≥ 8 GB capacity compatible with the motherboard.
    • Control status: Set-once internal hardware.
    • Sourcing plan: retail shopping search: "120GB 2.5 SATA SSD".

  • Boot / Installation Medium (USB Flash Drive)

    • Identity: USB 2.0 or USB 3.0 flash drive / thumb drive for Live boot and OS/software installation.
    • Quantity: 1
    • Footprint/package: USB Type-A or Type-C thumb drive.
    • Electrical constraints: Standard 5 V DC USB bus power.
    • Substitution latitude: Must accommodate the hybrid ISO image (larger than 700 MB; typically ≥ 4 GB recommended).
    • Control status: Connected/disconnected by user during system setup.
    • Sourcing plan: retail shopping search: "16GB USB flash drive".

  • Boot / Installation Medium (MicroSD Card - Raspberry Pi Option)

    • Identity: High-speed MicroSD card (UHS-I / Class 10) for loading Raspberry Pi hybrid real-time images.
    • Quantity: 1 (required if using Raspberry Pi platform).
    • Footprint/package: MicroSD card (11 mm x 15 mm).
    • Electrical constraints: 3.3 V DC logic powered via Raspberry Pi card slot.
    • Substitution latitude: Any Class 10 or UHS-I MicroSD card ≥ 16 GB.
    • Control status: Inserted during installation.
    • Sourcing plan: retail shopping search: "32GB microSD card UHS-I Class 10".

  • Boot / Installation Medium (Blank DVD - Optical Option)

    • Identity: Recordable DVD disc (DVD-R or DVD+R, 4.7 GB). The image is explicitly noted as too large to fit on a standard CD.
    • Quantity: 1 (optional alternative to USB drive).
    • Footprint/package: 120 mm standard optical disc.
    • Electrical constraints: Passive optical media.
    • Substitution latitude: Any recordable single-layer DVD disc.
    • Control status: Handled during installation.
    • Sourcing plan: retail shopping search: "blank DVD-R disc 4.7GB".

  • Visual Display & Graphics Adapter

    • Identity: Computer display monitor and graphics adapter capable of minimum 1024 x 768 resolution. Graphics hardware must support modern OpenGL 3.3 core profile (available on Intel Sandy Bridge [2011] and newer, AMD r600 and newer, or modern onboard GPUs running open-source drivers like nouveau, Intel Mesa, AMD Mesa). Note: Proprietary NVidia and ATI fglrx drivers are explicitly unsupported due to compatibility/real-time issues. If GPU lacks OpenGL 3.3 core, system requires Mesa software rendering fallback (llvmpipe).
    • Quantity: 1
    • Footprint/package: External desktop monitor with HDMI/DisplayPort/DVI/VGA interface.
    • Electrical constraints: Powered via mains AC (100–240 V AC, 50/60 Hz).
    • Substitution latitude: Any monitor supporting ≥ 1024 x 768; GPU must support OpenGL 3.3 core or rely on software rasterization.
    • Control status: Operator visual console.
    • Sourcing plan: retail shopping search: "1080p computer monitor HDMI".

  • Machine Interface Hardware (Mesa Ethernet Motion Controller)

    • Identity: Mesa Electronics FPGA hardware motion controller / interface card (e.g., Mesa 7i76E, 7i92, 7i96, or equivalent Ethernet-connected driver card) or Mesa serial card utilizing the mesa_modbus / mesa_uart drivers.
    • Quantity: 1 (required when retrofitting machines that do not use software step generation via parallel port/GPIO).
    • Footprint/package: Industrial PCB assembly with screw terminals and RJ45 Ethernet port.
    • Electrical constraints: Logic powered by 5 V DC; field I/O typically powered by external 24 V DC industrial supply. Note: The documentation states that Preempt-RT kernel is strictly required for Mesa Ethernet cards; RTAI is unsupported for Mesa Ethernet interfaces.
    • Substitution latitude: Specific to machine retrofit design; must interface with LinuxCNC HAL via mesa_uart, mesa_modbus, or HostMot2 Ethernet drivers.
    • Control status: Machine controller interface board mounted in electrical enclosure.
    • Sourcing plan: general web research: "Mesa Electronics Ethernet FPGA motion control card".

Software and network dependencies

  • LinuxCNC Machine Control Application:

    • Name: LinuxCNC
    • Repository / Distribution Image: Official project repository at https://linuxcnc.org/dists/ and Live ISO at https://www.linuxcnc.org/iso/linuxcnc_2.9.8-amd64.hybrid.iso.
    • Packages: linuxcnc-uspace (for Preempt-RT and user-space/simulation configs) and linuxcnc (for kernel-space RTAI configs). Offline Debian packages: linuxcnc-uspace_2.9.8_amd64.deb and linuxcnc-uspace_2.9.8_arm64.deb.
    • Version: 2.9.8 (stated in documentation; documentation also notes Debian repository distributes 2.9.4, and describes upgrade path to 2.10.y).
    • Version source: stated in documentation (getting-linuxcnc.adoc and updating-linuxcnc.adoc).
    • Pinning status: Unpinned when installed via standard repository command sudo apt-get install linuxcnc or sudo apt-get install linuxcnc-uspace. Pinned to 2.9.8 when fetching the specific hybrid ISO or .deb file path.
    • Manifest location: Official APT repository sources in /etc/apt/sources.list:
      • Debian Trixie (Preempt-RT): deb https://linuxcnc.org trixie base 2.9-uspace
      • Debian Trixie (RTAI): deb https://linuxcnc.org trixie base 2.9-rt
      • Debian Bookworm (Preempt-RT): deb https://linuxcnc.org bookworm base 2.9-uspace
      • Debian Bookworm (RTAI): deb https://linuxcnc.org bookworm base 2.9-rt
      • Debian Bullseye (Preempt-RT): deb https://linuxcnc.org bullseye base 2.9-uspace
      • Debian Buster (RTAI): deb http://linuxcnc.org buster base
    • Check plan: vulnerability lookup: linuxcnc / Debian / 2.9.8

  • Host Operating System Distributions:

    • Name: Debian GNU/Linux and Ubuntu Linux.
    • Supported Variants:
      • Debian 13 ("Trixie"), 64-bit (amd64, arm64)
      • Debian 12 ("Bookworm"), 64-bit (amd64, arm64)
      • Debian 11 ("Bullseye"), 64-bit (amd64)
      • Ubuntu 20.04 ("Focal Fossa") or newer (amd64)
    • Unsupported: Debian 9 or older; Ubuntu Precise, Lucid, and Wheezy (EOL); standard stock Raspbian 12 / Raspberry Pi OS is explicitly marked unsupported due to bad latencies and failure of Debian Preempt-RT kernels to boot on Raspberry Pi hardware (custom builder required: https://github.com/rodw-au/rpi-img-builder-lcnc).
    • Version source: stated in documentation (system-requirements.adoc, getting-linuxcnc.adoc, updating-linuxcnc.adoc).
    • Check plans:
      • support-status lookup: Debian Trixie
      • support-status lookup: Debian Bookworm
      • support-status lookup: Debian Bullseye
      • support-status lookup: Ubuntu 20.04

  • Real-Time Operating System Kernels:

    • Name: Preempt-RT and RTAI (Real-Time Application Interface).
    • Packages & Versions:
      • Preempt-RT: Debian package linux-image-rt-amd64 (example kernel version stated in docs: 6.1.0-10-rt-amd64).
      • RTAI: Kernel version 5.4.258-rtai (provided via LinuxCNC Bookworm/Trixie RTAI repositories).
    • Version source: stated in documentation (getting-linuxcnc.adoc and updating-linuxcnc.adoc).
    • Pinning status: linux-image-rt-amd64 meta-package is unpinned in APT; RTAI kernel references specific release 5.4.258-rtai.
    • Check plans:
      • support-status lookup: Linux kernel 6.1-rt
      • support-status lookup: Linux kernel 5.4-rtai

  • Repository Setup Script:

    • Name: LinuxCNC installer and repository signing key script.
    • URL: https://www.linuxcnc.org/linuxcnc-install.sh
    • Version: not stated.
    • Version source: not stated.
    • Pinning status: Unpinned; fetched directly from remote web root.
    • Check plan: not checkable: version not stated

  • Media Flashing and Download Utilities:

    • zsync: Console file transfer tool used to download ISO files via HTTP. Unpinned (sudo apt-get install zsync in getting-linuxcnc.adoc).
    • balenaEtcher: USB image flashing software (https://etcher.balena.io/#download-etcher). Version not stated.
    • Rufus: USB formatting and booting tool (https://rufus.ie/). Version not stated.
    • Raspberry Pi Imager: Tool for writing arm64 images to SD card (https://www.raspberrypi.com/software/). Version not stated.
    • Infra Recorder: Windows open-source CD/DVD burner (https://infrarecorder.org/). Version not stated.
    • Check plan for all flashing utilities: not checkable: version not stated

  • Renderer and Graphics Libraries:

    • OpenGL 3.3 Core Profile: Hard requirement for preview renderers (AXIS, Gremlin GTK3, QtVCP, QtPlasmaC). AXIS utilizes vendored Togl widget (src/emc/usr_intf/axis/extensions/togl.c) with -coreprofile. Gremlin loads libGL.so dynamically via Python ctypes.
    • Mesa llvmpipe: Software fallback driver enabled via environment variable LIBGL_ALWAYS_SOFTWARE=1.
    • libgpiod: Host Linux library required for the hal_gpio HAL driver.
    • Version source: stated in documentation (updating-linuxcnc.adoc).
    • Check plan: not checkable: system runtime libraries unversioned in documentation.

  • Network Exposure and Interfaces:

    • Network Configuration: An internet connection is recommended for initial repository downloads, package updates, and community support, but offline operation is fully supported via the Live CD / USB or offline .deb bundles.
    • Network Hardware Interface: Mesa Ethernet FPGA cards communicate across a dedicated standard Ethernet link using raw Ethernet/IP packets.
    • Exposed Protocols / Ports: LinuxCNC includes an mqtt-publisher non-real-time HAL component that publishes internal machine state to an external MQTT broker (default MQTT port 1883 or 8883, broker host configured by user).
    • Default Credentials: Not stated in the sources. The documentation explicitly warns against configuring a root password during Debian installation to ensure standard sudo functionality remains active.
    • Remote Access: The documentation does not instruct users to enable SSH, open public firewall ports, or expose web interfaces.

Downloads and external URLs

  • Live Hybrid ISO (PC / amd64): https://www.linuxcnc.org/iso/linuxcnc_2.9.8-amd64.hybrid.iso
    • MD5 Checksum: cf77d61fcba9641d7205ac33751e5f38
    • SHA256 Checksum: 72eab92d7c34c238b0429054dc52d240df8dc5f083e769a39194cfac3e4984e8
  • Raspberry Pi Live Image (arm64):
    • MD5 Checksum: 4547e8a72433efb033f0a5cf166a5cd2
    • SHA256 Checksum: ff3ba9b8dfb93baf1e2232746655f8521a606bc0fab91bffc04ba74cc3be6bf0
  • Installer Shell Script: https://www.linuxcnc.org/linuxcnc-install.sh
  • Package Repository Dist Directory: https://linuxcnc.org/dists/
  • Downloads Landing Page: https://linuxcnc.org/downloads/
  • Raspberry Pi Image Builder Script: https://github.com/rodw-au/rpi-img-builder-lcnc
  • Balena Etcher Download: https://etcher.balena.io/#download-etcher
  • Rufus Utility Download: https://rufus.ie/
  • Infra Recorder Download: https://infrarecorder.org/
  • Windows zsync Port: https://www.assembla.com/spaces/zsync-windows/documents
  • LinuxCNC Hardware Requirements Wiki: http://wiki.linuxcnc.org/cgi-bin/wiki.pl?Hardware_Requirements
  • Mesa Modbus Driver Documentation: http://linuxcnc.org/docs/2.9/html/drivers/mesa_modbus.html
  • HAL GPIO Driver Documentation: http://linuxcnc.org/docs/2.9/html/drivers/hal_gpio.html

Fabrication

No custom PCB design files (Gerber, Eagle, or KiCad files), CAD mechanical models, or custom fabrication specifications are contained in this documentation package. The physical setup utilizes commercial-off-the-shelf (COTS) x86 computer systems or ARM single-board computers interconnected to existing machine actuators and industrial interface cards.