Skip to content

safety.md

Latest commit

 

History

History
52 lines (47 loc) · 2.79 KB

safety.md

File metadata and controls

52 lines (47 loc) · 2.79 KB
Raw

The safety model

A biped with no encoders, torque enough to hurt itself, and a battery that sags under load. The rules, compactly — each exists because something real went wrong without it.

Core rules

  • release_all is not a panic button. It makes a standing biped go limp, i.e. fall. It requires i_know_he_will_fall=True. Stop motion and hold torque instead; shutting the service down also leaves servos holding.
  • Positions outside a joint's travel are refused, not clamped (unless clamp=True). -1 is the "leave this servo alone" frame sentinel, never an angle.
  • Pose is a belief, not a measurement. No encoders exist. The belief is invalidated on every disconnect; playback homes before any interpolated move, because interpolating from a stale start produces fast unexpected motion.
  • The first move after power-on goes to Calibrate (all servos 90°), not STAND. A servo has no speed state until its position has been set once, so the first move is always full rate — it must be a short one. Re-homes from a trusted pose ramp 1°/step.
  • After any physical reassembly, re-confirm the joint map with scripts/confirm_servos.py --i-am-watching before motion — horns re-seat at wrong rotations, cables swap.
  • Battery floors account for sag (a resting reading does not): 7.60 V to start any motion, 7.90 V for multi-servo gaits. Calibrate them to your pack with scripts/diagnose_servo_power.py.
  • Abort policy is per action. Gestures halt immediately; gaits play on to the next stable frame, bounded by one gait cycle — halting midway through a headstand is worse than finishing it.
  • dry_run is enforced at connection open, so no code path can reach hardware during a dry run. No command is accepted before a completed handshake.

Humans and agents

  • Presence is not self-assertable. Motion requires a presence timestamp that only POST /api/presence refreshes (the GUI does, while its tab is visible). It is deliberately not a parameter on any motion endpoint; a caller that could vouch for itself would make the check theatre.
  • Escape means stop-and-hold, never release. Release hides behind a disclosure and a confirm: true.
  • Agents get guardrails, not approval gates: risk tiers (--agent-tiers; floor acrobatics are opt-in), per-agent rate limits, loop caps, battery floors, one motion at a time. Asserting presence, going limp, and driving raw joints are never an agent's — those endpoints refuse agent identities outright, and everything an agent does is audited with its identity.
  • Bind loopback. The robot itself has no authentication on any port, so Commander refuses to bind beyond loopback without a token, and the MCP server binds loopback or a Tailscale address only — never 0.0.0.0.