OpenArm manual

1. Your first OpenArm run

OpenArm is the two-arm manipulation workspace. Its reference task transfers an empty flask to an unpowered hotplate, then an empty beaker to ring-stand gauze. These are dry rigid-body tasks; heater operation, liquids and chemistry are not simulated.

1. Launch OpenArm. Wait until the status bar says Ready. The selected task is Bimanual Heater and Ring-Stand Stack.
2. Read the Task view and the visible Python files. The normal starter is designed for the original reference scene.
3. Press Run to reset and run that visible Python draft. Watch the simulator and open Diagnostics to inspect the result.
4. Use Pause to suspend a supported active run and Stop to cancel it. Reset restores the current scene’s starting state; it does not mean “empty the workcell.”

The guides can be read without WebMCP. The human Lab Builder also works without a native agent host. Loading the IDE requires a browser with WebAssembly and WebGL and access to the model and runtime assets; internet access is needed for external editor/Python dependencies. A desktop is recommended for editing.

2. Find your way around

Local persistence is not cloud storage. Python drafts use browser storage. General scene drafts and current simulation state are in memory; export a Lab Builder project before refreshing or leaving the IDE. File → Export Workspace is for the Python workspace, not a substitute for exporting an authored scene.

3. Choose the right scene mode

Reset preserves the selected scene mode. Use stage/apply to change modes. To return from an authored scene, use manage_openarm_workcell with scene_mode:"baseline", an empty equipment list and a fresh scene revision, then explicitly apply. The WebMCP manual shows the exact request.

4. Build and review a scene

Choose Lab Builder in the simulator header. It accepts a complete robobuddy.lab.scene.v2 JSON description. Complete equipment items need not exist in the catalog.

1. Author or import a draft. Import SceneSpec JSON or a project with auto_start:false. Importing only fills the editor. It does not change the workcell or execute a task.
2. Stage. Validate the construction and display a preview. Stage is full replacement of the authored scene, not an incremental patch.
3. Check candidate. Compile and briefly simulate a separate disposable candidate. Review initial overlaps, settling and relationship-contact observations. The active workcell remains unchanged.
4. Apply + reset. Explicitly replace the workcell. Application checks the candidate before switching; compile or initial-overlap failure retains the old physical session. A successful application resets the robot and invalidates prior task evidence.
5. Inspect and export. Review inventory, uncertainty and physical checks. Toggle Collision view to inspect the surfaces used by physics. Export the draft/project and, separately, evidence.

After editing a staged draft, stage it again. Check and Apply reject a visible draft that differs from the stage. Read current / staged loads the staged description when one exists, otherwise the active authored scene. Discard preview removes the stage, not active equipment. New empty draft changes the editor only.

5. Geometry, units and provenance

Use metres, radians and a Z-up world. Quaternions use normalized [w,x,y,z] order. An object’s position is its authored local origin, not automatically its center of mass.

Boxes and spheres are centered on their part origin. Cylinders, frustums, hollow profiles and extrusions start at local Z = 0. Each part can have its own position and rotation relative to its object. Parts in one object form one rigid body, even when disconnected.

Declare motion:"fixed" with a fixed_reason for installed equipment. A free object receives gravity and contacts. mass_kg, friction and part density are model parameters. Their limits are not OpenArm payload ratings. Overlapping components are counted separately in mass distribution.

For image-guided scenes, inventory the items as represented, approximated, unresolved or supplemental. Record geometry, pose, mass and friction provenance separately: source_provided, user_measured, image_estimated, fitted or assumed. Non-assumed mass and friction require explicit values. A “user measured” label remains an author declaration.

Record deliberate layout changes in adjustments. Relationships such as supported_by and attached_to are descriptive; they do not create hidden welds or move objects.

6. Define and evaluate a task

Scene construction and robot-task feasibility are separate. A valid scene may contain equipment OpenArm cannot reach or grasp. The builder does not generate a collision-free path for you.

Before grasping, open Task assessment and independent evidence. Assess or define a supported dry_transfer to a support port, or an insert between a cylindrical peg and an approximately vertical hollow-profile opening. Task definition does not move the robot.

Support, opening and peg ports derive their dimensions from construction parts; grasp ports are only author-proposed candidate points. Current generic task ports use construction parts. Catalog assets retain their separate legacy affordances.

For a successful evaluated single-gripper transfer, the system requires initial released support, sustained bilateral grasp, unsupported lift and carry, release at the receiving feature, gripper retreat and settled receiver contact. Palm or opposite-gripper assistance, another support after lift, prolonged loss of grasp or regrasp after release invalidates this task family. Reset and scene replacement invalidate old evidence.

Use run_openarm_program for a scene-specific bounded sequence without an implicit reset. Its authored_task_complete condition reads the independent authored evaluator. In contrast, run_robobuddy_program resets and runs the visible Python draft, which invalidates an already-defined authored trial. See the worked WebMCP example.

7. Try the non-catalog adapter

This supplied example is the controlled scene used in the contact-driven transfer regression. It is not a general motion plan for other scenes.

Download scene JSON · Download task JSON · Download program JSON

Import the scene in Lab Builder, Stage, Check candidate and Apply + reset. Define the downloaded task before any grasp. In a compatible agent host, supply the program to run_openarm_program after replacing its revision placeholder with the current authority.sceneRevision. The existing WebMCP API takes JSON objects, not file URLs.

The scene contains an authored bench, a compound sample adapter and a receiver. The program approaches, closes the left gripper, lifts, carries, lowers, releases and retreats. Its final predicate must confirm observed task completion. Do not reposition or scale the fixture and then assume this trajectory remains valid.

8. Useful controls and shortcuts

F10 / Ctrl+F10 belong to step/cursor paths where supported; live physical Python may disable them. Within Lab Builder, F5 and F10 are intercepted so editing JSON does not accidentally launch a Python run. Escape closes that panel first.

9. Troubleshooting

10. What this does not establish

Current general-builder budgets are 24 objects, 32 declared parts per object, 160 collision components per object and 512 per scene. Raw and normalized SceneSpec are limited to 512 kB. Mesh, repetition, volume and mass limits also apply; read the current schema rather than inferring capacity from appearance.

The general builder does not supply liquids, chemistry, glass deformation, arbitrary moving mechanisms, raw GLB/STL import, automatic concave decomposition, automatic image-to-3D conversion or hardware control. Novel equipment may be a useful rigid exterior without being an operational instrument.

Tests cover selected construction and manipulation cases. They do not establish a success rate for arbitrary unseen photos, the complete photographed funnel pickup/insertion task, compatibility with every in-app WebMCP host, or transfer to a physical robot. Keep estimated dimensions, simulation observations and hardware validation separate.