One joint node for a robot arm, taken apart into twenty chapters and built on a bench that has no robot arm on it. A NUCLEO-H7A3ZI-Q, a Raspberry Pi 4, three sensor shields, one transceiver, and no motor.
314 pages, 101 figures, 20 chapters. Each chapter stands on its own: it states what it adds to the node, what it depends on, what is real and what is only modelled, and it ends in something measurable.
Read it. The whole volume is in chapters/ as Markdown
with its figures beside it. Start with
About this volume, or take a chapter
from the table below.
Or build it. The PDF and a single self-contained HTML file come from the same source and stay local:
python build.py --chapter 7
That writes chapter-07-the-actuator-you-do-not-have.pdf and a matching
self-contained .html with its five figures inlined.
Contents Read it · The rule · The twenty chapters · Building · Checks · Layout · Requirements · Licence
Three things a robotics firmware role asks for cannot be demonstrated on this bench: a motor and drive stage, a force or torque sensor, and a real-time Ethernet fieldbus. The book names all three in chapter 1, designs around them deliberately, and marks every figure accordingly.
| In a figure | Means |
|---|---|
| A solid outline | hardware that is present |
| A dashed outline | a model standing in for hardware that is not |
| A dotted grey block | hardware that is absent and explained rather than built |
No measurement taken through a dashed block is a measurement of anything
physical. Every budget table carries a Measured column that reads not
measured until something has been. A claim the research could not confirm is
written as a question rather than as an assertion.
That discipline produced more of the book than expected. Several of its most useful paragraphs are of the form this is not what everybody says: that this part's flash word is sixteen bytes and not thirty-two, that its backup registers live in a different peripheral from its better known sibling's, that a widely repeated middleware footprint comes from a commercial blog rather than from the project, that a popular bootloader changed licence in 2025, and that the collaborative robot technical specification is not withdrawn. Appendix C lists them all; appendix D lists the eight gaps the research could not close, which are claimed as new work rather than dressed up as a survey.
Difficulty is 1 to 5. Effort is in evenings. Chapter 1 gates everything; after that the reading order is mostly preference, and the dependency map in the front matter draws the parts that are not.
And the appendix, which puts the twenty on one page so a chapter can be chosen by what it gives rather than by its title.
Every chapter has the same twenty-one sections: why it exists, the prior art and what is taken from it, what the node gains, the parts it uses, a system architecture figure, the peripheral configuration, the wiring, a memory and timing budget, a software design in UML, a data-flow sketch, a repository layout, numbered steps with real commands and real code, measurable acceptance criteria, the variants it touches, pitfalls, best practices, stretch goals, a sourced roadmap, the evidence to publish, and its sources.
python build.py --chapter 7 one chapter, PDF and self-contained HTML
python build.py --chapters all twenty, one file each
python build.py the whole book, PDF and one HTML file
python mdbuild.py the Markdown edition, chapters and figures
Built output is not committed, with one deliberate exception. The PDF and the HTML are artefacts of this source, they are regenerated in a couple of minutes, and keeping them out of the history keeps the repository small and every published file traceable to the commit it came from. The figures are the exception: they are committed as SVG, because the Markdown edition cannot draw a single diagram in a browser without them.
python prepublish.py everything the workflow cannot see
python lint.py house rules over every chapter
python crosscheck.py book-level consistency
python check_readmes.py every README still describes its chapter
python build.py --check sections/j07.tex compile one chapter and report on it
All four read the authoring sources, which are not published, so all four run on
the authoring machine rather than on a runner. prepublish.py is the one to
run: it regenerates the Markdown edition first, then refuses if anything it
regenerated moved, if a chapter is missing a figure or its project line, if a
source has been committed by accident, or if either of the other two checks
reports a problem.
check_readmes.py is the exception to all of that: it reads the published tree
only, so it runs on a push as well. It exists because an audit on
Sunday 8 November 2026 found four kinds of drift between the software and the
prose that indexes it, including this tree missing from the layout table above
and chapter 9 missing from the software index while carrying nine modules. A
generator, a test or a shipping source file that is not named in the README that
indexes it now fails the build, because a rule that depends on remembering is
not a rule.
lint.py checks prose for em and en dashes, non-ASCII characters, violent
idioms and the required section skeleton, and checks code blocks for non-ASCII
and for lines longer than the page can print. crosscheck.py checks what
per-chapter linting cannot see: the variant matrix, figure coverage,
cross-references, chapter titles against the authoring guide, and that every
date is written in full. Neither can run on a push any more, because the
runner cannot see the sources they read; they run in prepublish.py instead.
What .github/workflows/checks.yml still does
is the code, which has grown into most of the workflow. It runs every
generator's --check, every chapter's own tests, compiles the C for the host
and runs it, compiles chapter 9's bus and board layers for the part at
cortex-m7 with hard float, and links chapter 4's startup, console and linker
script into a real image whose first two words it reads back out of the .elf.
It also checks the links and that no authoring source has reached the published
tree.
The C is built there and in WSL on the skyhorizon laptop, never on the authoring machine, which has no compiler by house rule. So for any change to the software the workflow is where the first information about it comes from.
One exemption is worth knowing about. \pubdate{April 2010} marks a date a
publisher gives to month precision only. The house rule is that every date the
book states carries weekday, day, month and year, and that rule cannot apply to
a day a publisher never published; writing one would be inventing a fact. The
macro makes the exemption explicit in the source, so every month-and-year that
is not wrapped is still reported as a defect.
| Path | What it is |
|---|---|
chapters/NN-title.md |
the Markdown edition, one file per chapter, generated from sections/ |
figures/NAME.svg |
every figure rendered, committed so the Markdown draws in a browser. Its TikZ source is not published |
prepublish.py |
the four checks the workflow lost, run before pushing |
mdbuild.py |
the Markdown converter, which reuses build.py's parser |
build.py |
figures to SVG, PDF, per-chapter builds, and the HTML converter |
lint.py |
house-style check |
crosscheck.py |
book-level consistency |
AUTHORING.md |
the contract every chapter follows, the honesty rule, the confirm-before-writing list, the variant matrix |
SOURCE.md |
the prior-art pool with verification marks, the four licence categories, the corrections, the claimable gaps, the open questions |
CONTENTS.md |
the chapter table, generated, which the table above follows |
joint-node/ |
the software, one directory per chapter that has any, with its own README, tests and Makefile. Five of the twenty so far, and its README is the only honest place to read which |
build/ |
scratch output, ignored, safe to delete |
Chapter files use a j prefix so that a cross-reference or a copied figure can
never silently resolve against a sibling volume's files. The book's identity
lives in exactly one DOC block per tool file, and both build.py and
lint.py refuse to run if the folder name stops matching it.
MiKTeX or TeX Live with pdflatex, latex, dvisvgm, circuitikz,
tcolorbox and listings; Python 3.10 or newer. No Python package outside the
standard library is needed.
MIT, see LICENSE. The book cites a great deal of other people's
work: every chapter's Sources section records what was taken from where and
under what terms, and appendix F sets out the four licence categories the book
applies to its own dependencies.