Browse Source

update copyright footer

pull/14/head
Aaron Edsinger 2 years ago
parent
commit
c8d65982d5
45 changed files with 482 additions and 43 deletions
  1. +4
    -0
      README.md
  2. +24
    -6
      getting_started/README.md
  3. +19
    -1
      getting_started/best_practices.md
  4. BIN
     
  5. BIN
     
  6. BIN
     
  7. BIN
     
  8. BIN
     
  9. BIN
     
  10. BIN
     
  11. BIN
     
  12. BIN
     
  13. BIN
     
  14. BIN
     
  15. BIN
     
  16. BIN
     
  17. +13
    -8
      getting_started/quick_start_guide_re1.md
  18. +232
    -0
      getting_started/quick_start_guide_re2.md
  19. +4
    -0
      getting_started/safety_guide.md
  20. +11
    -4
      getting_started/troubleshooting_guide.md
  21. +7
    -6
      getting_started/untethered_operation.md
  22. +8
    -7
      getting_started/updating_software.md
  23. +2
    -1
      mkdocs.yml
  24. +0
    -0
      stretch_body/custom_wrist_dof/my_wrist_pitch.py
  25. +0
    -0
      stretch_body/custom_wrist_dof/stretch_user_params.yaml
  26. BIN
     
  27. BIN
     
  28. BIN
     
  29. BIN
     
  30. BIN
     
  31. BIN
     
  32. BIN
     
  33. +3
    -0
      stretch_body/tutorial_collision_avoidance.md
  34. +3
    -0
      stretch_body/tutorial_command_line_tools.md
  35. +2
    -1
      stretch_body/tutorial_contact_models.md
  36. +4
    -1
      stretch_body/tutorial_custom_wrist_dof.md
  37. +4
    -3
      stretch_body/tutorial_dynamixel_servos.md
  38. +3
    -0
      stretch_body/tutorial_introduction.md
  39. +2
    -1
      stretch_body/tutorial_parameter_management.md
  40. +4
    -0
      stretch_body/tutorial_robot_motion.md
  41. +3
    -0
      stretch_body/tutorial_robot_sensors.md
  42. +5
    -1
      stretch_body/tutorial_safe_coding.md
  43. +121
    -1
      stretch_body/tutorial_splined_trajectories.md
  44. +2
    -1
      stretch_body/tutorial_stretch_body_api.md
  45. +2
    -1
      stretch_body/tutorial_tool_change.md

+ 4
- 0
README.md View File

@ -10,3 +10,7 @@ The Stretch Tutorials reposotory provides tutorials on programming the Stretch R
| [Stretch Body](./stretch_body/README.md) | Learn how to program Stretch using its low level Python interface |
| [ROS 1](./ros1/README.md) | Learn how to program Stretch using its ROS1 interface |
| [ROS 2](./ros2/README.md) | Learn how to program Stretch using its ROS2 interface |
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 24
- 6
getting_started/README.md View File

@ -4,16 +4,34 @@ New to Stretch? Welcome!
Please take the time to get to know your robot by going through these tutorials in order.
## What Version of Robot Do I Have?
Stretch RE1 and RE2 are very similar. One quick way to tell the difference is look at the robot's hostame:
```bash
>>$ hostname
stretch-re2-2001
```
Another way is to look for the distinctive pink stripe on the RE2 base:
![](./images/pink_strip.png)
## Basics
| | Tutorial | Description |
|---|---------------------------------------------|----------------------------------------------------|
| 1 | [Safety Guide](safety_guide.md) | Guide to safe operation of the Stretch RE1 and RE2 |
| 2 | [Quick Start](quick_start_guide.md) | Unboxing Stretch and getting started |
| 3 | [Best Practices](best_practices.md) | Best practices to keep Stretch safe and healthy |
| 4 | [Troubleshooting](troubleshooting_guide.md) | Solutions to common issues |
| | Tutorial | Description |
| ---- | ------------------------------------------- | -------------------------------------------------- |
| 1 | [Safety Guide](safety_guide.md) | Guide to safe operation of the Stretch |
| 2 | [Quick Start RE1](quick_start_guide_re1.md) | Unboxing Stretch RE1 and getting started |
| 2 | [Quick Start RE2](quick_start_guide_re2.md) | Unboxing Stretch RE2 and getting started |
| 3 | [Best Practices](best_practices.md) | Best practices to keep Stretch charged and healthy |
| 4 | [Troubleshooting](troubleshooting_guide.md) | Solutions to common issues |
## Advanced
| |Tutorial | Description |
|---|----------------------------------|---------------------------------------------------------|
| 1 | [Untethered Operation](untethered_operation.md) | Setting up your network to work with Stretch untethered |
| 2 | [Updating Software](updating_software.md) | How to periodically update the Stretch software |
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 19
- 1
getting_started/best_practices.md View File

@ -1,9 +1,27 @@
# Tutorial: Stretch Best Practices
## Keeping the Robot Charged
Keeping Stretch charged is important to the long-term health of its batteries - and to the success of any project you develop on Stretch. Please read carefully the following guides and adopt their best-practices for battery health.
=== "Stretch RE1"
[RE1 Battery Maintenance Guide](https://docs.hello-robot.com/0.2/stretch-hardware-guides/battery_maintenance_guide_re1/).
=== "Stretch RE2"
[RE2 Battery Maintenance Guide](https://docs.hello-robot.com/0.2/stretch-hardware-guides/battery_maintenance_guide_re2).
## Keeping the Robot Healthy
While Stretch can tolerate a fair amount of misuse, the following best practices can help it achieve a long and healthy life.
| Video | Description |
|----------------------------------------------------------------------------| ---------------------------------------------- |
| [Stretch Best Practices - Powered Off Video](https://youtu.be/mQdOGEksdYM) | How to work with Stretch when its power is off |
| [Stretch Best Practices - Powered On Video](https://youtu.be/iEaapHNfEWA) | How to work with Stretch when its power is on |
------
<div align="center"> All materials are Copyright 2020 by Hello Robot Inc. The Stretch RE1 robot has patents pending</div>
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

BIN
View File


BIN
View File


BIN
View File


BIN
View File


BIN
View File


BIN
View File


BIN
View File


BIN
View File


BIN
View File


BIN
View File


BIN
View File


BIN
View File


BIN
View File


getting_started/quick_start_guide.md → getting_started/quick_start_guide_re1.md View File

@ -1,10 +1,10 @@
# Stretch RE1 and RE2: Quick Start Guide
# Stretch RE1: Quick Start Guide
Congratulations on your Stretch RE1! This guide will get you started with your new robot.
## Safety
Stretch has the potential to cause harm if not properly used. All users should review the [Stretch Safety Guide](robot_safety_guide.md) before operating the robot.
Stretch has the potential to cause harm if not properly used. All users should review the [Stretch Safety Guide](./safety_guide.md) before operating the robot.
## Unboxing
@ -18,9 +18,12 @@ A few items you'll want to know about before getting started.
The entire robot powers up and down with the On/Off switch. When powering down, we recommend selecting 'Power Off' from the Ubuntu Desktop prior to hitting the Off switch
![](./images/trunk_rs.png)
![](./images/trunk_rs.png)
The provided battery charger can be plugged and unplugged at any time during operation. Stretch uses the following charger modes:
@ -31,7 +34,7 @@ The provided battery charger can be plugged and unplugged at any time during ope
| SUPPLY | 1) Power the robot during tethered use<br/>2) Repair damaged batteries. |
| REPAIR | Repair damaged batteries. |
Please review the [Battery Maintenance Guide](./battery_maintenance_guide.md) for proper care and charging of Stretch batteries.
Please review the [Battery Maintenance Guide](https://docs.hello-robot.com/0.2/stretch-hardware-guides/battery_maintenance_guide_re1/) for proper care and charging of Stretch batteries.
![](./images/NOCO_Genius10_UI_rs.png)
@ -114,9 +117,9 @@ Log in to the robot computer. The default user credentials came in the box with
## Start Coding
Python is the easiest way to begin writing code for the robot. This section will give you a quick look at Stretch Body, which is the low level Python interface to the robot. Detailed information on the [Stretch Body Interface](stretch_body_guide.md) can be found here.
Python is the easiest way to begin writing code for the robot. This section will give you a quick look at Stretch Body, which is the low level Python interface to the robot. Detailed information on the [Stretch Body Interface](../stretch_body/README.md) can be found here.
Stretch is configured to run the XBox Controller demo in the background at startup. To run your own code you'll need kill off this process so that it doesn't contend with your code.
**NOTE**: Stretch is configured to run the XBox Controller demo in the background at startup. To run your own code you'll need kill off this process so that it doesn't contend with your code.
```console
$ pkill -f stretch_xbox*
@ -218,9 +221,11 @@ Hello Robot support monitors the forum closely and will quickly get back to you
Encounter any issues while getting started? Please let us know at support@hello-robot.com. Also take a minute to review the [Stretch Troubleshooting Guide](./troubleshooting_guide.md)
We recommend next exploring the ROS based demos that ship with Stretch. These [are found in the stretch_ros repository](https://github.com/hello-robot/stretch_ros/tree/master/stretch_demos).
We recommend next exploring the ROS based demos that ship with Stretch. These [are found in the stretch_ros repository](https://docs.hello-robot.com/0.2/stretch-ros/stretch_demos/).
That's it. Happy coding!
------
<div align="center"> All materials are Copyright 2020 by Hello Robot Inc. The Stretch RE1 robot has patents pending</div>
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 232
- 0
getting_started/quick_start_guide_re2.md View File

@ -0,0 +1,232 @@
# Stretch RE2: Quick Start Guide
Congratulations on your Stretch RE2! This guide will get you started with your new robot.
## Safety
Stretch has the potential to cause harm if not properly used. All users should review the [Stretch Safety Guide](./safety_guide.md) before operating the robot.
## Unboxing
Please watch the [Stretch Unboxing Video](https://youtu.be/O-6VrqqGlig).
## Robot Tour
A few items you'll want to know about before getting started.
### Power
The entire robot powers up and down with the On/Off switch. When powering down, we recommend selecting 'Power Off' from the Ubuntu Desktop prior to hitting the Off switch
![](./images/trunk_rs.png)
### Battery Voltage
The LED lightbar on the base indicates the battery voltage according to its color. It should be green, indicating a full charge. If it is orange or red the batteries require charging.
![](./images/lightbar_voltage.png)
### Charging the Battery
The provided battery charger can be plugged and unplugged at any time during operation. Stretch uses the following charger modes:
| Mode | Function |
| ------- | ------------------------------------------------------------ |
| STANDBY | Charger not charging the robot |
| 12V AGM | Charging while robot is powered down |
| SUPPLY | 1) Power the robot during tethered use<br/>2) Repair damaged batteries. |
| REPAIR | Repair damaged batteries. |
Please review the [Battery Maintenance Guide](https://docs.hello-robot.com/0.2/stretch-hardware-guides/battery_maintenance_guide_re1/) for proper care and charging of Stretch batteries.
![](./images/NOCO_Genius10_UI_rs.png)
### Runstop
The illuminated button on the head is its Runstop. Just tap it, you'll hear a beep and it will start flashing. This will pause motion of the primary robot joints during operation. This can be useful if the robot makes an unsafe motion, or if you just want to free up the robot motors while you roll it around.
To allow motion once again, hold the button down for two seconds. After the beep, motion can resume.
![](./images/runstop_rs.png)
### Safe Handling
Like any robot, it is possible to break Stretch if you're not careful. Use common sense when applying forces to its joints, transporting it, etc.
The [Stretch Unpowered Best Practices Video](https://youtu.be/mQdOGEksdYM) provides a quick overview of how to work with the robot.
**Things that won't hurt the robot**:
* Manually push and pull the arm (when the motor isn't holding a position).
* Manually raise and lower the lift (when the motor isn't holding a position).
* Manually tilt and roll the base around (when the motors aren't holding a position).
* Pick up and carry Stretch (while holding it by the mast, two people for safety).
**Things to be mindful of**:
* Manually moving the head and wrist. They will move but they want to go at their own speed.
* The arm will slowly descend when the robot is powered off. If the arm is retracted it may rest the tool on the base. If desired to hold the arm up when un-powered, the provided 'clip-clamp' can be clipped onto the mast below the shoulder to support it.
**Things that can hurt the robot**:
* Driving the wrist and gripper into the base. When the arm and wrist are stowed it is possible to collide the two.
* Getting the gripper stuck on something and then driving the arm, lift, or base.
* Laying the robot down with it weight on its camera.
* Trying to ride on the robot, getting it wet, etc. (eg, common sense)
## Hello World Demo
Stretch comes ready to run out of the box. The Xbox Teleoperation demo will let you quickly test out the robot capabilities by teleoperating it with an Xbox Controller.
![](./images/xbox.png)
**Note**: You will find the USB Dongle already plugged into the the USB port of the base trunk.
To start the demo after unboxing and turning the power on:
* Wait for about 45 seconds. You will hear the Ubuntu startup sound, followed by two beeps (indicating the demo is running).
* Hit the Connect button on the controller. The upper two LEDs of the ring will illuminate.
* Hit the Home Robot button. Stretch will go through its homing calibration routine.
* **Note**: make sure the space around the robot is clear before running the Home function
You're ready to go! A few things to try:
* Hit the Stow Robot button. The robot will assume the stow pose.
* Practice driving the robot around.
* Pull the Fast Base trigger while driving. When stowed, it will make Stretch drive faster
* Manually stop the arm or lift from moving to make it stop upon contact.
* Try picking up your cellphone from the floor
* Try grasping cup from a counter top
* Try delivering an object to a person
If you're done, hold down the Shutdown PC button for 2 seconds. This will cause the PC to turn off. You can then power down the robot. Or proceed to the next step...
Now that you're familiar with the robot, take a minute to watch the [Stretch Powered Best Practices Video](https://youtu.be/iEaapHNfEWA).
## Get Plugged In
Let's get plugged in.
* Plug in a mouse, keyboard and HDMI monitor to the robot trunk
* Plug in the battery charger
* Place the charger in SUPPLY mode
Log in to the robot computer. The default user credentials came in the box with the robot.
## Start Coding
Python is the easiest way to begin writing code for the robot. This section will give you a quick look at Stretch Body, which is the low level Python interface to the robot. Detailed information on the [Stretch Body Interface](../stretch_body/README.md) can be found here.
**NOTE**: Stretch is configured to run the XBox Controller demo in the background at startup. To run your own code you'll need kill off this process so that it doesn't contend with your code.
```console
$ pkill -f stretch_xbox*
```
While you're at it, disable this autoboot feature. You can always turn it back on later.
Search for 'Startup' from Ubuntu Activities. Uncheck the box for 'hello_robot_xbox_teleop'
![](./images/xbox_off_rs.png)
Now open up a Terminal. From the command line, first verify that that all of the hardware is present and happy
```console
$ stretch_robot_system_check.py
```
You may see a few joints reported in red because they haven't yet been calibrated. If so, home the robot
```console
$ stretch_robot_home.py
```
Once the robot has homed, let's write some quick test code:
```bash
>>$ ipython
Python 3.8.10 (default, Jun 22 2022, 20:18:18)
...
```
Now let's move the robot around using the [Stretch Body Robot API](https://github.com/hello-robot/stretch_body/blob/master/body/stretch_body/robot.py). Try typing in these interactive commands at the iPython prompt:
```python
import stretch_body.robot
robot=stretch_body.robot.Robot()
robot.startup()
robot.stow()
robot.arm.move_to(0.25)
robot.push_command()
robot.arm.move_to(0.0)
robot.push_command()
robot.lift.move_to(0.4)
robot.push_command()
robot.pretty_print()
robot.lift.pretty_print()
robot.head.pose('tool')
robot.head.pose('ahead')
robot.end_of_arm.move_to('wrist_yaw',0)
robot.end_of_arm.move_to('stretch_gripper',50)
robot.end_of_arm.move_to('stretch_gripper',-50)
robot.stow()
robot.stop()
```
## Change Credentials
Finally, we recommend that you change the login credentials for the default user, hello-robot.
```console
$ sudo passwd hello-robot
```
If you'd like to setup a new user account, check out the [Stretch Installation Guide](https://github.com/hello-robot/stretch_install/blob/master/README.md). In a lab setting, it's useful for lab members to have their own user accounts to run experiments.
## Power Down
The recommended power down procedure is
1. Place a clamp on the mast below the shoulder to prevent a slow drop (if this is a concern)
2. Shutdown the computer from the Desktop
3. When the laser range finder has stopped spinning, turn off the main power switch
4. Attach the charger
5. Place the charger in 12V AGM mode
## Join the Community Forum
Join the [Hello Robot Community](https://forum.hello-robot.com). We'd welcome hearing your feedback as you get to know your robot.
Hello Robot support monitors the forum closely and will quickly get back to you on any questions or issues you post.
## Further Exploration
Encounter any issues while getting started? Please let us know at support@hello-robot.com. Also take a minute to review the [Stretch Troubleshooting Guide](./troubleshooting_guide.md)
We recommend next exploring the ROS based demos that ship with Stretch. These [are found in the stretch_ros repository](https://docs.hello-robot.com/0.2/stretch-ros/stretch_demos/).
That's it. Happy coding!
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 4
- 0
getting_started/safety_guide.md View File

@ -209,3 +209,7 @@ The diagrams below show the potential crush points at the top and bottom of the
![](./images/lift_down_rs.png)
![](./images/lift_up_rs.png)
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 11
- 4
getting_started/troubleshooting_guide.md View File

@ -1,10 +1,10 @@
# Stretch RE1: Troubleshooting Guide
# Stretch RE1 and RE2: Troubleshooting Guide
This guide covers common issues and ways to resolve them. Please check the [Hello Robot Forum](https://forum.hello-robot.com) for additional topics not covered here.
## XBox teleoperation is not working
The provided Easy SMX wireless controller can accidentally be placed in the wrong mode. The mode is indicated by the round illuminated ring (shown as Connect below). The top 2 LEDs only should be illuminated. If a different LED pattern is shown then the button mapping expected by [stretch_xbox_controller_teleop.py](https://github.com/hello-robot/stretch_body/blob/master/tools/bin/stretch_xbox_controller_teleop.py0) will be incorrect.
The provided Easy SMX wireless controller can accidentally be placed in the wrong mode. The mode is indicated by the round illuminated ring (shown as Connect below). The top 2 LEDs only should be illuminated. If a different LED pattern is shown then the button mapping expected by [stretch_xbox_controller_teleop.py](https://github.com/hello-robot/stretch_body/blob/master/tools/bin/stretch_xbox_controller_teleop.py) will be incorrect.
To set the controller into the correct mode:
@ -19,7 +19,13 @@ In addition, check that the provided USB dongle is plugged into the robot USB po
## Battery is not staying charged
Please review the troubleshooting section of the [Battery Maintenance Guide](./battery_maintenance_guide.md).
=== "Stretch RE1"
Please review the troubleshooting section of the [RE1 Battery Maintenance Guide](https://docs.hello-robot.com/0.2/stretch-hardware-guides/battery_maintenance_guide_re1/).
=== "Stretch RE2"
Please review the troubleshooting section of the [RE2 Battery Maintenance Guide](https://docs.hello-robot.com/0.2/stretch-hardware-guides/battery_maintenance_guide_re2).
## RPC Transport Errors (Stretch doesn't respond to commands)
@ -55,4 +61,5 @@ To turn it off, search for 'Startup' from Ubuntu Activities. Uncheck the box for
![](./images/xbox_off_rs.png)
------
<div align="center"> All materials are Copyright 2020 by Hello Robot Inc. The Stretch RE1 robot has patents pending</div>
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 7
- 6
getting_started/untethered_operation.md View File

@ -1,7 +1,7 @@
# Untethered Operation
As a mobile manipulator, the Stretch RE1 can only go so far when tethered to the monitor, keyboard, and mouse setup. This guide will explain three methods of setting up the Stretch RE1 for untethered usage.
As a mobile manipulator, Stretch can only go so far when tethered to the monitor, keyboard, and mouse setup. This guide will explain three methods of setting up the Stretch for untethered usage.
These methods typically require a wireless network, but it is possible to set up any of these methods without a wireless network by [setting up a hotspot](#hotspot).
@ -13,7 +13,7 @@ This is the recommended approach if you are running Windows or MacOS. This metho
#### How To
While the Stretch RE1 is tethered to the monitor, keyboard, and mouse setup, first verify that the robot is connected to the wireless network then install Vino VNC server using the following command:
While Stretch is tethered to the monitor, keyboard, and mouse setup, first verify that the robot is connected to the wireless network then install Vino VNC server using the following command:
```console
$ sudo apt install vino
@ -39,7 +39,7 @@ This is the recommended approach if you are running an Unix-based operating syst
While the [Remote Desktop](#remote-desktop) approach is easy to set up, graphics and interaction with the remote desktop is often slow. In this method, we will use SSH and X Server to accomplish the same a bit faster. SSH stands for Secure Shell, enabling one to remotely use the terminal (shell) of another machine. X Server is used on many Unix variants to render the Windowed GUI of applications. With SSH and X Server, it is possible to render a Windowed GUI of an application running on the robot on your computer's screen.
The first step is to identify the robot's IP address on the local network. While the Stretch RE1 is tethered to the monitor, keyboard, and mouse, verify that the robot is connected to a wireless network. Then, open a terminal and run `ifconfig`, which will print out the network information of the machine. In the wireless section (typically named wlp2s0), look for something that looks like "inet 10.0.0.15". The four numbers represent the IP address of the robot on the local network. Using any other machine on the same local network, I can SSH into the robot using this IP address. Take note of the username and password of the robot. The default combo is printed on papers that came in the tools box alongside the robot.
The first step is to identify the robot's IP address on the local network. While Stretch is tethered to the monitor, keyboard, and mouse, verify that the robot is connected to a wireless network. Then, open a terminal and run `ifconfig`, which will print out the network information of the machine. In the wireless section (typically named wlp2s0), look for something that looks like "inet 10.0.0.15". The four numbers represent the IP address of the robot on the local network. Using any other machine on the same local network, I can SSH into the robot using this IP address. Take note of the username and password of the robot. The default combo is printed on papers that came in the tools box alongside the robot.
To SSH into the robot, run the following. It will require the password and may ask you to add the robot to the known hosts.
@ -47,7 +47,7 @@ To SSH into the robot, run the following. It will require the password and may a
$ ssh -X username@ip-address
```
Now that you're SSH-ed into the robot, you can disconnect any wires from the robot. You can accomplish any of the same tasks through the terminal. For example, you can type in `ipython` and interact with the robot using Stretch Body, as explained in the [Getting Started Guide](quick_start_guide.md#start-coding).
Now that you're SSH-ed into the robot, you can disconnect any wires from the robot. You can accomplish any of the same tasks through the terminal. For example, you can type in `ipython` and interact with the robot using Stretch Body, as explained in the [Quick Start Guide](./quick_start_guide_re2.md#start-coding).
Furthermore, Windowed GUI applications that would have displayed on the monitor will now display on your SSH-ed machine. For example, we can open Rviz to visualize what the robot is seeing. Open two terminals and SSH into the robot as explained above. In the first, run `roslaunch stretch_core stretch_driver.launch`. You should see some information print out in the terminal. In the second, run `rviz`. A window will pop up and information about the robot can be visualized by clicking on `Add -> RobotModel` and `Add -> By Topic -> /Scan`. Additional information on how to use ROS tools can be found in [ROS's tutorials](http://wiki.ros.org/ROS/Tutorials) or in our [Stretch ROS guides](README.md#ros-interface).
@ -75,7 +75,7 @@ This is the recommended approach if you are running Ubuntu 16.04/18.04/20.04 wit
#### How To
If you are developing ROS code to test on the Stretch RE1 and you already have ROS installed on your Ubuntu computer, then there is an easier way of using Rviz than the method described in [SSH & X Server](#ssh-x-server). In the ROS world, this concept is known as "remote master".
If you are developing ROS code to test on Stretch and you already have ROS installed on your Ubuntu computer, then there is an easier way of using Rviz than the method described in [SSH & X Server](#ssh-x-server). In the ROS world, this concept is known as "remote master".
First, identify your robot's and computer's IP address on the network (e.g. using `ifconfig`). These are `robot-ip-address` and `computer-ip-address` respectively.
@ -140,4 +140,5 @@ $ ssh-copy-id -i username@ip-address
This requires you to know the username and ip-address of the robot. Instructions on how to find this information is found in the [SSH & X Server](#ssh-x-server) section. You may now SSH into the robot as normal, and no prompt for the robot's password will appear.
------
<div align="center"> All materials are Copyright 2020 by Hello Robot Inc. The Stretch RE1 robot has patents pending</div>
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 8
- 7
getting_started/updating_software.md View File

@ -1,14 +1,14 @@
# Updating Stretch Software
Stretch's software is improved with new features and bug fixes with each update. In this guide, we cover when and how to update the various software components on your Stretch RE1.
Stretch's software is improved with new features and bug fixes with each update. In this guide, we cover when and how to update the various software components on your Stretch.
## When to Update
We develop our software publicly on Github, allowing anyone to follow/propose the development of a code feature or bug fix. While we wholeheartedly welcome collaboration on Github, it is not necessary to be active on Github to follow our software releases. We announce every major release of software on our [forum](https://forum.hello-robot.com/c/announcements). These are stable releases with code that has been extensively tested on many Stretch RE1s. To be notified of new releases, create an account on the forum and click the bell icon in the top left of the [announcements section](https://forum.hello-robot.com/c/announcements/6). The forum is also available to report issues and ask questions about any of our software packages.
We develop our software publicly on Github, allowing anyone to follow/propose the development of a code feature or bug fix. While we wholeheartedly welcome collaboration on Github, it is not necessary to be active on Github to follow our software releases. We announce every major release of software on our [forum](https://forum.hello-robot.com/c/announcements). These are stable releases with code that has been extensively tested on many Stretch robots. To be notified of new releases, create an account on the forum and click the bell icon in the top left of the [announcements section](https://forum.hello-robot.com/c/announcements/6). The forum is also available to report issues and ask questions about any of our software packages.
## How to Update
Each Stretch RE1 is shipped with firmware, a Python SDK, and ROS packages developed specifically for Stretch. At the moment, there are three separate processes for updating each of these components.
Each Stretch is shipped with firmware, a Python SDK, and ROS packages developed specifically for Stretch. At the moment, there are three separate processes for updating each of these components.
### Stretch ROS
@ -35,14 +35,14 @@ $ pip3 install -U hello_robot_stretch_body_tools_py3
The firmware and the Python SDK (called Stretch Body) communicate on an established protocol. Therefore, it is important to maintain a protocol match between the different firmware and Stretch Body versions. Fortunately, there is a script that handles this automatically. In the command line, run the following command:
```console
$ RE1_firmware_updater.py --status
$ REx_firmware_updater.py --status
```
This script will automatically determine what version is currently running on the robot and provide a recommendation for a next step. Follow the next steps provided by the firmware updater script.
### Ubuntu
The operating system upon which Stretch RE1 is built is called Ubuntu. This operating system provides the underlying packages that power Stretch's software packages. Furthermore, users of Stretch depend on this operating system and the underlying packages to develop software on Stretch. Therefore, it is important to keep the OS and these underlying packages up to date. In the command line, run the following command:
The operating system upon which Stretch is built is called Ubuntu. This operating system provides the underlying packages that power Stretch's software packages. Furthermore, users of Stretch depend on this operating system and the underlying packages to develop software on Stretch. Therefore, it is important to keep the OS and these underlying packages up to date. In the command line, run the following command:
```console
$ sudo apt update
@ -70,8 +70,9 @@ Please upgrade the firmware and/or version of Stretch Body.
This error appears because the low level Python SDK and the firmware cannot communicate to each other. There is a protocol mismatch preventing communication between the two. Simply run the following script and follow its recommendations to upgrade/downgrade the firmware as necessary to match the protocol level of Stretch Body.
```console
$ RE1_firmware_updater.py --status
$ REx_firmware_updater.py --status
```
------
<div align="center"> All materials are Copyright 2020 by Hello Robot Inc. The Stretch RE1 robot has patents pending</div>
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 2
- 1
mkdocs.yml View File

@ -86,7 +86,8 @@ nav:
- Overview: ./getting_started/README.md
- Basics:
- Robot Safety: ./getting_started/safety_guide.md
- Quick Start: ./getting_started/quick_start_guide.md
- Quick Start RE1: ./getting_started/quick_start_guide_re1.md
- Quick Start RE2: ./getting_started/quick_start_guide_re2.md
- Best Practices: ./getting_started/best_practices.md
- Troubleshooting: ./getting_started/troubleshooting_guide.md
- Advanced:

stretch_body/custom_wrist_dof.md/my_wrist_pitch.py → stretch_body/custom_wrist_dof/my_wrist_pitch.py View File


stretch_body/custom_wrist_dof.md/stretch_user_params.yaml → stretch_body/custom_wrist_dof/stretch_user_params.yaml View File


BIN
View File


BIN
View File


BIN
View File


BIN
View File


BIN
View File


BIN
View File


BIN
View File


+ 3
- 0
stretch_body/tutorial_collision_avoidance.md View File

@ -240,3 +240,6 @@ Finally, test out the model by driving the arm and lift around using the XBox te
>>$ stretch_xbox_controller_teleop.py
```
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 3
- 0
stretch_body/tutorial_command_line_tools.md View File

@ -95,3 +95,6 @@ Take a minute to explore each of these tools from the console.
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 2
- 1
stretch_body/tutorial_contact_models.md View File

@ -165,4 +165,5 @@ optional arguments:
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. The Stretch RE1 and RE2 robots have patents pending</div>
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 4
- 1
stretch_body/tutorial_custom_wrist_dof.md View File

@ -64,7 +64,7 @@ In [5]: w.pose('tool_up')
In [6]: w.pose('tool_down')
```
Finally, you'll want to make your WristPitch available from `stretch_body.robot` Add the following [YAML](./stretch_re1_user_params.yaml) to your `stretch_user_params.yaml`
Finally, you'll want to make your WristPitch available from `stretch_body.robot` Add the following [YAML](./custom_wrist_dof/stretch_user_params.yaml) to your `stretch_user_params.yaml`
```yaml
end_of_arm:
@ -87,3 +87,6 @@ In [4]: r.end_of_arm.move_by('wrist_pitch',0.1)
```
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 4
- 3
stretch_body/tutorial_dynamixel_servos.md View File

@ -141,7 +141,7 @@ Stretch Body's low level Dynamixel API includes a hierarchy of three classes
DynamixelXChain manages a set of daisy-chained servos on a single bus (for example the head_pan and head_tilt servos). It allows for greater communication bandwidth by doing group read/write over USB.
The [EndOfArm](https://github.com/hello-robot/stretch_body/blob/master/body/stretch_body/end_of_arm.py) class derives from DynamixelXChain in order to provide an extensible interface that supports a user integrating additional DOF to the robot. The tutorial [Adding Custom Wrist DOF](./tutorial_extending_wrist_dof.md) explains how to do this.
The [EndOfArm](https://github.com/hello-robot/stretch_body/blob/master/body/stretch_body/end_of_arm.py) class derives from DynamixelXChain in order to provide an extensible interface that supports a user integrating additional DOF to the robot. The tutorial [Adding Custom Wrist DOF](./tutorial_custom_wrist_dof.md) explains how to do this.
### DynamixelHelloXL430
@ -190,7 +190,7 @@ stretch_configuration_params.yaml param.head_pan.range_t [0, 3
stretch_configuration_params.yaml param.head_pan.zero_t 1250
```
In addition to `move_to` and `move_by`, the class also implements a splined trajectory interface as discussed in the [Splined Trajectory Tutorial](./tutorial_splined_trajectory.py).
In addition to `move_to` and `move_by`, the class also implements a splined trajectory interface as discussed in the [Splined Trajectory Tutorial](./tutorial_splined_trajectories.md).
### DynamixelXL430
@ -212,4 +212,5 @@ m.stop()
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. The Stretch RE1 robot has patents pending</div>
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 3
- 0
stretch_body/tutorial_introduction.md View File

@ -182,3 +182,6 @@ robot.push_command()
**NOTE**: The Dynamixel servos do not use the Hello Robot communication protocol. As such, the head, wrist, and gripper will move immediately upon issuing a motion command.
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 2
- 1
stretch_body/tutorial_parameter_management.md View File

@ -136,6 +136,7 @@ robot.write_user_param_to_YAML('base.wheel_separation_m', d_avg)
This will update the file `stretch_user_params.yaml`
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. The Stretch RE1 robot has patents pending</div>
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 4
- 0
stretch_body/tutorial_robot_motion.md View File

@ -312,3 +312,7 @@ Motion commands are non-blocking and it is the responsibility of the user code t
The Stretch_Body interface is not designed to support high bandwidth control applications. The natural dynamics of the robot actuators do not support high bandwidth control, and the USB based interface limits high rate communication.
In practice, a Python based control loop that calls push_command( ) at 1Hz to 10Hz is sufficiently matched to the robot natural dynamics.
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 3
- 0
stretch_body/tutorial_robot_sensors.md View File

@ -349,3 +349,6 @@ The `cliff_event` flag is set when any of the four sensor readings exceed `cliff
The cliff detection logic can be found in the [Pimu firmware](https://github.com/hello-robot/stretch_firmware/blob/master/arduino/hello_pimu/Pimu.cpp).
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 5
- 1
stretch_body/tutorial_safe_coding.md View File

@ -106,4 +106,8 @@ The [Robot Sentry](https://github.com/hello-robot/stretch_body/blob/master/pytho
## Collision Avoidance
See the [Collision Avoidance Tutorial](./collision_avoidance.md) for more information the the Stretch collision avoidance system.
See the [Collision Avoidance Tutorial](./tutorial_collision_avoidance.md) for more information the the Stretch collision avoidance system.
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 121
- 1
stretch_body/tutorial_splined_trajectories.md View File

@ -1 +1,121 @@
Coming soon
# Tutorial: Splined Trajectories
Stretch Body supports splined trajectory controllers across all of its joints. This enables Stretch to achieve smooth and coordinated full-body control of the robot.
## What are Splined Trajectories?
A splined trajectory is a smooth path that a robot joint follows over a specific period of time. [Cubic or quintic splines](https://en.wikipedia.org/wiki/Spline_(mathematics)) are used to represent the trajectory. As shown below, the splines (blue) are defined by a series of user provided waypoints (black dot). A waypoint is simply a target position, velocity, and optional acceleration at a given time. The spline ensures continuity and smoothness when interpolating between the waypoint targets.
During execution, the trajectory controller uses this splined representation to compute the instantaneous desired position, velocity, and acceleration of the joint (red). On Stretch, this instantaneous target is then passed to a lower-level position or velocity controller.
Splined trajectories are particularly useful when you want to coordinate motion across several joints. Because the trajectory representation is time based, it is straightforward to encode multi-joint coordination. Stretch Body supports both cubic and quintic spline. A quintic spline waypoint includes acceleration in the waypoint target, while a cubic spline does not.
<img src="./images/splined_traj.png" />
## The Splined Trajectory Tool
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:
```bash
stretch_trajectory_jog.py -h
usage: stretch_trajectory_jog.py [-h] [--text] [--preloaded_traj {1,2,3}] (--head_pan | --head_tilt | --wrist_yaw | --gripper | --arm | --lift | --base_translate | --base_rotate | --full_body)
Test out splined trajectories on the various joint from a GUI or text menu.
optional arguments:
-h, --help show this help message and exit
--text, -t Use text options instead of GUI
--preloaded_traj {1,2,3}, -p {1,2,3}
Load one of three predefined trajectories
--head_pan Test trajectories on the head_pan joint
--head_tilt Test trajectories on the head_tilt joint
--wrist_yaw Test trajectories on the wrist_yaw joint
--gripper Test trajectories on the stretch_gripper joint
--arm Test trajectories on the arm joint
--lift Test trajectories on the lift joint
--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:
xxx
**NOTE**: Use caution when commanding the base. Ensure that attached cables are long enough to support base motion. Alternatively you may want to put the base on top of a book so the wheel don't touch the ground.
Finally, you can explore a full-body trajectory using the non-GUI version of the tool:
## Programming Trajectories
Programming a splined trajectory is straightforward. Try the following from iPython:
```python
import stretch_body.robot
r=stretch_body.robot.Robot()
r.startup()
#Define the waypoints
times = [0.0, 10.0, 20.0]
positions = [r.arm.status['pos'], 0.45, 0.0]
velocities = [r.arm.status['vel'], 0.0, 0.0]
#Create the spline trajectory
for waypoint in zip(times, positions, velocities):
r.arm.trajectory.add(waypoint[0], waypoint[1], waypoint[2])
#Begin execution
r.arm.follow_trajectory()
#Wait unti completion
while r.arm.is_trajectory_active():
print('Execution time: %f'%r.arm.get_trajectory_time_remaining())
time.sleep(0.1)
r.stop()
```
This will cause the arm to move from its current position to 0.45m, then back to fully retracted. A few things to note:
* This will execute a Cubic spline as we did not pass in accelerations to in `r.arm.trajectory.add`
* The call to `r.arm.follow_trajectory` is non-blocking and the trajectory generation is handled by a background thread of the Robot class
If you're interested in exploring the trajectory API further the [code for the `stretch_trajectory_jog.py`](https://github.com/hello-robot/stretch_body/blob/master/tools/bin/stretch_trajectory_jog.py)is a great reference to get started.
## Advanced: Controller Parameters
Sometimes the robot motion isn't quite what is expected when executing a splined trajectories. It is important that the trajectory be well-formed, meaning that it:
* Respects the maximum velocity and accelerations limits of the joint
* Doesn't create a large 'excursion' outside of the acceptable range of motion in order to hit a target waypoint
* Doesn't have waypoints so closely spaced together that it exceeds the nominal control rates of Stretch (~10-20 Hz)
For example, the arm trajectory below has a large excursion outside of the joints range of motion (white). This is because the second waypoint expects a non-zero velocity when the arm reaches full extension.
<img src="./images/bad_trajectory.png" />
Often the trajectory waypoints will be generated from a motion planner. It is important that this planner incorporates the position, velocity, and acceleration constraints of the joint. These can be found by, for example
```bash
>>$ stretch_params.py | grep arm | grep motion | grep trajectory
stretch_body.robot_params.nominal_params param.arm.motion.trajectory_max.vel_m 0.4
stretch_body.robot_params.nominal_params param.arm.motion.trajectory_max.accel_m 0.4
>>$ stretch_params.py | grep arm | grep range_m
stretch_user_params.yaml param.arm.range_m [0.0, 0.515]
```
Fortunately the Stretch Body [Trajectory](https://github.com/hello-robot/stretch_body/blob/master/body/stretch_body/trajectories.py) classes do some preliminary feasibility checking of trajectories using the [is_segment_feasible function](https://github.com/hello-robot/stretch_body/blob/master/body/stretch_body/hello_utils.py#L290). This checks if the generated motions lie within the constraints of the `trajectory_max` parameters.
It is generally important for the waypoints to be spaced far apart. Stretch isn't a dynamic and fast moving robot, so there isn't a practical advantage to closely spaced waypoints at any rate.
The stepper controllers (arm, lift, and base) can be updated at approximately 20 Hz maximum. Therefore, if your waypoints are spaced 50 ms apart, you run the risk of overflowing the stepper controller. Likewise, the Dynamixel joints can be updated at approximately 12 Hz. As a rule of thumb, spacing the waypoints over 100 ms apart is a good idea.
------
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 2
- 1
stretch_body/tutorial_stretch_body_api.md View File

@ -417,4 +417,5 @@ p.stop()
::: stretch_body.pimu.Pimu
------
<div align="center"> All materials are Copyright 2020 by Hello Robot Inc. The Stretch RE1 robot has patents pending</div>
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

+ 2
- 1
stretch_body/tutorial_tool_change.md View File

@ -244,4 +244,5 @@ Stretch ROS also supports the tool plug-in architecture. Under ROS this is manag
More coming soon.
------
<div align="center"> All materials are Copyright 2020 by Hello Robot Inc. The Stretch RE1 robot has patents pending</div>
<div align="center"> All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. The Stretch RE1 and RE2 robots are covered by U.S. Patent 11,230,000 and other patents pending.</div>

Loading…
Cancel
Save