@ -11,14 +11,18 @@ Stretch Body includes a system to prevent inadvertent self-collisions. It will
This system is turned off by default starting with Stretch 2. It may be turned off by default on many RE1 systems. First check if the collision detection system is turned on:
If it is turned off you can enable it by adding the following to your stretch_user_yaml.py:
```bash
```{.bash .no-copy}
robot:
use_collision_manager: 1
```
@ -37,8 +41,12 @@ Fortunately, the simple kinematics of Stretch make self-collisions fairly uncomm
The collision avoidance system works by dynamically modifying the acceptable range of motion for each joint. By default, a joint's range is set to the physical hard stop limits. For example, the lift has a mechanical throw of 1.1m:
We see two models. One that protects the camera from the arm, and one that protects the base from the gripper. Each model is registered with the [RobotCollision](https://github.com/hello-robot/stretch_body/blob/master/body/stretch_body/robot_collision.py) instance as a loadable plug-in. The [Robot](https://github.com/hello-robot/stretch_body/blob/master/body/stretch_body/robot.py) class calls the `RobotCollision.step` method periodically at approximately 10hz.
@ -218,8 +229,8 @@ In this example, we include the `safety_margin` as a way to introduce some hyste
The following command should be run to add the working directory to the PYTHONPATH env. This can also be added to our `.bashrc` to permanently edit the path:
@ -140,8 +142,10 @@ The Stretch Factory package provides a tool to allow advanced users to recalibra
The tool sweeps the joint through its range of motion for `n-cycle` iterations. It computes the maximum contact forces in both directions, adds padding, `contact_thresh_calibration_margin`, to this value, and stores it to the robot's configuration YAML.
```bash
>>$ REx_calibrate_guarded_contact.py -h
```{.bash .shell-prompt}
REx_calibrate_guarded_contact.py -h
```
```{.bash .no-copy}
For use with S T R E T C H (R) RESEARCH EDITION from Hello Robot Inc.
@ -22,8 +26,12 @@ Typically, users will interact with these devices through either the [Head](http
You can directly command each servo using the command line tool `REx_dynamixel_servo_jog.py`. This can be useful for debugging new servos added to the end-of-arm tool during system bring-up. For example, to command the head pan servo:
[Dynamixel ID:011] ping Succeeded. Dynamixel model number : 1080
------ MENU -------
m: menu
@ -51,8 +59,12 @@ e: enable torque
Under high-load conditions, the servos may enter an error state to protect themselves from thermal overload. In this case, the red LED on the servo will flash (if visible). In addition, the servo will be unresponsive to motion commands. In this case, allow the overheating servo to cool down and reboot the servos using the `stretch_robot_dynamixel_reboot.py` tool:
```bash
$ stretch_robot_dynamixel_reboot.py
```{.bash .shell-prompt}
stretch_robot_dynamixel_reboot.py
```
Output:
```{.bash .no-copy}
For use with S T R E T C H (TM) RESEARCH EDITION from Hello Robot Inc.
---- Rebooting Head ----
@ -67,8 +79,12 @@ For use with S T R E T C H (TM) RESEARCH EDITION from Hello Robot Inc.
If it is unclear which servos are on the bus, and at what baud rate, you can use the `REx_dynamixel_id_scan.py` tool. Here we see that the two head servos are at ID `11` and `12` at baud `57600`.
@ -102,8 +118,12 @@ Scanning bus /dev/hello-dynamixel-head at baud rate 57600
Stretch ships with its Dynamixel servos configured to `baudrate=115200`. When adding your servos to the end-of-arm tool, you may want to set the servo baud using the `REx_dynamixel_set_baud.py` tool. For example:
Dynamixel servos come with `ID=1` from the factory. When adding your servos to the end-of-arm tool, you may want to set the servo ID using the `REx_dynamixel_id_change.py` tool. For example:
[Dynamixel ID:001] ping Succeeded. Dynamixel model number : 1080
Ready to change ID 1 to 13. Hit enter to continue:
@ -150,13 +174,17 @@ The [EndOfArm](https://github.com/hello-robot/stretch_body/blob/master/body/stre
DynamixelHelloXL430 provides an interface to servo motion that is consistent with the Stretch Body lift, arm, and base joints. It also manages the servo parameters and calibration. Let's explore this interface further. From iPython, let's look at the status message for DynamixelHelloXL430
```bash
```python
import stretch_body.dynamixel_hello_XL430
m = stretch_body.dynamixel_hello_XL430.DynamixelHelloXL430('head_pan')
We see that it reports the position in both radians (with respect to the joint frame) and ticks (with respect to the servo encoder). DynamixelHelloXL430 handles the calibration between the two using its method `ticks_to_world_rad` through the following params:
@ -28,9 +28,8 @@ Stretch also includes 3rd party hardware devices that are not accessible through
The primary developer interface to Stretch_Body is the [Robot class](https://github.com/hello-robot/stretch_body/blob/master/body/stretch_body/robot.py). Let's write some code to explore the interface. Launch an interactive Python terminal:
@ -66,11 +66,12 @@ All joints support [trapezoidal motion profile](https://www.motioncontroltips.co
We provide 'defaults' for the velocity and acceleration settings, as well as 'fast', and 'slow' settings. These values have been tuned to be appropriate for the safe movement of the robot. These values can be queried using the `stretch_params.py` tool:
```bash
>>$stretch_params.py | grep arm | grep motion | grep default
```{.bash .shell-prompt}
stretch_params.py | grep arm | grep motion | grep default
Each motor also has associated sensor data available in its status dictionaries. The corresponding 'jog' tool for each joint will pretty-print the sensor data for that motor to the console. For example:
```bash
>>$ stretch_arm_jog.py
```{.bash .shell-prompt}
stretch_arm_jog.py
```
```{.bash .no-copy}
For use with S T R E T C H (R) RESEARCH EDITION from Hello Robot Inc.
@ -202,8 +206,10 @@ These values are computed on the Pimu. As we can see in [its firmware code](http
Stretch Body also implements a bump detector using the IMU accelerometers. This detector simply [computes the sum of squares of AX, AY, and AZ](https://github.com/hello-robot/stretch_firmware/blob/master/arduino/hello_pimu/IMU.cpp#L223). This value is then compared to the following threshold to determine if a bump is detected:
@ -281,9 +287,10 @@ In addition to AX, AY, and AZ we also see the `single_tap_count` value which rep
The following Wacc parameters configure the accelerometer low-pass filter and single-tap settings. See the [ADXL343](https://www.analog.com/media/en/technical-documentation/data-sheets/ADXL343.pdf) datasheet for more details.
The sensors are calibrated such that a zero value (as defined by `cliff_zero`) indicates the sensor is at the correct height from the floor surface. A negative value indicates a drop off such as a stair ledge while a positive value indicates an obstacle like a threshold or high pile carpet. You may want to recalibrate this zero based on the surface the robot is on (eg, carpet, tile, etc). To do this:
```bash
>>$REx_cliff_sensor_calibrate.py
```{.bash .shell-prompt}
REx_cliff_sensor_calibrate.py
```
```{.bash .no-copy}
For use with S T R E T C H (R) RESEARCH EDITION from Hello Robot Inc.
The Runstop deactivates all robot motion. It can be triggered by the physical button on the robot's head. It can also be triggered by internal monitors of the system state. The default configuration of these parameters is:
@ -16,8 +16,10 @@ Splined trajectories are particularly useful when you want to coordinate motion
Stretch Body includes [a graphical tool for exploring splined trajectory control](https://github.com/hello-robot/stretch_body/blob/master/tools/bin/stretch_trajectory_jog.py) on the robot:
Test out splined trajectories on the various joint from a GUI or text menu.
@ -36,7 +38,6 @@ optional arguments:
--base_translate Test translational trajectories on diff-drive base
--base_rotate Test rotational trajectories on diff-drive base
--full_body Test trajectories on all joints at once
```
The tool GUI allows you to interactively construct a splined trajectory and then execute it on the robot. For example, on the arm:
@ -48,8 +49,8 @@ The tool GUI allows you to interactively construct a splined trajectory and then
Finally, you can explore a full-body trajectory using the non-GUI version of the tool:
```bash
>>$ stretch_trajectory_jog.py --full_body
```{.bash .shell-prompt}
stretch_trajectory_jog.py --full_body
```
## Programming Trajectories
@ -100,14 +101,20 @@ For example, the arm trajectory below has a large excursion outside of the joint
![](./images/bad_trajectory.png)
Often the trajectory waypoints will be generated from a motion planner. It is important for the planner to incorporate the position, velocity, and acceleration constraints of the joint. These can be found by, for example:
Often the trajectory waypoints will be generated from a motion planner. The planner needs to incorporate the position, velocity, and acceleration constraints of the joint. These can be found by, for example:
@ -77,8 +82,8 @@ The [Stretch Tool Share](https://github.com/hello-robot/stretch_tool_share/) is
To use Stretch Tool Share tools, first update your installation:
```console
$ pip install -U hello-robot-stretch-tool-share
```{.bash .shell-prompt}
pip install -U hello-robot-stretch-tool-share
```
As an example, we see on the Tool Share that there is a tool, the [ToolDryEraseToolHolderV1](https://github.com/hello-robot/stretch_tool_share/blob/master/python/stretch_tool_share/dry_erase_holder_v1/tool.py) which [extends the EndOfArm](https://github.com/hello-robot/stretch_tool_share/blob/master/python/stretch_tool_share/usbcam_wrist_v1/tool.py) class. To load this tool interface, modify your `stretch_user_params.yaml` to load the tool as before. We will also need to tell it where to find the tool's [parameter file](https://github.com/hello-robot/stretch_tool_share/blob/master/python/stretch_tool_share/dry_erase_holder_v1/params.py):
@ -116,24 +121,24 @@ Next, we'll see how to change the ROS interface for a tool. Here we will continu
Next, ensure ROS is up to date:
```console
$ cd ~/catkin_ws/src/stretch_ros/
$ git pull
```{.bash .shell-prompt}
cd ~/catkin_ws/src/stretch_ros/
git pull
```
To access the URDF data for the [ToolDryEraseHolderV1](https://github.com/hello-robot/stretch_tool_share/blob/master/python/stretch_tool_share/dry_erase_holder_v1/tool.py#L3) we'll need to clone the Tool Share repository:
Now we will update the tool Xacro for Stretch. Open the file `~/catkin_ws/src/stretch_ros/stretch_description/urdf/stretch_description.xacro` in an editor. Comment out the current tool Xacro and include the Xacro for the dry-erase holder.
@ -155,16 +160,16 @@ Now we will update the tool Xacro for Stretch. Open the file `~/catkin_ws/src/st
Finally, we'll update the calibrated URDF to use this new tool:
```console
$ cd ~/catkin_ws/src/stretch_ros/stretch_description/urdf