-
Notifications
You must be signed in to change notification settings - Fork 41
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
DOCS-2889: Turn access arm tutorial into how-to (#3650)
- Loading branch information
1 parent
100547b
commit 6927777
Showing
22 changed files
with
235 additions
and
503 deletions.
There are no files selected for viewing
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,219 @@ | ||
| --- | ||
| title: "Move a robot arm" | ||
| linkTitle: "Move a robot arm" | ||
| weight: 70 | ||
| type: "docs" | ||
| tags: ["arm", "components"] | ||
| images: ["/how-tos/move_to_position.gif"] | ||
| videos: ["/how-tos/move_to_position.webm", "/how-tos/move_to_position.mp4"] | ||
| description: "Connect to a robotic arm and control it with the arm API." | ||
| aliases: | ||
| - /tutorials/motion/accessing-and-moving-robot-arm | ||
| - /tutorials/motion/ | ||
| languages: ["Python", "Go"] | ||
| viamresources: ["arm"] | ||
| platformarea: ["mobility"] | ||
| level: "Intermediate" | ||
| date: "2024-10-31" | ||
| # updated: "" # When the tutorial was last entirely checked | ||
| cost: "8400" | ||
| --- | ||
|
|
||
| In this guide you'll use Viam's Python or Go SDK to get the current position of your robot arm and issue movement commands. | ||
|
|
||
| {{< alert title="In this page" color="tip" >}} | ||
|
|
||
| 1. [Access the arm](#access-the-arm) | ||
| 1. [Move the arm](#move-the-arm) | ||
|
|
||
| {{< /alert >}} | ||
|
|
||
| ## Requirements | ||
|
|
||
| You need the following hardware to complete this tutorial: | ||
|
|
||
| - A single-board computer or other computer to run `viam-server`. | ||
| - A Linux, macOS or Windows computer that can run SDK code. | ||
| - A [robotic arm](/components/arm/). | ||
|
|
||
| ## Access the arm | ||
|
|
||
| {{< table >}} | ||
| {{% tablestep link="/configure/" %}} | ||
| **1. Configure a machine with an arm** | ||
|
|
||
| {{% snippet "setup.md" %}} | ||
|
|
||
| Add an arm component. | ||
| Select a model that supports your arm. Refer to the [documentation for the model](/components/arm/#configuration) for information about your arm's configuration attributes. | ||
|
|
||
| {{<imgproc src="/how-tos/access-arm/config.png" resize="500x" class="fill aligncenter" style="width: 400px" declaredimensions=true alt="Configuration builder UI with a blank arm component">}} | ||
| Save your config. | ||
|
|
||
| {{% /tablestep %}} | ||
| {{% tablestep link="/appendix/apis/components/arm/#getendposition" %}} | ||
| **2. Get the position of the end effector** | ||
|
|
||
| One way to describe the state of a robot arm is with the position of the end effector, or the "tool" or "hand" of the arm. | ||
| The code to get this information is a part of the autogenerated code sample the Viam app provides for your machine. | ||
| Go to the **Code sample** page of the **CONNECT** tab and select either Python or Go. | ||
|
|
||
| {{% snippet "show-secret.md" %}} | ||
|
|
||
| Then, copy and paste the sample code into a file and run the resulting script to see the resources available on your screen and the position of the end effector output as a [`Pose`](/internals/orientation-vector/). | ||
| For more information, see [`GetEndPosition`](/appendix/apis/components/arm/#getendposition). | ||
|
|
||
| {{% /tablestep %}} | ||
| {{% tablestep %}} | ||
| **3. Get the joint positions** | ||
|
|
||
| The state of a robot arm can also be described as the list of positions of each joint attached to the arm. | ||
| To get that information, add the following code right after the code that gets the end effector pose from the prior code sample: | ||
|
|
||
| {{< tabs >}} | ||
| {{% tab name="Python" %}} | ||
|
|
||
| ```python | ||
| # Joint Positions of arm1 | ||
| my_arm_joint_positions = await arm_1.get_joint_positions() | ||
| print(f"myArm get_joint_positions return value: {my_arm_joint_positions}") | ||
| ``` | ||
|
|
||
| {{% /tab %}} | ||
| {{% tab name="Go" %}} | ||
|
|
||
| ```go | ||
| // Joint Positions of arm1 | ||
| myArmJointPositions, err := arm1.JointPositions(context.Background(), nil) | ||
| if err != nil { | ||
| logger.Error(err) | ||
| return | ||
| } | ||
| logger.Infof("myArm JointPositions return value:", myArmJointPositions) | ||
| ``` | ||
|
|
||
| {{% /tab %}} | ||
| {{< /tabs >}} | ||
|
|
||
| Run your code again. | ||
| Each individual value corresponds to the current position of a particular joint on your robot. | ||
| You can also see these values reflected on the **CONTROL** tab in the Viam app for your robot arm. | ||
|
|
||
| {{% /tablestep %}} | ||
| {{< /table >}} | ||
|
|
||
| ## Move the arm | ||
|
|
||
| The two main options for controlling arm movement are through **joint position commands** and through **pose commands**. | ||
| Joint position commands allow for more detailed control and flexibility instead of commanding movement with the end effector position in a pose command. | ||
|
|
||
| {{< alert title="Caution" color="caution" >}} | ||
| Be careful when instructing robot arms to move. | ||
| Before running any code, ensure your robotic arm has enough space and that there are no obstacles. | ||
| Also pay attention to your surroundings, double-check your code for correctness, and make sure anyone nearby is aware and alert before issuing commands to your machine. | ||
| {{< /alert >}} | ||
|
|
||
| {{< table >}} | ||
| {{% tablestep %}} | ||
| **1. Initiate motion with a joint position command** | ||
|
|
||
| {{< tabs >}} | ||
| {{% tab name="Python" %}} | ||
| Add the following line to your import list to be able to assign values to a `JointPositions` data structure: | ||
|
|
||
| ```python | ||
| from viam.proto.component.arm import JointPositions | ||
| ``` | ||
|
|
||
| Add the following code to your script: | ||
|
|
||
| ```python | ||
| # Command a joint position move: move the forearm of the arm slightly up | ||
| cmd_joint_positions = JointPositions(values=[0, 0, -30.0, 0, 0, 0]) | ||
| await arm_1.move_to_joint_positions(positions=cmd_joint_positions) | ||
| ``` | ||
|
|
||
| {{% /tab %}} | ||
| {{% tab name="Go" link="/appendix/apis/components/arm/#movetojointpositions" %}} | ||
| Add `armapi "go.viam.com/api/component/arm/v1"` to your import list. | ||
| Add the following code to your script: | ||
|
|
||
| ```go | ||
| // Command a joint position move: move the forearm of the arm slightly up | ||
| cmdJointPositions := &armapi.JointPositions{Values: []float64{0.0, 0.0, -30.0, 0.0, 0.0, 0.0}} | ||
| err = arm1.MoveToJointPositions(context.Background(), cmdJointPositions, nil) | ||
| if err != nil { | ||
| logger.Error(err) | ||
| return | ||
| } | ||
| ``` | ||
|
|
||
| {{% /tab %}} | ||
| {{< /tabs >}} | ||
|
|
||
| {{<gif webm_src="/how-tos/joint_positions.webm" mp4_src="/how-tos/joint_positions.mp4" alt="The robot arm moving through joint position commands" max-width="200px" class="alignleft">}} | ||
|
|
||
| Run the code. | ||
| The third joint of your arm should move 30 degrees. | ||
| For more information, see [`MoveToJointPositions`](/appendix/apis/components/arm/#movetojointpositions). | ||
|
|
||
| {{% /tablestep %}} | ||
| {{% tablestep link="/appendix/apis/components/arm/#movetoposition" %}} | ||
| **2. Command to move to position** | ||
|
|
||
| {{< tabs >}} | ||
| {{% tab name="Python" %}} | ||
|
|
||
| Add the following code to your script: | ||
|
|
||
| ```python | ||
| # Generate a simple pose move +100mm in the +Z direction of the arm | ||
| cmd_arm_pose = await arm_1.get_end_position() | ||
| cmd_arm_pose.z += 100.0 | ||
| await arm_1.move_to_position(pose=cmd_arm_pose) | ||
| ``` | ||
|
|
||
| {{% /tab %}} | ||
| {{% tab name="Go" %}} | ||
| Add `"go.viam.com/rdk/spatialmath"` to your import list. | ||
|
|
||
| Add the following code to your script: | ||
|
|
||
| ```go | ||
| // Generate a simple pose move +100mm in the +Z direction of the arm | ||
| currentArmPose, err := arm1.EndPosition(context.Background(), nil) | ||
| if err != nil { | ||
| logger.Error(err) | ||
| return | ||
| } | ||
| adjustedArmPoint := currentArmPose.Point() | ||
| adjustedArmPoint.Z += 100.0 | ||
| cmdArmPose := spatialmath.NewPose(adjustedArmPoint, currentArmPose.Orientation()) | ||
|
|
||
| err = arm1.MoveToPosition(context.Background(), cmdArmPose, nil) | ||
| if err != nil { | ||
| logger.Error(err) | ||
| return | ||
| } | ||
| ``` | ||
|
|
||
| {{% /tab %}} | ||
| {{< /tabs >}} | ||
|
|
||
| {{<gif webm_src="/how-tos/move_to_position.webm" mp4_src="/how-tos/move_to_position.mp4" alt="A robot arm moving to a commanded position" max-width="200px" class="alignright">}} | ||
|
|
||
| This code gets the arm's end position, makes a 100 millimeter adjustment in the +Z direction, and then uses that adjustment as a goal [`Pose`](/internals/orientation-vector/) when commanding arm motion. | ||
| Run the code to see your arm move 100 mm upwards. | ||
| For more information, see [`MoveToPosition`](/appendix/apis/components/arm/#movetoposition). | ||
|
|
||
| {{% /tablestep %}} | ||
| {{< /table >}} | ||
|
|
||
| ## Next steps | ||
|
|
||
| {{< cards >}} | ||
| {{% card link="/tutorials/services/plan-motion-with-arm-gripper" %}} | ||
| {{% card link="/tutorials/projects/claw-game/" %}} | ||
| {{< /cards >}} | ||
|
|
||
| For more resources on robot kinematics, read through the Wikipedia pages for [Forward kinematics](https://en.wikipedia.org/wiki/Forward_kinematics) and [Inverse kinematics](https://en.wikipedia.org/wiki/Inverse_kinematics). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.