Skip to content

docs: add robotics and Elixir vocabulary pages, one per audience - #280

Merged
jimsynz merged 3 commits into
mainfrom
docs/robotics-vocabulary
Sep 30, 2026
Merged

jimsynz merged 3 commits into
mainfrom
docs/robotics-vocabulary

Conversation

@jimsynz

@jimsynz jimsynz commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Adds the two vocabulary pages the docs have been missing, one per audience.

Robotics Vocabulary

The existing docs assume you know what a link, a joint or an estimator is, and spend their time explaining how BB models them. This is the page that goes the other way, for Elixir developers who have never had to describe a physical machine before.

Organised as shape / senses / doing / rules, framed around the robot being a supervision tree, and handing off to the existing tutorials and topics at each section boundary rather than re-explaining them. There's also a short section on ~u, since nothing introduced units to a newcomer.

Examples use the pan-tilt arm from the first tutorial throughout, except for unactuated joints and the :world link — an arm bolted to a bench can't illustrate those, so that one section uses a balancing robot and says so.

The material is reworked from the Goatmire 2026 balance bot workshop, including its six animated joint diagrams. Those now carry a prefers-color-scheme query in place of the deck's hardcoded colours, so they read in both hexdocs themes; assets: is added to the ex_doc config so they get copied.

The robotics-direction "For Elixirists" asides in the first-robot and kinematics tutorials now point here. I kept a one-line gloss in each rather than deleting outright — forward kinematics is tutorial 04's whole subject, so removing its definition would have made that page worse for someone arriving directly.

Elixir for Roboticists

The mirror, for people who already build robots and want to know how their concepts map across. Deliberately not an Elixir tutorial — what it covers is the part a language tutorial won't:

  • the concept mapping: node, topic, launch file, parameter server, and the two rows that need more than a table cell (tf, and why there's no separate orchestration layer)
  • why a supervision tree isn't a respawn loop — structural containment, declared restart strategies, and crashing as a legitimate design choice
  • what having no shared mutable state does to how you'd structure a robot
  • deployment: Nerves for devices that ship (plus NervesHub and NervesCloud for managing a fleet of them), mix release onto a board you manage, containers for the parts that aren't holding a motor, and simulation — with the same robot module in all four
  • toolchain habits that transfer badly from the ROS world

There's no section on realtime characteristics. That wants measured numbers rather than assertions, and is being worked on separately.

The two pages link to each other.

Notes

The companion PR in bb_pid_controller (beam-bots/bb_pid_controller#111) adds the PID explanation the vocabulary page links to.

Known limitation: the joint diagrams use SMIL, which CSS can't pause, so prefers-reduced-motion still gets the animation. The still frames were designed to read on their own, so it degrades to "a bit busy" rather than "unusable", but it isn't properly handled.

CI: canary, mix deps.audit and three downstream jobs fail here. They fail identically on #279, which is unrelated to this branch — the audit one is the new mint 1.10.1 advisory (EEF-CVE-2026-94194), published after the last green run on main.

The existing docs assume you know what a link, a joint or an estimator is
and explain how BB models them. This page goes the other way, for Elixir
developers who have never had to describe a physical machine before.

Organised as shape / senses / doing / rules, framed around the robot being
a supervision tree, and handing off to the existing tutorials and topics
rather than re-explaining them. The material is reworked from the Goatmire
2026 balance bot workshop, including its six animated joint diagrams,
which now carry a `prefers-color-scheme` query so they read in both
hexdocs themes.

Examples use the pan-tilt arm from the first tutorial throughout, except
for unactuated joints and the `:world` link — an arm bolted to a bench
can't illustrate those, so that one section uses a balancing robot.

The robotics-direction "For Elixirists" asides in the first-robot and
kinematics tutorials now point here.
@jimsynz
jimsynz force-pushed the docs/robotics-vocabulary branch from 0a17e74 to d2eeae4 Compare September 30, 2026 04:17
The mirror of the robotics vocabulary page, for people who already build
robots — in ROS, C++ or Python — and want to know how their existing
concepts map onto this.

Deliberately not an Elixir tutorial; there's a good ecosystem for that
already. What it covers is the part a language tutorial won't: the
concept mapping (node, topic, launch file, tf, parameter server), why a
supervision tree isn't a respawn loop, what having no shared state does
to how you'd structure a robot, and how a finished robot actually gets
onto hardware.

The deployment section covers Nerves for devices that ship, `mix release`
onto a board you manage, containers for the parts that aren't holding a
motor, and simulation. The point being that the robot module is the same
in all four.

Nothing about realtime characteristics — that deserves measured numbers
rather than assertions, and is being worked on separately.

The two vocabulary pages link to each other.
@jimsynz jimsynz changed the title docs: add a robotics vocabulary page for Elixir developers docs: add robotics and Elixir vocabulary pages, one per audience Sep 30, 2026
The Nerves paragraph stopped at getting firmware onto one board, which is
the least interesting half once there's a fleet. Adds what NervesHub does
— staged OTA rollouts, fleet health metrics, alerting, and a remote IEx
console into a device in the field — and notes NervesCloud as the hosted
option for anyone who'd rather not run the server.

The remote console point links back to the toolchain section, since it's
the same live-inspection story applied to hardware you can't reach.
@jimsynz
jimsynz merged commit 1a107ea into main Sep 30, 2026
37 of 42 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant