Mobile base with arm

A mobile manipulator is a base with an arm on top. It has two distinct kinds of motion: the base moves through the environment, and the arm moves within reach of the base. The frame system represents this by parenting the arm to the base rather than to the world. Every arm-attached component (the gripper, a wrist camera) then inherits the base’s motion, while navigation sensors mounted directly on the base form a parallel subtree. This guide builds the full hierarchy: world to base to (arm to (gripper, wrist camera), navigation sensors).

Frame hierarchy

world
└── my-base
    ├── my-arm (mounted on base)
    │   ├── my-gripper
    │   └── wrist-camera
    ├── nav-camera (front-facing)
    └── my-lidar

The hierarchy reflects what physically moves with what. The base’s parent is the world, so when the base drives, every frame below it shifts with it. The arm’s parent is the base, so arm motion moves the gripper and wrist camera but not the navigation sensors. This separation keeps the lidar’s reading about the floor consistent while the arm reaches for something.

Steps

1. Choose your world frame

For a mobile base, the world frame origin is the base center at machine start. Unlike a table-mounted arm where you pick a fixed physical landmark, the frame system tracks the base’s motion from this initial origin, so you do not mark anything physically. All component positions are defined relative to this point.

2. Add a frame to the base

In the CONFIGURE tab, click the base component’s card and then click Frame. (For details on the Frame editor, see Edit a frame in the Viam app.) Edit the JSON for each component below as you go.

{
  "parent": "world",
  "translation": { "x": 0, "y": 0, "z": 0 },
  "orientation": {
    "type": "ov_degrees",
    "value": { "x": 0, "y": 0, "z": 1, "th": 0 }
  }
}

Click Save in the top-right of the page (or press ⌘/Ctrl+S).

3. Add a frame to the arm

In the sidebar, click your arm component to open its card. On the card, click Frame. The arm’s parent is the base, not the world frame.

Measure the offset from the center of the base to the arm’s mounting point. For an arm mounted 100 mm forward of center and 200 mm above the base center:

{
  "parent": "my-base",
  "translation": { "x": 0, "y": 100, "z": 200 },
  "orientation": {
    "type": "ov_degrees",
    "value": { "x": 0, "y": 0, "z": 1, "th": 0 }
  }
}

If the arm is mounted off-center to one side, include an x offset as well.

Click Save.

4. Add frames to the gripper and wrist camera

Both the gripper and wrist camera are children of the arm.

Gripper (attached directly to the end effector). In the sidebar, click your gripper component to open its card, then click Frame:

{
  "parent": "my-arm",
  "translation": { "x": 0, "y": 0, "z": 0 },
  "orientation": {
    "type": "ov_degrees",
    "value": { "x": 0, "y": 0, "z": 1, "th": 0 }
  }
}

If there is an adapter plate between the arm and gripper, set the z translation to the plate height.

Wrist camera (mounted on the arm, offset from the end effector). In the sidebar, click your wrist camera component to open its card, then click Frame:

{
  "parent": "my-arm",
  "translation": { "x": 0, "y": 30, "z": 60 },
  "orientation": {
    "type": "ov_degrees",
    "value": { "x": 0, "y": 0, "z": 1, "th": 0 }
  }
}

Adjust the translation values to match the camera’s actual mounting position relative to the arm’s end effector. If the camera is tilted, add a rotation. For example, tilted 30 degrees downward:

{
  "orientation": {
    "type": "ov_degrees",
    "value": { "x": 1, "y": 0, "z": 0, "th": -30 }
  }
}

Click Save after adding each frame.

5. Add frames to navigation sensors

Navigation sensors are children of the base, not the arm.

Front-facing navigation camera. In the sidebar, click your front camera to open its card, then click Frame:

{
  "parent": "my-base",
  "translation": { "x": 0, "y": 200, "z": 120 },
  "orientation": {
    "type": "ov_degrees",
    "value": { "x": 0, "y": 0, "z": 1, "th": 0 }
  }
}

LIDAR mounted on top of the base. In the sidebar, click your LIDAR component to open its card, then click Frame:

{
  "parent": "my-base",
  "translation": { "x": 0, "y": 0, "z": 150 },
  "orientation": {
    "type": "ov_degrees",
    "value": { "x": 0, "y": 0, "z": 1, "th": 0 }
  }
}

Adjust translation values to match your sensor mounting positions.

Click Save after adding each frame.

6. Visualize and verify

1. Open the 3D SCENE tab.
2. Confirm the tree structure: arm, gripper, and wrist camera under the base; navigation sensors as direct children of the base.
3. Jog the arm from the CONTROL tab — the single clearest test that your hierarchy is correct. Only the arm subtree should move; the base and navigation sensors should stay put.
4. Drive the base a short distance. Every frame should shift together.
5. Measure a known physical offset (base center to lidar, for example) and compare to the translation values in your config.

7. Verify with TransformPose

Use TransformPose to verify the full chain of transforms. For example, transform the wrist camera’s origin from the camera frame to the world frame. The result should account for the base-to-arm offset, the arm’s current joint positions, and the arm-to-camera offset.

For details on the TransformPose API, see Frame system: TransformPose.

Troubleshooting

What’s next