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.
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 lint.py house rules over every chapter
python crosscheck.py book-level consistency
python build.py --check sections/j07.tex compile one chapter and report on it
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. Both run on every push, see
.github/workflows/checks.yml.
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 |
sections/jNN.tex |
one file per chapter, 01 to 20 |
sections/front.tex |
about, the honesty rule, the bench, how to read it |
sections/appendix.tex |
the chapters at a glance, the honesty ledger, the corrections, the gaps, the open questions, the licence categories, the reference library |
figures/jNN_{arch,wiring,uml,data,timing}.tex |
five figures per chapter |
figures/front_map.tex |
the dependency map |
main.tex |
preamble, authoring macros, five parts |
tikz_preamble.tex |
shared TikZ and circuitikz styles, including the field bus, frame layout, control loop, joint and safe-state styles, and the three honesty styles |
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 |
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.