Firmware and software

What runs on the body: responsibilities, rates, guarantees, and link-loss behaviour

Open on GitHub Mở trên GitHub

Snapshot of this document in the GEMs repository. The repository itself is the current version. Bản chụp tài liệu này trong repo GEMs. Bản đang chạy nằm ở chính repo.

What runs on the body. This chapter states responsibilities, rates and guarantees; it does not specify an implementation.

It does not describe the Main Controller, which runs off the body, on the IPC (01). The stack here executes, processes and records — it does not decide. Where the line between them is not obvious, 9.5 draws it.

7.1 The division

Two classifications apply to every piece of code on the body, and they are independent. Terms follow standard usage; see the glossary.

Where it runs — firmware or software. Firmware is software resident in the non-volatile memory of an embedded device and executed by it: in the wording of ISO/IEC 12207, the combination of a hardware device and the instructions and data that reside on it as read-only software. Here that means code running directly on a microcontroller, bare metal or under an RTOS. Software is code running under an operating system on an embedded computer — Linux, with or without a real-time kernel — including the device drivers that run there.

The Real-time Control Layer's code is firmware or software according to which processor D-3 selects (plan). Its deadlines do not change with the choice; only the evidence that they are met does.

How late it may be — the real-time class. A task's class is set by the consequence of missing its deadline, as the real-time systems literature defines it:

The rule that joins them: every hard real-time task runs on a platform whose worst-case latency is bounded. The two axes stay independent — the rule constrains the platform, not the layer — and the bound is established one of two ways, recorded per task in realtime_config/:

A Linux task without a real-time kernel and a real-time scheduling policy has no bounded worst case, and cannot carry a hard real-time task.

7.2 Real-time requirements

Every task's layer, rate, deadline, stage budget and deadline class is held in realtime_config/tasks.csv, and its platform and scheduling policy in realtime_config/scheduler.csv; python realtime_config/check_timing.py checks both against this section.

Multi-stream timestamping. Every sensor channel MUST carry timestamps on a common time base, established at the transport layer rather than inferred later. Channels arrive at rates differing by three orders of magnitude (05); without a shared clock, fusing them produces confident nonsense. The permitted skew between channels is ⟦IMPL⟧ and is bounded above by the reflex budget: skew that approaches 10 ms has already broken the reflex path.

Link round-trip is ~1 ms at ideal short range but cannot be relied on for ≤10 ms at kilometre range. The two rates above are therefore on-body by necessity, as 05.6 establishes. They are not a partitioning preference.

7.3 What the real-time code must guarantee

These bind the firmware and the Real-time Control Layer together — whichever layer decision D-3 places that layer in.

Guarantee 2 deserves emphasis because it is easy to specify as an afterthought. A body that loses power or loses its balance solver while standing is a falling mass of 70–160 kg (02.5) that may be in contact with a person. The failure state is a design requirement of the same rank as the loops themselves.

7.4 What software must guarantee

On guarantee 2. Agency tagging is done in firmware, at acquisition (7.3 guarantee 7), not as a later correction in software. Once a stream has been fused, filtered or compressed without the self-caused/external distinction attached, the distinction cannot be recovered downstream — the information that would have carried it has already been averaged away.

On guarantee 3. The cost is a compact context record per output event, microseconds against a 10 ms budget. This is what makes the body is replaceable, the data is preserved true rather than aspirational: the off-board compute is never blind to what the body has already done.

7.5 Link loss and the OBC

The OBC is mandatory (01). It is the unit's kernel for a link to the IPC that lags or fails, and it holds command only on a trigger, so that the unit never has two sources of commands at once (Plone, 2026-11-05):

The unit triggers the OBC itself because an IPC that is gone cannot. Command returns only when the Main Controller takes it, never because the link happens to come back, so a link that flickers cannot pass command back and forth, and the two sources never overlap at the handover. The Real-time Control Layer runs through every row; only the source of its setpoints changes. The heartbeat threshold is ⟦IMPL⟧: it depends on the link and on how long the Real-time Control Layer can hold without new setpoints.

In command, the OBC MUST:

What the OBC does not do: decide. It runs the reflexes the Main Controller loaded, choosing among them only within the bounds the Main Controller set, and preserves what it holds. Each reflex still runs its appraisal step on the unit, under the field the Main Controller loaded (firmware §2; RSIL §9.7); the Main Controller appraised what it loaded, and appraises the record again when command returns. The OBC is not a reduced controller and must not be specified as one, because a body that substitutes its own judgement during an outage produces actions no one can attribute afterwards — the precise failure the audit surface exists to prevent.

The boundary is architectural, not cautious. Reflexes are loadable; the interpretation of priorities in an unforeseen situation is not a reflex, and nothing in this repository claims to supply it.

7.6 Resource budget

7.7 Open constants

Operating point: ⟦CTRL⟧.