Compendium

Robotics Library — Per-Note Schema

3 min read

Robotics Library — Per-Note Schema

Every note in Robotics/ follows this structure. Predictability lets agents and humans find what they need without reading the whole note.

Status (2026-05-23). Schema applied across Tier 1 (25 notes) + Tier 2 (~22 notes) + Tier 3. Newer Tier 2 notes (Wave 13+) use a slightly leaner frontmatter — both styles coexist; both are valid.

Frontmatter

---
title: "<Topic> — Robotics Reference"
created: <ISO 8601>
agent: claude-code
type: robotics-reference
topic: <canonical slug, e.g., "brushless-dc-motors", "pid-control", "rrt-path-planning">
subdomain: <kinematics | dynamics | actuators | sensors | control | perception | planning | manipulation | mobility | power | safety | systems>
formalism: <continuous-time | discrete-time | hybrid | combinatorial | probabilistic>
key_standards: [ISO 10218, IEC 61508, ...]   # optional
practical_targets: [industrial-arm, mobile-robot, drone, humanoid, soft-robot, ...]
tags: [robotics-reference, <topic-slug>, <subdomain-tags>, ...]
official_refs: [<url>, ...]
latest_revision: "<x.y (yyyy-mm)>"   # only if applicable
---

Body sections (in order, all required unless flagged optional)

1. At a glance

One screen of bullets: what this is, why it matters, where it sits in the design stack, common variants, “first ask” before applying.

2. First principles

The physical / mathematical foundation. For a control note: the differential equation or signal-flow. For a motor: torque-speed, back-EMF, magnetic flux. For a sensor: physical principle (Hall effect, capacitance, ToF, photon arrival). Cite textbook references.

3. Practical math

The formulas you actually use during design — not derivations. Sized examples. Worked numerical case: “given X, compute Y.”

4. Design heuristics

Engineering judgement. Rules of thumb. Selection criteria. Common ratios. “If you need more than 50% duty cycle, derate by …“. The stuff that separates a textbook reader from someone who has built things.

5. Components & sourcing

Real parts, real vendors, real datasheets. Maxon, Faulhaber, Dynamixel for motors; STM32, RP2040, Jetson for compute; iSentek, Bosch, Honeywell for sensors. Price ranges (order of magnitude) where relevant. Common substitutes.

6. Reference data

Tables: torque curves, gear ratios, sensor resolutions, control gains as starting points, common bus speeds, payload ranges. Quantitative reference material.

7. Failure modes & debugging

What goes wrong and why. The “I tuned my PID and it oscillates” diagnostic flowchart. Thermal demagnetisation of magnets. Encoder drift. Sensor noise floors. Mechanical resonance.

8. Case studies

1–3 concrete designs that illustrate the topic: “Universal Robots UR5 elbow joint uses …”, “Boston Dynamics Spot uses … for ankle compliance”, “Industrial pick-and-place arm uses …“.

9. Cross-references

  • Adjacent robotics topics (Robotics/<other>)
  • Relevant engineering disciplines (Engineering/<other>)
  • Description languages for this topic ([[Languages/Tier3/robotics-control]], etc.)

10. Citations

  • Foundational textbooks (Craig “Introduction to Robotics”, Siciliano “Robotics: Modelling, Planning and Control”, etc.)
  • Standards (ISO/IEC numbers with year)
  • Datasheets (vendor + part number + revision)
  • Recent papers (with DOI / arXiv)
  • Construction guides (Hackaday, Make:, vendor app notes)

Writing rules

  • Show numbers. “100 W BLDC at 24 V, ~4 A peak, ~0.5 Nm continuous” beats “a moderately powerful brushless motor.”
  • Cite primary sources. Datasheets, standards, peer-reviewed papers. Avoid blog summaries except as exemplars.
  • Bias toward “I can build this.” Every note should answer: what part do I buy, what’s the math, what’s the gotcha.
  • Date everything version-sensitive. “As of YYYY-MM, ROS 2 Lyrical Luth is the current LTS” — not “current LTS.”
  • Cross-link. Robotics is a system discipline; isolate-able topics are rare.
  • God-mode section deferred vs the Languages library: instead of “God mode,” section 8 (case studies) is where deep insight lives — showing how the topic plays out in a real, named machine.

Graph View