Coordinate calibration
Capture Home and three surface points to map robot poses into the model frame.
Calibrate before the first run and after changing the end-effector assembly, Home pose or task axes. Stop the task, then open Settings → Devices → Coordinate calibration in the local console.
Prepare a reference surface
Choose a surface checked with a spirit level and keep the return path to Home clear. Use the same rigid contact point on the tool for every surface sample. Keep the tool orientation and gripper opening unchanged. Both UR and Franka use the flange centre as the control point.
- UR: adjust poses in PolyScope Local mode with zero TCP translation offset. On e-Series, switch to Remote before automatic returns, Return to point 1 or enabling control. Switch back to Local to continue manual teaching.
- Franka: release any other Desk control owner first. Guide with the arm buttons, then release them and let the arm settle before capture. After Home, select one translation axis at a time while keeping rotations constrained; release the buttons before changing axes too.
Other adapters with native guiding can use the axis controls; otherwise use the robot teaching controls while keeping read-only feedback available. Guiding axes are separate from the task axes established by calibration.
For Franka, configure the actual assembly load in setup first; UR sets loads in PolyScope. See Franka setup, UR setup, or Connect new hardware.
Capture four positions
Follow the four steps in the dialog. Let the arm settle, then choose Capture at each step.
| Step | Action |
|---|---|
| Home | Keep the whole gripper vertical with fingers down, about 30–50 cm above the surface. Leave room for the return path. |
| Point 1 (A) | Keep the orientation and touch the surface with the fixed contact point. |
| Point 2 (B) | Move across the surface toward camera left. A→B defines task +X. Keep the same orientation and contact point. |
| Point 3 (C) | Choose a point on the same surface, away from line AB. Capturing it automatically returns Home, saves calibration and enables control. |
The final step initializes the arm and gripper; the gripper may move. The browser then opens an optional direction check. Choose Done to return to the console and run a task.
Calibration is saved on the control computer at ~/.config/roboapi/calibration.json by default. Later starts reuse it: enable control in device settings without repeating the captures.
Adjust or resume calibration
| Action or condition | Result |
|---|---|
| Previous step | Removes the latest unsaved position, retaining earlier records and saved calibration. The arm does not move. |
| Return to point 1 | Physically returns to A during B/C teaching, retains the samples and resumes the current step. |
| Close the dialog | Retains the unfinished step. Choose Resume calibration in device settings. |
| Disconnect | After closing the dialog, use device settings to release connections and discard unfinished teaching. Saved calibration remains. |
| Automatic return fails | Samples remain available. Resolve the prompt and choose Retry without recapturing. |
| Control initialization fails after saving | Saved calibration remains. Resolve the prompt and retry enabling control without recalibrating. |
After saving, Previous step cannot undo those captures; choose Recalibrate to replace them. Use Stop during automatic motion. Use the robot's own controls to stop manual guiding.
Direction check
You can also open Settings → Devices → Direction check after calibration. The arm must be idle, control enabled and at the captured Home pose.
Each trial physically translates 5 cm, rotates 30°, then returns Home while keeping the gripper opening. Compare displacement and rotation with the on-screen guide. Trials do not call the model and are optional before running a task.
| Direction | Task-frame displacement | Task-frame rotation |
|---|---|---|
| Forward | −Y 5 cm | Roll −30° |
| Left | +X 5 cm | Pitch −30° |
| Up | +Z 5 cm | Yaw +30° |
Stop cancels the remaining trajectory, including the return. After a stop or failure, use the check panel's return action to go Home before another trial. This return keeps the gripper opening; the console's regular Home action opens the gripper.
Coordinates and integrations
Calibration maps Home to model position [-0.13, -0.46, 0.49] metres and quaternion [0, 1, 0, 0] in xyzw order. The surface normal toward Home defines +Z; the projection of A→B onto the surface defines +X; +Y completes the right-handed frame.
The browser automatically saves and enables control after capturing C and returning successfully. With HTTP or MCP, capturing C only captures the point and returns Home. Call save and enable-control operations separately.