.. _rigs4zephyr_reference_rig-file: Rig files ========== What a rig *is*, on disk: two files, ``boards/rigs//rig.yml`` (the :term:`rig metadata file`) and ``boards/rigs//.yml`` (the :term:`rig content file`), plus the optional qualifier-delta fragments that layer onto the content file. The authority is the loader itself — ``scripts/rigc/loader/documents.py``, ``axes.py``, ``delta.py`` and ``params.py`` — and every key below is read (or deliberately never read) exactly as that code does today. This page is reference, not narrative — :ref:`rigs4zephyr_tutorials_build-a-rig-that-exists` and :ref:`rigs4zephyr_tutorials_make-the-rig-permanent` teach the concept; this page looks up the facts. A shield can also become a rig of one instance without either file existing at all — see :ref:`rigs4zephyr_reference_promotion`. .. contents:: :local: :depth: 1 The two files --------------- Metadata files are named after the entity *type* — ``rig.yml``, the same filename in every rig's folder, the same way ``board.yml`` and ``shield.yml`` are. Content files are named after the entity *instance*: ``.yml``, constructed from the rig's own ``name:``, never read back from the folder it happens to live in. ``rig.yml`` The rig's identity and its qualifier axes. Carries **no hardware description whatsoever** — not an instance, not a wire, not a board. ``.yml`` The assembly: instances, and any wires between them. Required — a rig with no content file is refused (``lang-content``, naming the expected path) before anything else about it is read. Both are parsed by the same mark-aware YAML reader (``loader/documents.py``), with no ``rig:`` wrapper on the content side — only ``rig.yml`` nests its keys under a top-level ``rig:`` mapping. ``rig.yml`` — metadata ------------------------- .. code-block:: yaml rig: name: # required revision: # optional format: letter | number | major.minor.patch | custom default: "" # optional exact: true | false # optional, default false revisions: - name: "" variants: # optional default: # optional list: - # or {name: } ``rig: name:`` The rig's identity — its ``rig.yml`` ``name:`` field, not its folder name (the two conventionally match; nothing enforces it). Required; a missing ``rig:`` block or a missing ``name:`` inside it stops the load before anything else is read. ``rig: revision:`` The rig's own revision axis, in **upstream's hwmv2 shape** (``board.yml``'s own block, copied key for key) — the singular key ``revision:``, not the plural ``revisions:`` a shield's own axis uses (see :ref:`rigs4zephyr_reference_shield-template`). ``format:`` is required whenever this block is present, one of ``letter`` (a single uppercase letter), ``number`` (digits only), ``major.minor.patch`` (three dot-separated non-negative integers) or ``custom`` — declaring ``custom`` is legal YAML but rejected the moment the axis is actually resolved (rigc implements the first three formats only). Every declared id in ``revisions:`` must be a **quoted string** matching the declared format — an unquoted numeric-looking id is rejected rather than silently read as a YAML number. ``default:``, if given, must be one of the declared ids. ``exact: true`` disables hwmv2's own **nearest-lower match**: normally a requested revision that is not itself declared resolves down to the highest declared revision that is ``<=`` the request (comparing per-format — ``major.minor.patch`` also zero-pads a short request, ``"1"`` becoming ``"1.0.0"``, before either comparison runs); with ``exact: true``, any requested value that is not an exact declared member is refused instead. ``rig: variants:`` The rig's own variant axis — topology *alternates*, not a hardware axis: a variant selects which qualifier-delta fragments apply (below), never a board or a socket mapping. ``list:`` entries are either a bare name or ``{name: }`` (any other key on a mapping entry is silently ignored — see `What rig.yml never declares`_). ``default:``, if given, must be one of the listed names. Resolution takes an exact declared member only; there is no hwmv2 machinery on this axis. A rig with variants *and* revisions must not let any two distinct selections — a variant alone, a revision alone, or a combined ``(variant, revision)`` pair — construct the same delta-fragment stem (see `Qualifier delta fragments`_): a variant literally named the same as a revision id is the single-axis case of the same collision, and both are refused (``lang-variant``) at load time, before any fragment is read. Combined selection resolves variant, then revision — both independently against the declarations above, an unselected axis taking its declared default (or being refused if it has none and nothing was requested). There is no interaction between the two beyond the shared-stem collision check: a rig may declare either axis, both, or neither. What ``rig.yml`` never declares ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ **No ``board:`` key exists anywhere in this grammar — not at the top level, not per variant.** A rig describes a topology; the :term:`invocation coordinate` (``-b``/``-DBOARD=``, see :ref:`rigs4zephyr_reference_commands`) is the *only* source of the board, for every rig, with no exception — including a rig built against more than one real board (the same content file resolves on either, provided both boards expose the sockets it names; see :ref:`rigs4zephyr_tutorials_make-the-rig-permanent` and the ``arduino_r3`` alias convention it describes). A rig build with no board given is a configure-time error, not a fallback. A stray ``board:`` (or ``sockets:``) key on a ``variants:`` list entry is not rejected — it is **silently ignored**, the same as any other unrecognized key in this grammar. Nothing in ``rig.yml`` today populates a per-variant board or socket table. ``.yml`` — content --------------------------- .. code-block:: yaml instances: - name: # required shield: [@] # required socket: