DOCS-3944: Restructure motion docs #4279
Conversation
viambot
added
the
safe to build
✅ Deploy Preview for viam-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
JessamyT
force-pushed
the
3944motion
branch
2 times, most recently
from
b0db1ab to
cacfdc3
Compare
There was a problem hiding this comment.
To be replaced by prettier diagram; this is a mockup placeholder
| @@ -0,0 +1,73 @@ | |||
| --- | |||
| title: "Move an arm without code" | |||
There was a problem hiding this comment.
- I think the configure an arm page should just say "Confirm the x, y, and z axes of the arm by moving it in each direction using the Test tab." If we need to do more than that then we should add additional instructions in the app itself I think.
- Removing this page would also improve the flow of these pages: configure arm -> configure additional things -> move with motion planning. As you have it now people are almost required to after configuring the arm jump to move with no code, and then they get lost.
There was a problem hiding this comment.
So, it is pretty key that they do that to get an intuition for which direction is which, rather than just jumping straight to sending commands without really understanding what the commands will do, especially without the viz tab but even then. I wouldn't consider landing on this page to be lost; this is part of the intended flow. Maybe it's overkill? But it deserves more than a single sentence I'd think.
There was a problem hiding this comment.
This isn't a merge blocker, so read this and then either merge or make the change and then merge.
I don't disagree with you that that's important. I just don't know that it is big enough to require a page, rather than just being part of the config flow as something like
{{< alert title="Tip" color="tip" >}}
We recommend you open the **Test** panel to and to 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.
{{< /alert >}}
Specifically I am concerned that if you think this page is needed, does that mean the UI is unusable without detailed instructions.
If I look at the page the additional bits that aren't covered in the two sentences above are:
- the caution note - and I wonder if that should be with the arm test tab if it is important enough.
- "Enter joint positions or end effector poses, then click Execute. Or, use the Quick move interface to move each joint in 5 degree increments." - do we not expect that to be obvious from opening the test panel? If not maybe the test panel needs these instructions.
- A link to the arm API and a note that it's not recommended to use it for complex movements. - could probably be added to either motion planning page or configuration page or skipped if it's not recommended anyway.
- What clicking Current position does (UI issue if that's needed).
Do you see what I mean?
With the flow also - don't you need to test before you configure additional components? That's what I mean with the flow leading to you get lost, you configure an arm then you configure end effectors, then you test and I'd assume you may have to go back to configuration. And then you're jumping between these pages and are no longer "flowing" through these pages.
There was a problem hiding this comment.
I see what you mean.
Though, one reason to include the move arm with no code as a left heading is that it makes it more discoverable/if someone is scanning the docs they'll quickly say "oh nice I can easily test my arm without getting into the weeds. This gets into docs philosophy a bit so curious what you think about surfacing features in this way. Certainly if it actually truly impedes the flow of someone getting something done, we wouldn't want to do that. But if it was hypothetically neutral to the flow?
Another idea: Replace this with a page that is basically "Determine your frame system" that talks about using the test panel, the viz tab (hopefully dropping tomorrow) and how to understand this confusing topic. Using the test panel would just become part of that flow at various points.
Curious what @EshaMaharishi thinks
There was a problem hiding this comment.
I see the point about wanting app to be self-explanatory, but I do think sometimes people scan docs to understand the capabilities before trying things out, so personally I think it's useful to have the "move an arm with no code" content in the docs. I also agree it helps discoverability - if someone sees the expanded test section and viz tool in the docs, they're more likely to try it out in app.
I don't have strong thoughts on where the content lives within the "Move an arm" section though - a "Determine your frame system" (or maybe "Visualize and move an arm"?) sounds good, or another option could be to put it at the bottom of the "Configure an arm" page.
npentrel
left a comment
npentrel
left a comment
There was a problem hiding this comment.
Good work, this does make it easier to step through it. I think the main feedback is that I think we should get rid of the page about moving an arm without code and the move an arm page content.
|
|
||
| - Use the Viam app to move the arm with a no-code interface. | ||
| - Useful for getting started and quick testing. | ||
| - Use the arm API to move the arm with code. |
There was a problem hiding this comment.
This isn't really covered now, do we want to show this?
There was a problem hiding this comment.
It was intentional to not cover the arm API other than within the app interface, because it doesn't include obstacle avoidance etc. so using it is generally an antipattern
| Consider the example of nested reference frame configuration where [two dynamic components are attached](/operate/mobility/define-geometry/#configure-nested-reference-frames): a robotic arm, `A`, attaches to a gantry, `G`, which in turn is fixed in place at a point on the `World` of a table. | ||
| Consider the example of nested reference frame configuration where two dynamic components are attached: A robotic arm, `A`, attaches to a gantry, `G`, which in turn is fixed in place at a point in the `world` frame of a table. | ||
|
|
||
| The resulting tree of reference frames looks like: |
There was a problem hiding this comment.
the image underneath this is too large
|
|
||
| 1. Click **+ Add Frame**. | ||
|
|
||
| - If the camera is mounted on the arm: |
There was a problem hiding this comment.
This level of nesting is a bit much. Remove this level of nesting and just use paragraphs for each if clause.
| - If the camera is mounted on the arm: | |
| If the camera is mounted on the arm: |
There was a problem hiding this comment.
Yes--sorry--I applied part of the feedback, then wanted to stage before making these changes and was running into the hugo version issues. Will apply now!
| ## Move the arm using the arm API | ||
|
|
||
| The two main options for controlling arm movement with the arm API 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 number=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="/dev/reference/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`](/dev/reference/apis/components/arm/#movetojointpositions). | ||
|
|
||
| {{% /tablestep %}} | ||
| {{% tablestep number=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`](/operate/reference/orientation-vector/) when commanding arm motion. | ||
| Run the code to see your arm move 100 mm upwards. | ||
| For more information, see [`MoveToPosition`](/dev/reference/apis/components/arm/#movetoposition). | ||
|
|
||
| {{% /tablestep %}} | ||
| {{< /table >}} |
There was a problem hiding this comment.
Just to reconfirm, you don't think we should cover this here? This may otherwise be somewhat hard to find.
|
It looks like the following files may have been renamed. Please ensure you set all needed aliases: |
…dd tips, remove most of move arm landing content and replace
Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
npentrel
left a comment
npentrel
left a comment
There was a problem hiding this comment.
LGTM % read comments and action as you see fit
|
🔎💬 Inkeep AI search and chat service is syncing content for source 'Viam Docs' |
4 participants
Objectives:
Once agreed upon:
Note: