From 542171f2b19a30bd0cfbd41b114841aad629883e Mon Sep 17 00:00:00 2001 From: Brandon Shrewsbury Date: Tue, 14 Jul 2026 10:50:57 -0600 Subject: [PATCH] Correct motion and frame system API reference accuracy - api.md: the builtin motion service implements Move, GetPose (deprecated), DoCommand, and GetStatus; the five base-navigation methods return 'not supported by builtin' (confirmed against a live viam-server v1.0.0 and rdk services/motion/builtin at the v1.0.0 tag). The page previously said builtin supports 'Move, DoCommand, and GetStatus, and nothing else', contradicting its own GetPose section. Also: executeCheckStart is an optional key inside an execute DoCommand request, not a standalone command; documented the teleop commands; noted GetStatus is a common resource RPC absent from the generated table. - frame-system-api.md: fixed an inverted code comment (a Transform's reference_frame names the new frame; pose_in_observer_frame carries its pose in the parent frame); removed an unverifiable roadmap claim; named the Go client method for TransformPCD (TransformPointCloud); flipped negation-first passages positive; action-oriented description. - kinematics.md: DH parameters are a kinematic_param_type="DH" mode with a dhParams array, not inline in an SVA file; documented links[].orientation (linking the orientation-vector reference) and joints[].geometry (prismatic only); mimic multiplier defaults to 1.0; Viam Registry casing. - _index.md: replaced an idiom. --- docs/motion-planning/reference/_index.md | 4 +-- docs/motion-planning/reference/api.md | 17 ++++++++---- .../reference/frame-system-api.md | 26 +++++++++---------- docs/motion-planning/reference/kinematics.md | 17 +++++++----- 4 files changed, 37 insertions(+), 27 deletions(-) diff --git a/docs/motion-planning/reference/_index.md b/docs/motion-planning/reference/_index.md index a50b248019..5b14c1f50c 100644 --- a/docs/motion-planning/reference/_index.md +++ b/docs/motion-planning/reference/_index.md @@ -9,8 +9,8 @@ description: "Configuration, API, and technical reference for the motion service The motion service turns a high-level "move to this pose" request into a collision-free joint trajectory. This reference documents what you -configure, what the API exposes, and the formats and algorithms it uses -under the hood. For conceptual background, see +configure, what the API exposes, and the formats and algorithms behind +those requests. For conceptual background, see [How motion planning works](/motion-planning/how-planning-works/); for task-based guidance, start from the [section landing](/motion-planning/). diff --git a/docs/motion-planning/reference/api.md b/docs/motion-planning/reference/api.md index 5f34f62fe4..69f4fdb365 100644 --- a/docs/motion-planning/reference/api.md +++ b/docs/motion-planning/reference/api.md @@ -10,7 +10,7 @@ aliases: - /appendix/apis/services/motion/ --- -The motion service exposes the methods below for planning and executing component motion. Most methods are implemented only by module-based motion services. The builtin service supports `Move`, `DoCommand`, and `GetStatus`, and nothing else. +The motion service exposes the methods below for planning and executing component motion. Most methods are implemented only by module-based motion services. The builtin service implements `Move`, `GetPose` (deprecated), `DoCommand`, and `GetStatus`. `MoveOnMap`, `MoveOnGlobe`, `StopPlan`, `ListPlanStatuses`, and `GetPlan` return a `not supported by builtin` error; module-based motion services implement them. {{< readfile "/static/include/services/apis/generated/motion-table.md" >}} @@ -25,20 +25,27 @@ Plans and executes a motion to a destination pose. This is the primary method fo Key parameters: -- `component_name`: the arm or gantry to move +- `component_name`: the component to move (typically an arm or gantry in this section's examples) - `destination`: a `PoseInFrame` specifying the target pose and reference frame - `world_state`: optional obstacles and transforms - `constraints`: optional linear, orientation, or collision constraints +### MoveOnMap, MoveOnGlobe, StopPlan, ListPlanStatuses, and GetPlan + +Navigate mobile bases and manage the resulting plans. The builtin motion service returns a `not supported by builtin` error for each of these methods (for example, `MoveOnMap not supported by builtin`); module-based motion services implement them. + ### GetPose (deprecated) Returns a component's pose. Deprecated in favor of the robot service's `GetPose`. Python callers still use this motion-service method today; see the [Frame system API reference](/motion-planning/reference/frame-system-api/). ### DoCommand -Sends arbitrary commands. The builtin motion service supports `"plan"`, -`"execute"`, and `"executeCheckStart"` commands. +Sends arbitrary commands. The builtin motion service supports a `"plan"` +command (returns a trajectory without executing it), an `"execute"` command +(runs a trajectory; add the `"executeCheckStart"` key to an execute request +to verify the resource is at the trajectory's start first), and the teleop +commands (`teleop_start`, `teleop_move`, `teleop_stop`, and `teleop_status`). ### GetStatus -Returns generic resource status for the motion service. Useful for liveness checks. +Returns generic resource status for the motion service. `GetStatus` is a common resource RPC, so the generated table above omits it. Use it for liveness checks. diff --git a/docs/motion-planning/reference/frame-system-api.md b/docs/motion-planning/reference/frame-system-api.md index 702df194f4..13e686f732 100644 --- a/docs/motion-planning/reference/frame-system-api.md +++ b/docs/motion-planning/reference/frame-system-api.md @@ -4,7 +4,7 @@ title: "Frame system API reference" weight: 27 layout: "docs" type: "docs" -description: "The RPCs for querying and transforming frame system poses live on the robot service, not a standalone frame system service." +description: "Query and transform frame system poses with the robot service RPCs: FrameSystemConfig, GetPose, TransformPose, and TransformPCD." --- The RPCs for querying and transforming frame system poses live on the robot service, not on a dedicated `FrameSystemService`. New users often look for a separate service matching the concept; there is none. All four methods below belong to `RobotService` in `api/proto/viam/robot/v1/robot.proto`. @@ -16,13 +16,12 @@ The RPCs for querying and transforming frame system poses live on the robot serv | `TransformPose` | Convert a pose between reference frames. | | `TransformPCD` | Convert a point cloud between reference frames. | -The SDK client classes surface these as methods on the robot or -machine client object (`machine.transform_pose`, `machine.get_pose`, -and so on). You do not instantiate a separate frame system client. +Call these methods directly on the robot or machine client +(`machine.transform_pose`, `machine.get_pose`, and so on). ## Service names -You do not reference these names directly when calling the frame system from an SDK. They appear here so you can recognize them in error messages or module configuration: inside RDK, the frame system is registered under `builtin` (the default instance that ships with `viam-server`) and `$framesystem` (the name modules use to resolve a dependency on it). The RPCs on the robot/machine client hit the frame system transparently. +These names appear in error messages and module configuration: inside RDK, the frame system is registered under `builtin` (the default instance included with `viam-server`) and `$framesystem` (the name modules use to resolve a dependency on it). The RPCs on the robot/machine client hit the frame system transparently. ## FrameSystemConfig @@ -106,13 +105,11 @@ gripperInWorld, err := machine.GetPose( ### Python goes through the motion service, Go through the robot service -`GetPose` exists on two services in the proto: the robot service (current) and the motion service (older, deprecated, same parameter shape). The Go SDK surfaces the robot service version as `RobotClient.GetPose`; Go callers go through the robot service. The Python SDK never wrapped the robot service version, so Python callers use `MotionClient.get_pose` and hit the deprecated motion service path. +`GetPose` exists on two services in the proto: the robot service (current) and the motion service (older, deprecated, same parameter shape). The Go SDK exposes the robot service version as `RobotClient.GetPose`; Go callers go through the robot service. The Python SDK never wrapped the robot service version, so Python callers use `MotionClient.get_pose` and hit the deprecated motion service path. -The two paths return equivalent results today. The underlying API -surface will eventually consolidate, but until then Python callers -stay on the motion-service path. The CLI's `print-status`, `get-pose`, -and `set-pose` commands also invoke the deprecated motion-service -method internally. +The two paths return equivalent results. The CLI's `print-status`, +`get-pose`, and `set-pose` commands also invoke the deprecated +motion-service method internally. ## TransformPose @@ -183,8 +180,8 @@ motion to it. from viam.proto.common import PoseInFrame, Pose, Transform # 1. Declare the detected box as a supplemental transform. -# The Transform's reference_frame is the parent; the pose is the -# box's position in that parent. +# The Transform's reference_frame names the new frame (detected-box); +# pose_in_observer_frame gives its pose in the parent frame (my-camera). detected_box = Transform( reference_frame="detected-box", pose_in_observer_frame=PoseInFrame( @@ -245,7 +242,8 @@ arm navigates relative to), pass the same transform on the motion Transform a point cloud from one reference frame to another. Useful for aligning point clouds from multiple cameras into a common frame, or for -expressing lidar scans in world coordinates. +expressing lidar scans in world coordinates. The Go client exposes this +RPC as `TransformPointCloud`. | Parameter | Description | | ----------------- | ---------------------------------------------------------------------------------- | diff --git a/docs/motion-planning/reference/kinematics.md b/docs/motion-planning/reference/kinematics.md index e994df3b81..b1ea638f69 100644 --- a/docs/motion-planning/reference/kinematics.md +++ b/docs/motion-planning/reference/kinematics.md @@ -12,9 +12,9 @@ aliases: A kinematics file describes your arm's physical structure (link lengths, joint axes, joint limits) so the motion planner can solve the inverse kinematics problem: given a target pose, find joint angles that reach it. -{{< alert title="Most arms handle this automatically" color="tip" >}} +{{< alert title="Most arm modules handle this automatically" color="tip" >}} -Most arm modules in the Viam registry include a kinematics file. For standard +Most arm modules in the Viam Registry include a kinematics file. For standard commercial arms like the UR5e, xArm6, or Viam Arm, the module handles kinematics automatically; you do not need to provide or configure a kinematics file. Read this page if you are building a custom arm, using a @@ -75,7 +75,7 @@ Viam supports two kinematics file formats at the API level: | **SVA** (Spatial Vector Algebra) | Viam's native JSON format | When writing a Viam kinematics file directly. | | **URDF** | XML format used by ROS and many manufacturers | When the manufacturer ships a URDF and you want to reuse it. | -`GetKinematics` returns one of these two formats. Viam's SVA schema also accepts Denavit-Hartenberg parameters inline, as a convenience when you are converting a textbook DH table; DH is not a third API-level format. +`GetKinematics` returns one of these two formats. The same JSON file format also accepts Denavit-Hartenberg (DH) parameters: set `kinematic_param_type` to `"DH"` and supply a `dhParams` array, a convenience when you are converting a textbook DH table. DH is not a third API-level format. Most registry arm modules use SVA internally. You rarely need to write a kinematics file from scratch unless you are building a custom arm. @@ -93,7 +93,7 @@ kinematics file. ### 1. Check if your arm has a built-in kinematics file -Most arm modules in the Viam registry ship with a kinematics file built into +Most arm modules in the Viam Registry include a kinematics file built into the module. The module loads and applies the kinematics automatically when `viam-server` starts. @@ -190,6 +190,9 @@ Each field: - **`links[].id`**: unique name for the link - **`links[].parent`**: the joint or frame this link attaches to - **`links[].translation`**: offset in mm from the parent's origin +- **`links[].orientation`**: optional orientation of the link relative to its + parent, in any of the + [orientation formats](/motion-planning/reference/orientation-vectors/) - **`links[].geometry`**: optional collision shape (uses `type`, `x`/`y`/`z` for box, `r` for sphere/capsule/cylinder, `l` for capsule length or cylinder height) - **`joints[].id`**: unique name for the joint - **`joints[].type`**: `"revolute"` (rotates) or `"prismatic"` (slides) @@ -197,12 +200,14 @@ Each field: - **`joints[].axis`**: the axis of rotation or translation (unit vector) - **`joints[].min`** / **`joints[].max`**: joint limits in degrees (revolute) or mm (prismatic) +- **`joints[].geometry`**: optional collision shape, prismatic joints only - **`joints[].mimic`** (optional): make this joint follow another joint at a fixed multiplier and offset, for parallel-jaw grippers and other mechanically coupled axes. The mimic object takes `joint` (the source joint's `id`), `multiplier`, and `offset`; the joint's value is computed as - `multiplier * source_value + offset`. Mimic joints must not declare their own - `min`/`max`; the source joint's limits apply. + `multiplier * source_value + offset`. An omitted `multiplier` defaults to + 1.0. Mimic joints must not declare their own `min`/`max`; the source joint's + limits apply. ### 3. Import a URDF file