Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions docs/motion-planning/reference/frame-system-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ capabilities: ["frame-system", "motion-planning"]
diataxis: reference
---

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; the public API has none. All four methods below belong to `RobotService` in `api/proto/viam/robot/v1/robot.proto`. (Go module authors are the one exception: see [Service names](#service-names).)
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; the public API has none. All four methods below belong to `RobotService` in `api/proto/viam/robot/v1/robot.proto`. (Go and C++ module authors are the exception: see [Service names](#service-names).)

| Method | Purpose |
| ------------------- | ----------------------------------------------------------------------- |
Expand All @@ -20,15 +20,19 @@ The RPCs for querying and transforming frame system poses live on the robot serv

Call these methods directly on the robot or machine client
(`machine.transform_pose`, `machine.transform_pcd`, and so on).
Method availability varies by SDK: Go exposes all four, while Python
reaches `GetPose` through the motion service (see
[GetPose](#getpose) below).
The Python, Go, TypeScript, and C++ clients expose all four. Python
exposes `GetPose` on the machine client from v0.83.0 (see
[GetPose](#getpose) below), and C++ exposes `transform_pcd` from v0.42.0.
The Flutter SDK doesn't expose these methods on its robot client.

## Service names

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.

Go module authors can go one step further: declare a dependency on the frame system by the `$framesystem` name (`framesystem.PublicServiceName` in the RDK) and call the returned `framesystem.Service` directly. This gives module code the same frame-system queries with a resource dependency in place of a robot client connection.
Go and C++ module authors can go one step further and call the frame system as a resource dependency, in place of a robot client connection:

- **Go:** declare a dependency on the frame system by the `$framesystem` name (`framesystem.PublicServiceName` in the RDK) and call the returned `framesystem.Service` directly.
- **C++ (SDK v0.42.0 and later):** every modular resource receives the frame system in its dependencies under `FrameSystem::public_name()` (`$framesystem`), without listing it in `validate`. It is present only when the module runs under a `viam-server` parent, so check that the dependency exists, then `std::dynamic_pointer_cast` it to `FrameSystem` and call `get_frame_system_config`, `get_pose`, `transform_pose`, or `transform_pcd`.

## FrameSystemConfig

Expand Down
Loading