Build ~4 min read

at the endYou can name every part of the system and say what each one is allowed to do.

How to think about it¶

strands-arm is a camera on a robot arm you already own. This page gives you the eight ideas the rest of the docs assume, in order.

Why this page exists: the other pages use words like leader, yoke, guard and home without stopping. Read it once and none will surprise you.

Two arms, one idle¶

An SO-101 kit ships two identical arms. The follower does the work: it holds the gripper, runs the policy, appears in the papers. The leader is the input device: you hold it, the follower copies it. That is teleoperation, and it is the only job the leader has.

Teleop ends when the dataset is recorded. From then on the follower runs alone and the leader sits in the box, six servos and a bus cable doing nothing. strands-arm gives that arm a second job: filming the follower.

The head¶

Take the leader's handle off and two servos come free at the end of the arm. strands-arm bolts a camera onto them with three printed parts:

part	what it is	sits on
yoke	a fork that holds servo 6 sideways in a 22 mm bore	horn of servo 5
body	an 11.85 mm deep cradle for the Nicla Vision board	horn of servo 6
lid	a snap-on rim with one keyhole for the lens and the ToF	the body

Together: 15.4 g of PLA, 88 minutes on the printer, ten screws, all of them into servo metal. The parts are drawn in The head, printed in Print it, fitted in How it goes together.

Pan is servo 5, tilt is servo 6¶

The SO-101 numbers its servos 1 to 6 from the base. Joints 1 to 4 are the arm proper: shoulder pan, shoulder lift, elbow, wrist. Servo 5 was wrist roll; with the head on it turns the whole yoke, so it is pan. Servo 6 was the gripper trigger; it sits inside the yoke and nods the body, so it is tilt.

Every command, log line and dashboard label uses these numbers. When a page says "servo 6 clamped", it means the tilt servo.

The Nicla Vision¶

The camera is an Arduino Nicla Vision, a 22.86 mm square board with a 2 MP camera, ToF, IMU, Wi-Fi, BLE and a microphone on an STM32H7. Its firmware serves what it sees over Wi-Fi: a video stream, face and person detections, distance, orientation. The arm's software talks to it over the LAN and falls back to USB only when the LAN is silent. Details in Firmware.

The folded home¶

Every session starts and ends in one pose: the arm folded back over its base, forearm on top, head hanging down and looking forward. That is home. It is the pose the arm rests in with torque off, so nothing falls when power goes.

Home is stored, not assumed. The servo readings for it live in ~/.strands-arm/calib.json with one zero and one sign per servo, and every consumer of joint angles reads that file: the kinematics, the guard, autocal and the dashboard's 3D mirror. How it gets there is Calibrate.

The guard¶

Nothing writes to a servo except through one module, strands_arm/guard.py. It refuses more than it allows:

joints 1 to 4 move in steps of at most 10° at 30°/s, inside the hand-measured range, never unattended
pan and tilt stay inside the head window, ±160° / ±80° from the calibrated zero
no goal may leave a servo's saved angle window or cross the 0/360 wrap
under 6.5 V on the bus the arm may fold and hold, never rise
torque drops 2 s after the last command, and the arm is only ever released in the folded pose: stop on an upright arm holds, release folds first
every accepted and refused goal is appended to ~/.strands-arm/motion.log

Each rule was learned from something that went wrong; the list with its incidents is The guard.

Reading the arm is free. Moving it needs one of three things: --i-know on the command, STRANDS_ARM_I_KNOW=1 in the environment, or {"ok": true} in ~/.strands-arm/bench.json. The file is the "the bench is clear" switch; if it is missing or malformed the answer is no. strands-arm doctor shows which state you are in.

What the agent does with it¶

With the head on and the guard in place, the arm is a tool an agent can call. shot orbit and shot dolly are camera moves. watch face and watch person keep a detection centred and re-base the arm when the head runs out of travel. teach and replay record and play back a hand-moved path. record --lerobot writes what the camera saw as a dataset, serve --mcp exposes all of it to any MCP client. The verbs are in Talk to it; the same tools sit behind the Dashboard's chat.

Words you will meet¶

Hover any acronym on this site for a one-line definition: ToF, IMU, EEPROM, URDF, FOMO, MCP, MJPEG, SSE and the rest. The list lives in one file, docs/_glossary.md, and is appended to every page.

Next: Why the leader if you want the argument, The head if you want to build.