Visual documentation of how LinuxCNC actually works inside — made while learning the system before a first machine build, and shared in case it helps someone else arriving here.
Two self-contained HTML sheets, plus the verification work that backs them:
everything shown was read in the source, and every claim carries a file:line
citation that a script re-checks.
| Read against | LinuxCNC/linuxcnc @ caa13ca6ae (master, 2.10.0~pre1, 2026-07-30) |
linuxcnc-ethercat/linuxcnc-ethercat @ 87a72a8 (2026-08-03) |
|
| Licence | GPL-2.0 |
Both are single HTML files with no dependencies — download and open in any browser. (GitHub shows HTML as source rather than rendering it; use Download raw file, or clone the repository.)
sheets/linuxcnc-command-flow.htmlAn animated sheet following one command the whole way through:
.ngc → Interp → canon → interp_list → task → usrmotintf
→ emcmot shared segment → motion-command-handler → tpAddLine
→ TC_QUEUE → tpRunCycle → inverse kinematics → output_to_hal
→ HAL → pid → stepgen → hostmot2 → motor
…and the feedback path climbing back up. Hover any block to see its role and the source file that implements it. Three detail panels come with it:
head++ opening the seqlock to tail = head closing it.carte_pos_cmd down to
carte_pos_fb, with the transformation between each, as a closed loop.sheets/linuxcnc-code-notes-errata.htmlThe architecture diagram from the Code Notes redrawn as published, next to a corrected version reflecting the current source, with the joint-controller diagram audited alongside.
Written with the help of an AI assistant (Claude), under a deliberate discipline: nothing claimed without being read in the source, every statement carrying a citation, and the citations themselves machine-checked.
git clone https://github.com/LinuxCNC/linuxcnc.git
git clone https://github.com/linuxcnc-ethercat/linuxcnc-ethercat.git
git -C linuxcnc checkout caa13ca6ae
git -C linuxcnc-ethercat checkout 87a72a8
powershell -File linuxcnc-audit/tools/verify-citations.ps1
Expected: 111 pass, 0 fail. On a later HEAD a FAIL usually means the line
moved — re-anchor the citation rather than assume the finding broke.
The same discipline was turned on this work itself: four verification passes, the first two of which found and corrected twelve of its own errors before any of this was published. They are recorded, with the original wording preserved, in the findings file’s changelog.
The Code Notes open by warning that “much of this information is now outdated and has never been reviewed for accuracy.” Taking that at its word surfaced a number of places where the documentation and the source have drifted apart. Most are harmless; a few would bite someone.
LINUXCNC-FINDINGS.md — the knowledge base:
architecture facts (NML, HAL, the emcmot segment, queues, the servo cycle,
EtherCAT), the errata with their evidence, the points that check out
unchanged, what remains unverified, and the changelog.motion-commands-reference.md — all 76
motion commands read from command.c, with handler locations and rejection
conditions. The Code Notes document 27 of them.upstream/ — three small documentation patches for the
actionable items, applying cleanly on the audited master. Not submitted
upstream.Two examples of the kind of thing found: the HAL manual’s initf example names
a funct the EtherCAT driver doesn’t export, and pause is silently bypassed
during spindle-synchronized motion (G33 threading, rigid tapping) — sensible
behaviour, documented nowhere.
v2.9.10).
Most of it holds for 2.9 too; the exceptions are flagged in the findings file
— notably that on 2.9.x, iocontrol is still a separate process.GPL-2.0 (see LICENSE) — the patches derive from LinuxCNC’s
GPL-2.0 documentation, and the findings quote its source.