diff --git a/assets/operate/mobility/capsule.png b/assets/operate/mobility/capsule.png new file mode 100644 index 0000000000..28d261742e Binary files /dev/null and b/assets/operate/mobility/capsule.png differ diff --git a/assets/operate/mobility/gripper-frame.png b/assets/operate/mobility/gripper-frame.png new file mode 100644 index 0000000000..8b43891f76 Binary files /dev/null and b/assets/operate/mobility/gripper-frame.png differ diff --git a/docs/dev/reference/changelog.md b/docs/dev/reference/changelog.md index b9c3162323..1ca9173032 100644 --- a/docs/dev/reference/changelog.md +++ b/docs/dev/reference/changelog.md @@ -63,7 +63,7 @@ Organization owners and location owners can now move machines between locations {{% changelog color="removed" title="Frame tab removed, use Add Frame button" date="2025-05-15" %}} The frame tab no longer exists. -To add a frame to a component, click the **+ Add Frame** button on the component's configuration card. +To add a frame to a component, click the **+ Add frame** button on the component's configuration card. {{% /changelog %}} diff --git a/docs/dev/reference/glossary/origin-frame.md b/docs/dev/reference/glossary/origin-frame.md new file mode 100644 index 0000000000..7914503a40 --- /dev/null +++ b/docs/dev/reference/glossary/origin-frame.md @@ -0,0 +1,16 @@ +--- +title: Origin frame +id: origin-frame +full_link: +short_description: The origin frame is the frame at the base of an arm or other component that has a complex kinematics chain. +--- + +The origin frame is the frame at the base of an arm, gantry, or other component that has a complex kinematics chain. +This is typically the point at the center of where the component is mounted to a table or stand. + +Every component that has a kinematics chain has an origin frame and an end effector frame, for example `my_arm_origin` and `my_arm`. + +If you parent a gripper to the arm's `my_arm` frame, the frame system will know the gripper is at the end of the arm. +If you mistakenly parent the gripper to the arm's `my_arm_origin` frame, the frame system will think the gripper is at the base of the arm, and the gripper will not move when you move the arm. + +For more information, see [How the frame system works](/operate/reference/services/frame-system/#how-the-frame-system-works). diff --git a/docs/dev/reference/glossary/world-frame.md b/docs/dev/reference/glossary/world-frame.md new file mode 100644 index 0000000000..e9aed4e327 --- /dev/null +++ b/docs/dev/reference/glossary/world-frame.md @@ -0,0 +1,14 @@ +--- +title: World frame +id: world-frame +full_link: /operate/mobility/move-arm/frame-how-to/ +short_description: The fixed, user-defined global coordinate system that is the reference point for all other coordinate frames in a robotic system. +aka: world frame, world +--- + +The world reference [frame](/operate/reference/services/frame-system/) is the fixed, global coordinate system that serves as the reference point for all other coordinate frames in a robotic system. +It provides a consistent basis for describing the position and orientation of robots, components, and objects in the physical space. +All other coordinate frames (like robot frames, component frames, etc.) are defined relative to this world frame, either directly or through a chain of transformations. + +The user chooses the world frame, and defines it implicitly. +For example, if you have a robot arm mounted on a table and you define the arm's base frame as the world frame, then the arm's base frame is the origin of the world frame. diff --git a/docs/operate/_index.md b/docs/operate/_index.md index 155a1a9efb..391bfd5f12 100644 --- a/docs/operate/_index.md +++ b/docs/operate/_index.md @@ -43,8 +43,9 @@ To get started, install Viam on any device and integrate your hardware. Then you {{< /cards >}} {{< /how-to-expand >}} -{{< how-to-expand "Intelligent actuation and motion planning" "3" "INTERMEDIATE" "" "build-platform-motion" >}} +{{< how-to-expand "Intelligent actuation and motion planning" "4" "INTERMEDIATE" "" "build-platform-motion" >}} {{< cards >}} +{{% card link="/operate/mobility/motion-concepts/" noimage="true" %}} {{% card link="/operate/mobility/move-arm/" noimage="true" %}} {{% card link="/operate/mobility/move-base/" noimage="true" %}} {{% card link="/operate/mobility/move-gantry/" noimage="true" %}} diff --git a/docs/operate/get-started/other-hardware/_index.md b/docs/operate/get-started/other-hardware/_index.md index 79a5319431..4055ea4087 100644 --- a/docs/operate/get-started/other-hardware/_index.md +++ b/docs/operate/get-started/other-hardware/_index.md @@ -5,5 +5,6 @@ layout: "empty" type: "docs" empty_node: true open_on_desktop: true +description: "Integrate other hardware or software by creating a module." canonical: "/operate/get-started/other-hardware/create-module/" --- diff --git a/docs/operate/mobility/motion-concepts.md b/docs/operate/mobility/motion-concepts.md index a13bceefda..89a61267b4 100644 --- a/docs/operate/mobility/motion-concepts.md +++ b/docs/operate/mobility/motion-concepts.md @@ -39,12 +39,14 @@ You can use the following components to augment motion planning and navigation: ## The frame system -Viam's [frame system](/operate/reference/services/frame-system/) is a way to describe the spatial relationship between the components in your robot. -The motion service uses the frame system to plan the motion of components. +Viam's [frame system](/operate/reference/services/frame-system/) allows you to describe the spatial relationship between the components in your robot. +You configure your machine's frames once, and Viam keeps track of the frames as they move. +This means you can send motion service commands using a consistent coordinate system, regardless of where the components are at a given time. -For example, if you want to command an arm to move to coordinates of `(300, 0, 0)` millimeters, you first need to define the origin `(0, 0, 0)` of the coordinate system and the directions of the x, y, and z axes to give those coordinates meaning. +You must configure frames before you can use the motion service. +For example, if you want to command an arm to move to coordinates of `(300, 0, 0)` millimeters, you first need to decide on the origin `(0, 0, 0)` and the directions of the x, y, and z axes of the {{< glossary_tooltip term_id="world-frame" text="world" >}} coordinate system to give your coordinates meaning. -To give the necessary context, you define the arm's `frame` to describe its position and orientation relative to the world. +You then define the arm's `frame` to describe its position and orientation relative to the world frame. If you also have a gripper component, you define the gripper's `frame` to describe its position and orientation relative to the arm, so that when the arm moves, the motion service knows where the gripper is as well. ### Visualize components and frames diff --git a/docs/operate/mobility/move-arm/arm-motion.md b/docs/operate/mobility/move-arm/arm-motion.md index 69d9942489..ad85dc6dbf 100644 --- a/docs/operate/mobility/move-arm/arm-motion.md +++ b/docs/operate/mobility/move-arm/arm-motion.md @@ -9,6 +9,7 @@ aliases: - /how-tos/move-robot-arm/ - /tutorials/motion/accessing-and-moving-robot-arm/ - /tutorials/motion/ + - /operate/mobility/move-arm/arm-no-code/ date: "2025-05-21" --- @@ -142,7 +143,7 @@ The available geometry types are: | Geometry type | Description | Dimensions to define | | ------------- | ----------- | ------------------ | | box | A rectangular prism. | `x`, `y`, `z`: length in each direction in mm. | -| capsule | A cylinder with hemispherical end caps. | `radius` in mm, `length` in mm between the centers of the hemispherical end caps. | +| capsule | A cylinder with hemispherical end caps. | `radius` in mm, overall `length` in mm. | | sphere | A sphere. | `radius` in mm. | | mesh | A 3D model defined by a mesh. | `triangles`: a list of triangles, each defined by three vertices. | @@ -317,7 +318,7 @@ Follow the steps below to construct the necessary objects and pass them to `Move {{< /tabs >}} {{% alert title="Tip" color="tip" %}} - To get a better intuition for poses and where you want the arm to move, try [driving the arm manually with the control interface](/operate/mobility/move-arm/arm-no-code/) and notice how the pose indicated in the control interface corresponds to the arm's position in the real world. + To get a better intuition for poses and where you want the arm to move, try driving the arm manually from the **CONTROL** tab or **TEST** panel and notice how the pose indicated in the control interface corresponds to the arm's position in the real world. You can also [use the **VISUALIZE** tab](/operate/reference/services/frame-system/#visualize-components-and-frames) to see a representation of your arm's geometry and reference frames. {{% /alert %}} diff --git a/docs/operate/mobility/move-arm/arm-no-code.md b/docs/operate/mobility/move-arm/arm-no-code.md deleted file mode 100644 index c17dcd06b6..0000000000 --- a/docs/operate/mobility/move-arm/arm-no-code.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "Move an arm without code" -linkTitle: "Move an arm with no code" -weight: 30 -type: "docs" -layout: "docs" -description: "Move an arm without code using the web UI." -date: "2025-05-21" ---- - -{{}} - -You can move an arm without code using the web UI. -This is a good way to quickly test that your arm is working before writing code to move it. - -This is also a good way to confirm the directions of the x, y, and z axes of your arm. - -## Prerequisites - -{{< expand "A running machine connected to Viam." >}} - -{{% snippet "setup.md" %}} - -{{< /expand >}} - -{{< expand "Set up your arm hardware." >}} - -1. Mount your arm to a stable structure. - -1. Ensure there is enough space for the arm to move without hitting obstacles, people, or pets. - -1. Ensure the arm is connected to power, and to the computer running `viam-server`. - -{{< /expand >}} - -{{< expand "Configure your arm." >}} - -See [Configure an arm](/operate/mobility/move-arm/configure-arm/) for instructions. - -{{< /expand >}} - -## Move the arm - -1. Navigate to your machine's page. - -1. On your arm component's configuration card, select the **TEST** tab. - - {{% alert title="Caution" color="caution" %}} - Be careful when moving your robot arm. - Before moving the arm, ensure it has enough space and that there are no obstacles or people near the arm. - -Keep in mind: - -- Moving joints near the base of the arm even a few degrees can cause the end of the arm to move a significant distance. -- Moving the arm to a new pose can cause the arm to move in unexpected ways. - -{{% /alert %}} - -1. Enter joint positions or end effector poses, then click **Execute**. - Or, use the **Quick move** interface to move each joint in 5 degree increments. - - {{}} - - {{% alert title="Info" color="info" %}} - -The web UI uses the [arm API](/dev/reference/apis/components/arm/) to move the arm. -You can also use the arm API to move the arm in code, though it is not recommended for complex movements because it does not take into account obstacles or allow for complex motion planning. - -{{% /alert %}} - -1. To refresh the numbers in the **MoveToJointPositions** or **MoveToPosition** tables, click **Current position**. - -1. To confirm the directions of the x, y, and z axes of your arm, move the arm in each direction and note which way the arm moves in the real world. - It can be useful to label the axes on your workspace, for example with tape or markers. - -1. You can also use the **VISUALIZE** tab to see a representation of your arm's geometry and reference frames. diff --git a/docs/operate/mobility/move-arm/configure-additional.md b/docs/operate/mobility/move-arm/configure-additional.md index b2cf9e9f1b..5074a172c2 100644 --- a/docs/operate/mobility/move-arm/configure-additional.md +++ b/docs/operate/mobility/move-arm/configure-additional.md @@ -2,7 +2,7 @@ title: "Configure components attached to your arm" linkTitle: "Configure additional components" description: "Configure additional components such as grippers, cameras, and other sensors attached to your arm." -weight: 20 +weight: 30 type: "docs" layout: "docs" aliases: @@ -18,25 +18,28 @@ If you have a gripper, camera, or other components attached to your arm, you can You can also take into account passive objects attached to the arm such as a camera mount to avoid collisions. -## Configure a gripper +## Configure a gripper's frame If you have a gripper, you can configure it to move with the arm. -See [Configure a gripper](/operate/reference/components/gripper/) for instructions on configuring the gripper itself. -Then, configure the gripper's frame to describe its position and orientation relative to the arm: +Configure the gripper's frame to describe its position and orientation relative to the arm: + +1. See [Configure a gripper](/operate/reference/components/gripper/) for instructions on configuring the gripper itself. 1. In the **CONFIGURE** tab, find the gripper's configuration card. -1. Click **+ Add Frame**. +1. Click **+ Add frame**. 1. Select the arm's frame as the parent frame. -1. Enter the gripper origin's position and orientation relative to the center of the end of the arm. - It is up to you to decide what part of the gripper you want to use as the origin of the frame. - It is common to use a central point near the base of the gripper jaws as the origin. +1. Enter the gripper frame's position and orientation relative to the center of the end of the arm. + It is up to you to decide what part of the gripper you want to use as the gripper frame. + It can be convenient to use a point near the center of the gripper jaws as the gripper frame. + + When you make a call to the motion service to move the gripper to a location, the point you specify in this step is the part of the gripper that will move to that location. - {{}} + {{}} - For example, the gripper in the image above has a translation of 110 millimeters in the z-direction, and it is oriented along the same z-axis as the end of the arm but is rotated 90 degrees around the z-axis, so its frame configuration is: + The gripper in the image above has a translation of 110 millimeters in the z-direction, and it is oriented along the same z-axis as the end of the arm but is rotated 90 degrees around the z-axis, so its frame configuration is: ```json {class="line-numbers linkable-line-numbers"} { @@ -58,15 +61,26 @@ Then, configure the gripper's frame to describe its position and orientation rel } ``` +1. Check whether your gripper has a kinematics file. + + Some grippers have [kinematics files](/operate/reference/kinematic-chain-config/) that describe the position and orientation of the jaws of the gripper as they move, relative to the gripper's base. + This file typically also contains geometries to represent the gripper's volume and avoid collisions between the gripper and its environment. + You can check whether your gripper has a kinematics file by looking in its module source code, or by using the [`GetKinematics` method](/dev/reference/apis/components/gripper/). + + If you have a kinematics file, you do not need to add any geometries to the gripper's frame, assuming the gripper appears as expected in the **VISUALIZE** tab. + + _If you do not have a kinematics file, see [Configure the geometry of the object](#configure-the-geometry-of-the-object) to configure a geometry for the gripper to avoid collisions between the gripper and its environment._ + ## Configure a camera -If you have a camera that can see the environment, first configure the camera itself. -For example, you can use an Intel Realsense camera by configuring the `realsense` component according to its [documentation](https://app.viam.com/module/viam/realsense). -Then, configure the camera's frame to describe its position and orientation relative to the arm: +If you have a camera that can see the environment, configure the camera's frame to describe its position and orientation relative to the arm so that what the camera sees can be used to plan the arm's motion: + +1. Configure the camera itself. + For example, you can use an Intel Realsense camera by configuring the `realsense` model of the camera component according to its [documentation](https://app.viam.com/module/viam/realsense). 1. In the **CONFIGURE** tab, find the camera's configuration card. -1. Click **+ Add Frame**. +1. Click **+ Add frame**. 1. Edit the frame depending on where the camera is mounted: @@ -88,5 +102,150 @@ Then, configure the camera's frame to describe its position and orientation rela If you have a passive object attached to the arm such as a camera mount, you will want the motion service to be aware of it to avoid collisions. -You do not need to configure the object as a component, because you won't be interacting with it through a Viam API. -Instead, you will pass it as a _transform_ object when you call the `Move` motion service API method. +- If you have an object that is sometimes attached to the arm and sometimes not, for example an object that your gripper picks up, you can pass it as a _transform_ object when you call the `Move` motion service API method. + This is covered in the [move an arm guide](/operate/mobility/move-arm/arm-motion/#define-the-geometry-of-the-environment). +- If your object is always attached to the arm, you can configure it as a fake, generic component with a geometry by following the instructions in this section: + +### Add the component and frame + +1. In the **CONFIGURE** tab, click the **+** button > **Component or service** > **generic**. + +1. Select **fake** component (do not select service; services do not have geometries). + +1. Enter a name and click **Create**. + +1. Click **+ Add frame**. + +1. Set the parent frame to the name of the arm or gripper, depending on where the object is attached. + +### Configure the geometry of the object + +1. Copy the following geometry template into the frame configuration, depending on your object's shape: + + {{< tabs >}} + {{% tab name="Box" %}} + + A rectangular prism with dimensions `x`, `y`, and `z` in millimeters. + + ```json {class="line-numbers linkable-line-numbers"} + "geometry": { + "type": "box", + "x": 80, + "y": 250, + "z": 200 + } + ``` + + {{% /tab %}} + {{% tab name="Capsule" %}} + + A cylinder with hemispherical end caps. + `r` is the radius of the cylinder, and `l` is the overall length of the cylinder in millimeters. + + ```json {class="line-numbers linkable-line-numbers"} + "geometry": { + "type": "capsule", + "r": 20, + "l": 160 + } + ``` + + {{}} + + {{% /tab %}} + {{% tab name="Sphere" %}} + + A sphere with radius `r` in millimeters. + + ```json {class="line-numbers linkable-line-numbers"} + "geometry": { + "type": "sphere", + "r": 90 + } + ``` + + {{% /tab %}} + {{< /tabs >}} + +1. Edit the dimensions to match your object's dimensions. + +1. The origin of the geometry is at its center. + + Set the translation of the object's origin relative to its parent frame. + For example, if you have a capsule of length `160` and you want it to begin at the origin of the parent frame, set the translation to `"z"=80`. + +1. Click **Save**. + +1. Check that the object appears as expected in the **VISUALIZE** tab. + +1. If you need to change the object's orientation, you can make changes to the orientation, save the config, and return to the **VISUALIZE** tab to see the changes. + It can be helpful to understand the following: + + {{< tabs >}} + {{% tab name="Box" %}} + + The z-axis of a box is along its z-dimension and so forth with the x and y axes. + If your box is at a right angle to how you want it to be oriented, try changing the dimensions to match the correct directions. + + If you need to rotate the box about its z-axis, edit theta (`th`) to the desired angle and check the **VISUALIZE** tab to see the changes. + + To point the box's z-axis in a different direction, for example at a 30 degree angle from the parent frame's x-axis in the x-y plane, you can change its orientation to: + + ```json {class="line-numbers linkable-line-numbers"} + "orientation": { + "type": "ov_degrees", + "value": { + "th": 0, + "x": 0.866, + "y": 0.5, + "z": 0 + } + } + ``` + + Go to the **VISUALIZE** tab to see the changes. + + {{% /tab %}} + {{% tab name="Capsule" %}} + + The z-axis of a capsule is along its length. + + If, for example, you need the length of the capsule to be along the x-axis, you can change its orientation to: + + ```json {class="line-numbers linkable-line-numbers"} + "orientation": { + "type": "ov_degrees", + "value": { + "th": 0, + "x": 1, + "y": 0, + "z": 0 + } + } + ``` + + Go to the **VISUALIZE** tab to see that the z-axis of the capsule is now aligned with the parent frame's x-axis, 90 degrees from its original orientation. + + If you need the capsule to be aligned at a 45 degree angle between y and z, you can change its orientation to: + + ```json {class="line-numbers linkable-line-numbers"} + "orientation": { + "type": "ov_degrees", + "value": { + "th": 0, + "x": 0, + "y": 1, + "z": 1 + } + } + ``` + + You should not need to modify theta (`th`) for capsules since that would spin the round capsule around its axis, causing no meaningful change. + + {{% /tab %}} + {{% tab name="Sphere" %}} + + A sphere's orientation generally does not need to be changed. + + {{% /tab %}} + {{< /tabs >}} diff --git a/docs/operate/mobility/move-arm/configure-arm.md b/docs/operate/mobility/move-arm/configure-arm.md index 563259b96d..8257aec813 100644 --- a/docs/operate/mobility/move-arm/configure-arm.md +++ b/docs/operate/mobility/move-arm/configure-arm.md @@ -4,10 +4,12 @@ linkTitle: "Configure an arm" weight: 10 type: "docs" layout: "docs" -description: "Configure an arm including its reference frame." +description: "Configure an arm component to use your robotic arm with Viam." date: "2025-05-21" --- +Configure an [arm component](/operate/reference/components/arm/) to use your robotic arm with Viam. + ## Prerequisites {{< expand "A running machine connected to Viam." >}} @@ -49,90 +51,4 @@ date: "2025-05-21" ``` 1. You will need a reference frame to use your arm with the motion planning service. - Click **+ Add frame**. - - For a project with a single arm, you can define the arm's frame as being the same as the world frame, so leave the default values: - - ```json {class="line-numbers linkable-line-numbers"} - { - "orientation": { - "type": "ov_degrees", - "value": { - "th": 0, - "x": 0, - "y": 0, - "z": 1 - } - }, - "parent": "world", - "translation": { - "x": 0, - "y": 0, - "z": 0 - } - } - ``` - -1. Save your configuration. - -## Configure a different reference frame - -For a project with multiple arms, you can define a different [reference frame](/operate/reference/services/frame-system/) for each arm. -To use a reference frame for your arm that is different from the default world frame: - -1. Configure the arm as above, adding a frame with the **+ Add frame** button. - -1. Edit your arm's frame according to your needs. - The frame parameters are: - - - `parent`: The parent frame. - You can use the `world` frame, or another frame you have defined. - - For example, if you have an arm mounted on a gantry, you can use the gantry's frame as the parent frame of the arm by setting `"parent": "name-of-your-gantry"`. - This will cause the arm's frame to be updated as the gantry moves. - - - `orientation`: The orientation of the frame relative to the parent frame, represented as a vector. - If you use the default values, the frame is aligned with the parent frame. - - `translation`: The distance between the frame and the parent frame in each direction, in millimeters. - -1. Confirm the x, y, and z axes of the arm by moving it in each direction using the **TEST** tab. - -### Example: Two arms mounted on a table - -Imagine you have two arms mounted on a table, some distance apart. - -{{}} - -1. You define the frame of one arm to be at the same origin as the world frame. -1. You move the arm in each direction using the web UI and see that positive x is to the right, positive y is forward, and positive z is up. - You label the world frame axes on the table with tape for your reference. -1. You measure the distance between the two arms. - The second arm is 200mm to the left of the first arm, so `"y": 200`. -1. The second arm is facing towards the first arm. - By the right-hand rule, this means that the second arm is rotated negative 90 degrees around its z axis: `"th": -90`. - You edit the second arm's frame to reflect this: - - ```json {class="line-numbers linkable-line-numbers"} - { - "orientation": { - "type": "ov_degrees", - "value": { - "th": -90, - "x": 0, - "y": 0, - "z": 1 - } - }, - "parent": "world", - "translation": { - "x": 0, - "y": 200, - "z": 0 - } - } - ``` - - Because you aligned the first arm's origin frame with the world frame, the second arm's parent could be world or the first arm's origin frame (for example, `arm_1_origin`) with no difference in function. - -1. You check that the second arm's frame is configured correctly by moving it in each direction using web UI and confirming that it moves as expected. - When you move it in the positive x direction, it should move towards the first arm. + Continue to [Configure your frame system](/operate/mobility/move-arm/frame-how-to/). diff --git a/docs/operate/mobility/move-arm/frame-how-to.md b/docs/operate/mobility/move-arm/frame-how-to.md new file mode 100644 index 0000000000..d3ac666cf5 --- /dev/null +++ b/docs/operate/mobility/move-arm/frame-how-to.md @@ -0,0 +1,96 @@ +--- +title: "Configure your frame system" +linkTitle: "Configure your frame system" +weight: 20 +type: "docs" +layout: "docs" +description: "Decide on and configure the frames of your arm, its workspace, and other components." +--- + +Frames can be confusing. +This guide will help you decide on a coordinate system for your workspace, and then determine how the frames of your arm and other components relate to that workspace. + +Once you have configured frames for all your components, Viam will keep track of the positions and orientations as your robot moves, so you can plan motion in terms of a consistent coordinate system. + +For reference information, see [the frame system](/operate/reference/services/frame-system/). + +## Determine the world frame + +The world reference frame is the fixed coordinate system that serves as the reference point for the other frames in your robotic system. + +You choose the world frame, in whatever way is convenient for your application. +It generally makes sense to define the world frame's location as a point in your space that does not move and is easy to measure from. + +For example, if you are using a robot arm mounted to a table, it can be convenient to define the arm's base frame as equal to the world frame, or you can define the world frame as one corner of the table that the arm is mounted to. + +You do not explicitly configure the world frame. +You define it implicitly by configuring the frame of a component relative to world. + +### Add a frame to your arm + +1. Mount the arm in a fixed location. +1. On your arm's configuration card, click **+ Add frame**. +1. The card will populate with the following default values: + + ```json {class="line-numbers linkable-line-numbers"} + { + "orientation": { + "type": "ov_degrees", + "value": { + "x": 0, + "y": 0, + "z": 1, + "th": 0 + } + }, + "parent": "world", + "translation": { + "x": 0, + "y": 0, + "z": 0 + } + } + ``` + + This [orientation vector](/operate/mobility/orientation-vector/) of `x=0, y=0, z=1, th=0` means the frame is aligned with the world frame, and the `0, 0, 0` translation means the arm's {{< glossary_tooltip term_id="origin-frame" text="origin frame" >}} is coincident with the origin of the world frame. + You can think of it like this: The z-axis of the arm's origin frame is parallel to the z-axis of the world frame, and the origin of the arm's origin frame is in the same place as the origin of the world frame. + + If you want to define the world frame as the corner of the table, leave the default values for now, and continue to the next step so that you know which way `x` and `y` point and can edit the configuration accordingly. + +1. Click **Save**. + + By configuring your arm's frame like this, you have now defined the world frame as the same as the arm's base frame. + +### Figure out which way the arm's axes point + +The arm's base frame is now the world frame, but you do not know which way the x, y, and z axes of the arm frame point, unless you happen to be familiar with the arm's [kinematics file](/operate/reference/kinematic-chain-config/). + +1. On your arm's configuration card, click the **TEST** section (or use the **CONTROL** tab). + +1. Move the arm in each direction and note which way the arm moves. + For example, under the **MoveToPosition** section, move the arm in the positive Z direction. + If it moves upwards, then you know that the z-axis of the arm frame points upwards. +1. If the directions do not match your intended world frame, you can edit the arm's `orientation` field to rotate the arm frame to match your intended world frame. + For example, if the arm's x-axis points to the right, but you want it to point to the left, you can set the `orientation` field to `"x"=0, "y"=0, "z"=1, "th"=180`. + +1. For your reference, mark the X, Y, and Z axes of the world frame on your workspace with tape or a marker. + +### Add a frame offset + +If you want to define the world frame as the corner of the table, you can now edit the arm's frame to be offset from the world frame by the distance from the table corner to the arm's base: + +1. Measure the X and Y distance from your designated table corner to the center of the arm's base. +1. Edit the arm's frame configuration to set the `translation` field accordingly. + For example, if the arm's base is 100mm in the X direction and 200mm in the Y direction from the table corner, set the `translation` field to `"x"=100, "y"=200, "z"=0`. + If you chose not to align the arm's axes with the world axes, be sure to use the X, Y, and Z directions of the _world_ frame to set the `translation` field. +1. Click **Save**. + + The arm's frame is now offset from the world frame by the distance from the table corner to the arm's base. + +## Other ways to define the world frame + +If none of your components are fixed in place, it might make sense to define the world frame as the frame of the first component you add to your robot, for example, the mobile base. + +## Visualize components and frames + +{{< readfile "/static/include/snippet/visualize.md" >}} diff --git a/docs/operate/reference/components/arm/_index.md b/docs/operate/reference/components/arm/_index.md index 4c3468ed92..bd4f53fe44 100644 --- a/docs/operate/reference/components/arm/_index.md +++ b/docs/operate/reference/components/arm/_index.md @@ -29,6 +29,8 @@ When controlling an arm, you can place its end effector at arbitrary cartesian p ## Configuration +For a full guide, see [Configure an arm](/operate/mobility/move-arm/configure-arm/). + To use a robotic arm, you need to add it to your machine's configuration. Go to your machine's **CONFIGURE** page, and add a model that supports your arm. diff --git a/docs/operate/reference/services/frame-system/_index.md b/docs/operate/reference/services/frame-system/_index.md index 000f77bcd2..b4683643f1 100644 --- a/docs/operate/reference/services/frame-system/_index.md +++ b/docs/operate/reference/services/frame-system/_index.md @@ -37,16 +37,17 @@ It is a mostly static system for storing the "reference frame" of each component ## Configuration +For a full how-to guide, see [Configure your frame system](/operate/mobility/move-arm/frame-how-to/). + You can configure a reference frame within the frame system for each of your machine's components: 1. Navigate to the **CONFIGURE** tab of your machine's page. -1. Select **Builder** mode and [configure your arm](/operate/reference/components/arm/#configuration). - If you don't have a physical arm, you can use a `fake` model. +1. Find the configuration card for the component you want to add a frame to. -1. Click **+ Add Frame**. +1. Click **+ Add frame**. -1. Edit the frame configuration. +1. Leave the default values, or edit the frame configuration. The frame configuration is a JSON object with the following parameters: @@ -157,8 +158,6 @@ For non base components, there is no inherent concept of "forward," so it is up {{% /alert %}} -For an example of configuring relative frames of two arms, see [Configure a different reference frame](/operate/mobility/move-arm/configure-arm/#configure-a-different-reference-frame). - ## How the frame system works `viam-server` builds a tree of reference frames for your machine with the `world` as the root node and regenerates this tree following reconfiguration. diff --git a/docs/operate/reference/services/navigation/_index.md b/docs/operate/reference/services/navigation/_index.md index c43aa7d57c..557ab0b2bf 100644 --- a/docs/operate/reference/services/navigation/_index.md +++ b/docs/operate/reference/services/navigation/_index.md @@ -178,7 +178,7 @@ To make sure your rover base's autonomous GPS navigation with the navigation ser Add [reference frames](/operate/reference/services/frame-system/#configuration) to your rover [base](/operate/reference/components/base/) and [movement sensor](/operate/reference/components/movement-sensor/) configurations: - Navigate to the **CONFIGURE** tab of your machine's page. -- Find your base configuration card and click **+ Add Frame**. +- Find your base configuration card and click **+ Add frame**. - Since you haven't adjusted any parameters yet, the default reference frame will be shown for your base: {{}} @@ -192,7 +192,7 @@ Add [reference frames](/operate/reference/services/frame-system/#configuration) {{}} -- Add a frame to your movement sensor configuration by clicking **+ Add Frame**. +- Add a frame to your movement sensor configuration by clicking **+ Add frame**. - Set the `parent` within the frame card to the name of your base. - Give the movement sensor a `translation` that reflects where it is mounted on your base, measuring the coordinates with respect to the origin of the base. In other words, designate the base origin as `(0,0,0)` and measure the distance between that and the origin of the sensor to obtain the coordinates. diff --git a/static/include/snippet/visualize.md b/static/include/snippet/visualize.md index a4d66fa6d7..798897804c 100644 --- a/static/include/snippet/visualize.md +++ b/static/include/snippet/visualize.md @@ -11,6 +11,8 @@ To visualize a component without moving any real-world hardware, configure a `fa {{}} +1. Scroll to zoom, click and drag to tilt, and right-click and drag to pan. + 1. Use the tree menu or click on the visualization to select a component, link, or other object to display its position, orientation, and dimensions. 1. You can go to the **CONTROL** tab, move your components, and then return to the **VISUALIZE** tab to see the updated visualization.