A cell is one physical robot installation: the arms, the buses they hang on,
the cameras, the table, and the computer beside them. A benchmark fixes the
scene, the task and the verdict; a cell fixes none of them. Someone owns it,
brings it up, types instructions to the agent one after another in free play,
judges the outcome themselves (official_success is null) and must be able to
stop and recover the arms at any moment. This page is for that person.
ORA's real-cell kit (ora/cell/, README) is the
part every cell needs whatever the robot: the cell config, the calibration, one
holder of the cell at a time, bus and camera checks, camera calibration, the
depth service, the cell board, and the operator's verbs. A robot family plugs
into it with a CellAdapter. Today one family has one: the bimanual I2RT YAM
station (environment yam, model yam_station_linear_4310_d405,
backend README). It also has a
simulated cell, which runs the whole kit with no hardware
(below).
Everything below is one command, ora cell, run on the cell's computer.
Two files
| File | Who writes it | Schema | Where |
|---|---|---|---|
| Cell config | you, by hand, once per installation | ora.cell-config.v1 |
--cell PATH, else $ORA_CELL, else ~/.config/ora/cell.yaml |
| Cell calibration | the ora cell tools only |
ora.cell-calibration.v1 |
the config's calibration path |
The config says what the cell is: which robot, which bus each arm is on, which
camera device plays which role, and the limits you want. The calibration holds
what the tools measured: fixed-camera extrinsics, the table, gripper limits and
the rest pose, and where the installation departs from the robot model: each
arm's base pose (arm_base_corrections, a correction in the cell's world),
each joint's encoder zero error (joint_zero_offsets, model angle = reading +
offset) and each wrist camera's mount (wrist_camera_corrections). Every tool
and the worker apply these to the robot model, so planning, clearance checks
and camera poses use the measured robot; joint readings, the rest pose and the
robot's own encoder zeros stay as the motors report them. ora cell calibrate --method hand-eye measures all of them at once (below)
and keeps its fit's report in bundle_fit. A measured value never goes into the config, and a secret never
goes into either (model keys stay in ora providers). A calibration file from
the earlier YAM tools (ora.yam-cell-calibration.v1) still loads; its camera
serials are ignored, since they now live in the config.
Write the cell config
ora cell init --example PATH writes an example to fill in. A complete config,
with what each field does:
schema: ora.cell-config.v1 # required, exactly this
cell_id: my-cell-01 # required: names the cell on the board and to `ora cell`
robot:
environment: yam # required: the robot family's backend (ora/environment/backends/yam)
model: yam_station_linear_4310_d405 # required: the robot model (geometry, policy composition)
python: ~/envs/yam/bin/python # optional: the interpreter with the robot's drivers (i2rt,
# pyrealsense2, python-can); `ora cell` re-runs itself there
buses: {left: can_left, right: can_right} # required: arm -> bus interface, exactly the robot's arms
cameras: # role -> device; roles are the robot model's public cameras
overhead: {serial: "123456789012", mount: fixed_world} # mount: fixed_world or end_effector,
front: {serial: "123456789013", mount: fixed_world} # as the robot model mounts that role
wrist_left: {serial: "123456789014", mount: end_effector}
wrist_right: {serial: "123456789015", mount: end_effector}
calibration: ~/.config/ora/cells/my-cell-01.calibration.json # required: where the tools write
safety:
max_joint_speed_rad_s: 0.6 # optional, a positive number; may only lower the model's limit
operator_present_required: true # default true
foreign_controllers:
ignore: [] # command-line fragments of programs you vouch for: they run
# on this machine but never open the cell's buses
perception:
depth_completion: http://localhost:8770 # the board's depth service (`ora cell depth-service`); null: none
policy:
provider_profile: deepseek_flash_openai_low_16k_v1 # recorded with the cell; `ora cell` does not read it
ora cell init refuses a config that misses a required field, names an unknown
mount or gives a non-positive speed, and one that disagrees with its robot:
buses must name exactly the robot's arms, and every camera role must be one
of the robot model's cameras with the mount the model gives it. Today
max_joint_speed_rad_s and operator_present_required are validated but not
yet applied by any tool; the robot model's own limits hold, and a run on the
real arms needs runtime.operator_present: true in its RunSpec.
From a powered-off cell to a play session
ora cell setup walks a new cell through steps 1 to 6 below in one command:
devices, rest, grippers (limits and which way each opens), fixed_cameras,
handeye, table (the table's height from the calibrated fixed cameras) and
verify (the table each wrist camera sees through its arm is level and at that
height). It does only what is not done yet, asks before each step that moves
anything (on the terminal, or through the approval broker with --ask broker),
and stops at the first step that fails; run it again to go on. --status says
what each step's state is (done, missing, or stale: a gripper whose
reading left its limits after a power cycle, a table measured before the
calibration) and what comes next, without moving anything; --redo STEP repeats
a step. With --json the result is the last line of stdout and stderr carries
one JSON line per event: {"progress": ...} and {"step", "state": "running" | "done" | "failed"}. The checkerboard is asked once and kept in the calibration
(board).
Each step is one command. It refuses with a reason, and leaves the cell as safe
as it found it. Add --cell PATH to any of them, or set ORA_CELL once.
| Step | Command | Arms | Writes |
|---|---|---|---|
| 0 | ora cell init |
not touched | nothing: validates the config against its robot, shows each bus's state and whether each camera is connected |
| 1 | ora cell check |
unpowered or limp | nothing: no other reader or traffic on the buses, every camera free, one frame each with its share of valid depth; running programs that drive arms are listed |
| 2 | ora cell read |
read passively (YAM: DISABLE frames) | nothing: joints, faults, temperatures, tool positions, joints against the model's limits and the rest pose |
| 3 | ora cell record-rest |
read passively; put them at rest first | the rest pose; refused when a joint is outside the model's limits (an encoder zero has moved) |
| 4 | ora cell grippers |
each gripper opens and closes once, its arm held; then you say for each whether it is open or closed | the grippers' [closed, open] limits, the way you saw them (--orient alone checks them again, nothing moving) |
| 5 | ora cell calibrate --method charuco --square-mm N |
read passively | every fixed camera from one ChArUco board on the table, placed through the wrist cameras; N is one black square as shown, measured |
ora cell calibrate --method wrists --role ROLE |
read passively | one fixed camera from what the wrist cameras see of the table, marked provisional | |
ora cell calibrate --method arm-poses |
move together through a few poses near rest, then back to where they started and released | each fixed camera that already has a pose (from charuco or wrists), registered again on the moving arms; the captures stay under ~/.cache/ora/cell-calibration/ |
|
| 6 | ora cell calibrate --method hand-eye |
one at a time, around a checkerboard you place a few times, each motion after you approve it | after you approve the result: the fixed cameras, the wrist cameras' mounts, the arms' bases and their joint zeros, from one fit (Calibrate a new cell) |
| 7 | ora cell board [--port 8765] [--depth-service URL] |
held only when you ask | nothing: the operator's page at http://localhost:8765 (forward the port over ssh from elsewhere) |
| 8 | a free-play run on rig mode read |
never enabled | a play run: every motion is answered with its plan |
| 9 | a free-play run on rig mode on |
enabled and moved after you approve (board, ora cell approve, /approve) |
a play run |
calibrate, setup and grippers stop on SIGINT (Ctrl-C, the board's 中止, a
supervisor's stop) even when a shell started them in the background, which
leaves SIGINT ignored: they take it back at start and, with --json, say so on
stderr ({"interruptible": true}). grippers and calibrate ask for confirmation first (--yes skips it) and take
--no-save to report without writing. The board's page shows the cell's state,
the live view (the camera streams and one point cloud of the cell, with
completed depth when a depth service runs), the calibration checklist and the
verbs below. The depth service takes RGB and raw depth and returns completed
depth; start it where a GPU is:
ora cell depth-service --model auto|promptda|lingbot|inpaint [--port 8770] [--host 0.0.0.0] [--max-side N]
or run python -m ora.cell.depth.service ... under the interpreter that holds
the model. The board keeps the sensor's depth wherever it measured and uses the
model's only in holes near a measurement.
Steps 8 and 9 run the robot's worker with the cell config: the YAM runtime takes
runtime.rig_mode (sim, read, on) and runtime.cell_config (the config
path) in a RunSpec, and its preflight loads the config. A one-line
ora play --env yam entry is not wired yet.
Calibrate a new cell
The robot model says where the arms, their joints and their wrist cameras are on
paper; a real installation differs. The agent sees through the cameras and moves
the arms in one world, so every link between a pixel and a joint angle must
agree: where each fixed camera stands, how each wrist camera sits on its flange,
where each arm's base really is, and where each joint's encoder reads zero. A
wrist camera sees through its whole arm, so these errors show up mixed; only
views from many poses and several board positions, fitted together, tell them
apart. ora cell calibrate --method hand-eye does that.
You need a plain checkerboard, printed or bought, glued flat on something rigid (acrylic, aluminium, foam board) and matte; a ruler, to measure it; and tape or a weight to keep it still. The cell needs its rest pose (step 3), its grippers' limits (step 4) and a rough pose for at least one fixed camera (step 5): the board is located with it before any arm moves.
ora cell calibrate --method hand-eye [--square-mm 20 --pattern 11x8] [--placements 5] [--arms left,right]
It asks, in this order (on the terminal, or through the approval broker when
started without one or with --ask broker):
- The board (
value), unless given: one square's side in millimetres (measure ten squares and divide: a 2 % print scale is a 2 % error in every distance), and the inner corners asCOLSxROWS. - Each placement (
task): lay the board flat where the named arms reach and the fixed cameras see it, at a new position or angle each time. The first placement is for every arm (it ties them into one world); the others go to one arm in turn, so five give each of two arms three. The fixed cameras locate the board, and up to eight wrist views per arm are planned around it, each pose and every segment between poses checked against the table (or the board's plane), the other arm and the arm's own links. - Each motion (
motion): one arm moves at a time, the other at rest; the views are taken, and the arms return to where they started and are released. The operator's home (board,ora cell home,/home) stops it. A board no camera sees, too few safe views, a declined or stopped motion: the placement is asked again with the reason. Decline a placement to end the captures. - The result (
write): the changes in millimetres and degrees, the fit's error per camera, and the held-out error: each placement's wrist views predicted by a fit of all the others, the number that says what the calibration is worth where it was not fitted. It also names what should make you hesitate (a camera that fits badly, a placement predicted poorly, an arm seen in fewer than three placements). Approve, and the old calibration is copied beside itself (<name>.before-handeye-<time>.json) and the new one written; decline, and nothing changes.
On the cell board, the 手眼标定 panel starts the same command (--ask broker): the three board fields are optional (empty ones are asked), 开始
confirms first, and every question then appears in the board's 等你批准
card: 做好了 / 结束拍摄 for a placement, a value box for the board's size, 写入 /
不写入 for the result. The panel shows the progress lines and, at the end,
whether the calibration was written, its backup and what to hesitate about. The
board refuses to start while anything holds the cell (a play run: /quit it
first) or while the board itself holds the arms, and turns its live view off
first, since the calibration needs the cameras. 中止标定 sends the command
SIGINT: during a motion that is the operator's home (the arms stop, go back to
where they started, and the placement is asked again; 结束拍摄 then fits what
was captured), otherwise the calibration ends and nothing is written. A stop
asked before the command has taken SIGINT back (its first second or so) is held
and sent the moment it says it can take it, rather than lost. The play
terminal and ora web have no /calibrate: they exist only while a play run
holds the cell, which the calibration needs.
The fit (ora/cell/bundle.py) takes the first arm's base as the world, fits a
base correction for every other arm, the zero errors of each arm's inner joints
(the first joint's error is the base's turn, the last one's the camera mount's),
each wrist camera's mount and each fixed camera, and one pose per placement, all
against the board's corners in pixels. The cell lock is held from the first
placement to the last capture, so nothing else takes the arms in between; while
you place the board the arms are released at rest and the lock's label says so.
The captures stay under ~/.cache/ora/cell-calibration/handeye-<time>/, one
folder per placement; --records DIR ... fits them again without moving
anything, and --no-save reports without asking to write.
Calibrate again after a camera or an arm is moved, bumped or remounted, and
whenever ora cell read finds the rest pose away from the recorded one.
ora usually runs in the project's environment, which has none of the robot's
drivers. When the config names robot.python, every ora cell command re-runs
itself in that interpreter, with this checkout on PYTHONPATH.
The operator's verbs
The verbs act on the arms whoever holds them, and act now, also while a play
session executes a motion. They are implemented once
(ora/cell/operator/actions.py, and the answers to the worker's questions in
approval.py); the board's buttons, ora cell <verb> and the play terminal's
slash commands call the same functions, and ora web's page runs the play
terminal's own command lines (the web page from your laptop).
| Verb | Board | Shell | Play terminal | Web page (ora web) |
Effect |
|---|---|---|---|---|---|
| home | 回到起始位 | ora cell home |
/home |
Home | the arms go back to the recorded rest pose and only then are released; nothing drops |
| hold | 保持不动 | ora cell hold |
/hold |
Hold | take the arms and hold the measured pose |
| float | 浮动(手扶) | ora cell float |
/float |
Float… | gravity compensation for guiding by hand; confirmed first |
| release | 释放(会软掉) | ora cell release |
/release |
Release… | the arms go limp; confirmed first |
| estop | 紧急失能 | ora cell estop |
/estop |
E-stop… | DISABLE to every motor, whoever holds the cell; confirmed first |
| diagnose | 诊断 | ora cell diagnose |
/diagnose |
Diagnose | who holds the cell, bus states, faults, distance from rest, and what to do |
| stop | ora cell stop |
ask the program holding the cell to home and release | |||
| kill | 结束占用进程 | ora cell kill |
end the program holding the cell; enabled arms fall within the motor timeout; confirmed first | ||
| cameras | 相机复位 | ora cell cameras |
hardware-reset the cell's cameras | ||
| can | CAN 重置 | ora cell can |
re-initialise the bus interfaces (sudo; prints the command when it needs your password) | ||
| approve | 等你批准: 批准 | ora cell approve --id ID [--value V] |
/approve [value] |
the question's card: Approve… | yes to the worker's waiting question (see The robot's questions) |
| decline | 等你批准: 拒绝 | ora cell decline --id ID [--reason TEXT] |
/decline [reason] |
the question's card: Decline… | no to it; a declined motion's reason reaches the agent |
| mode | 动作批准: 每个动作都问 / 小动作自动 / 全部自动 | ora cell mode ask|safe|auto|status |
/mode [ask|safe|auto], Shift+Tab |
the footer's mode menu | which motions wait for a person (see The robot's questions); auto confirmed first |
The page also takes the play terminal's commands typed into its box.
How home gets the arms back:
- The board holds them (after
holdorfloat): it drives them home itself. - A program holds the cell and says it homes on a signal (an ORA worker, a
calibration motion): it is sent SIGUSR1 and drives its own arms home. An ORA
worker keeps holding them at rest and its episode goes on; the motion in
progress reports
operator_home. A program that does not answer within 20 s is ended and the arms are taken over at once, inside the motors' timeout. - Nobody holds them and they are already at rest: nothing moves.
- Otherwise the arms are taken over and driven home in a straight joint path at 0.25 rad/s. A path that meets the table or the other arm, or an arm that does not follow, stops there and holds; float the arms closer to rest by hand and try again.
hold and float keep the arms held, which needs a long-lived holder: the
cell board. ora cell hold|float therefore needs a running board, and while one
runs every ora cell <verb> goes through it (--board-port, else
$ORA_CELL_BOARD_PORT, else 8765). The play terminal's commands run
ora cell <verb> --json; they exist only when the run drives a real cell
(rig mode read or on). With --json, ora cell prints one object,
{"ok": true, "result": ...}, or {"ok": false, "error": ...} with exit 1;
--yes skips the confirmations. Episode-level controls stay in play's own
commands: /reset (a new round, which on a real cell begins at rest), /stop
and /quit (free play).
The robot's questions
A play session's worker runs in its own session with no terminal, so it asks
the person at the cell through the cell's approval broker
(ora/cell/operator/approval.py). On rig mode on it asks:
| Question | When | No answer in | Declined |
|---|---|---|---|
enable (要给两条手臂通电吗?) |
once, after the start-up checks, before i2rt takes the motors | 300 s | the run stops; nothing was enabled |
motion (左臂动作等待批准, 夹爪动作等待批准, …) |
each motion plan, unless auto-approve is on (below) or runtime.auto_approve |
180 s | the motion is refused as operator_declined, with the reason |
release (手臂没能回到起始位) |
at the end, only when the way home is blocked | 60 s, within the close budget | the arms stay held and home is tried again |
Stop here (ora cell stop-motion, approval.request_stop_motion) ends the motion
the worker is executing at its next control tick, where the arms are, and keeps
them held there; the motion reports operator_hold and the agent gets a fresh
observation. A motion the agent is still planning when the stop arrives is
refused at its approval, before anything moves (operator_declined, telling the
agent to read the operator's latest message). It writes stop-motion.json
beside the questions for the program that holds the cell; nothing else changes,
a request older than 10 s is ignored, and ora cell stop-motion --withdraw
takes back one nobody read (the agent answered in words, no motion came). A front end's stop and say sends it, then the message: the agent
reads the message with the new observation. home is different: it drives
the arms back to rest.
Each motion's receipt keeps when its question was asked and answered and by
whom (timestamps.approval: request_id, created_unix_s, answered_unix_s,
by, approved; also for an auto-approved or stopped motion). The context
projection drops timestamps, so the agent does not read it; a free-play
session announces the wait as approval_wait_s with each action_finished.
The cell's permission mode decides which motions wait for a person (ora cell mode ask|safe|auto|status, approval.mode_state / switch_mode): ask, the
default, asks every motion; safe lets a motion plan answer itself when it
lasts at most 10 s, moves no joint more than 0.6 rad and stays at least 3 cm
above the table and 15 cm from the other arm (a plan that does not state one of
these is asked); auto lets every motion of the worker that drives the arms
now answer itself (the auto-approve switch: ora play --auto-approve, ora cell auto-approve on). ask and safe belong to the cell (mode.json beside the
questions): they can be chosen before a worker starts and they stay across runs.
auto belongs to one worker and falls back to the cell's mode when it ends.
Enabling the arms and releasing them are asked in every mode, and every
self-answered motion is recorded as an answer (by: "safe mode (...)").
Every front end shows the mode and switches it; only auto is confirmed first.
The play terminal's footer starts with it (▸▸ ask · every motion asked,
safe · small motions run, auto · every motion runs, the last in bold red),
read from the broker's files at most once a second; /mode says it in full,
/mode ask|safe|auto sets it (ora cell mode … --by "play terminal") and
Shift+Tab cycles ask → safe → auto → ask (auto only on rig mode on).
ora web's footer shows the same words and opens a menu on a click, with
safe's limits; typed /mode … works as in the terminal. The board's 动作批准
panel is a three-way selector (每个动作都问 / 小动作自动 / 全部自动) that says who
set the mode and safe's limits. Each front end also shows the motions that
answered themselves, with the numbers safe mode checked (Ran without asking:
左臂动作 · safe mode (2.5 s, 0.30 rad, 8 cm above the table, 40 cm between the
arms)): the terminal as a notice, the page in its cell bar, the board under its
selector.
No answer in time counts as a decline. A guided setup step
(ora cell calibrate --method hand-eye) asks three more kinds: task (do
something by hand, such as placing the board, then approve; decline to stop),
value (approve with a value: ora cell approve --id ID --value 20, the
board's JSON {"value": "20"}; its details may name a unit and an
example) and write (save what was measured). Only a value question takes a
value, and its approval needs one. Each question says in plain words what
will happen (which arms, how long, how close to the table and to each other;
the plan itself is attached), and the board shows it as a card at the top
(等你批准, with 批准 and 拒绝 and an optional reason; a task card says 做好了
and 结束拍摄, a write card 写入 and 不写入, and a value card has a box for
the value). The shell answers
with ora cell pending, then ora cell approve --id ID or ora cell decline --id ID --reason TEXT; without --id, on a terminal, the one waiting question
is shown and answered after a yes. The play terminal's /approve and
/decline [reason] show the question with its id and send the answer after a
y; a value question is approved with /approve <value> (its unit and
example are named), and /approve without one, or a value for any other
question, is refused before anything is sent; during an on run it also says … 输入 /approve 或 /decline as soon as a
question appears. ora web's page shows each waiting question as a card above
its input box, with the same words, the id, the seconds left and a reason field
(a value field for a value question; Done… and End captures… for a
task, Save… and Don't save… for a write), and answers that id after a
confirmation; typed /approve <value> works as in the terminal. These answers touch only the broker's
files: never the cell lock, the board or the hardware.
An answer names the question's id, and an id that is not waiting (answered,
expired, or asked by a worker that has ended) is refused: nobody approves a plan
they did not see. A home sent while a motion waits for approval voids it,
since the plan starts where the arms were; the motion is declined with that
reason.
Closing an episode drives the arms home (the recorded rest pose, else the start
pose) and releases them there without a question: at rest nothing drops. The
episode's home is the operator tools' drive (ora/cell/homing.py): the
straight joint path is checked against the table and the other arm before
anything moves. If the way home is blocked (that check, or an arm that does not
follow), the arms hold where they are and release is asked:
approve to release them in place (support them first); decline, or leave it
unanswered, and they stay held while home is tried again, up to three times
within the worker's close budget (runtime.close_timeout_s, default 120 s,
less 15 s). At that bound the arms are released in place anyway, and the last
question says so: the worker is ending, and without its control loop the
motors let go after their timeout regardless. To keep them held past it, use
the board's 回到起始位 (ora cell home, /home): the board takes the arms over
and holds them for as long as needed.
Auto-approve
Approving every motion is unworkable for an operator working alone at the cell,
so the broker has an auto-approve switch (YOLO), for motion questions only.
Enabling the arms (where they start holding) and releasing them in place (where
they go limp) are always asked.
./scripts/ora play --env yam --rig-mode on --operator-present --auto-approve ... # on from the start
./scripts/ora cell auto-approve on # on for the worker driving the arms now
./scripts/ora cell auto-approve off
./scripts/ora cell auto-approve # status
In the play terminal, the same commands are /yolo on (asks y/N once), /yolo off
and /yolo; the switch is the permission mode auto, so /mode auto, the
board's 全部自动 and the page's footer menu turn it on too, and /mode ask or
/mode safe turn it off. While the switch is on, a motion question answers itself at once.
It still writes the normal answer file, with by: "auto-approve (<who turned it on>)" and the question's kind and title, so the record lists every motion
and shows that nobody looked at it. RealRig receives the same (approved)
outcome as for a person's approval, so the agent's receipt and the trace do not
change. A home sent while a plan is pending still voids it.
The switch is auto-approve.json in the broker's folder
(ora.cell-auto-approve.v1: kinds (only motion), by, since_unix_s,
pid, run). It answers only the questions of the one process named by pid,
so these rules apply:
- A real worker's start clears it, then sets it for itself only when its run was
started with
--auto-approve(runtime.auto_approve_motions). A switch never carries into another run. ora cell auto-approve onnames the worker that holds the cell lock in rig modeon, and is refused when there is none. Itsrunis that lock label.- A switch whose worker has ended is stale: it answers nothing, and the state reports it as off, with the reason.
ora cell auto-approve reads and writes only this file. It takes no lock and
starts no board.
runtime.auto_approve (RealRig's own flag, set only in a hand-written RunSpec)
is broader: the worker asks nothing at all, not even before enabling the arms or
releasing them at the end. ora play never sets it.
The broker's folder is $ORA_CELL_APPROVALS, else ora-cell-approvals beside
the cell lock (/tmp/ora-cell-approvals by default); the worker receives both
variables. Each question is <id>.request.json (ora.cell-approval-request.v1:
id, kind, title, text, details, created_unix_s, expires_unix_s,
timeout_s, the asker's pid and label) and each answer <id>.answer.json
(ora.cell-approval-answer.v1: id, approved, reason, by,
answered_unix_s, the question's kind and created_unix_s, and value for an
approved value question), created only once, so the first answer counts. The worker
removes its question once decided; answers stay for an hour as the record.
The web page from your laptop
ora web serves a live run's page on the computer the run runs on: the
conversation on one side and the cell's four cameras on the other, with the
cell's controls (the robot's questions, the permission mode and auto-approve,
the verbs, the held arms' alerts; free play). On a real cell that is the
cell's computer; from a laptop you reach the page through SSH. The examples
call the cell's computer yam (an alias in ~/.ssh/config) and the checkout
there /path/to/ORA (an absolute path).
Build the page once on the cell's computer, and again after an update that
changes it (ora web says so):
ssh yam 'cd /path/to/ORA && ./scripts/ora web setup'
Then, from the laptop's checkout, either start the play session with its terminal here and its page in the laptop's browser:
./scripts/ora-remote yam --repo /path/to/ORA --web play --env yam --rig-mode on --operator-present \
--cell ~/.config/ora/cell.yaml --provider PROFILE --confirm-launch
or open the page of a play session that already runs on the cell (started in a
tmux there, say, so that it outlives your SSH session):
./scripts/ora-remote yam --repo /path/to/ORA web --last
ora-remote hands a one-time launch token to the cell's computer in a 0600
file, starts ora web --socket there on a 0600 unix socket in your runtime
directory, forwards a local port to that socket (ssh -L) and opens
http://127.0.0.1:PORT/?ora_token=... here (web view).
Nothing listens beyond loopback on either side.
Without ora-remote, do the same by hand. On the cell's computer, next to the
running session:
ssh yam
cd /path/to/ORA
d=${XDG_RUNTIME_DIR:-$HOME/.cache}/ora-web; mkdir -p "$d"; chmod 700 "$d"
(umask 077; python3 -c 'import secrets; print(secrets.token_urlsafe(32))' > "$d/token"); cat "$d/token" # copy it
./scripts/ora web --last --socket "$d/web.sock" --token-file "$d/token" --no-browser
and on the laptop, with the directory and the token that printed:
ssh -N -L 127.0.0.1:8790:/run/user/1000/ora-web/web.sock yam # the socket's absolute path
# open http://127.0.0.1:8790/?ora_token=TOKEN
The token works once: the browser exchanges it for a cookie, and a second
browser needs a new ora web. ora web reads and removes the token file.
Run ora web from the checkout the session runs from, with the same
ORA_CELL_LOCK, ORA_CELL_APPROVALS and ORA_CELL_ALERTS as the session
(normally none of them is set): its gateway reads the questions, the switch,
the alerts and the cell lock from those files, and its buttons run that
checkout's scripts/ora cell. When the session ends, the page shows what it
recorded and its cell controls keep working until you stop ora web
(Ctrl+C); the board (ora cell board) and the shell do too.
A simulated cell
The kit names no robot, and the YAM station has a simulated CellAdapter too: a
cell config with robot.sim: true runs every ora cell command, the board and
ora cell setup against kinematic arms and cameras MuJoCo renders, with nothing
plugged in. Use it to learn the setup and the board, to try a change to the
calibration on a cell whose truth you know, or while someone else has the arms.
ora cell sim init ~/.config/ora/sim-cell.yaml --python ~/envs/yam/bin/python
ora cell board --cell ~/.config/ora/sim-cell.yaml --port 8766 # one terminal
ora cell sim operator --cell ~/.config/ora/sim-cell.yaml # another: the person at the cell
ora cell setup --cell ~/.config/ora/sim-cell.yaml --ask broker # a third, or start it from the board
ora cell sim status --cell ~/.config/ora/sim-cell.yaml # the calibration against the truth
sim init writes the config (environment yam, buses sim_left and
sim_right, cameras named sim-...); --python names an interpreter with
MuJoCo, mink and i2rt, where every ora cell command then runs. The cell keeps
everything in its state directory, <config>.sim/ beside the config (or
robot.sim: {state: DIR}):
| File | Holds |
|---|---|
world.json |
the truth, written by the first command: where the right arm's base really is, each inner joint's encoder zero error, each wrist camera's mount error, where the fixed cameras stand, the table, the checkerboard (20 mm, 11x8) and each gripper's motor readings at its stops. Edit it, with the cell idle, to inject another error |
arms.json |
each arm's encoder readings, its gripper's reading and which process holds its motors |
board.json |
where the checkerboard lies on the table, absent when it is off |
bus/, cell.lock, approvals/, alerts.json |
the simulated buses, and the cell's lock, questions and alerts |
The simulated cell keeps its own lock, approvals and alerts there unless
ORA_CELL_LOCK, ORA_CELL_APPROVALS or ORA_CELL_ALERTS name others, so it
never shares them with a real cell on the same computer, and its adapter
refuses the real cell's /tmp/ora-cell.lock. Pass --cell (or set ORA_CELL)
to ora cell pending and approve so they find its questions; run the board on
another port than a real cell's.
What is simulated, and how:
- Arms. Held, they follow every command at once; released, they stay where
they are. Their encoders read the true angle minus the injected zero error.
estopandreleasefrom another process disable them, and a calibration motion then stops as on a real cell. Their speed is the kit's: a calibration takes as long as at the real cell. - Buses. Files: every reader or held arm counts as a receiver while open
and every read or command as a frame, so
ora cell check,diagnose, the board's bus chips and the motions' guards see other programs as they would on socketcan. - Cameras. The two fixed cameras and the two wrist cameras are rendered at
848x480 with their intrinsics and metric depth, from the truth's model: the
right base moved, the joints and wrist mounts off. The kit plans and fits on
the plain robot model, as at a real cell. Rendering needs a headless OpenGL
(
MUJOCO_GL=egl, the default here, orosmesa). - Grippers. Their stops come back from the gripper calibration named by the motor's direction, so the right gripper's are swapped until you, or the simulated operator, say it is open.
- The person.
ora cell sim place X Y [--yaw DEG]lays the board with its middle at (X, Y) on the table andsim cleartakes it off.sim operatoranswers the cell's questions as a person would until you stop it (--seconds S): it folds the arms to rest, says the board's size and which way each gripper opens from the truth, lays the board where each placement asks (and nearer the arm when asked again, declining after four tries), approves every motion and the write. Answer some yourself from the board and stop it to try a decline.
ora cell sim status prints the injected errors, the board, the arms and
recovery: for each arm, the calibrated base and wrist mount against the truth
(mm, degrees), the joint zeros injected, found and their difference, each fixed
camera's distance from where it stands, and the table height's. A fresh setup
finds the default errors (a 7.5 mm, 0.7 degree base and zeros up to 1.4
degrees) to within a millimetre and a tenth of a degree. The truth's left arm base is the
calibration's world, and the first and last joints' zeros belong to the base and
the wrist mount: injected there, the calibration cannot tell them apart and
moves them elsewhere. tests/ora/environment/backends/yam/test_sim_cell_flow.py
runs the whole setup this way in about a minute (in the YAM interpreter;
test_sim_cell.py checks the arms, buses and operator without MuJoCo).
A simulated cell drives no robot: the YAM worker refuses it for rig modes
read and on (its sim rig mode is the episode simulation).
The safety contract
Every real backend keeps these properties. The kit's tests (tests/ora/cell/)
check its half of them against a fake robot: one holder, a home that holds
instead of dropping, and the refusals.
- Read before write. Nothing is enabled before an occupancy check and a passive read: no other reader or traffic on the buses, joints inside the model's limits.
- One holder. Every program that touches the buses or the cameras takes
the cell lock (
$ORA_CELL_LOCK, else/tmp/ora-cell.lock) and says in it what it does;ora cell diagnosereads it. Programs outside ORA do not know the lock, which is why the occupancy check still listens to the buses. - Modes.
sim,read(motors never enabled; every motion answered with its plan) andon(requiresoperator_present: true; enabling the arms and each motion approved, the motions unless configured otherwise). - Return to rest never drops. From any state,
homedrives the arms to the recorded rest pose and only then releases; a blocked path holds in place. Disabling motors (the arms fall) is separate and confirmed:release,estop. A worker that ends releases its arms at rest without asking and asks before releasing them anywhere else. - Guards stop and hold. Tracking error, torque, temperature, a dead
control loop or a foreign controller stop the motion where the arms are
measured. On YAM a joint pushed on from outside stops it long before the
motor-torque guard: each tick the measured joint torque minus i2rt's own
model torque (its gravity and friction terms) is the external load, and a
load over the joint's limit (6 N·m shoulder and elbow, 2.5 N·m wrist;
yam_station.EXTERNAL_LOAD_STOP_NM) for 5 ticks isexternal_load_stop, naming the arm, the joint and the load. Each motion's peak loads go to the worker'srig-loads/<action_id>.json, the data the limits are tuned on (ora/environment/backends/yam/external_load.py). Withora play --smooth-commands(runtime.smooth_arm_commands, off by default) each control tick's arm target is reached along the line from the last one, streamed at 250 Hz with that line's velocity as i2rt's feed-forward, instead of one position step per tick with a zero velocity target; a hold is still commanded at once. - A gripper works only when told to. Every program that takes the arms
over (the play worker, the board's holder, a calibration motion) relaxes the
grippers at once: the motor stays enabled but gives no torque. A gripper
command engages it for that move; the operator tools relax it again once it
arrives, and the worker relaxes every gripper when the arms reach rest. A
gripper held by position control pushes whenever its target is out of reach
(a stop, an object, limits named the wrong way round) and overheats within
minutes, which stops the arm's control loop. Which way a gripper opens is
what the person saw (
ora cell grippers), not the motor's nominal direction. On YAM a gripper command runs in force control: the motor's own position gain is off, its damping stays, and each tick the worker sends a torque capped at 15 N of grip from the first contact on, friction compensation included (grippers.force_torque; the acef teleoperation follower's law, soft gain 1 N·m/rad, friction 0.12 N·m past a 0.02 rad deadband). The command is ramped, never stepped (40 mm/s of aperture closing, 80 mm/s opening; it leads the measured jaw by at most 3 mm), and jaws that stall on an object are held 1 mm past where they stopped instead of being driven on to closed (yam_station.GRIPPER_*). A close stepped to the end under position control crossed the whole aperture in 0.26 s and snapped a fingertip (2026-11-14); i2rt's force limiter acts only once it has seen the jaws blocked. The operator tools' grip (the board calibration closes and opens the jaws once) moves the same way, in force control and ramped, and relaxes each gripper as soon as it arrives or stalls.ora cell grippersstill drives the jaws to their stops under position control: that is how it finds them. - Alerts reach the person. Whoever holds the arms publishes their alerts
(
ora/cell/alerts.py: a motor warming up or near its protection, a gripper pushing, a stopped control loop) every half second; the board shows them as a banner. A critical one stops a calibration motion like the operator's home. - A start-up self-check before anything is enabled. The YAM worker
checks, from what it measured at start: no motor fault; every motor below
50 °C; the joints inside the model's limits; each gripper motor's reading
within its recorded [closed, open] limits (0.1 rad of margin: a motor zero
that moved over a power cycle makes the opening wrong by the whole travel);
the table the wrist cameras see where the calibration puts it; one frame
with enough valid depth from every camera; and the calibration's age (named
past 14 days, never refused). On
ona failed check refuses the start before the arms are enabled, and the refusal lists every failed check with its fix; a check that could not be made is named and does not refuse. Onreadthe same checks run with nothing enabled, so areadsession is the dry run of a real start. The result is the worker'srig-startup.json(self_check);ora cell setup --statusreports the gripper check asstale(ora/environment/backends/yam/selfcheck.py). - Forbidden frames. Writes that change the robot's own calibration (on
YAM's DM motors, frame
0xFE, the encoder zero) cannot be built.
Add a new robot
A new installation of a supported robot model needs only its cell.yaml and
steps 0 to 9. A new robot family adds a CellAdapter, the seam between the kit
and the robot's drivers (ora/cell/adapter.py; provisional, drawn from one
family). Put it in ora/environment/backends/<environment>/cell_adapter.py as
make_adapter(config):
- Facts the kit reads:
environment,model,arms,buses(arm to bus interface, from the config),camera_mounts(each public camera role tofixed_worldorend_effector),wrist_cameras(wrist camera role to arm),joint_names,control_hz,tracking_stop_rad(the operator motions' tracking stop),finger_open_m,foreign_controller_markers(command-line fragments of programs that drive these arms), and for the hand-eye plannerreach_seed_offset(the joint offset from rest that brings the wrist out over the table, its inverse kinematics' seed),reach_offset_limit_rad(no joint is planned further from rest) andwrist_image_occluded(pixel boxes of the wrist image the jaws hide). open_reader(gripper_limits)returns aReaderwhoseread()returns oneArmReadingper arm (joints, gripper, faults, temperatures, torques) without enabling any motor, andclose().take_over(arms, mode=, gripper_limits=)returns aHeld: refuse a bus another program uses first, release whatever was enabled if taking over fails partway, thenjoints(),command(targets)(joint targets; grippers held),alive()(each arm's control loop),set_mode("hold"|"float")without letting go, andrelease(), the only call that makes the arms limp.disable_all(): the last resort; it must work whoever holds the buses.calibrate_grippers(arms, should_stop): each gripper's [closed, open] limits.kinematics(table): the robot model'sKinematics(MuJoCo model and data,world_offset,arm_limitsandset_statein encoder readings,tcp,chain,wrist_camera,inter_arm_distance,table_distance,self_distances(an arm's wrist against its own lower links),ik,within_limits, and the calibration's corrections:camera_corrections,joint_offsets,set_base_corrections).calibration_offsets(): joint offsets from rest for the camera calibration poses; the kit checks every path for table and inter-arm clearance.facts(): what the operator should know about the robot, shown on the board.
The robot's worker keeps the same contract: it takes the cell lock for its
whole episode; if it returns its arms to rest on SIGUSR1 it puts [homes on SIGUSR1] in its lock label, and [at rest, holding] once there
(ora/cell/lock.py); its drivers cannot build a frame that rewrites the
robot's calibration. Then check the adapter without hardware: a fake one in the
shape of tests/support/cell/fake.py exercises the kit, and
ora cell init checks a config against the real one. A family may also ship a
simulated adapter, sim_cell_adapter.py with the same make_adapter(config),
which a config with robot.sim loads instead; it gives the kit its own bus
(Bus: receivers, traffic, interface per channel) and camera_driver
(CameraDriver: open, connected, busy, reset), which a hardware
adapter leaves out to get socketcan and RealSense. The robot model also
needs its geometry, controller constants, embodiment and tool surface, and the
family a Rig qualified in sim before read and on
(design note, section 8).