Tin

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.tintin run gate.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)
}
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.tintin run drive.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}")
}
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.tintin check reply.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 })
}
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° while the shoulder lift is already above 45°. Run a policy that holds the lift at 60° and raises the elbow by 1 rad per second, and print how many steps ran and why the run stopped.

Checking needs JavaScript; the solution below works without it.

Solution
task-1.solution.tintin run task-1.solution.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}")
}
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 · arm.drive · Capabilities