<!-- Robots · Tin · https://tin.ad/docs/learn/robots/ · generated from the built page -->

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

# Robots

**Goal.** Declare a robot from the registry, move its joints by name, and read where they are.

A robot program is a loop: look at the joints, decide where they should go, send the targets. Most bugs are
in the names and the numbers: a joint spelled wrong, degrees where radians were meant. In Tin both are caught
before the program runs.

## Declare a robot

`robot Arm = so101` takes a robot from the registry: its joints, their ranges and their speed
limits, read from the robot's published description. `Arm()` opens one in the built-in world, a
deterministic simulator that runs everywhere Tin runs. A `Pose` names joint targets; joints it
leaves out hold where they are:

*arm.tin · tin run arm.tin*

```tin
robot Arm = so101

fn main() {
  var arm = Arm()
  print(arm.jointNames())
  arm.act(Pose { shoulder_pan: 0.5rad })
  print(arm.observe().at("shoulder_pan").rad().fixed(3))
  arm.reach(Pose { shoulder_pan: 0.5rad, elbow_flex: 30deg }, 1s)
  let o = arm.observe()
  print("t={o.t} elbow={o.at("elbow_flex").deg().fixed(1)}deg")
}
```

<!-- output -->
```text
["shoulder_pan", "shoulder_lift", "elbow_flex", "wrist_flex", "wrist_roll", "gripper"]
0.080
t=1.02s elbow=29.1deg
```

`act` writes the targets and lets one 20 ms control period pass; the joint gets 0.08 rad of the
way, because the SO-101's joints turn at most 4 rad/s. `reach` ramps there in a straight line over the
time you give, and `observe` says where every joint is and when.

## Joint names are checked

The compiler knows the arm's joints, so a typo is an error with the list and the fix:

*typo.tin · tin check typo.tin*

```tin
robot Arm = so101

fn main() {
  var arm = Arm()
  arm.act(Pose { sholder_pan: 0.5rad })
}
```

<!-- compiler output -->
```text
error: Arm (so101) has no joint 'sholder_pan'
 --> typo.tin:5:18
  |
5 |   arm.act(Pose { sholder_pan: 0.5rad })
  |                  ^^^^^^^^^^^
  = note: Arm joints: shoulder_pan, shoulder_lift, elbow_flex, wrist_flex, wrist_roll, gripper
  = fix: use shoulder_pan
```

## Angles are units

Like durations, angles carry their unit: `0.5rad`, `30deg`. A bare number does not
compile, so nobody has to guess what `0.5` meant:

*bare.tin · tin check bare.tin*

```tin
robot Arm = so101

fn main() {
  var arm = Arm()
  arm.act(Pose { gripper: 0.5 })
}
```

<!-- compiler output -->
```text
error: expected Angle, found float
 --> bare.tin:5:27
  |
5 |   arm.act(Pose { gripper: 0.5 })
  |                           ^^^
  = note: an Angle needs a unit: write 0.5rad or 30deg, or `n * 1rad` for a number in a variable
  = fix: add a unit: rad
```

## A robot that moves is a var

Every value in Tin is a copy. Moving the arm changes it, so it is declared with `var`; a function
that moves an arm you pass takes it `inout`, the same rule as for any value you change in place.

## Real physics in one word

The built-in world is a servo model, not physics. Give the robot a world and the same program runs in MuJoCo,
with gravity, contacts and the arm's own motors; the playground draws it as it moves:

```tin
robot Arm = so101 { world: mujoco }

fn wave(o: Observation): Option<Pose> => Some(Pose { shoulder_pan: 0.5rad * sin(o.t / 1s * 2.0), elbow_flex: -0.6rad })

fn main() {
  var arm = Arm()
  let r = arm.run(policy(wave), 4s, 50Hz)
  print("{r.steps} steps, elbow at {arm.observe().at("elbow_flex")}")
}
```

Nothing else changed: the names, the units and the safety gate are the same, and the run repeats to the last
digit under `tin run`, in the browser and as a native executable. The first run downloads MuJoCo and
the arm's model files, checked by hash. [Open it in the playground](https://tin.ad/docs/play/#ex=mujoco/wave),
or read [Worlds](https://tin.ad/docs/ref/robot/#worlds) for the other robots and `world: py`.

## A learned policy

Walking is not something you write by hand. A policy trained in simulation is a file of weights, and
`onnx(...)` runs one in the same loop, behind the same gate. This one is holosoma, a humanoid controller,
asked to walk forward at half a metre per second:

```tin
robot Body = g1 { world: mujoco }

fn main() {
  var g1 = Body()
  let start = g1.base().unwrap()
  let r = g1.run(onnx("holosoma?vx=0.5"), 8s, 50Hz)
  print("{r.steps} ticks, {g1.base().unwrap().x - start.x} m forward")
}
```

The compiler knows what the preset needs. It was trained on the G1, so it is a compile error on an arm. It reads
the body's tilt and spin, which only a physics world has, so it is also a compile error in the built-in world. The
weights are not part of Tin: the first run downloads them from their publisher at a pinned version and refuses
them unless they hash to the pinned SHA-256. [Watch it walk in the
playground](https://tin.ad/docs/play/#ex=policies/walk), or read [Learned policies](https://tin.ad/docs/ref/robot/#learned) for `hub(...)` and
`remote(...)`.

## Tasks

### Task 1: Reach and settle

Move the shoulder lift to 20&deg; and the elbow to 45&deg; over two seconds, wait half a second for the
joints to settle, then print the time and both angles in degrees with one decimal.

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.reach(Pose { shoulder_lift: 20deg, elbow_flex: 45deg }, 2s)
  arm.wait(500ms)
  let o = arm.observe()
  print("{o.t}: lift {o.at("shoulder_lift").deg().fixed(1)}deg, elbow {o.at("elbow_flex").deg().fixed(1)}deg")
}
```

<!-- output -->
```text
2.5s: lift 20.0deg, elbow 45.0deg
```

## Recap

- `robot Arm = so101` gives a type and a constructor; joint names are checked when you compile.
- Angles are units: `0.5rad`, `30deg`; a bare number does not compile.
- A robot that moves is a `var`: moving it changes it.

In the reference: [Robots](https://tin.ad/docs/ref/robot/) · [The registry](https://tin.ad/docs/ref/robot/#registry) · [Worlds](https://tin.ad/docs/ref/robot/#worlds) · [Learned policies](https://tin.ad/docs/ref/robot/#learned)
