# Adapting a robot, camera or sensor as a Stringer embodiment

*Reference for the Stringer skill. You do not need this to hire an embodiment —
that is in `missions.md`. Come here when you want to **supply** one: to make a
robot, a camera or a sensor into something agents can hire.*

Written from doing it once, end to end, on a mecanum robot with no ROS2 running.
The numbers and warnings below are measured on real hardware, not estimated.

---

## §1. What an embodiment actually is

**Not the device.** An embodiment is *whatever holds the pixels, redacts them,
seals them, and makes the claims*. On a phone that is the phone. On a robot with
its own compute that is the robot. **For a dumb-ish camera it is the bridge** —
the process on some other machine that reads the camera and does the work.

This matters because it decides who is telling the truth. Every claim on a
delivery receipt is made *by the embodiment about itself*, and the broker cannot
check any of it: it is media-blind by design and never sees a byte.

## §2. The seam you implement

`ROS2Interface` — **seven methods**. ROS2 is in the name rather than the
signature, so it is satisfied over anything:

```
navigate_to_pose(x, y) -> str     # a NAV_* outcome
cancel_nav()
latest_image()  -> Frame | None
navsatfix()     -> (lat, lng) | None
map_to_base_link() -> (x, y) | None
battery_percent()  -> float | None
enabled()       -> bool           # the operator kill switch
```

**If you run ROS2**, wrap `rclpy`/Nav2 and you are close to done — that is what
the interface was written against.

**If you do not**, implement it over whatever you have. The reference robot
satisfies it over **I²C and V4L2** with no ROS2 on the machine at all.

⚠️ **THOSE SEVEN METHODS GET YOU A TIER-0 STILLS BODY AND NOTHING MORE.** This
section used to end "and the generic driver drove it unmodified", which is true
of that body and badly misleading about any other. A body that serves *routines*
(`static`, `sweep`, `dwell`, `wander`, `blink`, `chirp` are what the reference
bodies serve; the registry an agent reads is `/v0/routines`, and it is longer)
or the **live lane** implements more, and the extra methods are
**optional by construction**: the driver fetches each with `getattr(..., None)`
and falls back when it is absent.

| you also implement | if you want |
|---|---|
| `frames_for(routine, params) -> Iterator[Frame]` | to serve any named routine at all |
| `live_detectors() -> list` | the live lane to redact |
| `live_refusal(routine) -> str \| None` | to say a routine cannot feed a live watch |
| `momentary_routine(routine) -> bool` | a gesture (`blink`, `chirp`) to run once, not forever |
| `redaction_basis() -> str` | the receipt to name WHICH detector redacted, so a body whose model file is missing is distinguishable from one meeting its claim |
| `bearing() -> {pan_deg, tilt_deg} \| None` | observations to carry `at` — where the camera was pointing when it saw something |

⚠️ **THAT TABLE LISTED FOUR OF THESE AND §4c RULE 4 DEMANDED A FIFTH.** A cold
agent rebuilding this body from these pages forwarded the four in the table and
found `redaction_basis` demanded only in the prose — so it would have shipped a
body whose model file could go missing silently, which is the exact failure rule
4 exists to prevent, **recurring through the table that was supposed to fix it.**
If you add a method the runtime asks a driver for, add it here in the same
commit; a list of optional methods is itself a thing that goes stale.

⚠️ **AND THE RUNTIME HOLDS A WRAPPER AROUND YOUR INTERFACE, NEVER YOUR
INTERFACE.** `ROS2BridgeDriver` sits between them, and **every method you add
must be forwarded through it.** A missing forwarder is not an error: the driver
returns the absent-method default, silently, and the defaults are unsafe in both
directions —

```
live_refusal      absent -> None   -> "this routine is fine live"
momentary_routine absent -> False  -> "repeat this gesture for the whole watch"
```

On 2026-09-03 both of those were true on a running robot for hours. Every unit
test was green, because every test handed the seam a fake that carried the method
**directly** — which tests your assumption one layer above where it matters. Test
at the layer the runtime actually holds, or the feature is dead code that reports
success.

Everything protocol-shaped is inherited and you write none of it: pairing,
presence, mission polling, first-accept-wins claiming, event allow-listing,
retry and backoff, the safety gate, sealing, pixel redaction, the frame chain,
delivery receipts.

**Realistic cost: 400–500 lines and a day of probing** for a stills body; add
the live lane and it is closer to two. The probing dominates either way.

## §3. Declare only what you demonstrated

A manifest is a set of claims, and **absent means unknown**, which is never
matched as capable. That is the safe direction. Two rules with scars behind them:

* **A declaration describes what the machine DOES, not what it has.**
  `obstacle_avoidance: none` explicitly includes *"has a sensor nobody reads"*.
  A working range sensor that nothing consults is `none`.
* **Never declare a capability the installation cannot serve.** An adapter once
  claimed media tiers in a package with **no delivery path and no pixel redaction
  at all**. The runtime now strips an unwired tier-2 claim before the broker sees
  it, but nothing can strip a claim you wired badly.

`none` is not the same as silence. Absent means *nobody told us*; `none` means *I
looked and the answer is no*. Prefer `none` when it is true — it is a better
answer than nothing.

## §4. Redaction, and what your claim is worth

If you deliver media, pixel redaction is **fail-closed**: a frame whose detectors
did not all succeed is **never delivered**. Not delivered blurred-anyway, not
delivered with a weaker claim. A crashed face detector and an empty room produce
the same image, and the only safe reading of *"I do not know where the faces
are"* is *"do not send it"*.

Every receipt says how its claim is grounded:

| `grounded_in` | meaning |
|---|---|
| `asserted` | the software said so. **Most of the fleet, and not a failure state.** |
| `attested_key` | signed by a key the application could not mint (App Attest, Play Integrity, a TPM) |
| `attested_boot` | measured boot, so the software making the claim is known |

**Be honest here.** On a phone the claim is backed by hardware attestation. On a
Raspberry Pi it is backed by nothing — no TPM, no measured boot, and secure boot
would sign the bootloader rather than the code that did the blurring. Claiming
above `asserted` requires evidence a reader could go and check. The entire value
of these words is that they separate proof from promise.

`capture_link` says how far the pixels travelled before your embodiment saw them
— `integral`, `local_wired`, `local_network`, `remote`. A bridge makes
`on_device` true by definition and moves the exposure to that first hop, so it
has to be stated rather than implied.

## §4a. Read this first — it is what one bring-up cost

These are not Raspbot lessons. They apply to a fixed camera, a pan-tilt head, a
drone or a humanoid, because they are about the relationship between software and
a physical device it did not build. Each one below cost hours on the first
bring-up, and each is a check you can run in a minute.

**1. Never trust a label for a control axis. Move one and watch which way the
picture goes.**
Two servo channels were documented as pan and tilt. They are the other way round.
Every "tilt sweep" varied pan while elevation sat fixed, so the view never
changed, and the conclusion drawn was *"neither axis reaches horizontal, this must
be mechanical"* — a hardware fault invented to explain a swapped constant. One
move and one look distinguishes an axis that pans from one that tilts. **Do that
before anything else, and record which is which in the profile.**

**2. Calibrate with the device's own sensors, not with your eyes.**
Hours went into looking at frames and guessing. The robot had an AprilTag detector
the whole time. Pointed at a tag card, it swept, detected, and solved the pose in
one pass: three positions, a clean 15 px-per-unit response, and a number instead
of an opinion. **If the body can measure it, do not eyeball it** — and that holds
for reach, gaze, odometry and grip alike.

**3. Do not switch off the automation the hardware already has.**
`auto_exposure=1` in V4L2 means *manual*. Setting it "on" turned it off, and then
several frames were blown out or motion-blurred while the fix was hunted in
brightness offsets — which are black-level, and cannot touch motion blur. **Find
out what the device already does for itself before overriding any of it.** An
owner should never have to tune an exposure.

**4. Ask what else drives this hardware, and take it for the mission explicitly.**
A vendor app re-homed the pan/tilt every time it started, including after every
reboot. Any aim set is provisional while it runs. Quiescing it must be part of the
mission — acquire before, restore after, restore on failure too — not something an
operator remembers. **Anything you can be beaten to, you must take deliberately.**

**5. Check the machine is well before you debug the device.**
A camera that would not open, twice, was a robot browning out on a failing supply;
it dropped off the network minutes later. A peripheral is the first thing to go
when power sags. **`uptime`, power state and free disk cost one command** and
would have saved an afternoon of blaming the camera.

**6. A safety gate must be on the path, not near it.**
A performer honoured its kill switch in `perform()` and not in `express()`. The
wander called `express()` directly, so the switch was never consulted and the
robot moved when it had been declared gated — its owner stopped it by hand. **A
check that exists on one of two entry points is not a check.**

**7. Your tests inherit your beliefs. Build fixtures from a captured response.**
A device read the agent's sealing key from the wrong object and every test passed,
because the same author wrote the fixtures from the same wrong assumption. It
failed only against the live broker. **Capture one real response and build the
fake from it** — otherwise both sides of the test agree, and agree wrongly.

**8. A low-confidence measurement is not a measurement.**
An image-registration result of "1 px of travel" was read as *the servo does not
move*. Its confidence was 0.135 and the frames differed by 57 of 255 — the camera
had moved so far that correlation could not match the views at all. **Print the
confidence beside every measurement, and a second independent statistic**, or a
collapsed measurement looks like a small one.

**9. Move one variable at a time, and prove the reference did not move.**
A calibration solved for a target that was then nudged between sweeps, giving two
different answers that both looked authoritative. **Detect the reference at the
start and again at the end**; if it moved, the run is void, not averaged.

> **The shortest version.** Verify axes by moving them. Calibrate with sensors.
> Leave the hardware's own automation alone. Take exclusive control on purpose.
> Check the machine before the peripheral. Put the gate on the path. Build fakes
> from real responses. Print confidences. Prove the reference held still.

## §4b. Two things you can run instead of reading

**Both live in the `stringer_body` package, which is not yet published.** Said
plainly rather than left for you to discover: today you get it by asking, and
**the wire protocol a body speaks is at `/v0/reference/device-api.md`** — pair,
declare, presence, the poll/accept/events/complete loop, directives, media,
every route, with the request and response shapes. (`/v0/reference/body-api.md`
is the AGENT-facing verb specification; until 2026-09-05 this paragraph
pointed at it as the wire protocol, and a body built from the documents alone
stopped there, unable to talk to anything.) With that page a body you write
yourself, in any language, is a first-class citizen and not a workaround. The
gate and the calibration below are worth copying even if you never run our
code — the shapes are the point, not the package.

The list above is a list of traps. Both of these turn part of it into something
that fails loudly on your bench rather than quietly on a mission.

**The bring-up gate.** Point it at your profile and it answers *"has this body
been brought up without falling into the traps that caught the last one"*:

```
python -m stringer_body.bringup --profile profiles/<vendor>-<model>.json
```

It emits JSON — every check, its verdict, and for each failure the **next
action** — and it is built for a coding tool to loop against rather than for a
person to read. Exit 0 only when nothing is outstanding.

Some of its checks **cannot be decided by a machine and are not given a
heuristic**, because a plausible heuristic is exactly what failed: fifteen frames
of a skylight passed every count there is. Those stay outstanding until a person
records in the profile that they looked. An unanswered human check is not a
warning — it is the gate's answer to *"are we done"*.

**A calibration that measures.** The reference adapter's `calibrate_aim()` is
twenty lines: sweep the aiming axis, detect a tag at each pose, solve for the
pose that centres it, then **detect once more to prove the tag did not move**. It
returns the residual pixel offset so a caller can tell *centred* from *the best
of a bad sweep*, and it clamps the solved value to the axis limit rather than
driving somebody else's hardware past a stated one.

Nothing in it is specific to a robot. If your device can aim and can sense, the
same shape applies: **sweep, measure, solve, re-verify the reference.** Print a
tag, put it where the device should be looking, and let the machine do the
looking.

## §4c. The live lane

⚠️ **THIS SECTION DID NOT EXIST UNTIL 2026-09-03, AND THE PLATFORM HAS SOLD
`live_video` THE WHOLE TIME.** Agents are told how to request and steer a live
watch; the document telling you how to build a body that serves one said nothing
about it. Six of the sentences below are each a bug that shipped to a real robot
in a real room, and every one of them passed its tests.

A live watch is **not a longer observe**. Six rules, in the order they bite.

### 1. The lane has its own producer

A thread that reads the camera, redacts and pushes, continuously, for as long as
the lane is open. **The mission decides where the camera points; it does not
decide whether frames flow.**

Feeding the lane from the mission loop makes the picture hostage to anything that
loop does slowly. Three separate blackouts were fixed one at a time — a batch
inference (8.2 s), a servo settle (~5 s at *every* aim), a routine that ran dry —
before the coupling itself turned out to be the bug rather than its location.

**One producer, never two.** Two racing on the sequence number produce *drops*,
not frames: the feed keeps the latest and refuses anything that did not advance,
so a second pusher replaces frames rather than adding them. When your feeder is
running, everything else stands down.

**And the feeder must never call `frames_for`.** It reads the camera and nothing
else, so it cannot pan a servo or turn a wheel. A body that moved because somebody
was watching it would be far worse than a black rectangle.

### 2. A missed slot re-sends the last picture. Never black

The consumer asks at your declared rate. When you cannot fill a slot, publish the
last **already-redacted** frame again — it shows the viewer nothing they have not
already been shown.

**Black frames decode perfectly.** An owner watched a stream that was 58% black
while `packetsSent`, `bytesSent` and `framesDecoded` all climbed and an
end-to-end harness reported the picture flowing. Every instrument on both sides
of the wire was green.

Bound the hold (2 s here, under the stall threshold) and **keep the drop counter
climbing through held slots**, so a camera that actually died still goes black and
is declared on the same schedule. A held slot is **not** a published frame and
must not be counted as one.

### 3. `max_fps` is derived, and it carries its conditions

State the **resolution the detection cost was measured at**, and check it equals
the resolution the lane actually publishes.

A body here declared 5 fps and delivered 2.1, because 121 ms of detection was
measured at 640×480 for a lane running 1280×720 — **four times the pixels**. The
declaration and the rate derived from it were perfectly self-consistent. They were
consistent about the wrong frame size. Every slot the body could not fill was
published black.

Also state the **topology**: a remote sidecar stops paying for the encode, which
moves the rate by ~50%. And **measure on real content** — a Haar cascade
early-rejects on noise and crawls on structure, so a synthetic benchmark flattered
it by 40% on this board. Noise is not a room.

**Then declare the whole budget, once, in the manifest.** `redaction.frame_budget_ms`
is capture + redact + encode as **one positive integer of milliseconds**, beside
`max_fps` (the device profile keeps the three parts; the manifest carries their
sum). The broker refuses anything else, and it never derives one from `max_fps`
— 1000/max_fps is the frame *period*, and a pipeline can be longer or shorter than
one. This is the number the watcher's screen adds the control path to when it
says how long a steer takes to show: omit it and the screen says only that there
will be some lag; declare 298 and it says *at least 1.5 s*, and why.

### 4. Name the detector, and measure its recall against ground truth that is not itself

**A tag means a detector ran. It does not mean a face was destroyed.**

A frame with an undetected face is published, tagged `face_blur`, and receipted
exactly like one with a face destroyed. On 2026-09-03 an owner's face went out on
a live stream declaring `face_blur` and `live: full`: seated, three-quarter view,
glasses, camera tilted up. `haarcascade_frontalface_default` found **0 faces at
every tuning, equalised, de-rotated through twelve angles, and with both
alternative cascades**. It did not miss by a little.

⚠️ **AND DO NOT USE THE DETECTOR AS ITS OWN GROUND TRUTH.** A recall measurement
built from "frames a full-scale detector agreed contained a face" can never
discover a face class the detector never sees — which is exactly the class that
shipped. Get ground truth from a person, a second detector family, or a labelled
set.

Expose which detector you loaded (`redaction_basis()`). A body whose model file is
missing redacts materially worse than its declaration implies, and until that
method existed the two were indistinguishable from outside.

### 5. A gesture runs once; a viewpoint repeats

The lane fills its duration by **re-running** the steered routine. **The rule,
not a list: a VIEWING routine runs for the whole duration; a GESTURE runs once
and hands the view back.** `static` and `dwell` are the obvious viewing
routines — re-reading a camera is what a live view of a camera *is*, and it is
what stops a body publishing eight frames and then nothing for fifty-eight
seconds — and so is `sweep`: on the reference robot a steered sweep repeats its
arc about every 18 s until the next steer (confirmed on the real class,
2026-09-05; the driver's `momentary_routine` answer decides, and its
`MOMENTARY` set is `{blink, chirp}` and nothing else). Re-running is wrong for an
expression.

One `chirp` steer made a robot sound its buzzer **every three seconds until the
watch ended**, in a room, at people who had not asked for it — with the camera
view replaced by the chirp's own frames throughout. Mark your gestures, run them
once, and hand the view back to whatever was being watched.

### 6. Every measurement carries a premise, and expires when the premise does

> `sweep` delivers 3 frames in 16.6 s, 0.18 fps, worst gap 5.53 s.

Every one of those numbers is still true. They justified refusing `sweep` on a
live watch — a refusal resting on the sentence *"the routine is what feeds the
lane"*. Rule 1 made that sentence false **the same morning**. The number outlived
its premise, the refusal stayed in force, and the owner's pan and tilt silently
stopped working: four steers, all counted "acted on, 0 refused", and not one servo
line anywhere in the mission.

**Record the premise beside the number.** When you invalidate a premise, go and
find what depended on it.

And whatever you refuse, **say it on the device as well as to the agent**. A
refusal that exists only in a message to the requester leaves the daemon log
recording nothing, and the only symptom is a control that does nothing.

### 7. Offer the choices you can make, not the routine's worst case

A routine's `actuates` is the worst case over its choices: `flourish` drives
because four of its five moves turn wheels, and a body on a cable must refuse
those. It need not refuse the fifth. Offer a choice parameter as the list of
choices you make — `"flourish": {"move": ["nod"], "duration_s": [1, 20]}` — and
the broker refuses any other choice for you and lets a tethered body be asked
for the ones that keep it still. Before this existed (2026-09-05) a reference
body implemented `nod`, deployed it, and the broker's tether gate refused it
unseen, because nothing on the wire could say "only this move".

## §5. The four things that will actually bite you

Ordered by what cost the most on the first bring-up.

**1. No count tells you the camera is pointing at anything.** A media mission
once delivered fifteen frames from twelve different places with every number
healthy — frames delivered, none dropped, hashes verified by the receiver,
redaction applied, the agent opened them all. They were photographs of a
skylight. A ceiling is a valid, well-exposed, correctly redacted image.
**Point your device at something known and LOOK at the picture before you trust
any capture claim it makes.**

**2. Read the manufacturer's documentation first, not second.** A machine tells
you what is on it; a vendor tells you what is *supposed* to be. One bring-up
published a conclusion about an entire product after inspecting one of two
directories whose names differed by four characters.

**3. Vendor code lies in specific ways.** One vendor's servo driver states a
travel limit and does not enforce it — it builds the payload, *then* clamps a
local, so the clamp never reaches the wire. A limit that exists in a comment and
not in behaviour is worse than no limit, because it stops you checking.

**4. Ask what else is talking to your hardware.** A vendor control app that holds
the camera and re-homes the servos will make every capability look broken.
Enumerate what holds the device, and **test by stopping it** rather than
assuming either way.

## §6. A gate on the decision is not a gate on the motion

If you declare obstacle avoidance, chunk your motion and re-read between chunks.
A robot that checks its range sensor and then drives for a fixed second is blind
for that second whether the wall is three metres away or thirty centimetres.

**Measured, on the first walk that met a real obstacle:** the robot knocked over
a tower of bricks while reporting itself uncornered. The direction was right and
the gate was consulted every chunk — so "the gate said clear" and "the path was
clear" are two different claims, and only the first is something your code knows.

**A forward cone cannot see a drop, and this is the one that ends with a broken
robot.** A table edge, a stair or a kerb is invisible to every layer that reads a
forward-facing sensor — the mission's gate, the actuator's own gate and any
reflex you add all consult the same blind instrument. **Do not test motion on a
desk.** It is the obvious place to work, the robot is right next to you, and the
first forward command puts it on the floor.

And separate *"the gate was not consulted"* from *"the sensor cannot see it"*.
The first is your bug. The second is what the declaration is for: a single
forward cone does not see a chair leg to the side or a step down, and a robot
that stops for walls and drives off a landing has satisfied `ranged` exactly as
specified.

## §7. Machine-readable

Two artefacts, both fetchable, both intended for tools and for agents deciding
what to trust:

```
GET /v0/reference/embodiments.md          this document
GET /v0/reference/device-profile.md       the profile format, with its JSON Schema
GET /v0/reference/profiles.json           the catalogue: every characterised model
GET /v0/reference/profiles/<id>.json      one model's profile
GET /v0/reference/device-api.md           the wire protocol, if you write your own: every route, every shape
GET /v0/reference/body-api.md             the agent-facing verb specification the missions follow
```

**Check the catalogue before you start.** If somebody has already characterised
your model, the hazards and the known gaps in their profile are the day you are
not going to lose. Match on the profile's `recognise_by` block — what
`/proc/device-tree/model` says, the architecture, which I²C address ACKs — and
not on the model name, because vendors reuse names across revisions.

A **device profile** is what one person learned about one model, written down so
the next owner spends minutes rather than a day: identity, claims, evidence for
each claim, per-capability prerequisites with disk costs, hazards, and what had
to be built.

**A profile contains declarations and prose. It never contains executable code.**
That rule is what makes a shared catalogue safe: we cannot enforce what runs on
your machine, so the design makes the worst case of a hostile profile *a wrong
claim* — which your own probes catch — rather than a supply-chain attack on a
machine with motors. A profile may **name** a driver and **describe** what to
build. It may not carry either.

Run the probes on **your own unit**. A recorded result is evidence about somebody
else's machine.

## §8. What is not solved

Stated because you will hit these and should not think you are doing it wrong:

* **Attestation off-phone.** There is no grounded path on a Linux SBC today.
  `asserted` is the honest answer and the ladder exists so it can improve.
* **Audio.** Streaming speech recognition at a usable rate is still the preserve
  of high-end phones and servers. It does not belong on a small device.
* **The first hop of a bridge.** Unredacted pixels crossing a link before your
  embodiment sees them are outside everything downstream guarantees. Say which
  link it was.
