Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 10 additions & 8 deletions docs/design/policy-channel-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -514,9 +514,10 @@ axes, every field, what each one changes on the robot. It is not repeated here,
is only the reasoning for the mechanism existing at all.

The one thing worth restating, because it is what the mechanism is *for*: `kind` and
`command.encoding` are two axes, and an episodic policy becomes a skill only on a constant
command. A `phase` or `posture_flag` entry contributes timing to an arm the daemon drives instead
— which is how a retrained ground pick with a longer cycle is a tag rather than a daemon release.
`command.encoding` are two axes. An episodic policy on a constant command becomes a skill; one on
a phase command does too, if it is added with `policy add` — the daemon writes the same
`[cos 2πφ, sin 2πφ, 0]` the ground pick already writes. A set's own phase entry is still the
ground pick, and `posture_flag` is still the sit↔stand.

**The per-policy fields are the same ones a single-policy repo uses**, plus `file`. That is what
makes the ask to a community publisher "add these fields" rather than "adopt our format", and it
Expand Down Expand Up @@ -593,10 +594,11 @@ them to hand back to. `sitstand` is latched and driven internally by the shutdow
by a button — `scripted`, in the manifest's word. `ground_pick`
writes a phase rather than a constant. None of the four is a generic one-shot, and a set entry
may not answer to `ground_pick` or `sit_toggle` — a second network behind either name would be
fed an all-zero command it never trained on. The guard is on the encoding as well as the name: a
`phase` or `posture_flag` entry is never loaded as a skill however it is called. What the set
*does* get to say about these arms is their timing (§9.3) — the pick's cycle and cutoff, the
rise and the seat's settle — since those are properties of the trained network, not of the build.
fed an all-zero command it never trained on. The set never auto-loads a `phase` or `posture_flag`
entry as a skill; those encodings belong to the ground pick and the sit↔stand. `policy add` is
the other path, and it will take a phase policy as a skill. What the set *does* get to say about
these arms is their timing (§9.3) — the pick's cycle and cutoff, the rise and the seat's settle
— since those are properties of the trained network, not of the build.

**A running skill has the fall reflex off** for its whole duration: the limp-fall predictor is
only consulted while the controller is not `busy()`, and any active skill makes it busy. That was
Expand Down Expand Up @@ -743,7 +745,7 @@ its meaning for the things that genuinely are models and not control policies, s
| Reload is a third thing, not reset-all | They look identical from outside and conflating them discards every override (§9.1) |
| One-shot skills are config, not code | Kicks and roulade were the same arm with different numbers; a community one is a fifth set (§10) |
| `kind` says who ends a policy, not how long | An episodic one returns itself; a perpetual one needs the daemon to drive it back; a scripted one is episodic but interruptible (§9.3, §10.1) |
| `command.encoding` says what the daemon feeds it | Constant → a skill; `phase` → the ground pick; `posture_flag` → the sit↔stand. Only the first is loadable as a one-shot (§9.3) |
| `command.encoding` says what the daemon feeds it | Constant → a skill; `phase` → a skill the daemon clocks (`policy add`), or the ground pick of a set; `posture_flag` → the sit↔stand (§9.3) |
| The set carries its own timing | The pick's cycle and cutoff, the rise and the seat's settle are properties of the trained network, not literals in a build; `[policy]` keys still win (§9.3) |
| Skills leave walk, stand, sitstand and ground_pick alone | The fallback pair, one driven internally, one phase-driven — none is a generic one-shot (§10.2) |
| Buttons are config; Start and Select are not | The button that stops a robot is the one worth not being able to lose (§10.3) |
Expand Down
9 changes: 4 additions & 5 deletions docs/design/remote-access-design.md
Original file line number Diff line number Diff line change
Expand Up @@ -781,11 +781,10 @@ the peer connection, and a Gradio callback runs in whichever worker thread the r
**Two refusals, and which side owns them is most of what writing this settled.** `policy.fetch`
checks the claims that are about the robot — `obs_len`, `action_len`, `model_api`, `robot.model` —
and it checks them *before* the download, so a client should not repeat them and should show what
the robot said. `robot.setSkill` checks nothing about the command encoding: a phase policy
installed as a one-shot is **accepted**, and the robot then feeds a constant to a network trained
on a phase, which is plausible movement and wrong movement. That rule lives in `robotctl`, and
`robotctl` is not in the path of a click — so `catalogue.refusal` is the same rule written a second
time, and any client that grows this button needs it a third.
the robot said. `robot.setSkill` now clocks a phase skill the same way `policy add` does; a
posture-flag policy is still refused. A client that does not send `encoding` / `period_s` still
gets a constant, which is why the playground's `catalogue.refusal` keeps its own copy of the rule
for anything this daemon cannot drive, and any client that grows this button needs that too.

**A `401` from the rendezvous is the token and nothing else, and proving that took reading their
`app.py` after guessing wrong.** The first version of this page listed robots with `GET
Expand Down
24 changes: 14 additions & 10 deletions docs/policy-manifest.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,15 @@ contract.
| `encoding` | the twist | who |
| --- | --- | --- |
| absent or `constant` | a fixed twist for the window, `idle` on the way back | every kick, the roulade, every community one-shot so far |
| `phase` | `[cos 2πφ, sin 2πφ, 0]`, φ from 0 over `period_s` s, hands back at `end_phase` | the ground pick; the roller crouch |
| `phase` | `[cos 2πφ, sin 2πφ, 0]`, φ from 0 over `period_s` s; episodic hands back at `end_phase`; perpetual wraps | the ground pick; the roller crouch; a community skill added with `policy add` |
| `posture_flag` | one slot carries `sit` or `stand` | the sit↔stand |

Only a constant-command `episodic` policy can be a generic one-shot. A `phase` or `posture_flag`
policy is refused by `policy add` and belongs in the slot the daemon drives (`policy load
ground_pick …`, `policy load sitstand …`). The daemon guards this on the encoding, not the name.
A constant-command `episodic` policy is a generic one-shot, and so is a `phase` policy: `policy
add` accepts it and the daemon writes the clock. Episodic duration is `period_s × end_phase`.
Perpetual still needs `--hold`, and φ wraps until then. A `posture_flag` policy is refused by
`policy add` and belongs in the slot the daemon drives (`policy load sitstand …`). The official
set's phase entries are still each mode's ground pick (`policy load ground_pick …`). The daemon
guards this on the encoding, not the name.

## Fields

Expand All @@ -50,7 +53,7 @@ a policy only on a claim that is present and wrong.
| `name` | str | skills | what a client asks for; defaults to the file's stem |
| `description` | str | display | one line, untrusted — what `policy search` shows under each hit, and `policy fetch` on the way in |
| `kind` | str | skills, slots | see above |
| `duration_s` | float | skills | seconds it runs; for a phase policy `period_s × end_phase` |
| `duration_s` | float | skills | seconds it runs; for an episodic phase policy `period_s × end_phase` |
| `chain` | bool | skills | a held button starts another run when this one ends |
| `action_scale` | float | skills | its own output scale while it runs |
| `unwind_s` | float | skills, sitstand | seconds driving `command.idle` before handing back; for the sit↔stand, the rise |
Expand All @@ -60,7 +63,7 @@ a policy only on a claim that is present and wrong.
| `entry_pose` | str | display | the pose the policy expects to start from, e.g. `standing` |
| `command.encoding` | str | skills | see above |
| `command.idle` | [3] | skills | the twist that means "stop doing the thing" |
| `command.period_s`, `command.end_phase` | float | ground pick | the phase cycle |
| `command.period_s`, `command.end_phase` | float | skills, ground pick | the phase cycle; a skill needs a positive `period_s`; episodic hands back at `end_phase` |
| `command.sit`, `command.stand`, `command.slot` | | display | the flag's values and where it rides |
| `command.twist`, `command.head`, `command.body` | prose | display | what each block means to a person |
| `training` | object | display | `task_id`, `repo`, `commit`, `branch`, `dirty`, `run`, `checkpoint`, `exported` |
Expand Down Expand Up @@ -97,10 +100,11 @@ and offline rehearsal.

The repo carries exactly one `.onnx`, named `policy.onnx`. `robotctl policy add polite-bow
<user>/microduck-polite-bow` reads `duration_s`, `chain`, `action_scale`, `command.idle` and
`unwind_s`, refuses on `obs_len`, `action_len`, `model_api`, `robot.model` or a non-constant
encoding, and writes the skill. `RemiFabre/microduck-flamingo-cycle` is a published `perpetual`
example: no `duration_s`, so `--hold` is required, and its `command.idle` is what the unwind
drives.
`unwind_s`, refuses on `obs_len`, `action_len`, `model_api`, `robot.model` or a `posture_flag`
encoding, and writes the skill. A phase encoding needs a positive `command.period_s`; episodic
duration is `period_s × end_phase` when the manifest does not declare `duration_s`. Perpetual
still needs `--hold`. `RemiFabre/microduck-flamingo-cycle` is a published `perpetual` example: no
`duration_s`, so `--hold` is required, and its `command.idle` is what the unwind drives.

## The official set

Expand Down
15 changes: 11 additions & 4 deletions docs/robot/cheatsheet.md
Original file line number Diff line number Diff line change
Expand Up @@ -386,6 +386,12 @@ an all-zero command and being selected *is* the trigger. A policy that reads its
something else — flamingo's is `[flag, side, 0]` — needs it spelled out, and its README says
what the slots mean.

A policy whose command is a **phase** (`encoding: phase` in the manifest) is a skill too. The
robot writes `[cos 2πφ, sin 2πφ, 0]` from 0 at `1/period_s`. An episodic one hands back at
`end_phase` (`duration_s = period_s × end_phase`). A perpetual one still needs `--hold`, and φ
wraps until then. `period_s` has to be a positive number of seconds. A posture-flag policy is
still a sit↔stand, not a skill.

`sudo robotctl policy remove <name>` takes one out. A skill this robot's release ships comes back
when you do, since removing the entry only removes the override.

Expand Down Expand Up @@ -533,10 +539,11 @@ all-zero command it was trained against, becomes a skill the robot answers to by
for `robot do` and a button, with nothing else edited. A **`perpetual`** one is a gait and needs
a slot pointed at it instead.

A policy the daemon has to *drive* — writing a phase over time, or flipping a posture flag —
declares that under `command.encoding`, and its numbers become that arm's timing rather than a
new skill. The ground pick and the sit↔stand are the two, and getting one of those entries wrong
is the one mistake here worth being careful about.
A policy the official set drives itself — the ground pick's phase, the sit↔stand's posture flag
— declares that under `command.encoding`, and those entries' numbers become that arm's timing
rather than a new skill. A community phase policy is the other path: `policy add` installs it as
a skill and the daemon clocks it. A posture-flag policy is still only the sit↔stand. Getting a
set's ground-pick or sit↔stand entry wrong is the one mistake here worth being careful about.

The manifest in full, every field, and what each one changes on the robot:
[`../policy-manifest.md`](../policy-manifest.md).
Expand Down
68 changes: 64 additions & 4 deletions duck-ipc-proto/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -674,7 +674,17 @@ pub const JSONRPC_VERSION: &str = "2.0";
/// display the tag's sequence ends with. No params; [`IntentResult`] once it has started, so a
/// client watches [`method::PHOTO_LIST`] for the picture. Answered by `nfcd`; an older one answers
/// METHOD_NOT_FOUND, by name, which is how a client tells a robot that cannot.
pub const API_VERSION: u32 = 68;
///
/// # v69 — a phase-encoded skill
///
/// [`SkillParams`] gains `encoding`, `period_s` and `end_phase`, so a policy whose command is a
/// phase can be a one-shot: the daemon writes `[cos 2πφ, sin 2πφ, 0]` the way the ground pick
/// already does. **It bumps because [`SkillParams`] denies unknown fields.** A v68 `robotd`
/// would accept the call only by ignoring those members, and then run a phase policy on a
/// constant command — a robot moving plausibly and wrongly. Refusing the unknown members is
/// what this bump makes an older daemon do; a board has to be on this release before
/// `robotctl policy add` can install a phase skill.
pub const API_VERSION: u32 = 69;

/// The observation width every policy this robot family runs is built against.
///
Expand Down Expand Up @@ -3869,10 +3879,14 @@ pub struct PolicyFetchResult {
/// The manifest's `command.idle` — the twist that means "stop", and what a skill unwinds to.
pub idle: Option<[f64; 3]>,
/// The manifest's `command.encoding`: absent or `"constant"` for the skill family, `"phase"`
/// for a ground pick, `"posture_flag"` for a sit↔stand. What decides whether the policy can
/// be a generic one-shot at all — a phase policy fed a constant is a robot moving plausibly
/// and wrongly.
/// for a clocked skill (and for a ground pick in that slot), `"posture_flag"` for a
/// sit↔stand. A phase skill is one `policy add` can install; a posture-flag policy is not.
pub encoding: Option<String>,
/// Phase encoding: seconds per cycle. Present when `encoding` is `"phase"`.
pub period_s: Option<f64>,
/// Phase encoding: the fraction of the cycle at which an episodic skill hands back.
/// Absent on a perpetual one, which wraps instead.
pub end_phase: Option<f64>,
/// Whether holding the button chains another run, from the manifest.
pub chain: bool,
/// The manifest's `schema_version`, so a client can say which convention it read.
Expand Down Expand Up @@ -6086,6 +6100,17 @@ pub struct SkillParams {
/// Servo gain relative to the gait's, when this skill wants its own.
#[serde(skip_serializing_if = "Option::is_none")]
pub gain_ratio: Option<f64>,
/// How the daemon feeds this skill its command: absent or `"constant"` is a fixed twist;
/// `"phase"` is `[cos 2πφ, sin 2πφ, 0]` with φ from 0 at `1/period_s`.
#[serde(skip_serializing_if = "Option::is_none")]
pub encoding: Option<String>,
/// Seconds per phase cycle, when `encoding` is `"phase"`.
#[serde(skip_serializing_if = "Option::is_none")]
pub period_s: Option<f64>,
/// Fraction of the cycle at which an episodic phase skill hands back. Absent on a
/// perpetual one, which wraps instead.
#[serde(skip_serializing_if = "Option::is_none")]
pub end_phase: Option<f64>,
/// Read-only: whether config has an opinion about this skill, or it is one the release ships.
/// Ignored on the way in — a client cannot make a built-in an override by saying so.
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
Expand Down Expand Up @@ -7763,6 +7788,41 @@ mod tests {
assert_eq!(back.as_call().unwrap(), call);
}

/// A phase skill's new members survive the wire, and a payload from before them still
/// parses. The other direction — an older daemon refusing members it does not know — is
/// [`an_unknown_params_member_is_refused_by_name`]: [`SkillParams`] denies unknown fields,
/// which is why [`API_VERSION`] moved. Without that, a v68 `robotd` would run a phase
/// policy on a constant command.
#[test]
fn a_phase_skill_round_trips_and_an_older_payload_still_parses() {
let params = SkillParams {
name: "dance".into(),
duration: Some(2.8),
encoding: Some("phase".into()),
period_s: Some(4.0),
end_phase: Some(0.7),
..Default::default()
};
let call = Call::RobotSetSkill(params.clone());
let line = serde_json::to_string(&Request::call(Id::Number(1), &call)).unwrap();
assert!(
line.contains(r#""encoding":"phase""#) && line.contains(r#""period_s":4.0"#),
"{line}"
);
let back: Request = serde_json::from_str(&line).unwrap();
assert_eq!(back.as_call().unwrap(), call);

let old: SkillParams = serde_json::from_str(r#"{"name":"bow","duration":4.0}"#).unwrap();
assert_eq!(old.encoding, None);
assert_eq!(old.period_s, None);
assert_eq!(old.end_phase, None);
let written = serde_json::to_string(&old).unwrap();
assert!(
!written.contains("encoding") && !written.contains("period_s"),
"a constant skill must not mention a clock it does not use: {written}"
);
}

/// An unknown method and unparseable parameters are different failures, and a client
/// acts on them differently.
#[test]
Expand Down
Loading