Repository navigation
docs: add robotics and Elixir vocabulary pages, one per audience - #280
Merged
Merged
Conversation
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
force-pushed
the
docs/robotics-vocabulary
branch
from
September 30, 2026 04:17
0a17e74 to
d2eeae4
Compare
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.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
:worldlink — 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-schemequery 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:
mix releaseonto a board you manage, containers for the parts that aren't holding a motor, and simulation — with the same robot module in all fourThere'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-motionstill 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.auditand three downstream jobs fail here. They fail identically on #279, which is unrelated to this branch — the audit one is the newmint1.10.1 advisory (EEF-CVE-2026-94194), published after the last green run on main.