> For the complete documentation index, see [llms.txt](https://docs.hello-robot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello-robot.com/stretch4_docs/working-with-stretch/motion_basics/scripting-joint-motion.md).

# Scripting Joint Motion

## Overview

Individual joint motion can be set from the[ RobotClient API ](/stretch4-body-repo/core-framework/primer_robot_client.md)— although if ROS2 is being used then typically motion will be set from [stretch\_core API](https://docs.hello-robot.com/stretch4-ros2-repo/).

The RobotClient API abstracts away the many configuration settings for joint motion — and the default YAML params are generally sufficient for most users.

### Design Pattern

Commanding joint motion typically follows a standard design pattern of

```
1. Create RobotClient
2. Startup RobotClient
3. Start control loop <100hz
4. For each loop
 - Do a RobotClient pull_status
 - Compute motion setpoints
 - Command RobotClient motion
 - Do a RobotClient push_command
5. Exit loop and stop RobotClient
```

See the [Robot Client API](/stretch4-body-repo/core-framework/primer_robot_client.md#example-reactive-control-loop) for more information.

### What can I control?

The available subsystems that support motion commands are:

```python
robot_client.lift
robot_client.arm
robot_client.end_of_arm
robot_client.omnibase
```

See the [Robot Client API](/stretch4-body-repo/core-framework/primer_robot_client.md) for the availabe motion API for each.

### MOVE\_BY

All joints support a `move_by` which create motion relative to the current position. For example, here is the API for the Lift and Arm:

{% @github-files/github-code-block url="<https://github.com/hello-robot/stretch4_body/blob/4be724431ea21c87d41bdf03f3cce36cd4ba4562/stretch4_body/robot/robot_client.py#L748-L768>" visible="false" %}

For example, to move the Lift up by 0.1m:

{% code expandable="true" %}

```python
from stretch4_body.robot.robot_client import RobotClient
r = RobotClient()
r.startup()
r.lift.move_by(x_m=0.1)
r.push_command()
r.wait_on_motion_finish()
r.stop()
```

{% endcode %}

This example uses the default velocity, acceleration, and other motion settings — as define in by the parameter system.

### MOVE\_TO

In the same way, the `move_to` methods for joints allow moving to absolution positions. For example, to move the Lift to 0.5m:

{% code expandable="true" %}

```python
from stretch4_body.robot.robot_client import RobotClient
r = RobotClient()
r.startup()
r.lift.move_to(x_m=0.5)
r.push_command()
r.wait_on_motion_finish()
r.stop()
```

{% endcode %}

### SET\_VELOCITY

Joints support a `set_velocity` command as well. This method should be used with care — as a runaway velocity can cause harm. While the Stretch Body Server enforces joint limits to prevent runaways, it is still advised to only use `set_velocity` in a carefully constructed control-loop with a watchdog.

The nominal API for the Lift and Arm look like:

{% @github-files/github-code-block url="<https://github.com/hello-robot/stretch4_body/blob/main/stretch4_body/robot/robot_client.py#L775>" visible="false" %}

### Working with the EndOfArm

The [End-Of-Arm (EOA)](/stretch4-body-repo/subsystems-and-hardware/primer_end_of_arm.md) supports a chain of Feetech servos that individually support motion through the RobotClient API. While similar to the Lift and Arm, the notable difference is that the joint name must be provided.

{% @github-files/github-code-block url="<https://github.com/hello-robot/stretch4_body/blob/4be724431ea21c87d41bdf03f3cce36cd4ba4562/stretch4_body/robot/robot_client.py#L748-L768>" visible="false" %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hello-robot.com/stretch4_docs/working-with-stretch/motion_basics/scripting-joint-motion.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.