<!-- Safety and agents · Tin · https://tin.ad/docs/learn/robot-safety/ · generated from the built page -->

[Learn](https://tin.ad/docs/learn/) · Robots · 34 of 34

# Safety and agents

**Goal.** Bound what a robot may do, and let an agent drive it without being able to slip past the bounds.

A bug in a web page shows a wrong number. A bug in a robot program moves something heavy. So every write to
a robot, from `act`, from each step of `reach` and from every tick of a run, passes one
gate, and there is no other way to send a target.

## The gate

In order: an emergency stop refuses everything; an unknown joint or a target that is not a finite angle is
refused; a target outside the joint's range or the safe bounds you set with `arm.safe` is clipped;
then every check you added with `arm.validate` may refuse it. A refused pose changes nothing, and a
run it happens in ends with a fault, every joint holding where it is:

*gate.tin · tin run gate.tin*

```tin
robot Arm = so101

fn main() {
  var arm = Arm()
  arm.safe("elbow_flex", -30deg, 30deg)
  arm.validate((p, o) => if p.get("gripper").or(0rad) > 1rad { Some("the gripper opens at most 1rad") } else { None })

  // a validator's refusal ends a run with a fault, and the arm holds where it is
  let r = arm.run(policy(o => Some(Pose { gripper: o.t / 1s * 2rad })), 2s, 10Hz)
  print("{r.steps} steps, stopped by {r.stoppedBy}")

  // the program's own targets are clipped to the bounds
  arm.reach(Pose { elbow_flex: 80deg }, 500ms)
  print(arm.target().get("elbow_flex").or(0rad).deg().fixed(1))

  arm.estop()
  print(arm.run(policy(o => Some(Pose { gripper: 0rad })), 1s, 10Hz).stoppedBy)
}
```

<!-- output -->
```text
6 steps, stopped by fault: the gripper opens at most 1rad
30.0
estop
```

## An agent at the controls

`arm.drive(agent, goal, turns)` lets a model move the arm. Each turn the agent sees every joint, its
bounds and its speed limit, and answers with targets. Its targets are refused, never clipped: outside a range or
a bound, faster than a joint may turn, or turned down by a validator, the move stops and the agent is told why.
Nothing moves until a person approves the drive, once; without an approver it is denied:

*drive.tin · tin run drive.tin*

```tin
robot Arm = so101

agent Driver {
  model: "mock"
  system: "You move a robot arm. Keep every joint inside its bounds."
}

fn main() {
  var arm = Arm()
  arm.safe("shoulder_pan", -0.5rad, 0.5rad)
  let d = arm.drive(Driver, "point at the door", 5)
  print("approved: {d.approved}, moved {d.moved}, refused {d.refused}")
}
```

<!-- output -->
```text
approved: false, moved 0, refused 0
```

Run it with `tin run drive.tin --yes` to approve. `tin caps` lists the robot, its joints and
`robot.move` on everything that can move it.

## A reply cannot move the arm on its own

A model's answer is untrusted, as in every other Tin program. If a value computed from a reply reaches
`act`, `reach` or `run`, the program does not compile, because there the gate would
clip a bad target instead of refusing it and nobody approved the motion:

*reply.tin · tin check reply.tin*

```tin
robot Arm = so101

type Where = { pan: float }
agent Pointer { model: "mock" }

fn main() {
  var arm = Arm()
  let w: Where = Pointer.ask("where is the door?")
  arm.act(Pose { shoulder_pan: w.pan * 1rad })
}
```

<!-- compiler output -->
```text
error: in main: a value from a model's reply moves a robot outside arm.drive
 --> reply.tin:6:1
  |
6 | fn main() {
  | ^^^^^^^
  = note: main gets text from agent.ask / agent.try and builds a pose or policy from it for Robot.act (through Robot.act): there the gate clips a bad target to the range instead of refusing it, and no operator approved the motion
  = note: let the agent drive: `arm.drive(Agent, goal, turns)` refuses anything outside the ranges, safe bounds or speed limits and asks the operator once
  = note: or match the reply against cases and move to poses the program writes itself
```

Choosing between poses your program wrote itself, based on a reply, is fine.

## Tasks

### Task 1: A validator of your own

Add a validator that refuses any pose sending the elbow above 45&deg; while the shoulder lift is already
above 45&deg;. Run a policy that holds the lift at 60&deg; and raises the elbow by 1 rad per second, and print
how many steps ran and why the run stopped.

Your answer   Checking needs JavaScript; the solution below works without it.

**Solution

*task-1.solution.tin · tin run task-1.solution.tin*

```tin
robot Arm = so101

fn main() {
  var arm = Arm()
  arm.validate((p, o) => if o.at("shoulder_lift") > 45deg && p.get("elbow_flex").or(0rad) > 45deg { Some("lift and elbow both above 45deg") } else { None })
  let r = arm.run(policy(o => Some(Pose { shoulder_lift: 60deg, elbow_flex: o.t / 1s * 1rad })), 3s, 20Hz)
  print("{r.steps} steps, stopped by {r.stoppedBy}")
}
```

<!-- output -->
```text
16 steps, stopped by fault: lift and elbow both above 45deg
```

## Recap

- Every write passes one gate: estop, range, safe bounds, speed, validators.
- The program's own targets are clipped; an agent's are refused.
- A model's reply reaches a robot only through `arm.drive`, which the operator approves once.

In the reference: [The safety gate](https://tin.ad/docs/ref/robot/#gate) · [arm.drive](https://tin.ad/docs/ref/robot/#drive) · [Capabilities](https://tin.ad/docs/ref/robot/#caps)
