Headless-app aliases + motion service reference migration

docs/build-apps/overview.md

@@ -6,6 +6,16 @@ layout: "docs"
 type: "docs"
 description: "Build software that uses a Viam SDK to talk to your machines and the Viam cloud, from web dashboards to long-running backend services."
 date: "2026-04-10"
+aliases:
+  - /operate/control/headless-app/
+  - /product-overviews/sdk-as-client/
+  - /program/sdk-as-client/
+  - /program/sdks/
+  - /program/
+  - /program/run/
+  - /program/debug/
+  - /how-tos/develop-app/
+  - /use-cases/develop-app/
 ---
 
 A Viam app is software that uses a Viam SDK to talk to a machine or to the Viam cloud. It runs outside `viam-server`: in a browser, on a phone, on a server, or on a laptop. Viam apps come in many shapes: a browser dashboard, a Flutter app on a kiosk, a Python service that polls sensors, a Go program that orchestrates a fleet.

docs/reference/services/_index.md

@@ -9,8 +9,9 @@ description: "Configuration reference for Viam built-in services: per-service mo
 date: "2026-04-14"
 ---
 
-Configuration reference for Viam built-in services. For API method reference, see [APIs](/reference/apis/).
+Configuration reference for Viam built-in services. Each page covers available models, configuration attributes, and JSON templates. For API method reference, see [Service APIs](/reference/apis/services/).
 
 {{< cards >}}
 {{% card link="/reference/services/vision/" %}}
+{{% card link="/reference/services/motion/" %}}
 {{< /cards >}}

docs/reference/services/motion/_index.md

@@ -0,0 +1,173 @@
+---
+title: "Motion service reference"
+linkTitle: "Motion"
+weight: 40
+layout: "docs"
+type: "docs"
+description: "The motion service enables your machine to plan and move its components relative to itself, other machines, and the world."
+date: "2026-04-18"
+aliases:
+  - /operate/reference/services/motion/
+  - /services/motion/
+  - /mobility/motion/
+---
+
+The motion service enables your machine to plan and move itself or its components relative to itself, other machines, and the world.
+The motion service:
+
+1. Gathers the current positions of the machine’s components as defined with the [frame system](/motion-planning/frame-system/overview/).
+2. Plans the necessary motions to move a component to a given destination while obeying any [constraints you configure](constraints/).
+
+The motion service can:
+
+- use motion [planning algorithms](algorithms/) locally on your machine to plan coordinated motion across many components.
+- pass movement requests through to individual components which have implemented their own motion planning.
+
+## Configuration
+
+You need to configure frames for your machine's components with the [frame system](/motion-planning/frame-system/overview/).
+This defines the spatial context within which the motion service operates.
+
+The motion service itself is enabled on the machine by default, so you do not need to add any extra configuration to enable it.
+
+## Access the motion service in your code
+
+Use the motion service in your code by creating a motion service client and then calling its methods.
+As with other resource clients, how you get the client depends on whether your code is part of a client application or a module:
+
+{{< tabs >}}
+{{% tab name="From a client application" %}}
+
+To access a motion service, use its name from the machine configuration.
+To access the motion service built into `viam-server` from your client application code, use the resource name `builtin` to get a motion service client:
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+```python {class="line-numbers linkable-line-numbers"}
+# Get a motion service client
+motion_service = MotionClient.from_robot(machine, "builtin")
+
+# Then use the motion service, for example:
+moved = await motion_service.move(gripper_name, destination, world_state)
+```
+
+{{% /tab %}}
+{{% tab name="Go" %}}
+
+```go {class="line-numbers linkable-line-numbers"}
+// Get a motion service client
+motionService, err := motion.FromProvider(machine, "builtin")
+if err != nil {
+  logger.Fatal(err)
+}
+
+// Then use the motion service, for example:
+moved, err := motionService.Move(context.Background(), motion.MoveReq{
+  ComponentName: gripperName,
+  Destination: destination,
+  WorldState: worldState
+})
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+{{% /tab %}}
+{{% tab name="From within a module" %}}
+
+To access a motion service, use its name from the machine configuration.
+To access the motion service built into `viam-server` from your module code, you need to add the motion service as a [module dependency](/build-modules/dependencies/), using the resource name `builtin`.
+For example:
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+1. Edit your `validate_config` function to add the `builtin` motion service as a dependency so that it is available to your module.
+   You do not need to check for it in your config because the built-in motion service is always enabled.
+
+   ```python {class="line-numbers linkable-line-numbers"}
+   @classmethod
+   def validate_config(
+       cls, config: ComponentConfig
+   ) -> Tuple[Sequence[str], Sequence[str]]:
+       req_deps = []
+       req_deps.append("builtin")
+       return req_deps, []
+   ```
+
+1. Edit your `reconfigure` function to add the motion service as an instance variable so that you can use it in your module:
+
+   ```python {class="line-numbers linkable-line-numbers"}
+   def reconfigure(
+       self, config: ComponentConfig, dependencies: Mapping[ResourceName, ResourceBase]
+   ):
+       motion_resource = dependencies[Motion.get_resource_name("builtin")]
+       self.motion_service = cast(MotionClient, motion_resource)
+
+       return super().reconfigure(config, dependencies)
+   ```
+
+1. You can now use the motion service in your module, for example:
+
+   ```python {class="line-numbers linkable-line-numbers"}
+   def move_around_in_some_way(self):
+       moved = await self.motion_service.move(gripper_name, destination, world_state)
+       return moved
+   ```
+
+{{% /tab %}}
+{{% tab name="Go" %}}
+
+The following example assumes your module uses `AlwaysRebuild` and does not have a `Reconfigure` function defined.
+
+```go {class="line-numbers linkable-line-numbers"}
+// Return the motion service as a dependency
+func (cfg *Config) Validate(path string) ([]string, []string, error) {
+  deps := []string{motion.Named("builtin").String()}
+  return deps, nil, nil
+}
+
+// Then use the motion service, for example:
+func (c *Component) MoveAroundInSomeWay() error {
+  c.Motion, err = motion.FromDependencies(deps, "builtin")
+  if err != nil {
+    return nil, err
+  }
+  moved, err := c.Motion.Move(context.Background(), motion.MoveReq{
+    ComponentName: gripperName,
+    Destination: destination,
+    WorldState: worldState
+  })
+  return moved, err
+}
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+If you created your own custom motion service, you can access it using the resource name you gave it in your machine's configuration.
+You'll also need to check for it in your validate function, since it is not built into `viam-server`.
+
+{{% /tab %}}
+{{< /tabs >}}
+
+## API
+
+The [motion service API](/reference/apis/services/motion/) supports the following methods:
+
+{{< readfile "/static/include/services/apis/generated/motion-table.md" >}}
+
+## Test the motion service
+
+You can test motion on your machine from the [**CONTROL** tab](/monitor/).
+
+![Motion card on the Control tab](/services/motion/motion-rc-card.png)
+
+Enter x and y coordinates to move your machine to, then click the **Move** button to issue a `MoveOnMap()` request.
+
+{{< alert title="Info" color="info" >}}
+
+The `plan_deviation_m` for `MoveOnMap()` on calls issued from the **CONTROL** tab is 0.5 m.
+
+{{< /alert >}}

docs/reference/services/motion/algorithms.md

@@ -0,0 +1,62 @@
+---
+title: "Motion planning algorithms"
+linkTitle: "Algorithms"
+weight: 20
+layout: "docs"
+type: "docs"
+description: "Information about the motion planning algorithms Viam uses."
+date: "2026-04-18"
+aliases:
+  - /operate/reference/services/motion/algorithms/
+  - /services/motion/algorithms/
+  - /mobility/motion/algorithms/
+---
+
+Robotic motion planning is heavily reliant on planning algorithms to determine how to achieve motion for a particular scenario.
+Many algorithms already exist for this problem, and motion planning is a domain where improvements and novel developments occur frequently.
+Viam does not implement all motion planning algorithms but has implemented a few in its strategy for planning general robot motion.
+The algorithms Viam supports are all based in principle on [RRT](https://en.wikipedia.org/wiki/Rapidly-exploring_random_tree):
+
+The algorithms that Viam uses for motion planning depend on the type of the robot in question; planning for "Kinematic Chains", consisting of Gantry and Arm components is treated differently than planning for Base components
+
+## Kinematic Chains
+
+### RRT\*-Connect
+
+RRT\*-Connect is an asymptotically optimal planner that samples the planning space randomly, connecting viable paths as it finds them.
+It continues sampling after it finds its first valid path, and if it finds future paths that are more efficient, it updates to report those instead.
+For Viam, efficiency/path quality is measured in terms of total kinematics state excursion.
+For an arm, the sum of all joint changes is minimized.
+For a gantry, the sum of all linear movement is minimized.
+This algorithm can route around obstacles, but cannot satisfy topological constraints.
+
+### CBiRRT
+
+CBiRRT stands for Constrained, Bi-directional implementation of [RRT](https://en.wikipedia.org/wiki/Rapidly-exploring_random_tree).
+It creates paths which conform to specified constraints, and attempts to smooth them afterwards as needed.
+By default, it does not constrain the path of motion at all.
+This is to ensure that paths will be found when using defaults.
+CBiRRT returns the first valid path that it finds.
+The CBiRRT algorithm Viam uses is based on the algorithm described in the paper [Manipulation Planning on Constraint Manifolds](https://www.ri.cmu.edu/pub_files/2009/5/berenson_dmitry_2009_2.pdf)
+
+### How the motion service applies these algorithms
+
+By default, Viam's motion planning library uses a hybrid approach:
+
+First, Viam runs RRT*-Connect for 1.5 seconds.
+If RRT*-Connect does not return a path, then Viam calls CBiRRT to attempt to find a path.
+CBiRRT takes a more incremental approach which often performs better in difficult, constrained scenarios.
+If CBiRRT is successful, it returns a path.
+If unsuccessful, CBiRRT returns an error.
+However, if RRT*-Connect is initially successful, Viam evaluates the path for optimality.
+If the total amount of joint excursion is more than double the minimum possible to go directly to the best Inverse Kinematics solution, then Viam runs CBiRRT to attempt to get a better path than what RRT*-Connect was able to create.
+Viam smooths the two paths, then compares them to one another, and returns the most optimal path.
+
+## Bases
+
+### TP-Space-RRT
+
+This algorithm is based on the research described in the paper: [TP-Space RRT - Kinematic Path Planning of Non-Holonomic Any-Shape Vehicles](https://www.researchgate.net/publication/275584014_TP-Space_RRT_-_Kinematic_Path_Planning_of_Non-Holonomic_Any-Shape_Vehicles). This algorithm is suitable to planning for Bases since it is able to incorporate non-holonomic constraints into the planner directly to only return plans that are kinematically feasible for the base. One such example of a constraint that this allows us to impose is a minimum turning radius constraint, which is expressed through the [Base's](/operate/reference/components/base/) [GetProperties](https://docs.viam.com/components/base/#getproperties) method.
+
+This algorithm works by exploring a series of continuous trajectory-parameter spaces (TP-space) which describe different actions the base can take, such as, for example, turn and then go straight.
+This concept is then used within an RRT framework to compose these different actions into a series of sequential actions to be taken in order to navigate the base to its goal.