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:
tin run gate.tinrobot 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:
tin run drive.tinrobot 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:
tin check reply.tinrobot 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.
Solution
tin run task-1.solution.tinrobot 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