diff --git a/getting_started/README.md b/getting_started/README.md index de514d5..19c2a10 100644 --- a/getting_started/README.md +++ b/getting_started/README.md @@ -6,7 +6,7 @@ Please take the time to get to know your robot by going through these tutorials ## 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: +Stretch RE1 and RE2 are very similar. One quick way to tell the difference is to look at the robot's hostame: ```bash >>$ hostname diff --git a/getting_started/command_line_tools.md b/getting_started/command_line_tools.md new file mode 100644 index 0000000..847b02b --- /dev/null +++ b/getting_started/command_line_tools.md @@ -0,0 +1,116 @@ +# Command Line Tools + +The Stretch RE1 or RE2 comes with a set of command line tools that are helpful for introspection during general use or while troubleshooting issues. This page provides an overview of these tools. If you like, visit the [stretch_body](https://github.com/hello-robot/stretch_body/tree/master/tools/bin) repository to have a look under the hood. + +You can execute these commands from anywhere in the terminal. We recommend you to execute these commands as we follow each one of them. You can also find the description for the utility each tool provides by passing the optional '-h' flag along with the tool name in the terminal. For example, from anywhere in the terminal execute: +```console +stretch_about.py -h +``` + +## System Information +### stretch_about.py +This tool displays the model and serial number information as an image. + +### stretch_about_text.py +This tool displays the model and serial number information as text. + +### stretch_version.sh +This script prints the version information for various software packages on the robot. + +### stretch_params.py +This tool prints the Stretch parameters to the console. + +### stretch_robot_monitor.py +This tool runs the Robot Monitor and prints to console. + +### stretch_robot_urdf_visualizer.py +This tool allows you to visualize robot URDF. + +## Introspection +### stretch_robot_system_check.py +This tool checks that all robot hardware is present and reporting sane values. + +### stretch_robot_battery_check.py +This is a tool to print battery state to console. + +### stretch_hardware_echo.py +This tool echoes the robot and computer hardware details to the console. + +### stretch_robot_dynamixel_reboot.py +This tool reboots all Dynamixel servos on robot. + +### stretch_pimu_scope.py +This tool allows you to visualize Pimu (Power+IMU) board data with an oscilloscope. Pass the '-h' flag along with the command to see optional arguments. + +### stretch_wacc_scope.py +This is a tool to visualize Wacc (Wrist+Accel) board data with an oscilloscope. Pass the '-h' flag along with the command to see optional arguments. + +### stretch_realsense_visualizer.py +This is a tool to test the Realsense D435i Camera. Pass the '-h' flag along with the command to see optional arguments. + +### stretch_respeaker_test.py +This tool allows you to record and playback audio via Respeaker. + +### stretch_audio_test.py +This tool allows you to test the audio system. + +## Homing Joints +### stretch_robot_home.py +This tool calibrates the robot by finding zeros for all robot joints. + +### stretch_gripper_home.py +This tool calibrates the gripper position by closing until motion stops. + +### stretch_wrist_yaw_home.py +This tool calibrates the wrist_yaw position by moving to both hardstops. + +### stretch_arm_home.py +This tool calibrates arm position by moving to hardstop. + +### stretch_lift_home.py +This tool calibrates the lift position by moving to the upper hardstop. + +## Jogging Joints +### stretch_robot_jog.py +This tool prints all robot data to console. + +### stretch_gripper_jog.py +This tool allows you to jog the griper from the keyboard. + +### stretch_wrist_yaw_jog.py +This tool allows you to jog the wrist_yaw joint from the keyboard. + +### stretch_arm_jog.py +This tool allows you to jog the arm motion from the keyboard. + +### stretch_lift_jog.py +This tool allows you to jog the lift motion from the keyboard. + +### stretch_base_jog.py +This tool allows you to jog the base motion from the keyboard. + +### stretch_head_jog.py +This tool allows you to jog the head from the keyboard. + +## Jogging Modules +### stretch_wacc_jog.py +This tool allows you to command and query the Wacc (Wrist Accelerometer) board from the keyboard. + +### stretch_pimu_jog.py +This tool allows you to comnmand and query the Pimu (Power+IMU) board from the keyboard. + +### stretch_rp_lidar_jog.py +This is a tool to control the RP-Lidar. Pass the '-h' flag along with the command to see optional arguments. + +### stretch_trajectory_jog.py +This tool allows you to test out splined trajectories on the various joint from a GUI or text menu. Pass the '-h' flag along with the command to see optional arguments. + +## Teleoperation +### stretch_robot_stow.py +This tool moves robot to stow position. + +### stretch_robot_keyboard_teleop.py +This tool allows you to control the robot base, lift, arm, head, and tool from the keyboard. + +### stretch_xbox_controller_teleop.py +This tool allows you to jog the robot from an XBox Controller. \ No newline at end of file diff --git a/getting_started/updating_software.md b/getting_started/updating_software.md index a127d7b..c034385 100644 --- a/getting_started/updating_software.md +++ b/getting_started/updating_software.md @@ -12,17 +12,41 @@ Each Stretch is shipped with firmware, a Python SDK, and ROS packages developed ### Stretch ROS -Stretch ROS is the [Robot Operating System](https://www.ros.org/about-ros/) (ROS) interface to the robot. Many robotics developers find ROS useful to bootstrap their robotics software developments. You may update it using the following commands: +Stretch ROS is the [Robot Operating System](https://www.ros.org/about-ros/) (ROS) interface to the robot. Many robotics developers find ROS useful to bootstrap their robotics software developments. Depending on whether you want to setup a ROS or ROS 2 workspace, the easiest way to download the most recent updates in the stretch_ros and stretch_ros2 repos, while resolving all source built dependencies at the same time, is by following the instructions in the [Creating a New ROS Workspace](https://github.com/hello-robot/stretch_install/blob/master/docs/ros_workspace.md) section in the stretch_install repo. +**Warning**: Before you proceed, please ensure that all your personal files in the catkin or ament workspace have been backed up safely. This is important because executing the following set of commands deletes your existing workspace and replaces it with a fresh one. + +To download the stretch_install repo, execute: ```console -$ roscd stretch_core -$ git pull +cd ~/ +git clone https://github.com/hello-robot/stretch_install.git +cd stretch_install +git pull ``` -### Stretch Body +To replace the ROS Melodic catkin_ws in Ubuntu 18.04, execute: +```console +# Create a ROS workspace +./factory/18.04/stretch_create_catkin_workspace.sh -w +``` -Stretch Body is the Python SDK to the robot. It abstracts away the low level details of communication with the embedded devices and provides an intuitive API to working with the robot. You may update it using the following commands: +To replace the ROS Noetic catkin_ws in Ubuntu 20.04, execute: +```console +# Create a ROS workspace +./factory/20.04/stretch_create_catkin_workspace.sh -w +``` +To replace the ROS 2 Galactic ament_ws in Ubuntu 20.04, execute: +```console +# Create a ROS2 workspace +./factory/20.04/stretch_create_ament_workspace.sh -w +``` + +### Stretch Body Python SDK + +Stretch Body is the Python SDK to the robot. It abstracts away the low level details of communication with the embedded devices and provides an intuitive API to working with the robot. You may update it using the following commands depending on the Python version. + +If you are using Python2, execute: ```console $ pip install -U hello-robot-stretch-body $ pip install -U hello-robot-stretch-body-tools @@ -30,6 +54,14 @@ $ pip install -U hello-robot-stretch-factory $ pip3 install -U hello_robot_stretch_body_tools_py3 ``` +For Python3, execute: +```console +python3 -m pip -q install --no-warn-script-location hello-robot-stretch-body +python3 -m pip -q install --no-warn-script-location hello-robot-stretch-body-tools +python3 -m pip -q install --no-warn-script-location hello-robot-stretch-factory +python3 -m pip -q install --no-warn-script-location hello-robot-stretch-tool-share +``` + ### Stretch Firmware 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: diff --git a/mkdocs.yml b/mkdocs.yml index 5210edc..8bbe5db 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -92,9 +92,10 @@ nav: - Best Practices: ./getting_started/best_practices.md - Troubleshooting: ./getting_started/troubleshooting_guide.md - Advanced: + - Command Line Tools: ./getting_started/command_line_tools.md - Untethered Operation: ./getting_started/untethered_operation.md - Updating Software: ./getting_started/updating_software.md - - Stretch Body: + - Stretch Body Python SDK: - Overview: ./stretch_body/README.md - Basics: - Introduction: ./stretch_body/tutorial_introduction.md @@ -113,100 +114,67 @@ nav: - Safety Features: ./stretch_body/tutorial_safe_coding.md - ROS: - - ROS1 (Melodic): - - Overview: ./ros1_melodic/README.md - - Basics: - - Getting Started: ./ros1_melodic/getting_started.md - - Gazebo Basics: ./ros1_melodic/gazebo_basics.md - - Teleoperating Stretch: ./ros1_melodic/teleoperating_stretch.md - - Internal State of Stretch: ./ros1_melodic/internal_state_of_stretch.md - - RViz Basics: ./ros1_melodic/rviz_basics.md - - Navigation Stack: ./ros1_melodic/navigation_stack.md - - MoveIt! Basics: ./ros1_melodic/moveit_basics.md - - Follow Joint Trajectory Commands: ./ros1_melodic/follow_joint_trajectory.md - - Perception: ./ros1_melodic/perception.md - - ArUco Marker Detection: ./ros1_melodic/aruco_marker_detection.md - - ReSpeaker Microphone Array: ./ros1_melodic/respeaker_microphone_array.md - - FUNMAP: https://github.com/hello-robot/stretch_ros/tree/master/stretch_funmap - - Other Examples: - - Teleoperate Stretch with a Node: ./ros1_melodic/example_1.md - - Filter Laser Scans: ./ros1_melodic/example_2.md - - Mobile Base Collision Avoidance: ./ros1_melodic/example_3.md - - Give Stretch a Balloon: ./ros1_melodic/example_4.md - - Print Joint States: ./ros1_melodic/example_5.md - - Store Effort Values: ./ros1_melodic/example_6.md - - Capture Image: ./ros1_melodic/example_7.md - - Voice to Text: ./ros1_melodic/example_8.md - - Voice Teleoperation of Base: ./ros1_melodic/example_9.md - - Tf2 Broadcaster and Listener: ./ros1_melodic/example_10.md - - PointCloud Transformation: ./ros1_melodic/example_11.md - - ArUco Tag Locator: ./ros1_melodic/example_12.md - - 2D Navigation Goals: ./ros1_melodic/example_13.md - - ROS1 (Noetic): - - Overview: ./ros1/README.md - - Basics: - - Getting Started: ./ros1/getting_started.md - - Gazebo Basics: ./ros1/gazebo_basics.md - - Teleoperating Stretch: ./ros1/teleoperating_stretch.md - - Internal State of Stretch: ./ros1/internal_state_of_stretch.md - - RViz Basics: ./ros1/rviz_basics.md - - Navigation Stack: ./ros1/navigation_stack.md - - MoveIt! Basics: ./ros1/moveit_basics.md - - Follow Joint Trajectory Commands: ./ros1/follow_joint_trajectory.md - - Perception: ./ros1/perception.md - - ArUco Marker Detection: ./ros1/aruco_marker_detection.md - - ReSpeaker Microphone Array: ./ros1/respeaker_microphone_array.md - - FUNMAP: https://github.com/hello-robot/stretch_ros/tree/master/stretch_funmap - - Other Examples: - - Teleoperate Stretch with a Node: ./ros1/example_1.md - - Filter Laser Scans: ./ros1/example_2.md - - Mobile Base Collision Avoidance: ./ros1/example_3.md - - Give Stretch a Balloon: ./ros1/example_4.md - - Print Joint States: ./ros1/example_5.md - - Store Effort Values: ./ros1/example_6.md - - Capture Image: ./ros1/example_7.md - - Voice to Text: ./ros1/example_8.md - - Voice Teleoperation of Base: ./ros1/example_9.md - - Tf2 Broadcaster and Listener: ./ros1/example_10.md - - PointCloud Transformation: ./ros1/example_11.md - - ArUco Tag Locator: ./ros1/example_12.md - - 2D Navigation Goals: ./ros1/example_13.md - - ROS2 (Galactic, Beta): - - Overview: ./ros2/README.md - - Basics: - - Getting Started: ./ros2/getting_started.md - - Gazebo Basics: ./ros2/gazebo_basics.md - - Teleoperating Stretch: ./ros2/teleoperating_stretch.md - - Internal State of Stretch: ./ros2/internal_state_of_stretch.md - - RViz Basics: ./ros2/rviz_basics.md - - Navigation Stack: - - Navigation Basics: ./ros2/navigation_stack.md - - Simple Commander API: ./ros2/navigation_simple_commander.md - - MoveIt 2: - - MoveIt Basics: ./ros2/moveit_basics.md - - MoveIt with RViz: ./ros2/moveit_rviz_demo.md - - MoveGroup C++ API: ./ros2/moveit_movegroup_demo.md - - Follow Joint Trajectory Commands: ./ros2/follow_joint_trajectory.md - # - Perception: ./ros2/perception.md - # - ArUco Marker Detection: ./ros2/aruco_marker_detection.md - # - ReSpeaker Microphone Array: ./ros2/respeaker_microphone_array.md - # - FUNMAP: https://github.com/hello-robot/stretch_ros/tree/master/stretch_funmap - # - ROS testing: ./ros2/ros_testing.md - # - Other Nav Stack Features: ./ros2/other_nav_features.md - - Other Examples: - - Teleoperate Stretch with a Node: ./ros2/example_1.md - - Filter Laser Scans: ./ros2/example_2.md - - Mobile Base Collision Avoidance: ./ros2/example_3.md - - Give Stretch a Balloon: ./ros2/example_4.md - # - Print Joint States: ./ros2/example_5.md - # - Store Effort Values: ./ros2/example_6.md - # - Capture Image: ./ros2/example_7.md - # - Voice to Text: ./ros2/example_8.md - # - Voice Teleoperation of Base: ./ros2/example_9.md - - Tf2 Broadcaster and Listener: ./ros2/example_10.md - - Obstacle Avoider: ./ros2/obstacle_avoider.md - - Align to ArUco: ./ros2/align_to_aruco.md - - Deep Perception: ./ros2/deep_perception.md - # - PointCloud Transformation: ./ros2/example_11.md - # - ArUco Tag Locator: ./ros2/example_12.md - + - Overview: ./ros1/README.md + - Basics: + - Getting Started: ./ros1/getting_started.md + - Teleoperating Stretch: ./ros1/teleoperating_stretch.md + - Internal State of Stretch: ./ros1/internal_state_of_stretch.md + - RViz Basics: ./ros1/rviz_basics.md + - Navigation Stack: ./ros1/navigation_stack.md + # - MoveIt! Basics: ./ros1/moveit_basics.md + - Follow Joint Trajectory Commands: ./ros1/follow_joint_trajectory.md + - Perception: ./ros1/perception.md + - ArUco Marker Detection: ./ros1/aruco_marker_detection.md + - ReSpeaker Microphone Array: ./ros1/respeaker_microphone_array.md + - FUNMAP: https://github.com/hello-robot/stretch_ros/tree/master/stretch_funmap + - Gazebo Basics: ./ros1/gazebo_basics.md + - Other Examples: + - Teleoperate Stretch with a Node: ./ros1/example_1.md + - Filter Laser Scans: ./ros1/example_2.md + - Mobile Base Collision Avoidance: ./ros1/example_3.md + - Give Stretch a Balloon: ./ros1/example_4.md + - Print Joint States: ./ros1/example_5.md + - Store Effort Values: ./ros1/example_6.md + - Capture Image: ./ros1/example_7.md + - Voice to Text: ./ros1/example_8.md + - Voice Teleoperation of Base: ./ros1/example_9.md + - Tf2 Broadcaster and Listener: ./ros1/example_10.md + - PointCloud Transformation: ./ros1/example_11.md + - ArUco Tag Locator: ./ros1/example_12.md + - 2D Navigation Goals: ./ros1/example_13.md + - ROS 2 (Beta): + - Overview: ./ros2/README.md + - Basics: + - Getting Started: ./ros2/getting_started.md + # - Teleoperating Stretch: ./ros2/teleoperating_stretch.md + - Follow Joint Trajectory Commands: ./ros2/follow_joint_trajectory.md + - Internal State of Stretch: ./ros2/internal_state_of_stretch.md + - RViz Basics: ./ros2/rviz_basics.md + # - Navigation Stack: ./ros2/navigation_stack.md + - MoveIt 2: + - MoveIt Basics: ./ros2/moveit_basics.md + - MoveIt with RViz: ./ros2/moveit_rviz_demo.md + - MoveGroup C++ API: ./ros2/moveit_movegroup_demo.md + # - Perception: ./ros2/perception.md + # - ArUco Marker Detection: ./ros2/aruco_marker_detection.md + # - ReSpeaker Microphone Array: ./ros2/respeaker_microphone_array.md + # - FUNMAP: https://github.com/hello-robot/stretch_ros/tree/master/stretch_funmap + # - ROS testing: ./ros2/ros_testing.md + # - Other Nav Stack Features: ./ros2/other_nav_features.md + # - Gazebo Basics: ./ros2/gazebo_basics.md + - Other Examples: + - Teleoperate Stretch with a Node: ./ros2/example_1.md + - Filter Laser Scans: ./ros2/example_2.md + - Mobile Base Collision Avoidance: ./ros2/example_3.md + - Give Stretch a Balloon: ./ros2/example_4.md + # - Print Joint States: ./ros2/example_5.md + # - Store Effort Values: ./ros2/example_6.md + # - Capture Image: ./ros2/example_7.md + # - Voice to Text: ./ros2/example_8.md + # - Voice Teleoperation of Base: ./ros2/example_9.md + - Tf2 Broadcaster and Listener: ./ros2/example_10.md + - Obstacle Avoider: ./ros2/obstacle_avoider.md + - Align to ArUco: ./ros2/align_to_aruco.md + - Deep Perception: ./ros2/deep_perception.md + # - PointCloud Transformation: ./ros2/example_11.md + # - ArUco Tag Locator: ./ros2/example_12.md diff --git a/ros1/README.md b/ros1/README.md index a65bd48..4db7fa9 100644 --- a/ros1/README.md +++ b/ros1/README.md @@ -1,24 +1,28 @@ ![](../images/banner.png) -# Tutorial Track: Stretch ROS1 +# Tutorial Track: Stretch ROS -This tutorial track is for users looking to become familiar with programming the Stretch RE1 and RE2 via ROS1 Noetic. We recommend going through the tutorials in the following order: +## Robot Operating System (ROS) + +Despite the name, ROS is not an operating system. ROS is a middleware framework that is a collection of transport protocols, development and debugging tools, and open-source packages. As a transport protocol, ROS enables distributed communication via messages between nodes. As a development and debugging toolkit, ROS provides build systems that allows for writing applications in a wide variety of languages (Python and C++ are used in this tutorial track), a launch system to manage the execution of mutiple nodes simultaneously, and command line tools to interact with the running system. Finally, as a popular ecosystem, there are many open-source ROS packages that allow users to quickly prototype with new sensors, actuators, planners, perception stacks, and more. + +This tutorial track is for users looking to become familiar with programming the Stretch RE1 and RE2 via ROS Noetic. We recommend going through the tutorials in the following order: ## Basics | | Tutorial | Description | |---|---------------------------------------------------------------------------------|----------------------------------------------------| -| 1 | [Getting Started](getting_started.md) | | -| 2 | [Gazebo Basics](gazebo_basics.md) | | -| 3 | [Teleoperating Stretch](teleoperating_stretch.md) | | -| 4 | [Internal State of Stretch](internal_state_of_stretch.md) | | -| 5 | [RViz Basics](rviz_basics.md) | | -| 6 | [Navigation Stack](navigation_stack.md) | | -| 7 | [MoveIt! Basics](moveit_basics.md) | | -| 8 | [Follow Joint Trajectory Commands](follow_joint_trajectory.md) | | -| 9 | [Perception](perception.md) | | -| 10 | [ArUco Marker Detection](aruco_marker_detection.md) | | -| 11 | [ReSpeaker Microphone Array](respeaker_microphone_array.md) | | -| 12 | [FUNMAP](https://github.com/hello-robot/stretch_ros/tree/master/stretch_funmap) | | +| 1 | [Getting Started](getting_started.md) | Setup instructions for ROS on Stretch. | +| 2 | [Gazebo Basics](gazebo_basics.md) | Use Stretch in a simulated environment with Gazebo. | +| 3 | [Teleoperating Stretch](teleoperating_stretch.md) | Control Stretch with a keyboard or xbox controller. | +| 4 | [Internal State of Stretch](internal_state_of_stretch.md) | Monitor the joint states of Stretch. | +| 5 | [RViz Basics](rviz_basics.md) | Visualize topics in Stretch. | +| 6 | [Navigation Stack](navigation_stack.md) | Motion planning and control for the mobile base using Nav stack. | +| 7 | [MoveIt! Basics](moveit_basics.md) | Motion planning and control for the arm using MoveIt. | +| 8 | [Follow Joint Trajectory Commands](follow_joint_trajectory.md) | Control joints using joint trajectory server. | +| 9 | [Perception](perception.md) | Use the Realsense D435i camera to visualize the environment. | +| 10 | [ArUco Marker Detection](aruco_marker_detection.md) | Localize objects using ArUco markers. | +| 11 | [ReSpeaker Microphone Array](respeaker_microphone_array.md) | Learn to use the ReSpeaker Microphone Array. | +| 12 | [FUNMAP](https://github.com/hello-robot/stretch_ros/tree/master/stretch_funmap) | Fast Unified Navigation, Manipulation and Planning. | ## Other Examples diff --git a/ros1/getting_started.md b/ros1/getting_started.md index 183394e..6f219e5 100644 --- a/ros1/getting_started.md +++ b/ros1/getting_started.md @@ -1,60 +1,28 @@ # Getting Started -## Ubuntu +## Prerequisites +1. A Stretch robot (see below for simulation instructions if you don’t have a robot) +2. Follow the [Getting Started]() guide (hello_robot_xbox_teleop must not be running in the background) +3. Interacting with Linux through the [command line](https://ubuntu.com/tutorials/command-line-for-beginners#1-overview) +4. Basic understanding of [ROS](http://wiki.ros.org/ROS/Tutorials) +5. Setup [untethered operation](https://docs.hello-robot.com/0.2/stretch-tutorials/getting_started/untethered_operation/) (optional) -Hello Robot utilizes Ubuntu, an open-source Linux operating system, for the Stretch platform. If you are unfamiliar with the operating system, we encourage you to review a [tutorial](https://ubuntu.com/tutorials/command-line-for-beginners#1-overview) provided by Ubuntu. Additionally, the Linux command line, BASH, is used to execute commands and is needed to run ROS on the Stretch robot. Here is a [tutorial](https://ryanstutorials.net/linuxtutorial/) on getting started with BASH. - -## Installing Noetic on Stretch -Instructions on installing Noetic can be found in our open-source [installation guide](https://github.com/hello-robot/stretch_ros/blob/dev/noetic/install_noetic.md). Then create a catkin workspace for your ROS packages. Here is an [installation guide for creating a workspace](http://wiki.ros.org/catkin/Tutorials/create_a_workspace). Once your system is set up, clone the [stretch_tutorials](https://github.com/hello-robot/stretch_tutorials) to your workspace and build the package in your workspace. This can be done by copying the commands below and pasting them into your terminal. - -```bash -cd ~/catkin_ws/src -git clone https://github.com/hello-robot/stretch_tutorials.git -cd stretch_tutorials -git checkout noetic -cd ~/catkin_ws -catkin_make -``` ### Connecting a Monitor If you cannot access the robot through ssh due to your network settings, you will need to connect an HDMI monitor, USB keyboard, and mouse to the USB ports in the robot's trunk. -## ROS Setup on Local Computer - -Hello Robot is currently running Stretch on Ubuntu 20.04 and ROS Noetic. To begin the setup, start with [installing Ubuntu desktop](https://ubuntu.com/tutorials/install-ubuntu-desktop#1-overview) on your local machine. Then follow the [installation guide for ROS Noetic](http://wiki.ros.org/noetic/Installation/Ubuntu) on your system. - -Currently, the Realsense2_description package isn't installed by rosdep and requires a user to install the package manually. Run the following command in your terminal - -```bash -sudo apt-get install ros-noetic-realsense2-camera -``` - -After your system is setup, clone the [stretch_ros](https://github.com/hello-robot/stretch_ros.git), [stretch_tutorials](https://github.com/hello-robot/stretch_tutorials.git), and [realsense_gazebo_plugin packages]( https://github.com/pal-robotics/realsense_gazebo_plugin) to your **src** folder in your preferred workspace. -```bash -cd ~/catkin_ws/src -git clone https://github.com/hello-robot/stretch_ros -git clone https://github.com/pal-robotics/realsense_gazebo_plugin -git clone https://github.com/hello-robot/stretch_tutorials.git -``` - - -Change the directory to that of your catkin workspace and install system dependencies of the ROS packages. Then build your workspace. -```bash -cd ~/catkin_ws -rosdep install --from-paths src --ignore-src -r -y -catkin_make -``` - +## Setting Up Stretch in Simulation +Users who don’t have a Stretch, but want to try the tutorials can set up their computer with Stretch Gazebo. -Once `caktin_make` has finished compiling,source your workspace and **.bashrc** file -```bash -echo "source /home/USER_NAME/catkin_ws/devel/setup.bash" -source ~/.bashrc -``` +Although lower specifications might be sufficient, for the best experience we recommend the following for running the simulation: +**Processor**: Intel i7 or comparable +**Memory**: 16 GB +**Storage**: 50 GB +**OS**: Ubuntu 20.04 +**Graphics Card**: NVIDIA GTX2060 (optional) -## RoboMaker +### Setup +Hello Robot is currently running Stretch on Ubuntu 20.04 and ROS Noetic. To begin the setup, follow the [Run the new robot installation script](https://github.com/hello-robot/stretch_install/blob/master/docs/robot_install.md#run-the-new-robot-installation-script) on your system. -

- -

+Finally, follow the [Creating a new ROS workspace](https://github.com/hello-robot/stretch_install/blob/master/docs/ros_workspace.md) guide to create a fresh catkin workspace complete with all the dependencies. -If you cannot dual boot and install ubuntu on your local machine, an alternative is to use [AWS RoboMaker](https://aws.amazon.com/robomaker/). AWS RoboMaker extends the ROS framework with cloud services. The service provides a robotics simulation service, allowing for testing the Stretch platform. If you are a first-time user of AWS RoboMaker, follow the [guide here](https://github.com/aws-robotics/aws-robomaker-robotics-curriculum/blob/main/getting-started-with-aws-robomaker/_modules/mod-2a-aws.md) to get up and running with the service. \ No newline at end of file +To begin working with a simulated Stretch, follow the [Gazebo basics](https://docs.hello-robot.com/0.2/stretch-tutorials/ros1_melodic/gazebo_basics/) tutorial. \ No newline at end of file diff --git a/ros1/teleoperating_stretch.md b/ros1/teleoperating_stretch.md index b5a08e1..abda158 100644 --- a/ros1/teleoperating_stretch.md +++ b/ros1/teleoperating_stretch.md @@ -1,34 +1,60 @@ ## Teleoperating Stretch ### Xbox Controller Teleoperating -

- -

+If you have not already had a look at the [Xbox Controller Teleoperation](https://docs.hello-robot.com/0.2/stretch-tutorials/getting_started/quick_start_guide_re2/#hello-world-demo) section in the Quick Start guide, now might be a good time to try it. -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. +### Keyboard Teleoperating: Full Body + +For full body teleoperation with the keyboard, you first need to run the `stretch_driver.launch` in a terminal. + +```bash +# Terminal 1 +roslaunch stretch_core stretch_driver.launch +``` +Then in a new terminal, type the following command + +```bash +# Terminal 2 +rosrun stretch_core keyboard_teleop +``` + +Below are the keyboard commands that allow a user to control all of Stretch's joints. +``` +---------- KEYBOARD TELEOP MENU ----------- + + i HEAD UP + j HEAD LEFT l HEAD RIGHT + , HEAD DOWN + + + 7 BASE ROTATE LEFT 9 BASE ROTATE RIGHT + home page-up -Note: Make sure the USB Dongle is plugged into the the USB port of the base trunk. + 8 LIFT UP + up-arrow + 4 BASE FORWARD 6 BASE BACK + left-arrow right-arrow + 2 LIFT DOWN + down-arrow -To start the demo: -* Remove the 'trunk' cover and power on the robot -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 + w ARM OUT + a WRIST FORWARD d WRIST BACK + x ARM IN -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 + 5 GRIPPER CLOSE + 0 GRIPPER OPEN -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. + step size: b BIG, m MEDIUM, s SMALL + + q QUIT + +------------------------------------------- + +``` +To stop the node from sending twist messages, type **Ctrl** + **c**. ### Keyboard Teleoperating: Mobile Base @@ -81,63 +107,8 @@ To stop the node from sending twist messages, type **Ctrl** + **c**. ### Create a node for Mobile Base Teleoperating To move Stretch's mobile base using a python script, please look at [example 1](example_1.md) for reference. -### Keyboard Teleoperating: Full Body - -For full body teleoperation with the keyboard, you first need to run the `stretch_driver.launch` in a terminal. - -```bash -# Terminal 1 -roslaunch stretch_core stretch_driver.launch -``` -Then in a new terminal, type the following command - -```bash -# Terminal 2 -rosrun stretch_core keyboard_teleop -``` - -Below are the keyboard commands that allow a user to control all of Stretch's joints. -``` ----------- KEYBOARD TELEOP MENU ----------- - - i HEAD UP - j HEAD LEFT l HEAD RIGHT - , HEAD DOWN - - - 7 BASE ROTATE LEFT 9 BASE ROTATE RIGHT - home page-up - - - 8 LIFT UP - up-arrow - 4 BASE FORWARD 6 BASE BACK - left-arrow right-arrow - 2 LIFT DOWN - down-arrow - - - w ARM OUT - a WRIST FORWARD d WRIST BACK - x ARM IN - - - 5 GRIPPER CLOSE - 0 GRIPPER OPEN - - step size: b BIG, m MEDIUM, s SMALL - - q QUIT - -------------------------------------------- - -``` -To stop the node from sending twist messages, type **Ctrl** + **c**. - - ## Teleoperating in Gazebo - ### Keyboard Teleoperating: Mobile Base For keyboard teleoperation of the Stretch's mobile base, first [startup Stretch in simulation](gazebo_basics.md). Then run the following command in a new terminal. diff --git a/ros2/README.md b/ros2/README.md index f688646..8496d23 100644 --- a/ros2/README.md +++ b/ros2/README.md @@ -1,29 +1,31 @@ ![](../images/banner.png) -# Tutorial Track: Stretch ROS2 (Beta) +# Tutorial Track: Stretch ROS 2 (Beta) -NOTE: ROS2 support for Stretch is currently under active development and is considered 'beta'. +NOTE: Stretch's ROS2 packages and this ROS2 tutorial track are both under active development. They are considered 'beta', and we welcome any feedback. If you find any issues or bugs, please see the [Stretch ROS2](https://github.com/hello-robot/stretch_ros2/issues) and [Stretch Tutorials](https://github.com/hello-robot/stretch_tutorials/issues) issue trackers. -This tutorial track is for users looking to become familiar with programming the Stretch RE1 and RE2 via ROS2. We recommend going through the tutorials in the following order: +## Robot Operating System 2 (ROS 2) + +Despite the name, ROS is not an operating system. ROS is a middleware framework that is a collection of transport protocols, development and debugging tools, and open-source packages. As a transport protocol, ROS enables distributed communication via messages between nodes. As a development and debugging toolkit, ROS provides build systems that allows for writing applications in a wide variety of languages (Python and C++ are used in this tutorial track), a launch system to manage the execution of mutiple nodes simultaneously, and command line tools to interact with the running system. Finally, as a popular ecosystem, there are many open-source ROS packages that allow users to quickly prototype with new sensors, actuators, planners, perception stacks, and more. + +This tutorial track is for users looking to become familiar with programming the Stretch RE1 and RE2 via ROS 2. We recommend going through the tutorials in the following order: ## Basics | | Tutorial | Description | |--|---------------------------------------------------------------------------------|----------------------------------------------------| -| 1 | [Getting Started](getting_started.md) | | -| 2 | [Gazebo Basics](gazebo_basics.md) | | -| 3 | [Teleoperating Stretch](teleoperating_stretch.md) | | -| 4 | [Internal State of Stretch](internal_state_of_stretch.md) | | -| 5 | [RViz Basics](rviz_basics.md) | | -| 6 | [Navigation Stack](navigation_stack.md) | | -| 7 | [MoveIt! Basics](moveit_basics.md) | | -| 8 | [Follow Joint Trajectory Commands](follow_joint_trajectory.md) | | -| 9 | [Perception](coming_soon.md) | | -| 10 | [ArUco Marker Detection](comming_soon.md) | | -| 11 | [ReSpeaker Microphone Array](respeaker_microphone_array.md) | | -| 12 | [FUNMAP](https://github.com/hello-robot/stretch_ros/tree/master/stretch_funmap) | | -| 13 | [ROS testing](coming_soon.md) | | -| 14 | [Other Nav Stack Features](coming_soon.md) | | - +| 1 | [Getting Started](getting_started.md) | Setup instructions for ROS 2 on Stretch| +| 2 | [Follow Joint Trajectory Commands](follow_joint_trajectory.md) | Control joints using joint trajectory server. | +| 3 | [Internal State of Stretch](internal_state_of_stretch.md) | Monitor the joint states of Stretch. | +| 4 | [RViz Basics](rviz_basics.md) | Visualize topics in Stretch. | +| 5 | [MoveIt2 Basics](moveit_basics.md) | Motion planning and control for the arm using MoveIt. | +| 6 | [MoveIt2 with Rviz](moveit_rviz_demo.md) | Motion planning and control for the arm using MoveIt. | +| 7 | [MoveIt2 MoveGroup C++ API](moveit_movegroup_demo.md) | Motion planning and control for the arm using MoveIt. | + ## Other Examples To help get you get started on your software development, here are examples of nodes to have the stretch perform simple tasks. @@ -36,6 +38,9 @@ To help get you get started on your software development, here are examples of n | 3 | [Mobile Base Collision Avoidance](example_3.md) | Stop Stretch from running into a wall.| | 4 | [Give Stretch a Balloon](example_4.md) | Create a "balloon" marker that goes where ever Stretch goes.| | 5 | [Tf2 Broadcaster and Listener](example_10.md) | Create a tf2 broadcaster and listener.| +| 6 | [Obstacle Avoider](obstacle_avoider.md) | Avoid obstacles using the planar lidar. | +| 7 | [Align to ArUco](align_to_aruco.md) | Detect ArUco fiducials using OpenCV and align to them.| +| 8 | [Deep Perception](deep_perception.md) | Use YOLOv5 to detect 3D objects in a point cloud.|