diff --git a/README.md b/README.md index 4b3337f..8b167f9 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,14 @@ ![](./images/banner.png) -# Overview -![](./images/stretch_top_view.png) -The Stretch Tutorials repository provides tutorials on programming Stretch robots. The tutorials are organized into the following tracks. +# Tutorials + +The Stretch Tutorials repository provides tutorials on programming Stretch robots. The tutorials are organized into the following tracks. -| Tutorial Track | Description | -|--------------------------------------------------------|-------------------------------------------------------------------| -| [Getting to Know Stretch](./getting_started/README.md) | Everything a new user of Stretch needs to get started | -| [Stretch Body Python SDK](./stretch_body/README.md) | Learn how to program Stretch using its low level Python interface | -| [ROS](./ros1/README.md) | Learn how to program Stretch using its ROS interface | -| [ROS 2 (Beta)](./ros2/README.md) | Learn how to program Stretch using its ROS2 interface | -| [Stretch Tool Share](./stretch_tool_share/README.md) | Learn how to update the end of arm tool hardware | +| Tutorial Track | Description | +| ------------------------------------------------- | ----------------------------------------------------------------------------- | +| [Developing with Stretch](./developing/basics.md) | Dig into the concepts and tools you'll need to develop software with Stretch. | +| [Python Tutorials](./python/sensors.md) | Learn how to program Stretch using its Python SDK | +| [ROS 2 Tutorials](./ros2/getting_started.md) | Learn how to program Stretch using its ROS 2 SDK | ------
All materials are Copyright 2022-2024 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks.
diff --git a/developing/basics.md b/developing/basics.md new file mode 100644 index 0000000..6d16e97 --- /dev/null +++ b/developing/basics.md @@ -0,0 +1,250 @@ +# The Basics + +This tutorial introduces the basics of developing with Stretch. It'll cover the concepts and development tools you'll come across, including: + + 1. the robot's operating system + 2. where important files live + 3. using the terminal + +## Operating System + +Stretch's onboard computer is running a desktop Linux operating system called Ubuntu. When you power up Stretch, you'll see the desktop. You'll find Ubuntu's desktop has the same elements as Windows or Mac OS desktops. + +![desktop](./images/desktop.png) + +### Connecting to Wifi + +The system tray shows whether Stretch is connected to the internet. + + - Connected via Wifi: ![wifi connected](./images/wifi_connected.png) + - Connected via Ethernet: ![ethernet connected](./images/ethernet_connected.png) + +To connect via Wifi to a new network, first open Wifi settings. + +![system tray - wifi settings](./images/status_bar_wifi.png) + +Click on your Wifi network and fill out the connection form. + +![wifi connection form](./images/wifi_connect_form.png) + +### Desktop Applications + +Since Ubuntu is a desktop operating system, you can download any applications you need (e.g. Slack, Discord). Ubuntu has an app store called "Ubuntu Software" that makes the install easy. You can also find software online. + +![Ubuntu apps](./images/applications.png) + +Some of the preinstalled applications: + + - **Web Browser:** Firefox + - **Code Editors:** Visual Studio Code, PyCharm, + - **Media Player:** VLC + - **File Explorer:** Files + +### User Accounts + +The default user account is called Hello Robot with the username `hello-robot`. This is also the admin account. + +![default user](./images/default_user.png) + + +#### Changing your Credentials + +The password for the Hello Robot account is printed on the welcome sheet included in the box with Stretch. If you're having trouble finding it, reach out to [support](mailto:support@hello-robot.com). We recommend changing the password for this account. + +![changing password](./images/changing_password.png) + +#### Adding New Users + +If you're sharing Stretch with other developers, it's a good idea to make an account for yourself and your team members. Your code and data will be password protected in your own account, and other developers can change or upgrade their own Stretch SDK without affecting yours and accidentally breaking your code. + +!!! warning + + User accounts cannot completely insulate your account from changes in another. For example, if the robot's tool was changed, your account would have an outdated configuration for what tool is attached to the robot. A non-exhaustive list of changes that could break/affect accounts: + + - Making hardware changes to the robot + - Updating the firmware + - Installing/changing [APT packages](#apt-package-manager) + +Start by logging into the admin Hello Robot user. Go to Users system settings and unlock adminstrator actions. + +![unlock users](./images/unlock_users.png) + +Click "Add User..." and complete the subsequent form. + +![new user form](./images/adding_new_user.png) + +Log out and back in as the new user. Open a terminal and execute the following to pull down the Stretch Install repository: + +```{.bash .shell-prompt .copy} +git clone https://github.com/hello-robot/stretch_install ~/stretch_install +``` + +Make sure it's up-to-date: + +```{.bash .shell-prompt .copy} +cd ~/stretch_install && git pull +``` + +Run the new user install script to set up the SDK for this new account: + +```{.bash .shell-prompt .copy} +./stretch_new_user_install.sh +``` + +Finally, reboot the robot and run a system check in the new user account to confirm if everything was set up correctly. + +```{.bash .shell-prompt .copy} +stretch_robot_system_check.py +``` + +## Where Files Live + +In this section, we'll cover where to find the files that are important for developing code. + +![files app](./images/files_app.png) + +### The Home Folder + +Your account's files all live under the home folder. This directory contains standard organizational folders like `Documents` or `Downloads`, as well as folders that are unique to Stretch's SDK, such as: + + - `stretch_user`: The [Stretch User folder](#the-stretch-user-folder) is required to be present in the home directory for Stretch's SDK to work correctly. It contains calibration data unique to your robot and assets (e.g. neural net checkpoints, maps for navigation, etc.) used by various programs. If you're missing this directory, reach out to support. + - `ament_ws`: The Ament Workspace folder contains Stretch's ROS2 SDK. This directory will be covered in more detail in the [Using ROS 2 with Stretch](#TODO) tutorial. If this folder is missing, you may be using an older [robot distribution](../../../software/distributions/) and should consider upgrading. + - `catkin_ws`: The Catkin Workspace folder contains Stretch's ROS1 SDK. If this folder exists, you may be using an older [robot distribution](../../../software/distributions/) and should consider upgrading. + +![files](./images/files.png) + +### The Stretch User Folder + +The Stretch User folder contains calibration data unique to your robot and assets (e.g. neural net checkpoints, maps for navigation, etc.) used by various programs in Stretch's SDK. The directories in this folder are: + + - `stretch-yyy-xxxx`: This is the [robot calibration directory](#the-robot-calibration-folder). Its naming scheme is "stretch-" following by "re1" for a Stretch RE1, "re2" for a Stretch 2, or "se3" for a Stretch 3, finally followed by your robot's four digit serial number. + - `stretch_deep_perception_models`: This directory contains open deep learning models from third parties, including object detection, head detection, facial landmarks detection, and human pose detection. + - `maps`: This directory contains [occupancy maps](https://www.cs.cmu.edu/~16831-f14/notes/F14/16831_lecture06_agiri_dmcconac_kumarsha_nbhakta.pdf) that are to be used with the Stretch Nav2 ROS2 package. + - `debug`: This directory contains debug output from the Stretch FUNMAP ROS2 package. + - `log`: This directory contains logfiles from various Stretch programs. + +### The Robot Calibration Folder + +The naming scheme for the robot calibration directory is `stretch-yyy-xxxx`, where "stretch-" is followed by "re1" for a Stretch RE1, "re2" for a Stretch 2, or "se3" for a Stretch 3, and finally followed by your robot's four digit serial number. For example, a Stretch 3 with serial number 3001 would be called `stretch-se3-3001`. The important directories in this folder are: + + - `calibration_ros`: This folder contains calibrated URDFs. The concepts of URDFs and calibrations will be covered in more detail in the [URDF Calibration](#urdf-calibration) section below. + - `exported_urdf`: This folder contains a single calibrated standalone URDF of your Stretch. It will be covered in more detail in the [URDF Calibration](#urdf-calibration) section below. + - `stretch_user_params.yaml`: This YAML file is for you to edit when you want to change a robot parameter. The [Advanced Features](#TODO) tutorial later in this series explains what robot parameters are and why you might want to change them. + - `stretch_configuration_params.yaml`: This YAML file contains robot parameters unique to your robot. You don't want to edit this file. + - `udev`: This folder contains a backup of the udev rules that enable Stretch's USB system to function correctly. + +### The /etc/hello-robot Folder + +This is a system level folder, available to all users on the robot. It contains: + + - `stretch-yyy-xxxx`: A system-wide backup of the [robot calibration directory](#the-robot-calibration-folder). Often, this is the oldest version since the Stretch User copy in each user account is updated by the SDK. + +## Terminal + +The terminal is an essential tool to developing on Stretch and on Linux systems in general. We'll become familiar with it in this section. + +![terminal app](./images/terminal_app.png) + +### Terminology + +What exactly is a "terminal"? How does it relate to a "command prompt" or a "shell"? Let's clarify some terminology: + + - **Terminal Emulator** or "terminal", as it's often shortened to, is an application with a simple user interface: you type commands into the terminal, press enter to execute, and it prints out the results. On Windows, this application is called Command Prompt, and on MacOS and Ubuntu, it's called the Terminal. + - ![a terminal emulator window](./images/empty_terminal.png) + - **Shell** is the program that actually interprets your commands, performs some action with them, and returns the output to the terminal. The shell on your Stretch is called [Bash](https://www.gnu.org/software/bash/). You may see the term "shell script", which refers to ".sh" or ".bash" files containing a series of commands written for Bash. Each shell has unique commands it accepts, so for example, commands for Bash won't work on a Windows shell. Fortunately, Bash is ubiquitous in computing, and learning its commands will be useful. + - **Command Line** refers to the line on which you type the commands. It looks like this: blinking command line. You'll notice the line contains some information before the blinking cursor. The format is usually `user@hostname:current_path$ type_command_here`. Here, the user is hello-robot, the hostname is stretch-re2-2002 (hostnames for Stretch robots follows the `stretch-yyy-xxxx` format described above), the current path/folder is `~` (the tilde represents the home directory), then the dollar sign, and finally, the cursor where you can type your commands. On this docs site, instructions will often provide commands for you to run in the terminal and you will see that they often have `$` before them. The dollar sign is signifying that what comes after is meant to be run on the command line (`$` is not actually part of the command). + - For example, the command below is proceeded by a dollar sign, signifying `pwd` is a command line command. + ```{.bash .shell-prompt .copy} + pwd + ``` + - **CLI** stands for "command line interface" and refers to the commands that a program makes available for you to use from the command line. The Stretch SDK comes with a CLI and the [Command Line Tools](./cli.md) tutorial explores this CLI in more detail. + - **Git** is a program for keeping track of code changes and the git CLI is a popular method of collaboratively developing code. + - **SSH** is a program that allows you to access the shell of another machine. You can "secure shell" or "ssh into" another machine using the SSH CLI. SSH is a popular method of running commands on Stretch while having no wires connected to the robot. + +### Copying/Pasting to the Terminal + +TODO - Ctrl C vs Ctrl Shift C + +### The Change Directory Command + +You can use the terminal to navigate the file system. When you open a terminal, you'll be in the home directory (often denoted by `~`). `cd` allows you to change directory to another directory. For example, you can go into the Stretch User directory using: + +```{.bash .shell-prompt .copy} +cd stretch_user/ +``` + +After typing or copying this command into the terminal, press ++enter++ to execute the command. + +![Example of using cd](./images/cd_example.png) + +Your location among the directories is called a "file path" (e.g. the command above places you in the `~/stretch_user` filepath). You can return to the home directory at anytime by typing `cd` without any following arguments. + +### Tab Completion + +TODO + +``` +cd stre +``` + +### Commands + +| Command | Arguments | Description | Examples | +|-----------|----------------------------------|---------------------------------------------------------------------------------|------------------------------------| +| **pwd** | none | Print Working Directory - Prints out your current filepath | `pwd` | +| **ls** | any number of optional filepaths | List - Used to display a list of all files and folders in the current directory | `ls` | +| **mkdir** | a single filepath | Make New Directory - Used to create folders | `mkdir temporary_folder` | +| **rmdir** | a single filepath | Remove Directory - Used to delete folders | `rmdir temporary_folder` | +| **touch** | a single filepath | File Creation - Used to create empty files | `touch temporary_file` | +| **gedit** | a single filepath | File Editor - Brings up a text editor | `gedit temporary_file` | +| **cat** | a single filepath | Concatenate - Prints out the contents of a file | `cat temporary_file` | +| **mv** | two filepaths | Move - Used to move files between directories and/or rename files | `mv temporary_file ~/stretch_user` | +| **rm** | a single filepath | Remove - Used to delete files | `rm ~/stretch_user/temporary_file` | + +TODO - [Link to file system video here](https://youtu.be/Fqu2P2M092Y) + +#### Flags + +TODO + +### APT Package Manager + +APT is a system package manager used to install applications. It can install packages that have no GUI. For example, all ROS2 software is installed through APT. The APT CLI enables you to introspect and install new software onto Stretch. Since APT makes changes at the system level, it requires "super user access", which means each of the commands below is preceded by `sudo` and will ask for your password. + +| Command | Arguments | Description | Examples | +|-----------------|-----------------------------|---------------------------------------------------------------|-----------------------| +| **apt list** | none | List - Displays all of the packages installed | `sudo apt list` | +| **apt update** | none | Update - Refreshes APT's indices of packages available online | `sudo apt update` | +| **apt upgrade** | none | Upgrade - Updates all APT packages to their latest versions | `sudo apt upgrade` | +| **apt install** | any number of package names | Install - Used to install new packages | `sudo apt install sl` | +| **apt remove** | a single package name | Uninstall - Used to remove packages | `sudo apt remove sl` | + +!!! note + + You may not be able to run APT immediately after a reboot as the OS may be running automatic updates in the background. You might see `Could not get lock /var/lib/dpkg/lock-frontend` when trying to use the APT CLI. Typically, waiting 10-20 minutes will allow you to use APT again. + +### Git & GitHub + +Git is a open source tool used for version control of source code. The Git CLI is a common way of interacting with Git repositories of code. Independently, GitHub is a popular website for publishing your Git repositories, and GitHub's features facilitate collaborative development online. At Hello Robot, we use both of these tools in our development flow (see the [Contributing](../../../software/contributing/) guide for info on our Github repos). Github has published a great [quick start](https://docs.github.com/en/get-started/quickstart/hello-world) tutorial covering Git's CLI and GitHub's features, so it's recommended that you follow that guide to learn more about these tools. + +### Environment Variables + +Bash environment variables are configurable variables that programs can read in to configure their behavior. Some variables are standard across Linux. For example, the `HOME` variable will point to your account's home folder. You can print out the value of the `HOME` variable using the `echo` command. When evaluating an environment variable in a command, prepend a dollar sign to the variable. + +```{.bash .shell-prompt .copy} +echo $HOME +``` + +There are also custom environment variables. For example, Stretch robots are preconfigured with two custom variables that enable the Stretch SDK to function. They are `HELLO_FLEET_PATH` and `HELLO_FLEET_ID`. `HELLO_FLEET_PATH` points to the robot's Stretch User directory, and `HELLO_FLEET_ID` is the robot's `stretch-yyy-xxxx` formatted name. + +![Stretch environment variables](./images/hello_env_vars.png) + +Bash environment variables can be configured to persist between terminal sessions by defining them in a hidden configuration file located at `~/.bashrc`. Try opening this file with `gedit ~/.bashrc` and scrolling to the bottom to see Stretch's BashRC setup. + +### File Descriptors + +TODO - [Link to file descriptors video here](https://youtu.be/Fqu2P2M092Y) + +### Piping + +TODO - [Link to piping video here](https://youtu.be/Fqu2P2M092Y) diff --git a/developing/cli.md b/developing/cli.md new file mode 100644 index 0000000..50613e0 --- /dev/null +++ b/developing/cli.md @@ -0,0 +1,409 @@ +# Command Line Tools + +This tutorial covers the command line tools included in the Stretch CLI. For a primer on using CLIs and the terminal, see [The Basics](basics.md#terminal) tutorial. The Stretch CLI is split among Stretch's Python packages. They are: + + - Stretch Body - Tools that perform common tasks that are useful when developing with Stretch. + - Stretch PyFUNMAP - Tools that explore the capabilities of PyFUNMAP. + - Stretch Diagnostics - Tools for diagnosing issues with your robot. + - Stretch URDF - Tools for working with Stretch's URDFs. + - Stretch Factory - Tools used at Hello Robot during the robot's bring-up. + +## Stretch Body Tools + +These tools perform common tasks that are useful when working with Stretch (e.g. homing routine, joint jogging, etc.). + +### `stretch_robot_system_check.py` +[Link to source code](https://github.com/hello-robot/stretch_body/blob/master/tools/bin/stretch_robot_system_check.py) + +The robot system check tool runs a series of tests, such as if each subsystem is online, and reports pass or fail. If everything passes in the report, the robot is ready to be used. You would use this tool everytime you use the robot. A passing output should look like: + +
stretch_robot_system_check.py 
+For use with S T R E T C H (R) RESEARCH EDITION from Hello Robot Inc.
+---------------------------------------------------------------------
+
+---- Checking Devices ----
+[Pass] : hello-wacc
+[Pass] : hello-motor-left-wheel
+[Pass] : hello-pimu
+[Pass] : hello-lrf
+[Pass] : hello-dynamixel-head
+[Pass] : hello-dynamixel-wrist
+[Pass] : hello-motor-arm
+[Pass] : hello-motor-right-wheel
+[Pass] : hello-motor-lift
+[Pass] : hello-respeaker
+
+---- Checking Pimu ----
+[Pass] Voltage = 12.863744497299194
+[Pass] Current = 2.67002009121435
+[Pass] Temperature = 23.45359845039172
+[Pass] Cliff-0 = 16.7066650390625
+[Pass] Cliff-1 = 0.47015380859375
+[Pass] Cliff-2 = -15.3138427734375
+[Pass] Cliff-3 = -5.50537109375
+[Pass] IMU AZ = -9.81534139672
+[Pass] IMU Pitch = 0.0
+[Pass] IMU Roll = 0.0
+
+---- Checking EndOfArm ----
+[Pass] Ping of: wrist_pitch
+[Pass] Ping of: wrist_roll
+[Pass] Ping of: wrist_yaw
+[Pass] Homed: wrist_yaw
+[Pass] Ping of: stretch_gripper
+[Pass] Homed: stretch_gripper
+
+
+---- Checking Head ----
+[Pass] Ping of: head_pan
+[Pass] Ping of: head_tilt
+
+---- Checking Wacc ----
+[Pass] AX = 9.628660202026367
+
+---- Checking hello-motor-left-wheel ----
+[Pass] Position = -3.035825729370117
+
+---- Checking hello-motor-right-wheel ----
+[Pass] Position = 2.784149408340454
+
+---- Checking hello-motor-arm ----
+[Pass] Position = 0.013962420634925365
+[Pass] Position Homed = True
+
+---- Checking hello-motor-lift ----
+[Pass] Position = 31.580163955688477
+[Pass] Position Homed = True
+
+---- Checking for Intel D435i ----
+Bus 002 Device 002: ID 8086:0b3a Intel Corp. Intel(R) RealSense(TM) Depth Camera 435i
+[Pass] : Device found
+
+---- Checking Software ----
+[Pass] Ubuntu 22.04 is ready
+[Pass] All APT pkgs are setup correctly
+[Pass] Firmware is up-to-date
+         hello-pimu = v0.6.2p4
+         hello-wacc = v0.5.1p3
+         hello-motor-arm = v0.6.2p4
+         hello-motor-lift = v0.6.3p4
+         hello-motor-left-wheel = v0.6.2p4
+         hello-motor-right-wheel = v0.6.2p4
+[Pass] Python pkgs are up-to-date
+         hello-robot-stretch-body = 0.6.8
+         hello-robot-stretch-body-tools = .6.3
+         hello-robot-stretch-tool-share = 0.2.8
+         hello-robot-stretch-factory = 0.4.13
+         hello-robot-stretch-diagnostics = 0.0.14
+         hello-robot-stretch-urdf = 0.0.18
+[Pass] ROS2 Humble is ready
+         Workspace at ~/ament_ws/src/stretch_ros2
+
+ +In addition to checking the robot's hardware, this tool also prints out a software report. This includes which version of Stretch's Python, ROS2, etc. software your system has installed. Check out the [Keeping your Software Up-to-date](../../../software/updating_software/#identifying-your-current-software) guide for a how-to on using this report to keep your robot's software up-to-date. + +### `stretch_robot_home.py` +[Link to source code](https://github.com/hello-robot/stretch_body/blob/master/tools/bin/stretch_robot_home.py) + +This tool will start Stretch's homing procedure, where every joint's zero is found. Robots with relative encoders (vs absolute encoders) need a homing procedure when they power on. For Stretch, it's a 30-second procedure that must occur everytime the robot is powered on before you may send motion commands to or read correct joint positions from Stretch's joints. Normal output from this tool looks like: + +```{.whatever .shell-prompt} +stretch_robot_home.py +For use with S T R E T C H (R) RESEARCH EDITION from Hello Robot Inc. +--------------------------------------------------------------------- + +--------- Homing Head ---- +--------- Homing Lift ---- +Homing Lift... +Hardstop detected at motor position (rad) 105.44721221923828 +Marking Lift position to 1.096683 (m) +Marking Lift position to 0.000000 (m) +[INFO] [robot_monitor]: Guarded contact lift +Lift homing successful +--------- Homing Arm ---- +Homing Arm... +Hardstop detected at motor position (rad) -1.5079643726348877 +Marking Arm position to 0.000000 (m) +[INFO] [robot_monitor]: Guarded contact arm +[INFO] [robot_monitor]: Wrist single tap: 9 +Arm homing successful +Moving to first hardstop... +First hardstop contact at position (ticks): 4097 +----- +Homing offset was 3671 +Marking current position to zero ticks +Homing offset is now -427 (ticks) +----- +Current position (ticks): 24 +Moving to calibrated zero: (rad) +[INFO] [robot_monitor]: Wrist single tap: 11 +[INFO] [robot_monitor]: Wrist single tap: 15 +[INFO] [robot_monitor]: Wrist single tap: 21 +[INFO] [robot_monitor]: Wrist single tap: 27 +[INFO] [robot_monitor]: Wrist single tap: 28 +[INFO] [robot_monitor]: Wrist single tap: 33 +[INFO] [robot_monitor]: Wrist single tap: 38 +[INFO] [robot_monitor]: Wrist single tap: 40 +Moving to first hardstop... +First hardstop contact at position (ticks): -9 +----- +Homing offset was 2234 +Marking current position to zero ticks +Homing offset is now 2237 (ticks) +----- +Current position (ticks): 35 +Moving to calibrated zero: (rad) +``` + +### `stretch_robot_stow.py` + +Useful to return the robot arm to a safe position within the base footprint. Normal output from this tool looks like: + +```{.whatever .shell-prompt} +stretch_robot_stow.py +For use with S T R E T C H (R) RESEARCH EDITION from Hello Robot Inc. +--------------------------------------------------------------------- + +--------- Stowing Arm ---- +--------- Stowing EOA_Wrist_DW3_Tool_SG3 ---- +--------- Stowing Lift ---- + +``` + +### `stretch_robot_battery_check.py` + +A quick way to check the robot's battery voltage / current consumption. Normal output from this tool looks like: + +
stretch_robot_battery_check.py
+For use with S T R E T C H (R) RESEARCH EDITION from Hello Robot Inc.
+---------------------------------------------------------------------
+
+[Pass] Voltage with 12.791140079498291
+[Pass] Current with 6.154119995023523
+[Pass] CPU Temp with 45
+
+ +### `stretch_robot_keyboard_teleop.py` + +This tool enables jogging of the robot's joints from the keyboard. + +5 + +What's the difference between jog and `stretch_robot_keyboard_teleop.py` + +### `stretch_xbox_controller_teleop.py` + +6 + +Useful to quickly test if a robot can achieve a task by manually teleoperating the robot + +### `stretch_gamepad_teleop.py` + +7 + +### `stretch_free_robot_process.py` + +8 + +### `stretch_params.py` + +9 + +This tool prints the Stretch parameters to the console. + +### `stretch_realsense_visualizer.py` + +10 + +This is a tool to test the Realsense D435i Camera. Pass the '-h' flag along with the command to see optional arguments. + +### `stretch_rp_lidar_jog.py` + +11 + +### `stretch_audio_test.py` + +12 + +This tool allows you to test the audio system. + +### `stretch_respeaker_test.py` + +13 + +This tool allows you to record and playback audio via Respeaker. + +### `stretch__home.py` + +14 + + - stretch_arm_home.py + - stretch_gripper_home.py + - stretch_lift_home.py + - stretch_wrist_yaw_home.py + +### `stretch__jog.py` + +15 + + - stretch_arm_jog.py + - stretch_base_jog.py + - stretch_gripper_jog.py + - stretch_head_jog.py + - stretch_lift_jog.py + - stretch_pimu_jog.py + - stretch_wacc_jog.py + - stretch_wrist_yaw_jog.py + +### `stretch__scope.py` + +16 + + - 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_about.py` + +17 + +This tool displays the model and serial number information as an image. + +### `stretch_about_text.py` + +18 + +This tool displays the model and serial number information as text. + +### `stretch_hardware_echo.py` + +Can we get rid of this? + +This tool echoes the robot and computer hardware details to the console. + +### `stretch_trajectory_jog.py` + +19 + +### `stretch_robot_dynamixel_reboot.py` + +20 + +Resets all Dynamixels in the robot, which might be necessary if a servo overheats during use and enters an error state. + +This tool reboots all Dynamixel servos on the robot. + +### `stretch_robot_monitor.py` + +21 + +What does this do? + +This tool runs the Robot Monitor and prints to the console. + +### `stretch_robot_urdf_visualizer.py` + +Can we replace this with the new Stretch URDF tools? + +This tool allows you to visualize robot URDF. + +### `stretch_version.sh` + +Can we get rid of this? + +This script prints the version information for various software packages on the robot. + + +## Stretch PyFUNMAP Tools + +### pyfunmap_head_scan_visualizer.py + + +## Stretch Diagnostics Tools + +### `stretch_diagnostic_check.py` + + +## Stretch URDF Tools + +### stretch_urdf_example.py + +### stretch_urdf_viz.py + + +## Stretch Factory Tools + +These tools are used at Hello Robot during the robot's system bring-up. They generally interact with the lowest level interface of the hardware, making measurements and writing calibration data to the robot's calibration folder. + +!!! warning + + It is possible to cause bodily harm and/or break your robot with these tools. Used improperly, these tools might not respect joint torque and position limits. They may overwrite existing calibration data as well. + +### RE1_migrate_contacts.py + +### RE1_migrate_params.py + +### REx_D435i_check.py + +### REx_base_calibrate_imu_collect.py + +### REx_base_calibrate_imu_process.py + +### REx_base_calibrate_wheel_separation.py + +### REx_calibrate_gravity_comp.py + +### REx_calibrate_guarded_contact.py + +### REx_calibrate_range.py + +### REx_cliff_sensor_calibrate.py + +### REx_comm_rates.py + +### REx_discover_hello_devices.py + +### REx_dmesg_monitor.py + +### REx_dynamixel_id_change.py + +### REx_dynamixel_id_scan.py + +### REx_dynamixel_jog.py + +### REx_dynamixel_reboot.py + +### REx_dynamixel_set_baud.py + +### REx_firmware_flash.py + +### REx_firmware_updater.py + +### REx_gamepad_configure.py + +### REx_gripper_calibrate.py + +### REx_hello_dynamixel_jog.py + +### REx_stepper_calibration_YAML_to_flash.py + +### REx_stepper_calibration_flash_to_YAML.py + +### REx_stepper_calibration_run.py + +### REx_stepper_ctrl_tuning.py + +### REx_stepper_gains.py + +### REx_stepper_jog.py + +### REx_stepper_mechaduino_menu.py + +### REx_trace_firmware.py + +### REx_trace_robot.py + +### REx_usb_reset.py + +### REx_wacc_calibrate.py diff --git a/developing/images/adding_new_user.png b/developing/images/adding_new_user.png new file mode 100644 index 0000000..18e4c3d Binary files /dev/null and b/developing/images/adding_new_user.png differ diff --git a/developing/images/applications.png b/developing/images/applications.png new file mode 100644 index 0000000..6717bb4 Binary files /dev/null and b/developing/images/applications.png differ diff --git a/developing/images/cd_example.png b/developing/images/cd_example.png new file mode 100644 index 0000000..941adcd Binary files /dev/null and b/developing/images/cd_example.png differ diff --git a/developing/images/changing_password.png b/developing/images/changing_password.png new file mode 100644 index 0000000..0cbccd6 Binary files /dev/null and b/developing/images/changing_password.png differ diff --git a/developing/images/command_line_blinking.gif b/developing/images/command_line_blinking.gif new file mode 100644 index 0000000..0889b0f Binary files /dev/null and b/developing/images/command_line_blinking.gif differ diff --git a/developing/images/default_user.png b/developing/images/default_user.png new file mode 100644 index 0000000..7d960cd Binary files /dev/null and b/developing/images/default_user.png differ diff --git a/developing/images/desktop.png b/developing/images/desktop.png new file mode 100644 index 0000000..337e7aa Binary files /dev/null and b/developing/images/desktop.png differ diff --git a/developing/images/empty_terminal.png b/developing/images/empty_terminal.png new file mode 100644 index 0000000..03c9f59 Binary files /dev/null and b/developing/images/empty_terminal.png differ diff --git a/developing/images/ethernet_connected.png b/developing/images/ethernet_connected.png new file mode 100644 index 0000000..e647e7b Binary files /dev/null and b/developing/images/ethernet_connected.png differ diff --git a/developing/images/files.png b/developing/images/files.png new file mode 100644 index 0000000..0712cd6 Binary files /dev/null and b/developing/images/files.png differ diff --git a/developing/images/files_app.png b/developing/images/files_app.png new file mode 100644 index 0000000..4048b84 Binary files /dev/null and b/developing/images/files_app.png differ diff --git a/developing/images/hello_env_vars.png b/developing/images/hello_env_vars.png new file mode 100644 index 0000000..d3bc390 Binary files /dev/null and b/developing/images/hello_env_vars.png differ diff --git a/developing/images/status_bar_wifi.png b/developing/images/status_bar_wifi.png new file mode 100644 index 0000000..e5fad3a Binary files /dev/null and b/developing/images/status_bar_wifi.png differ diff --git a/developing/images/terminal_app.png b/developing/images/terminal_app.png new file mode 100644 index 0000000..9d9b8b1 Binary files /dev/null and b/developing/images/terminal_app.png differ diff --git a/developing/images/unlock_users.png b/developing/images/unlock_users.png new file mode 100644 index 0000000..8e03295 Binary files /dev/null and b/developing/images/unlock_users.png differ diff --git a/developing/images/wifi_connect_form.png b/developing/images/wifi_connect_form.png new file mode 100644 index 0000000..4020683 Binary files /dev/null and b/developing/images/wifi_connect_form.png differ diff --git a/developing/images/wifi_connected.png b/developing/images/wifi_connected.png new file mode 100644 index 0000000..7ae7fc2 Binary files /dev/null and b/developing/images/wifi_connected.png differ diff --git a/developing/networking.md b/developing/networking.md new file mode 100644 index 0000000..c9572d4 --- /dev/null +++ b/developing/networking.md @@ -0,0 +1,3 @@ +# Networking Guide + +TODO diff --git a/developing/python.md b/developing/python.md new file mode 100644 index 0000000..acf0852 --- /dev/null +++ b/developing/python.md @@ -0,0 +1,44 @@ +# Using Python with Stretch + +This tutorial covers the TODO. + +TODO - [Link to video here](https://youtu.be/Fqu2P2M092Y) + +## Creating Python Scripts + +### Python in the Terminal + +### Python IDEs + +## Pip - Python's Package Manager + +### Stretch Packages + +#### API Refs + +### Useful Packages for Robotics + + - numpy + - scipy + - cv2 + - pytorch + +### Editable Install + +## Debugging + +### Interpreting Stack Traces + +### pdb + +### iPython + +### Pickle + +## Profiling + +### cProfile + +## Virtual Environments + +### Conda diff --git a/getting_started/README.md b/getting_started/README.md deleted file mode 100644 index eb60b21..0000000 --- a/getting_started/README.md +++ /dev/null @@ -1,39 +0,0 @@ -![](../images/banner.png) -# Tutorial Track: Getting to Know Stretch -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 Stretch 2 are very similar. One quick way to tell the difference is to look at the robot's hostname: - -```{.bash .shell-prompt} -hostname -``` -```{.bash .no-copy} ---- OUTPUT --- -stretch-re2-2001 -``` - -Another way is to look for the distinctive pink stripe on the base of Stretch 2: - -![](./images/pink_strip.png) - -## Basics -| | 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 Stretch 2](quick_start_guide_re2.md) | Unboxing Stretch 2 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 | - ------- -
All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks.
diff --git a/getting_started/best_practices.md b/getting_started/best_practices.md deleted file mode 100644 index 24e06bc..0000000 --- a/getting_started/best_practices.md +++ /dev/null @@ -1,26 +0,0 @@ -# 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" - - [Stretch RE1 Battery Maintenance Guide](https://docs.hello-robot.com/0.2/stretch-hardware-guides/docs/battery_maintenance_guide_re1/) - -=== "Stretch 2" - - [Stretch 2 Battery Maintenance Guide](https://docs.hello-robot.com/0.2/stretch-hardware-guides/docs/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 | - ------- -
All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks.
\ No newline at end of file diff --git a/getting_started/command_line_tools.md b/getting_started/command_line_tools.md deleted file mode 100644 index f787b55..0000000 --- a/getting_started/command_line_tools.md +++ /dev/null @@ -1,116 +0,0 @@ -# Command Line Tools - -The Stretch robot 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 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: -```{.bash .shell-prompt} -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 the 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 is reporting sane values. - -### stretch_robot_battery_check.py -This is a tool to print the battery state to the 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 the 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 the 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 the 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 command 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 the 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/images/300 b/getting_started/images/300 deleted file mode 100644 index e69de29..0000000 diff --git a/getting_started/images/300-0 b/getting_started/images/300-0 deleted file mode 100644 index f34d0b4..0000000 Binary files a/getting_started/images/300-0 and /dev/null differ diff --git a/getting_started/images/NOCO_Genius10_UI_rs.png b/getting_started/images/NOCO_Genius10_UI_rs.png deleted file mode 100644 index 32bc53c..0000000 Binary files a/getting_started/images/NOCO_Genius10_UI_rs.png and /dev/null differ diff --git a/getting_started/images/clip-clamp.png b/getting_started/images/clip-clamp.png deleted file mode 100644 index a215a50..0000000 Binary files a/getting_started/images/clip-clamp.png and /dev/null differ diff --git a/getting_started/images/clip-clamp_rs.png b/getting_started/images/clip-clamp_rs.png deleted file mode 100644 index f918a49..0000000 Binary files a/getting_started/images/clip-clamp_rs.png and /dev/null differ diff --git a/getting_started/images/hand_crush2_rs.png b/getting_started/images/hand_crush2_rs.png deleted file mode 100644 index 097fd03..0000000 Binary files a/getting_started/images/hand_crush2_rs.png and /dev/null differ diff --git a/getting_started/images/hand_crush_rs.png b/getting_started/images/hand_crush_rs.png deleted file mode 100644 index 286daa3..0000000 Binary files a/getting_started/images/hand_crush_rs.png and /dev/null differ diff --git a/getting_started/images/lift_down_rs.png b/getting_started/images/lift_down_rs.png deleted file mode 100644 index 60366a0..0000000 Binary files a/getting_started/images/lift_down_rs.png and /dev/null differ diff --git a/getting_started/images/lift_rs.png b/getting_started/images/lift_rs.png deleted file mode 100644 index 273f085..0000000 Binary files a/getting_started/images/lift_rs.png and /dev/null differ diff --git a/getting_started/images/lift_up_rs.png b/getting_started/images/lift_up_rs.png deleted file mode 100644 index b280d5b..0000000 Binary files a/getting_started/images/lift_up_rs.png and /dev/null differ diff --git a/getting_started/images/lightbar_voltage.png b/getting_started/images/lightbar_voltage.png deleted file mode 100644 index 9f7bc90..0000000 Binary files a/getting_started/images/lightbar_voltage.png and /dev/null differ diff --git a/getting_started/images/pink_strip.png b/getting_started/images/pink_strip.png deleted file mode 100644 index 30e4029..0000000 Binary files a/getting_started/images/pink_strip.png and /dev/null differ diff --git a/getting_started/images/runstop_rs.png b/getting_started/images/runstop_rs.png deleted file mode 100644 index 8a27775..0000000 Binary files a/getting_started/images/runstop_rs.png and /dev/null differ diff --git a/getting_started/images/trunk.jpg b/getting_started/images/trunk.jpg deleted file mode 100644 index b3c9d77..0000000 Binary files a/getting_started/images/trunk.jpg and /dev/null differ diff --git a/getting_started/images/trunk.png b/getting_started/images/trunk.png deleted file mode 100644 index 874379b..0000000 Binary files a/getting_started/images/trunk.png and /dev/null differ diff --git a/getting_started/images/trunk_re2.png b/getting_started/images/trunk_re2.png deleted file mode 100644 index 6923d23..0000000 Binary files a/getting_started/images/trunk_re2.png and /dev/null differ diff --git a/getting_started/images/trunk_re2_rs.png b/getting_started/images/trunk_re2_rs.png deleted file mode 100644 index 11cc247..0000000 Binary files a/getting_started/images/trunk_re2_rs.png and /dev/null differ diff --git a/getting_started/images/trunk_re2_rs2.png b/getting_started/images/trunk_re2_rs2.png deleted file mode 100644 index a01dfe4..0000000 Binary files a/getting_started/images/trunk_re2_rs2.png and /dev/null differ diff --git a/getting_started/images/trunk_rs.png b/getting_started/images/trunk_rs.png deleted file mode 100644 index 2d2893f..0000000 Binary files a/getting_started/images/trunk_rs.png and /dev/null differ diff --git a/getting_started/images/warning_rs.png b/getting_started/images/warning_rs.png deleted file mode 100644 index 0e7f188..0000000 Binary files a/getting_started/images/warning_rs.png and /dev/null differ diff --git a/getting_started/images/xbox.png b/getting_started/images/xbox.png deleted file mode 100644 index 08dab81..0000000 Binary files a/getting_started/images/xbox.png and /dev/null differ diff --git a/getting_started/images/xbox_off_rs.png b/getting_started/images/xbox_off_rs.png deleted file mode 100644 index 92fdc9f..0000000 Binary files a/getting_started/images/xbox_off_rs.png and /dev/null differ diff --git a/getting_started/quick_start_guide_re1.md b/getting_started/quick_start_guide_re1.md deleted file mode 100644 index 426bf04..0000000 --- a/getting_started/quick_start_guide_re1.md +++ /dev/null @@ -1,217 +0,0 @@ -# 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](./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 before hitting the Off switch - -![](./images/trunk_rs.png) - -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
2) Repair damaged batteries. | -| REPAIR | Repair damaged batteries. | - -Please review the [Battery Maintenance Guide](https://docs.hello-robot.com/0.2/stretch-hardware-guides/docs/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 the 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, the 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 its 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's capabilities by teleoperating it with an Xbox Controller. - -![](./images/xbox.png) - -!!! note - You will find the USB Dongle already plugged into the USB port of the base trunk. - -To start the demo after unboxing: - -* 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. - -!!! warning - 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 a cup from a countertop -* 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. - -* Remove the 'trunk' cover and power on the robot if it's not already on. -* 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. - -Stretch is configured to run the Xbox Controller demo in the background at startup. To run your own code you'll need to kill this process so that it doesn't contend with your code. - -```{.bash .shell-prompt} -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 - -```{.bash .shell-prompt} -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 - -```{.bash .shell-prompt} -stretch_robot_home.py -``` - -Once the robot has homed, let's write some quick test code: - -```{.bash .shell-prompt} -ipython -``` - -Now let's move the robot around using the Robot API. Try typing in these interactive commands at the iPython prompt: - -```{.python .no-copy} -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() -``` -!!! note - The iPython interpreter also allows you to execute blocks of code in a single go instead of running commands line by line. To end the interpreter session, type exit() and press enter. -## Change Credentials - -Finally, we recommend that you change the login credentials for the default user, hello-robot. - -```{.bash .shell-prompt} -sudo passwd hello-robot -``` - -If you'd like to set up 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 dropping -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! - ------- -
All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks.
diff --git a/getting_started/quick_start_guide_re2.md b/getting_started/quick_start_guide_re2.md deleted file mode 100644 index 1bca9bb..0000000 --- a/getting_started/quick_start_guide_re2.md +++ /dev/null @@ -1,236 +0,0 @@ -# Stretch 2: Quick Start Guide - -Congratulations on your Stretch 2! 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). Please note that the unboxing instructions for a Stretch 2 are the same as for a Stretch RE1. - -## 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_re2_rs2.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 the 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, the motion can resume. - -![](./images/runstop_rs.png) - -### LED Lightbar - -The LED lightbar in the base provides a simple way to quickly ascertain the robot's state. At all times its color indicates the battery voltage. - -![](./images/lightbar_voltage.png) - -More information on the voltage display is available in the [Battery Maintenance Guide](https://docs.hello-robot.com/0.2/stretch-hardware-guides/docs/battery_maintenance_guide_re2/#state-of-battery-charge) - -The lightbar will also flash as follows: - -| Mode | Flashing | -|--------------------|-----------------------| -| Normal Operation | None | -| Runstopped | Rapid flash at 1 Hz | -| Charger plugged in | Slow strobe at 0.5 Hz | - -## Hello World Demo - -Stretch comes ready to run out of the box. The Xbox Teleoperation demo will let you quickly test out the robot's capabilities by teleoperating it with an Xbox Controller. - -![](./images/xbox.png) - -**Note**: You will find the USB Dongle already plugged into 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 a cup from a countertop -* Try delivering an object to a person - -If you're done, let's power down. First, attach the clip-clamp just below the shoulder as shown. -![](./images/clip-clamp_rs.png) - -Hold down the Shutdown PC button on the Xbox controller for 2 seconds. This will cause the PC to turn off. You can then power down the robot with the On/Off switch. - -Now that you're familiar with the robot, take a minute to watch the [Stretch Powered Best Practices Video](https://youtu.be/iEaapHNfEWA). Please note that the best practice instructions for a Stretch 2 are the same as for a Stretch RE1. - -### 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. Please note that the best practice instructions for a Stretch 2 are the same as for a Stretch RE1. - -**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 lift will slowly descend when the robot is powered off. If the arm is retracted it may come to 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 its weight on its camera. -* Trying to ride on the robot, getting it wet, etc. (eg, common sense) - -### 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
2) Repair damaged batteries. | -| REPAIR | Repair damaged batteries. | - -Please review the [Battery Maintenance Guide](https://docs.hello-robot.com/0.2/stretch-hardware-guides/docs/battery_maintenance_guide_re2/) for proper care and charging of Stretch batteries. - -![](./images/NOCO_Genius10_UI_rs.png) - -## Get Plugged In - -Let's get plugged in. - -* Power up the robot -* 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. - -Stretch is configured to run the Xbox Controller demo in the background at startup. To run your own code you'll need to kill this process so that it doesn't contend with your code. - -```{.bash .shell-prompt} -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 all of the hardware is present and happy - -```{.bash .shell-prompt} -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 - -```{.bash .shell-prompt} -stretch_robot_home.py -``` - -Once the robot has homed, let's write some quick test code: - -```{.bash .shell-prompt} -ipython -``` - -Now let's move the robot around using the [Stretch Body Robot API](https://docs.hello-robot.com/0.2/stretch-tutorials/stretch_body/tutorial_stretch_body_api/). Try typing in these interactive commands in the iPython prompt: - -```{.python .no-copy} -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() -``` -!!! note - The iPython interpreter also allows you to execute blocks of code in a single go instead of running commands line by line. To end the interpreter session, type exit() and press enter. - -## Change Credentials - -Finally, we recommend that you change the login credentials for the default user, hello-robot. - -```{.bash .shell-prompt} -sudo passwd hello-robot -``` - -If you'd like to set up 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! - ------- -
All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks.
- diff --git a/getting_started/safety_guide.md b/getting_started/safety_guide.md deleted file mode 100644 index 144db1b..0000000 --- a/getting_started/safety_guide.md +++ /dev/null @@ -1,210 +0,0 @@ -# Robot Safety Guide - -![](./images/warning_rs.png) - -The Stretch robots are potentially dangerous machines with safety hazards. **If improperly used they can cause injury or death.** - -* **All users must carefully read the following safety information before using the robot.** -* Anyone near the robot who has not read this safety information must be closely supervised at all times and made aware that the robot could be dangerous. -* Only use the robot after inspecting the surrounding environment for potential hazards. - -## Intended Use - -**The Stretch robots are intended for use by researchers to conduct research in controlled indoor environments.** This product is not intended for other uses and lacks the required certifications for other uses, such as use in a home environment by consumers. - -## Safety Hazards - -As described later in this document, we have designed Stretch to be safer than previous commercially-available human-scale mobile manipulators, so that researchers can explore the future of mobile manipulation. For example, we have made it smaller and lighter weight with backdrivable torque-sensing joints that can stop when they detect contact. - -Nonetheless, Stretch is a research robot that can be dangerous. Researchers must use Stretch carefully to avoid damage, injury, or death. Here, we list several safety hazards that researchers must consider before and while using Stretch. - -### Stretch Can Put People And Animals At Risk - -As described in more detail later, Stretch can put people and animals at risk. People and animals near the robot must be closely supervised at all times. At all times, an experienced researcher must carefully monitor the robot and be prepared to stop it. Any people near the robot must be made aware that the robot could be dangerous. Before any use of the robot near people or animals, researchers must carefully assess and minimize risks. - -**Researchers who use the robot near children, animals, vulnerable adults, or other people do so at their own risk. Researchers must take appropriate precautions and obtain the required approvals from their organizations.** - -### Stretch Can Topple Onto A Person - -The robot may drive off stairs, push or pull itself over with its telescoping arm, fall over while attempting to traverse a threshold or encounter obstacles that cause it to fall on or otherwise collide with people, causing injury. - -**Operate the robot only on flat surfaces away from stairs or other obstacles that may cause it to topple, and do not allow the robot to push or pull itself over.** - -### Stretch Should Not Be Lifted By A Single Person - -Stretch with the standard gripper weighs about 23 kg (50.5 lb), so two or more people should lift and carry the robot. A single person can move the robot around by enabling the runstop button, tilting it over, and rolling it on flat ground. - -**At least two people should lift and carry the robot when needed.** - -### Stretch Can Cause Lacerations -The robot's wrist and tool have sharp edges that can cause lacerations or punctures to the skin or the eyes. - -**Operate the robot away from eyes and other sensitive body parts.** - -### Stretch Can Trap, Crush, Or Pinch Body Parts - -The robot has moving joints that can trap, crush or pinch hands, fingers, or other body parts. The robot could also injure a person or animal by driving over a body part. - -**Keep body parts away from the trap, crush, and pinch points during robot motion, including underneath the wheels.** - -### Stretch Can Entrap Loose Clothing Or Hair - -The robot's shoulder and telescoping arm have rollers that can pull in and entrap loose clothing or hair. - -**Keep loose clothing and long hair away from the robot's shoulder and telescoping arm when either is in motion.** - -### Stretch Has Flammable Components - -The robot has polyurethane covers that are flammable and must be kept away from potential ignition sources, such as open flames and hot surfaces. The robot’s head, shoulder, and mobile base have polyurethane covers. - -**Keep the robot away from potential ignition sources and always have a working fire extinguisher nearby.** - -### Stretch Is An Electrical Device - -Stretch has batteries, electronics, wires, and other electrical components throughout its body. It also provides uncovered connectors that provide power. While the robot has fuses to reduce electrical risks, users must be careful. - -**Keep the robot dry and away from liquids, avoid electrical shocks, ensure power cables and wires are in good condition, be careful with the robot’s connectors, and generally exercise caution while working with this electrical device.** - -### Stretch Can Perform Dangerous Activities - -Stretch is a versatile robot capable of performing many actions, including actions that would be dangerous to people. For example, if a dangerous object is held by or affixed to the robot, such as a knife, a heavy object, or breakable glass, the robot can become very dangerous. Likewise, the robot is capable of physically altering the environment in ways that would be dangerous, such as turning a knob that releases gas from a gas stove. - -**Users must be cautious while using the robot to ensure it interacts safely with people and the surrounding environment.** - -### Stretch Is An Open Platform That Can Be Made More Dangerous - -Stretch is an open platform with user-modifiable and user-extensible hardware and software. User changes to the hardware or software can entail serious risks. For example, when shipped, the robot has conservative settings that restrict its speed and the forces it applies to reduce the risks associated with the robot. By modifying the robot, users could enable the robot to move at unsafe speeds and apply unsafe forces. As another example, improper electrical connections could result in a fire. - -**Researchers who choose to modify or extend the robot’s hardware or software do so at their own risk and should be careful to understand the implications of their modifications or extensions. Changes to the robot could result in dangerous situations that cause injury or death.** - -## Additional Risks - -**The most important aspects of safety with Stretch are to use good judgment and common sense.** Additional important considerations follow: - -* **If the robot appears to be damaged, stop the robot immediately.** -* **Always be ready to stop the robot.** -* **Do not operate the robot unless an experienced user is present and attentive.** -* Be aware that the robot can move in unexpected ways. -* Do not put fingers or other objects into the channel that runs along the length of the mast. A belt moves within this channel. -* Keep an eye on cords, rugs, and any other floor hazards as the robot drives. -* Keep the robot at least 3 meters from ledges, curbs, stairs, and any other toppling hazard. -* Do not operate the robot outdoors. -* Do not attempt to ride the robot. -* Do not have the robot hold sharp objects. -* Do not attempt to service the robot without supervision by Hello Robot. - -## Other Problems Will Likely Occur - ->“**Anticipate potential problems** and hazards. Always imagine what might ->happen if the robot malfunctions or behaves in a way different from the desired ->action. Be vigilant.” - [PR2 User Manual](https://www.clearpathrobotics.com/assets/downloads/pr2/pr2_manual_r321.pdf) by Willow Garage from October 5, 2012 - -Stretch is a complex device that includes many mechanical, electrical, and computational systems that have been designed to work together. **Be prepared for something to go wrong.** For example, a motor control board might fail, software might not operate as anticipated, an unexpected process might still be running on the robot, or the batteries for the Xbox-style controller or the robot itself might run out. - - -## Safety Features - -We have considered safety from the outset in the design of Stretch. - -* **Runstop**: The illuminated runstop button on Stretch’s head can be used to pause the operation of the four primary joints (base, lift, and arm) of the robot when it is in motion. -* **Lightweight design:** The overall mass of Stretch with the standard gripper is 23Kg (50.5lb), and the majority of the mass is in the base. The carbon fiber arm and aluminum mast make for a remarkably lightweight upper body. While this reduces the risk of crushing, crushing injuries can still occur and should be carefully monitored. -* **Gravity friendly**: Due to Stretch’s design, its actuators don't have to counteract gravity on a large lever arm. As a result, the motors and gearboxes are lower torque and lower weight than a conventional mobile manipulator with a comparable reach, avoiding the often dangerously strong shoulder joints of typical robot arms. -* **Low gear ratio**: The primary joints of Stretch (base, lift, and arm) have low gear-ratios (approx 5:1), allowing for backdriving of joints when powered off. A low gear-ratio also reduces the effective inertia of each joint, limiting the impacted force during undesired contact with people and the environment. -* **Contact Sensitivity**: The four primary joints of Stretch (base, lift, and arm) have contact sensitivity. We measure motor currents to estimate contact forces. Because Stretch is a low gear-ratio robot, current sensing provides a fairly sensitive measure of contact forces. -* **Firmware limits**: Motor torques are limited at the lowest level of the firmware to configured bounds. -* **Velocity limits**: Fast motions of the base are restricted when the arm is up high and the tool is outside the base footprint. This limits the likelihood of toppling or snagging the tool during base motion. -* **Tilt detection**: The robot can detect when its body is tilted beyond a safe threshold. The robot can be configured to trigger a runstop event during an over-tilt event. - -## Safety Markings - -Stretch has the following safety markings: -Top of the shoulder, indicating potential pinch point between rollers and mast. - -![](./images/hand_crush_rs.png) - -Top of the base, indicating potential pinch point between arm and base. - -![](./images/hand_crush2_rs.png) - -## Runstop - -![](./images/runstop_rs.png) - -The runstop allows the user to pause the motion of the four primary actuators (base, lift, and arm) by tapping the illuminated button on the head. An experienced operator should always keep the runstop within reach, allowing them to stop the motion of the robot if it is deemed unsafe. - -!!! warning - The runstop is not equivalent to an Emergency Stop found on industrial equipment and no safety guarantees are made by its function. - -When the runstop is enabled, these actuators are in a ‘Safety Mode’ that inhibits the motion controller at the firmware level. Disabling the runstop allows normal operation to resume. - -The runstop logic is: - - - - - - - - - - - - - - - - - - - - - - -
ActionRunstop StateButton Illumination
Robot startupMotion enabledSolid
Tap runstop buttonMotion disabledFlashing at 1Hz
Hold down runstop button for >2sMotion enabledSolid
- - -## Safety Hazard Details - -### Sharp Edges - -The Stretch robot is a piece of laboratory equipment. As such, its structure has moderately sharp edges and corners that can be unsafe. These edges can get snagged during motion, or they may cause lacerations when sufficient force is applied to a person. Care should be taken when grasping or otherwise making contact with Stretch that a sharp corner or edge is not contacted. - -### Toppling - -Stretch is a relatively lightweight robot. In some kinematic configurations, a high center of gravity can make it prone to toppling. Toppling can occur when: - -* The mobile base is moving at a moderate or fast speed and hits a bump, threshold, or other change in floor property. -* The arm is raised high and pushes or pulls on the environment with sufficient force. -* The robot drives over a drop-off such as a stair or a curb. - -!!! warning - While Stretch has cliff sensors, they do not currently inhibit motion of the base. During typical use, the robot will not attempt to stop itself at a cliff, and can fall down stairs and hurt itself or a person. - -### Pinch Points - -Pinch points around the robot's head, gripper, and wrist can cause discomfort and care should be taken when handling these joints as they move. - -The shoulder, which travels up and down on the lift, has a series of rollers that ride along the mast. While the shoulder shells can prevent large objects from getting pinched by the rollers, small and thin objects can be pulled into and crushed. - -The telescoping arm, which extends and retracts, has rollers that ride along the telescoping elements. While the arm link cuffs can reduce the chance of large objects getting pinched, small and thin objects, such as hair, can be pulled in. - -Extra care should be taken with long hair, clothing, and small fingers around the shoulder rollers. - -### Crush Points - -The lift degree of freedom is the strongest joint on the robot and as such can apply potentially unsafe forces to a person. - -![](./images/lift_rs.png) - -The lift, while in motion, may trap or crush objects between the ‘shoulder’ and another surface. As such, best practices for lift safety should always be used when using the lift degree of freedom. - -The lift has a max theoretical strength of nearly 200N of linear force. In practice, this force is limited by the lift’s Guarded Move function, which places the lift in Safety Mode when the actuator forces exceed a threshold. - -The diagrams below show the potential crush points at the top and bottom of the lift range of motion. - -![](./images/lift_down_rs.png) - -![](./images/lift_up_rs.png) - ------- -
All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks.
\ No newline at end of file diff --git a/getting_started/troubleshooting_guide.md b/getting_started/troubleshooting_guide.md deleted file mode 100644 index ec026fa..0000000 --- a/getting_started/troubleshooting_guide.md +++ /dev/null @@ -1,175 +0,0 @@ -# Stretch 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.py) will be incorrect. - -To set the controller into the correct mode: - -- Hold the center button down for 5s. It will switch modes. Release. -- Repeat until the top half of the ring (upper two lights) is illuminated. - -In addition, check that the provided USB dongle is plugged into the robot USB port in its trunk. - -![](./images/xbox.png) - -## Battery is not staying charged - -=== "Stretch RE1" - - Please review the troubleshooting section of the [Stretch RE1 Battery Maintenance Guide](https://docs.hello-robot.com/0.2/stretch-hardware-guides/battery_maintenance_guide_re1/). - -=== "Stretch 2" - - Please review the troubleshooting section of the [Stretch 2 Battery Maintenance Guide](https://docs.hello-robot.com/0.2/stretch-hardware-guides/battery_maintenance_guide_re2). - -## Port Busy or RPC Transport Errors - -If more than one instance of Stretch Body's [Robot](https://github.com/hello-robot/stretch_body/blob/master/body/stretch_body/robot.py) class is instantiated at a time, Stretch Body will report communication errors and will not always execute motion commands as expected. This is because the [Robot](https://github.com/hello-robot/stretch_body/blob/master/body/stretch_body/robot.py) class manages communications with the robot hardware and it doesn't support multiple writes to the USB devices. - -
- Examples of busy port or RPC errors - - ```{.bash .no-copy} - [ERROR] [pimu]: Port /dev/hello-pimu is busy. Check if another Stretch Body process is already running - [WARNING] [pimu]: Unable to open serial port for device /dev/hello-pimu - [ERROR] [hello-motor-left-wheel]: Port /dev/hello-motor-left-wheel is busy. Check if another Stretch Body process is already running - [WARNING] [hello-motor-left-wheel]: Unable to open serial port for device /dev/hello-motor-left-wheel - [ERROR] [hello-motor-right-wheel]: Port /dev/hello-motor-right-wheel is busy. Check if another Stretch Body process is already running - [WARNING] [hello-motor-right-wheel]: Unable to open serial port for device /dev/hello-motor-right-wheel - [ERROR] [hello-motor-lift]: Port /dev/hello-motor-lift is busy. Check if another Stretch Body process is already running - [WARNING] [hello-motor-lift]: Unable to open serial port for device /dev/hello-motor-lift - [ERROR] [hello-motor-arm]: Port /dev/hello-motor-arm is busy. Check if another Stretch Body process is already running - [WARNING] [hello-motor-arm]: Unable to open serial port for device /dev/hello-motor-arm - [ERROR] [wacc]: Port /dev/hello-wacc is busy. Check if another Stretch Body process is already running - [WARNING] [wacc]: Unable to open serial port for device /dev/hello-wacc - [ERROR] [pimu]: Port /dev/hello-pimu is busy. Check if another Stretch Body process is already running - [WARNING] [pimu]: Unable to open serial port for device /dev/hello-pimu - [ERROR] [hello-motor-left-wheel]: Port /dev/hello-motor-left-wheel is busy. Check if another Stretch Body process is already running - [WARNING] [hello-motor-left-wheel]: Unable to open serial port for device /dev/hello-motor-left-wheel - [ERROR] [hello-motor-lift]: Port /dev/hello-motor-lift is busy. Check if another Stretch Body process is already running - [WARNING] [hello-motor-lift]: Unable to open serial port for device /dev/hello-motor-lift - [ERROR] [hello-motor-arm]: Port /dev/hello-motor-arm is busy. Check if another Stretch Body process is already running - [WARNING] [hello-motor-arm]: Unable to open serial port for device /dev/hello-motor-arm - ``` - - or - - ```{.bash .no-copy} - [WARNING] [head_tilt]: DynamixelHelloXL430 Ping failed... head_tilt - DynamixelHelloXL430 Ping failed... head_tilt - ``` - - or - - ```{.bash .no-copy} - serial.serialutil.SerialException: device reports readiness to read but returned no data (device disconnected or multiple access on port?) - ``` - - or - - ```{.bash .no-copy} - Traceback (most recent call last): - File "/home/hello-robot/.local/bin/stretch_robot_system_check.py", line 42, in - r.startup() - File "/home/hello-robot/repos/stretch_body/body/stretch_body/robot.py", line 167, in startup - if not self.devices[k].startup(threaded=False): - File "/home/hello-robot/repos/stretch_body/body/stretch_body/end_of_arm.py", line 26, in startup - return DynamixelXChain.startup(self, threaded=threaded) - File "/home/hello-robot/repos/stretch_body/body/stretch_body/dynamixel_X_chain.py", line 80, in startup - if not self.motors[mk].startup(threaded=False): - File "/home/hello-robot/repos/stretch_body/body/stretch_body/stretch_gripper.py", line 22, in startup - return DynamixelHelloXL430.startup(self, threaded=threaded) - File "/home/hello-robot/repos/stretch_body/body/stretch_body/dynamixel_hello_XL430.py", line 193, in startup - self.motor.set_temperature_limit(self.params['temperature_limit']) - File "/home/hello-robot/repos/stretch_body/body/stretch_body/dynamixel_XL430.py", line 707, in set_temperature_limit - dxl_comm_result, dxl_error = self.packet_handler.write1ByteTxRx(self.port_handler, self.dxl_id, XL430_ADDR_TEMPERATURE_LIMIT, int(x)) - File "/home/hello-robot/.local/lib/python3.8/site-packages/dynamixel_sdk/protocol2_packet_handler.py", line 653, in write1ByteTxRx - return self.writeTxRx(port, dxl_id, address, 1, data_write) - File "/home/hello-robot/.local/lib/python3.8/site-packages/dynamixel_sdk/protocol2_packet_handler.py", line 643, in writeTxRx - rxpacket, result, error = self.txRxPacket(port, txpacket) - File "/home/hello-robot/.local/lib/python3.8/site-packages/dynamixel_sdk/protocol2_packet_handler.py", line 346, in txRxPacket - rxpacket, result = self.rxPacket(port) - File "/home/hello-robot/.local/lib/python3.8/site-packages/dynamixel_sdk/protocol2_packet_handler.py", line 257, in rxPacket - rxpacket.extend(port.readPort(wait_length - rx_length)) - File "/home/hello-robot/.local/lib/python3.8/site-packages/dynamixel_sdk/port_handler.py", line 78, in readPort - return self.ser.read(length) - File "/usr/lib/python3/dist-packages/serial/serialposix.py", line 509, in read - raise SerialException('read failed: {}'.format(e)) - serial.serialutil.SerialException: read failed: device reports readiness to read but returned no data (device disconnected or multiple access on port?) - ``` - - or - - ```{.bash .no-copy} - Transport RX Error on RPC_ACK_SEND_BLOCK_MORE False 0 102 - ---- Debug Exception - --------------- New RPC ------------------------- - Framer sent RPC_START_NEW_RPC - ... - ``` - - or - - ```{.bash .no-copy} - IOError(None): None - ... - ``` -
- -To check if an instance of [Robot](https://github.com/hello-robot/stretch_body/blob/master/body/stretch_body/robot.py) is already instantiated, you may use the Unix [top](https://www.unixtutorial.org/commands/top) command to monitor active processes. You may use the Unix [pkill](https://linuxize.com/post/pkill-command-in-linux/) command to end the background instance of Robot. - -```{.bash .shell-prompt} -pkill -9 python -``` - -As shipped, Stretch launches [stretch_xbox_controller_teleop.py](https://github.com/hello-robot/stretch_body/blob/master/tools/bin/stretch_xbox_controller_teleop.py) upon boot. It is necessary to turn off this automatic launch feature, otherwise, your own Robot instance will conflict with this script. Additionally, if you are logged into multiple accounts, a Robot instance may be active in another user account. - -To turn it off, search for 'Startup' from Ubuntu Activities. Uncheck the box for 'hello_robot_xbox_teleop'. - -![](./images/xbox_off_rs.png) - -## Invalid homing offset for single-turn mode Dynamixel - -If you see a warning similar to: - -```{.no-copy} -[WARNING] [head_tilt]: Dynamixel head_tilt: Servo is in single-turn mode yet has invalid homing offset of -1682. - This may cause unexpected results if not set to zero (using REx_dynamixel_jog.py) - Please contact Hello Robot support for more information -``` - -You have a "single-turn" Dynamixel servo (e.g. `head_tilt` in the above warning) that has an invalid "homing offset" saved to the servo's flash memory. This can lead to the motor returning its joint position incorrectly. In order to reset the homing offset to zero, create an instance of the Dynamixel class in Stretch Body and set the homing offset to zero. For example, doing this for the `head_tilt` servo looks like: - -```{.python .no-copy} -hello-robot@stretch-re1-xxxx:~$ ipython3 -Python 3.8.10 (default, Mar 13 2023, 10:26:41) -Type 'copyright', 'credits' or 'license' for more information -IPython 8.7.0 -- An enhanced Interactive Python. Type '?' for help. - -In [1]: import stretch_body.dynamixel_hello_XL430 - -In [2]: servo = stretch_body.dynamixel_hello_XL430.DynamixelHelloXL430(name="head_tilt", chain=None) - -In [3]: servo.startup() -[WARNING] [head_tilt]: Dynamixel head_tilt: Servo is in single-turn mode yet has invalid homing offset of -1682. - This may cause unexpected results if not set to zero (using REx_dynamixel_jog.py) - Please contact Hello Robot support for more information -Out[3]: True - -In [4]: servo.disable_torque() - -In [5]: servo.motor.set_homing_offset(0) - -In [6]: servo.enable_torque() - -In [7]: servo.stop() - -In [8]: -Do you really want to exit ([y]/n)? -``` - ------- -
All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks.
\ No newline at end of file diff --git a/getting_started/untethered_operation.md b/getting_started/untethered_operation.md deleted file mode 100644 index 8d4deb0..0000000 --- a/getting_started/untethered_operation.md +++ /dev/null @@ -1,143 +0,0 @@ - -# Untethered Operation - -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). - -## Remote Desktop - -#### Requirements - -This is the recommended approach if you are running Windows or MacOS. This method requires a Virtual Network Computing (VNC) package. Using any of the free or paid options available for Windows, MacOS, and Chrome will be fine since they all use the Remote Frame Buffer (RFB) protocol to communicate with the robot. If you're using Ubuntu, Remmina Remote Desktop Client will be installed by default. - -#### How To - -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: - -```{.bash .shell-prompt} -sudo apt install vino -``` - -Go to System Settings. Select the Sharing tab and turn it on then, turn on Screen Sharing and choose a password. If you plan to connect to the robot from a Windows or MacOS machine, then open a terminal and run the following command. - -```{.bash .shell-prompt} -sudo gsettings set org.gnome.Vino require-encryption false -``` - -Finally, we need the robot's IP address, username, and password. 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. The robot's default username and password are printed on papers that came in the tools box alongside the robot. - -VNC will only function properly with an external display attached to the robot. Using a dummy HDMI dongle when operating the robot untethered via VNC is recommended. One possible dummy HDMI dongle can be found on Amazon [here](https://www.amazon.com/gp/product/B07BBT9NCZ/). On your computer, connect to the same wireless network as the robot and open the VNC package being used. Using the robot's IP address and username, initialize a new connection to the robot. The robot's desktop will open in a new window. - -## SSH & X Server - -#### Requirements - -This is the recommended approach if you are running a Unix-based operating system, like Ubuntu or Arch Linux. This method requires both SSH and X Server to be installed. While most Unix-based operating systems have both installed by default, MacOS will only have SSH installed and Windows has neither installed by default. It is possible to install these tools for MacOS or Windows. - -#### How To - -While the [Remote Desktop](#remote-desktop) approach is easy to set up, graphics and interaction with the remote desktop are 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 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. - -```{.bash .shell-prompt} -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 [Quick Start Guide](./quick_start_guide_re2.md#start-coding). - -Furthermore, Windowed GUI applications that would have been 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). - -#### Moving files to/from the robot wirelessly - -It's common to need to move files to/from the robot wirelessly and a tool similar to SSH can help with this: Secure Copy (SCP). - -To send the files from your computer to the robot, run: -```{.bash .shell-prompt} -scp ./filename username@ip-address:~/path/to/put/it/ -``` - -To copy the files from the robot to your computer, run the reverse: -```{.bash .shell-prompt} -scp username@ip-address:/path/to/filename ~/path/to/put/it/ -``` - -This works for [copying directories](https://stackoverflow.com/a/11304926/4753010) and their contents as well. - -## ROS Remote Master - -#### Requirements - -This is the recommended approach if you are running Ubuntu 16.04/18.04/20.04 with ROS kinetic/melodic/noetic installed on your computer. This method will utilize the local installation of ROS tools, such as Rviz, rostopic, and rosservice, while retrieving data from the robot. - -#### How To - -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. - -Next, run the following on the robot: - -```{.bash .no-copy} -export ROS_IP=robot-ip-address -export ROS_MASTER_URI=http://robot-ip-address:11311/ -``` - -Next, start the ROS launch files on the robot as you normally would. Finally, on your computer, run: - -```{.bash .no-copy} -export ROS_IP=computer-ip-address -export ROS_MASTER_URI=http://robot-ip-address:11311 -``` - -If you use ROS Remote Master often, you can export these environment variables in your [bashrc](https://www.maketecheasier.com/what-is-bashrc/). - -Tools like [rostopic](http://wiki.ros.org/rostopic) and [rosservice](http://wiki.ros.org/rosservice) can now be used on your computer as you would have on the robot. For example, you can use `rostopic list` on your computer to print out the topics available on the robot. Additional information can be found in the ROS [Multiple Machines Tutorial](http://wiki.ros.org/ROS/Tutorials/MultipleMachines). - -#### Visualizing remotely with RViz - -If you'd like to visualize the robot model on your computer using Rviz, you'll need to set up a ROS workspace with the [Stretch Description](https://github.com/hello-robot/stretch_ros/tree/master/stretch_description) package. First, copy over the `~/stretch_user` directory from the robot to your computer (e.g. using [Secure Copy](#moving-files-tofrom-the-robot-wirelessly)). Second, clone [Stretch Install](https://github.com/hello-robot/stretch_install/), and checkout the [noetic branch](https://github.com/hello-robot/stretch_install/tree/dev/install_20.04) if you are running ROS Noetic on the robot. Finally, run the [stretch_create_ros_workspace.sh](https://github.com/hello-robot/stretch_install/blob/master/stretch_create_ros_workspace.sh) script. A ROS Workspace with the Stretch ROS packages is now set up on your computer. Furthermore, Stretch Description has been set up with your robot's calibrated URDF. - -We can now use remote master and Rviz to visualize what the robot is seeing on your computer. Open two terminals. First, [SSH](#ssh-x-server) into the robot and 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 Rviz can be found in [ROS's tutorials](http://wiki.ros.org/ROS/Tutorials) or our [Stretch ROS guides](README.md#ros-interface). - -## Additional Ideas - -Although the methods described above will enable you to wirelessly control the robot, there are several ways to improve the usability and security of your wireless connection. These ideas are listed here. - -### Hotspot - -Often the trouble with wirelessly controlling the robot is the network. If your network is using industrial security like 2-factor authentication, there may be trouble connecting the robot to the network. If the network is servicing a large number of users, the connection may feel sluggish. The alternative is to skip the network by connecting directly to the robot. After starting a hotspot on the robot, you can follow instructions for any of the methods described above to control the robot. The trade-off is that while connected to the robot's hotspot, you will be unable to connect to the internet. - -To set up the robot's hotspot, visit the Ubuntu Wifi Settings page in the robot. Click on the hamburger menu in the top right and select "Enable hotspot". From your local machine, connect to the robot's hotspot and save the credentials. To change the hotspot's password or enable the hotspot automatically whenever the robot boots, see the following [Stackoverflow post](https://askubuntu.com/questions/500370/setting-up-wireless-hotspot-to-be-on-at-boot). - -### VS Code Remote Development - -It is possible to simultaneously develop code on the robot while running wireless experiments using the Remote Development Extension provided by the VS Code IDE. If you're already using the [VS Code IDE](https://code.visualstudio.com/), navigate to the Extensions tab and search for [Remote Development Extension by Microsoft](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack). After installing, click on a green button in the bottom left of the screen and then select "Remote-SSH: Connect to Host". Setting this up for the first time will require you to know the robot's IP address and username. Add a new host with the information. While connecting, VS Code will ask you for the password of the robot. Once you are connected, you can open any folder and edit the code remotely. Combined with the method explained in [SSH & X Server](#ssh-x-server), this is a powerful method of iteratively developing code while testing it. - -### Static IP Address - -Routers that serve wireless networks often dynamically assign IP addressess to machines that connect to the network. This means that your robot's IP address may have changed since the last time you turned it on. Since it becomes a pain to connect to the monitor, keyboard, and mouse setup every time to run `ifconfig`, many users prefer to assign the robot a static IP address. If you control the router, visit the router's settings page to set up the robot's static IP address. It is common at universities and companies to have staff dedicated to the management of the network. This staff will often be able to set up a static IP address for the robot. - -### Public Key Authentication - -The method of SSH described in [SSH & X Server](#ssh-x-server) uses basic password authentication when connecting. There is a better and more secure method of SSH-ing into the robot called Public Key Authentication. This method will allow multiple developers to SSH into the robot without having to share the robot's admin password. - -The first step is to generate public and private keys on your computer. Linux and MacOS machines can simply open the terminal and run: - -```{.bash .shell-prompt} -ssh-keygen -t ed25519 -f -C "" -``` - -It will prompt you to enter a password. If you do, you'll need it to use the private key when you SSH into the robot. Next, we give the robot the public key. Linux and MacOS machines can run: - -```{.bash .shell-prompt} -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 are 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. - ------- -
All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks.
diff --git a/getting_started/updating_software.md b/getting_started/updating_software.md deleted file mode 100644 index d8123f7..0000000 --- a/getting_started/updating_software.md +++ /dev/null @@ -1,107 +0,0 @@ -# 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. - -## When to Update - -We develop our software publicly on GitHub, allowing anyone to follow and 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 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 - -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 set up a ROS or ROS 2 workspace, the easiest way to download the most recent updates in the stretch_ros and stretch_ros2 code repositories, 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: -```{.bash .shell-prompt} -cd ~/ -git clone https://github.com/hello-robot/stretch_install.git -cd stretch_install -git pull -``` - -To replace the ROS Melodic catkin_ws in Ubuntu 18.04, execute: -```{.bash .shell-prompt} -./factory/18.04/stretch_create_catkin_workspace.sh -w -``` - -To replace the ROS Noetic catkin_ws in Ubuntu 20.04, execute: -```{.bash .shell-prompt} -./factory/20.04/stretch_create_catkin_workspace.sh -w -``` - -To replace the ROS 2 Galactic ament_ws in Ubuntu 20.04, execute: -```{.bash .shell-prompt} -./factory/20.04/stretch_create_ament_workspace.sh -w -``` - -### Stretch Body Python SDK - -Stretch Body is the Python SDK for the robot. It abstracts away the low-level details of communication with the embedded devices and provides an intuitive API for working with the robot. You may update it using the following commands depending on the Python version. - -If you are using Python2, execute: -```{.bash .shell-prompt} -pip install -U hello-robot-stretch-body -pip install -U hello-robot-stretch-body-tools -pip install -U hello-robot-stretch-factory -pip3 install -U hello_robot_stretch_body_tools_py3 -``` - -For Python3, execute: -```{.bash .shell-prompt} -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: - -```{.bash .shell-prompt} -REx_firmware_updater.py --status -``` - -This script will automatically determine what version is currently running on the robot and provide a recommendation for the next step. Follow the next steps provided by the firmware updater script. - -### Ubuntu - -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: - -```{.bash .shell-prompt} -sudo apt update -sudo apt upgrade -``` - -[Apt](https://en.wikipedia.org/wiki/APT_(software)) is the package manager that handles updates for all Ubuntu packages. - -## Troubleshooting - -### Firmware Mismatch Error - -When working with Stretch Body, if you see the following error: - -```{.bash .no-copy} ----------------- -Firmware protocol mismatch on /dev/XXXX. -Protocol on board is pX. -Valid protocol is: pX. -Disabling device. -Please upgrade the firmware and/or version of Stretch Body. ----------------- -``` - -This error appears because the low-level Python SDK and the firmware cannot communicate with 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. - -```{.bash .shell-prompt} -REx_firmware_updater.py --status -``` - ------- -
All materials are Copyright 2022 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks.
diff --git a/mkdocs.yml b/mkdocs.yml index b7b75c5..0f24d7d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: Stretch Tutorials +site_name: tutorials site_url: https://docs.hello-robot.com/stretch_tutorials site_description: "Hello Robot Stretch Tutorials" copyright: 'Copyright © 2022 Hello Robot Inc' @@ -83,118 +83,39 @@ extra: nav: - Overview: ./README.md - - Getting to Know Stretch: - - Overview: ./getting_started/README.md - - Basics: - - Safety Guide: ./getting_started/safety_guide.md - - Quick Start Stretch RE1: ./getting_started/quick_start_guide_re1.md - - Quick Start Stretch 2: ./getting_started/quick_start_guide_re2.md - - 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 Python SDK: - - Overview: ./stretch_body/README.md - - Basics: - - Introduction: ./stretch_body/tutorial_introduction.md - - Command line Tools: ./stretch_body/tutorial_command_line_tools.md - - Robot Motion: ./stretch_body/tutorial_robot_motion.md - - Robot Sensors: ./stretch_body/tutorial_robot_sensors.md - - Advanced: - - Dynamixel Servos: ./stretch_body/tutorial_dynamixel_servos.md - - Parameter Management: ./stretch_body/tutorial_parameter_management.md - - Splined Trajectories: ./stretch_body/tutorial_splined_trajectories.md - - Collision Avoidance: ./stretch_body/tutorial_collision_avoidance.md - - Contact Models: ./stretch_body/tutorial_contact_models.md - - Changing Tools: ./stretch_body/tutorial_tool_change.md - - Custom Wrist DOF: ./stretch_body/tutorial_custom_wrist_dof.md - - Safety Features: ./stretch_body/tutorial_safe_coding.md - - ROS: - - 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: - - Mobile Base Velocity Control: ./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 - - Autodocking: ./ros1/autodocking_nav_stack.md - - ROS 2 (Beta): - - Overview: ./ros2/README.md - - Basics: - - Getting Started: ./ros2/getting_started.md - - Introduction to ROS 2: ./ros2/intro_to_ros2.md - - Introduction to HelloNode: ./ros2/intro_to_hellonode.md - - Teleoperating Stretch: ./ros2/teleoperating_stretch.md - - Internal State of Stretch: ./ros2/internal_state_of_stretch.md - - RViz Basics: ./ros2/rviz_basics.md - - Nav2 Stack: - - Overview: ./ros2/navigation_overview.md - - Nav2 Basics: ./ros2/navigation_stack.md - - Nav2 Simple Commander: ./ros2/navigation_simple_commander.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: - - Respeaker Mic Array: ./ros2/respeaker_mic_array.md - - Respeaker Topics: ./ros2/respeaker_topics.md - - FUNMAP: https://github.com/hello-robot/stretch_ros2/tree/humble/stretch_funmap - # - MoveIt 2: - # - MoveIt Basics: ./ros2/moveit_basics.md - # - MoveIt with RViz: ./ros2/moveit_rviz_demo.md - # - MoveGroup C++ API: ./ros2/moveit_movegroup_demo.md - # - ROS testing: ./ros2/ros_testing.md - # - Other Nav Stack Features: ./ros2/other_nav_features.md - # - Gazebo Basics: ./ros2/gazebo_basics.md - - Other Examples: - - Mobile Base Velocity Control: ./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 - - ArUco Tag Locator: ./ros2/example_12.md - - Obstacle Avoider: ./ros2/obstacle_avoider.md - - Align to ArUco: ./ros2/align_to_aruco.md - - Deep Perception: ./ros2/deep_perception.md - - Avoiding Race Conditions and Deadlocks: ./ros2/avoiding_deadlocks_race_conditions.md - # - PointCloud Transformation: ./ros2/example_11.md + - Developing with Stretch: + - The Basics: ./developing/basics.md + - Networking Guide: ./developing/networking.md + - Command Line Tools: ./developing/cli.md + - Using Python with Stretch: ./developing/python.md + + - Python Tutorials: + - ./python/sensors.md - - Stretch Tool Share: - - Overview: ./stretch_tool_share/README.md - - Basics: - - Gripper Removal: ./stretch_tool_share/gripper_removal.md - - Gripper Puller: ./stretch_tool_share/gripper_puller.md - - Dry Erase Holder: ./stretch_tool_share/dry_erase_holder.md - - Dex Wrist: ./stretch_tool_share/dexwrist.md - - Dex to Standard Wrist: ./stretch_tool_share/dex_to_standard.md - - Advanced: - - Updating URDF: ./stretch_tool_share/updating_urdf.md + - ROS 2 Tutorials: + - Getting Started: ./ros2/getting_started.md + - Robot Drivers: ./ros2/robot_drivers.md + - Writing Nodes: ./ros2/writing_nodes.md + - Navigation with Nav2: + - Overview: ./ros2/navigation_overview.md + - Nav2 Basics: ./ros2/navigation_stack.md + - Nav2 Simple Commander: ./ros2/navigation_simple_commander.md + - Manipulation with MoveIt2: + - MoveIt Basics: ./ros2/moveit_basics.md + - MoveIt with RViz: ./ros2/moveit_rviz_demo.md + - MoveGroup C++ API: ./ros2/moveit_movegroup_demo.md + - FUNMAP: + - Mapping: ./ros2/writing_nodes.md + - Navigation: ./ros2/writing_nodes.md + - Manipulation: ./ros2/writing_nodes.md + - Perception: ./ros2/perception.md + - Examples: + - Filter Laser Scans: ./ros2/example_2.md + - Collision Avoidance: ./ros2/example_3.md + - Rviz Markers: ./ros2/example_4.md + - Offloading Computation: ./ros2/remote_compute.md + - ArUco Locator: ./ros2/example_12.md + - Voice Teleop: ./ros2/example_9.md + - Playing Audio: ./ros2/example_9.md + - Rosbags & MCAPs: ./ros2/example_9.md diff --git a/mkdocs_dws.yml b/mkdocs_dws.yml new file mode 100644 index 0000000..868789f --- /dev/null +++ b/mkdocs_dws.yml @@ -0,0 +1,88 @@ +site_name: developing +site_url: https://docs.hello-robot.com/stretch_tutorials +site_description: "Hello Robot Stretch Tutorials" +copyright: 'Copyright © 2022 Hello Robot Inc' +site_author: Hello Robot Inc +use_directory_urls: True +docs_dir: developing +site_dir: ../site + +theme: + name: material + #font: Arial + palette: + - scheme: default + primary: hello-robot-light + toggle: + icon: material/lightbulb-outline + name: Switch to dark mode + - scheme: slate + primary: hello-robot-dark + toggle: + icon: material/lightbulb + name: Switch to light mode + logo: images/hello_robot_logo_light.png + favicon: images/hello_robot_favicon.png + features: + - navigation.instant + +extra_css: + - ./extra.css + +markdown_extensions: + - pymdownx.highlight + - pymdownx.superfences + - pymdownx.inlinehilite + - pymdownx.keys + - admonition + - pymdownx.tabbed: + alternate_style: true + +plugins: + - same-dir +# - simple: +# merge_docs_dir: true +# include_extensions: [".css", ".png"] +# include_folders: ['../hello_helpers'] + - mike: + # these fields are all optional; the defaults are as below... + version_selector: true # set to false to leave out the version selector + css_dir: css # the directory to put the version selector's CSS + javascript_dir: js # the directory to put the version selector's JS + canonical_version: null # the version for ; `null` + # uses the version specified via `mike deploy` + - search + - tags + - mkdocstrings: + default_handler: python + handlers: + python: + selection: + docstring_style: numpy + rendering: + show_root_heading: true + show_source: false + members_order: source + heading_level: 3 + show_if_no_docstring: true + +extra: + version: + provider: mike + default: latest + social: + - icon: material/home + link: https://hello-robot.com + - icon: material/twitter + link: https://twitter.com/HelloRobotInc + - icon: material/github + link: https://github.com/hello-robot + - icon: material/linkedin + link: https://linkedin.com/company/hello-robot-inc + + +nav: + - The Basics: ./basics.md + # - Networking Guide: ./networking.md # TODO + # - Command Line Tools: ./cli.md + # - Using Python with Stretch: ./python.md diff --git a/mkdocs_pt.yml b/mkdocs_pt.yml new file mode 100644 index 0000000..a411cc2 --- /dev/null +++ b/mkdocs_pt.yml @@ -0,0 +1,91 @@ +site_name: python +site_url: https://docs.hello-robot.com/stretch_tutorials +site_description: "Hello Robot Stretch Tutorials" +copyright: 'Copyright © 2022 Hello Robot Inc' +site_author: Hello Robot Inc +use_directory_urls: True +docs_dir: python +site_dir: ../site + +theme: + name: material + #font: Arial + palette: + - scheme: default + primary: hello-robot-light + toggle: + icon: material/lightbulb-outline + name: Switch to dark mode + - scheme: slate + primary: hello-robot-dark + toggle: + icon: material/lightbulb + name: Switch to light mode + logo: images/hello_robot_logo_light.png + favicon: images/hello_robot_favicon.png + features: + - navigation.instant + +extra_css: + - ./extra.css + +markdown_extensions: + - pymdownx.highlight + - pymdownx.superfences + - pymdownx.inlinehilite + - pymdownx.keys + - admonition + - pymdownx.tabbed: + alternate_style: true + +plugins: + - same-dir +# - simple: +# merge_docs_dir: true +# include_extensions: [".css", ".png"] +# include_folders: ['../hello_helpers'] + - mike: + # these fields are all optional; the defaults are as below... + version_selector: true # set to false to leave out the version selector + css_dir: css # the directory to put the version selector's CSS + javascript_dir: js # the directory to put the version selector's JS + canonical_version: null # the version for ; `null` + # uses the version specified via `mike deploy` + - search + - tags + - mkdocstrings: + default_handler: python + handlers: + python: + selection: + docstring_style: numpy + rendering: + show_root_heading: true + show_source: false + members_order: source + heading_level: 3 + show_if_no_docstring: true + +extra: + version: + provider: mike + default: latest + social: + - icon: material/home + link: https://hello-robot.com + - icon: material/twitter + link: https://twitter.com/HelloRobotInc + - icon: material/github + link: https://github.com/hello-robot + - icon: material/linkedin + link: https://linkedin.com/company/hello-robot-inc + + +nav: + - ./moving.md + # - ./sensors.md # TODO + # - ./audio.md + # - ./pyfunmap.md + # - ./ik.md + # - ./visual_servoing.md + # - ./other.md diff --git a/mkdocs_rt.yml b/mkdocs_rt.yml new file mode 100644 index 0000000..1a8029f --- /dev/null +++ b/mkdocs_rt.yml @@ -0,0 +1,109 @@ +site_name: ros2 +site_url: https://docs.hello-robot.com/stretch_tutorials +site_description: "Hello Robot Stretch Tutorials" +copyright: 'Copyright © 2022 Hello Robot Inc' +site_author: Hello Robot Inc +use_directory_urls: True +docs_dir: ros2 +site_dir: ../site + +theme: + name: material + #font: Arial + palette: + - scheme: default + primary: hello-robot-light + toggle: + icon: material/lightbulb-outline + name: Switch to dark mode + - scheme: slate + primary: hello-robot-dark + toggle: + icon: material/lightbulb + name: Switch to light mode + logo: images/hello_robot_logo_light.png + favicon: images/hello_robot_favicon.png + features: + - navigation.instant + +extra_css: + - ./extra.css + +markdown_extensions: + - pymdownx.highlight + - pymdownx.superfences + - pymdownx.inlinehilite + - pymdownx.keys + - admonition + - pymdownx.tabbed: + alternate_style: true + +plugins: + - same-dir +# - simple: +# merge_docs_dir: true +# include_extensions: [".css", ".png"] +# include_folders: ['../hello_helpers'] + - mike: + # these fields are all optional; the defaults are as below... + version_selector: true # set to false to leave out the version selector + css_dir: css # the directory to put the version selector's CSS + javascript_dir: js # the directory to put the version selector's JS + canonical_version: null # the version for ; `null` + # uses the version specified via `mike deploy` + - search + - tags + - mkdocstrings: + default_handler: python + handlers: + python: + selection: + docstring_style: numpy + rendering: + show_root_heading: true + show_source: false + members_order: source + heading_level: 3 + show_if_no_docstring: true + +extra: + version: + provider: mike + default: latest + social: + - icon: material/home + link: https://hello-robot.com + - icon: material/twitter + link: https://twitter.com/HelloRobotInc + - icon: material/github + link: https://github.com/hello-robot + - icon: material/linkedin + link: https://linkedin.com/company/hello-robot-inc + + +nav: + - Getting Started: ./getting_started.md + - Robot Drivers: ./robot_drivers.md + # - Writing Nodes: ./writing_nodes.md # TODO + - Navigation with Nav2: + - Overview: ./navigation_overview.md + - Nav2 Basics: ./navigation_stack.md + - Nav2 Simple Commander: ./navigation_simple_commander.md + # - Manipulation with MoveIt2: # TODO + # - MoveIt Basics: ./moveit_basics.md # TODO + # - MoveIt with RViz: ./moveit_rviz_demo.md # TODO + # - MoveGroup C++ API: ./moveit_movegroup_demo.md # TODO + - FUNMAP: https://github.com/hello-robot/stretch_ros2/tree/humble/stretch_funmap#overview + # - Mapping: ./writing_nodes.md #TODO + # - Navigation: ./writing_nodes.md #TODO + # - Manipulation: ./writing_nodes.md # TODO + - Perception: ./perception.md + - Examples: + - Filter Laser Scans: ./example_2.md + - Collision Avoidance: ./example_3.md + - Rviz Markers: ./example_4.md + - Offloading Computation: ./remote_compute.md + - ArUco Locator: ./example_12.md + - Voice Teleop: ./example_9.md + - Playing Audio: ./example_9.md + - Rosbags & MCAPs: ./example_9.md diff --git a/python/audio.md b/python/audio.md new file mode 100644 index 0000000..e428c92 --- /dev/null +++ b/python/audio.md @@ -0,0 +1,4 @@ +# Playing & Recording Audio + +tbd + diff --git a/python/ik.md b/python/ik.md new file mode 100644 index 0000000..7622637 --- /dev/null +++ b/python/ik.md @@ -0,0 +1,4 @@ +# Inverse Kinematics + +tbd + diff --git a/python/images/stretch_arm_lift_joint_limits.png b/python/images/stretch_arm_lift_joint_limits.png new file mode 100644 index 0000000..4e71334 Binary files /dev/null and b/python/images/stretch_arm_lift_joint_limits.png differ diff --git a/python/images/stretch_head_joint_limits.png b/python/images/stretch_head_joint_limits.png new file mode 100644 index 0000000..db95e5b Binary files /dev/null and b/python/images/stretch_head_joint_limits.png differ diff --git a/python/images/stretch_joints.png b/python/images/stretch_joints.png new file mode 100644 index 0000000..ea80f47 Binary files /dev/null and b/python/images/stretch_joints.png differ diff --git a/python/images/stretch_pitch_joint_limits.png b/python/images/stretch_pitch_joint_limits.png new file mode 100644 index 0000000..de0ac63 Binary files /dev/null and b/python/images/stretch_pitch_joint_limits.png differ diff --git a/python/images/stretch_roll_joint_limits.png b/python/images/stretch_roll_joint_limits.png new file mode 100644 index 0000000..329cd9e Binary files /dev/null and b/python/images/stretch_roll_joint_limits.png differ diff --git a/python/images/stretch_yaw_joint_limits.png b/python/images/stretch_yaw_joint_limits.png new file mode 100644 index 0000000..e52f468 Binary files /dev/null and b/python/images/stretch_yaw_joint_limits.png differ diff --git a/python/moving.md b/python/moving.md new file mode 100644 index 0000000..e70a776 --- /dev/null +++ b/python/moving.md @@ -0,0 +1,217 @@ +# Commanding Stretch to Move + +This tutorial covers sending various kinds of motion commands to Stretch. + +## Introducing Stretch Body + +"Stretch Body" is a Python library for Stretch. It's already installed on your robot. The library gives you an interface to command Stretch's body to move. We start by creating an instance of the `stretch_body.robot.Robot` class. + +```python +import stretch_body.robot + +r = stretch_body.robot.Robot() +``` + +The hardware can only talk to one instance at a time, so if you see an `Another process is already using Stretch. Try running "stretch_free_robot_process.py"` error, you'll need to close the other application or use the `stretch_free_robot_process.py` CLI to free up the hardware. + +Next, we'll call the `startup()` method, which opens USB communication with the hardware, loads the parameters that dictate robot behavior, and launches a few helper threads to poll for status in the background. + +```python +did_startup = r.startup() +print(f'Robot connected to hardware: {did_startup}') +``` + +To close down the connection to the hardware, use `stop()`. Next, we'll check if the robot is "homed", i.e. the robot knows the zero position for each joint. + +```python +is_homed = r.is_homed() +print(f'Robot is homed: {is_homed}') +``` + +To execute the homing procedure, use `home()`. Ensure the robot has space around it. + +## Sending Position Commands + +Stretch has the following joints: + + + + 1. Left and right wheels, constituting a differential drive + 1. Pristmatic vertical lift + 1. Prismatic telescoping horizontal arm + 1. Up to three revolute joints in the wrist: yaw, pitch, and roll + - Print out `r.end_of_arm.joints` to see which joints your Stretch has + 1. Gripper + 1. Two revolute joints in the head: pan & tilt + +Each of these joints are accessible as an attribute of the `Robot` object. + +```python +# The mobile base: +print(r.base) + +# The arm/lift: +print(r.arm, r.lift) + +# The wrist/gripper +print(r.end_of_arm) + +# The head +print(r.head) +``` + +Use the `move_to(pos)` method under each joint to queue up a command. + +```python +r.arm.move_to(0.2) # 0.2 meters +r.lift.move_to(0.6) # 0.6 meters +``` + +The arm and lift won't move yet. The commands have been queued up, but the hardware will wait to begin moving until we call `push_command()`. + +```python +r.push_command() +``` + +The mobile base doesn't have a move method. Instead, its methods are `translate_by(delta)` and `rotate_by(delta)`. + +```python +r.base.translate_by(0.2) # 0.2 meters +r.push_command() +r.base.rotate_by(0.1) # 0.1 radians +r.push_command() +``` + +You'll notice the base doesn't translate forward by 0.2m. Instead, it skips to rotating counter-clockwise by 0.1rad. This happens because `push_command()` is asynchronous (i.e. the method returns immediately, and the program flow continues immediately to execute the rotation command). Use the `wait_command()` method to wait for the command to complete execution. + +```python +r.base.translate_by(0.2) # 0.2 meters +r.push_command() +r.wait_command() + +r.base.rotate_by(0.1) # 0.1 radians +r.push_command() +r.wait_command() +``` + +The wrist and head joints are Dynamixel servos. Their API is `move_to(name, pos)`, and their commands aren't queued. They execute immediately. + +```python +print(f'Wrist joints: {r.end_of_arm.joints}') # ['wrist_yaw', 'wrist_pitch', 'wrist_roll', 'stretch_gripper'] +r.end_of_arm.move_to('wrist_yaw', 1.57) +``` + +`wait_command()` will still work here. The gripper uses the same `move_to(name, pos)` API, and accepts values between -100 to 100, where the gripper is fully closed at -100 and fully open at 100. + +```python +r.end_of_arm.move_to('stretch_gripper', 100) +``` + +## Querying Stretch's current joint state + +The current state of each joint is available in a Python dictionary called `status` under each joint. + +```python +# Wheel odometry +print(r.base.status['x'], r.base.status['y'], r.base.status['theta']) # (x meters, y meters, theta radians) + +# Arm/lift positions +print(r.arm.status['pos'], r.lift.status['pos']) # (arm meters, lift meters) +``` + +The wrist and head joints are Dynamixel servos. Their `status` dictionary is under the `get_joint(name)` method. + +```python +# Wrist positions +print(f'Wrist joints: {r.end_of_arm.joints}') +print(r.end_of_arm.get_joint('wrist_yaw').status['pos']) # radians + +# Head positions +print(f'Head joints: {r.head.joints}') +print(r.head.get_joint('head_pan').status['pos']) # radians +``` + +## Querying Stretch's joint limits + +Whereas the mobile base is unbounded (i.e. `translate_by(delta)` can take any value for delta), the rest of the joints have joint limits. They are available as part of the `soft_motion_limits` dictionary. + +### Arm & Lift + +![](./images/stretch_arm_lift_joint_limits.png){ width="500" loading=lazy } + +```python +print(r.lift.soft_motion_limits['hard']) # (lower bound in meters, upper bound in meters) +print(r.arm.soft_motion_limits['hard']) +``` + +`soft_motion_limits` is a dictionary with four keys: "collision", "user", "hard", and "current". Each key maps to a `[lower bound, upper bound]` tuple. "collision" is used by Stretch Body's self collision avoidance algorithm to set *soft*ware limits on the joint. "user" is used by you, the user, to set application specific software joint limits. "hard" is the hardware limits of the joint. And "current" is the aggregate of the previous three limits into the final limits enforced by the software. + +### Wrist Joints + +| Yaw | Pitch | Roll | +| ----------- | ------ | ------- | +| ![](./images/stretch_yaw_joint_limits.png){ loading=lazy } | ![](./images/stretch_pitch_joint_limits.png){ loading=lazy } | ![](./images/stretch_roll_joint_limits.png){ loading=lazy } | + +```python +print(r.end_of_arm.get_joint('wrist_yaw').soft_motion_limits['hard']) # (lower bound in radians, upper bound in radians) +print(r.end_of_arm.get_joint('wrist_pitch').soft_motion_limits['hard']) +print(r.end_of_arm.get_joint('wrist_roll').soft_motion_limits['hard']) +``` + +### Head Joints + +![](./images/stretch_head_joint_limits.png){ width="500" loading=lazy } + +```python +print(r.head.get_joint('head_pan').soft_motion_limits['hard']) # (lower bound in radians, upper bound in radians) +print(r.head.get_joint('head_tilt').soft_motion_limits['hard']) +``` + +## Sending Velocity Commands + +Each joint accepts velocity commands via the `set_velocity(vel)` API. + +```python +r.arm.set_velocity(0.01) # extends 1 cm/s +r.push_command() +``` + +Once again, Dynamixel joints push their commands immediately. + + +```python +r.end_of_arm.get_joint('wrist_yaw').set_velocity(0.1) # rotate CCW at 0.1 rad/s +``` + +The base can execute translational (`v`) and rotational (`ω`) velocity simultaneously via `set_velocity(v, ω)`. You will often see navigation motion planners choose to control mobile bases with `v` and `ω` velocities. + +```python +r.base.set_velocity(0.01, 0.05) # follow a circular path +r.push_command() +``` + +## Following Cubic/quintic Splines + +Stretch's joints can follow trajectories defined as splines. You will often see geometric motion planners, graphics software (e.g. Blender, Unity3D), and motion capture systems choose to formulate robot trajectories as splines. Spline trajectories are a series of position waypoints, associated with a time at which the joint should reach the position, and optionally associated with a velocity/acceleration that the joint should be traveling at when it passes the waypoint. + +Each joint has a `trajectory` attribute that is an instance of either `stretch_body.trajectories.RevoluteTrajectory` (for the wrist & head joints), `stretch_body.trajectories.PrismaticTrajectory` (for the arm & lift), or `stretch_body.trajectories.DiffDriveTrajectory` (for the base). Adding waypoints looks like: + +```python +r.arm.trajectory.add(t_s=0.0, x_m=0.0, v_m=0.0) +r.arm.trajectory.add(t_s=10.0, x_m=0.5, v_m=0.0) +r.arm.trajectory.add(t_s=20.0, x_m=0.0, v_m=0.0) # 20 second trajectory extending & retracting the arm +``` + +Then begin tracking the trajectory using: + +```python +r.follow_trajectory() +``` + +Trajectories are preemptive. You can edit the future waypoints in a trajectory while the robot is actively tracking it. For example, geometric planners can use this adapt to changing environments. + +You can stop a trajectory early using `stop_trajectory()`. + +### Coordinated Motion through Trajectories + +Check out the [Creating smooth motion using trajectories](https://forum.hello-robot.com/t/creating-smooth-motion-using-trajectories/671) tutorial for more info on creating coordinated joint movements. diff --git a/python/other.md b/python/other.md new file mode 100644 index 0000000..3c8dab0 --- /dev/null +++ b/python/other.md @@ -0,0 +1,4 @@ +# Other Stretch Python Libraries + +tbd + diff --git a/python/pyfunmap.md b/python/pyfunmap.md new file mode 100644 index 0000000..3433e8e --- /dev/null +++ b/python/pyfunmap.md @@ -0,0 +1,4 @@ +# Using PyFUNMAP + +tbd + diff --git a/python/sensors.md b/python/sensors.md new file mode 100644 index 0000000..32c1355 --- /dev/null +++ b/python/sensors.md @@ -0,0 +1,46 @@ +# Working with Sensors + +## Realsense Cameras + +Use the `pyrealsense2` library to interact with the two Intel Realsense depth cameras on Stretch 3. The library can configure camera parameters, collect imagery, calculate point clouds, and much more. Start by creating a "pipeline", which is an interface for streaming data from the camera. + +```python +import pyrealsense2 as rs + +cam = rs.pipeline() +cam.start() +cam.stop() +``` + +`start()` returns a "profile", which returns information about the Realsense camera. + +``` +profile = cam.start() +print(profile.get_device().get_info()) # "D435if" +``` + +### Configuration + +We pass a "config" to `start()` to choose which camera we want to stream from, what resolution the imagery should be, what frames per second the data should arrive at, and more. + +``` +config = rs.config() +config.enable_device(d405_info['serial_number']) +width, height, fps = 640, 480, 15 +config.enable_stream(rs.stream.depth, width, height, rs.format.z16, fps) +config.enable_stream(rs.stream.color, width, height, rs.format.bgr8, fps) +profile = cam.start(config) +``` + +### Frames + + + +### API and Docs + +https://github.com/IntelRealSense/librealsense/tree/master/wrappers/python#python-wrapper + +https://intelrealsense.github.io/librealsense/python_docs/_generated/pyrealsense2.html + + + diff --git a/python/visual_servoing.md b/python/visual_servoing.md new file mode 100644 index 0000000..932993f --- /dev/null +++ b/python/visual_servoing.md @@ -0,0 +1,4 @@ +# Visual Servoing + +tbd + diff --git a/ros2/README.md b/ros2/README.md index 87f33b2..c77faee 100644 --- a/ros2/README.md +++ b/ros2/README.md @@ -1,11 +1,13 @@ ![](../images/banner.png) # Tutorial Track: Stretch ROS 2 (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 in the [stretch_ros2](https://github.com/hello-robot/stretch_ros2) repository, 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. - ## Robot Operating System 2 (ROS 2) +ROS 2 is the successor to ROS, The ROS in ROS 2 stands for "robot operating system", but despite the name, ROS is not an operating system. It's 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 allow 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 multiple 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. + + 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 allow 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 multiple 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 get familiar with programming Stretch robots via ROS 2. We recommend going through the tutorials in the following order: diff --git a/ros2/getting_started.md b/ros2/getting_started.md index 4a58b9c..e071ff4 100644 --- a/ros2/getting_started.md +++ b/ros2/getting_started.md @@ -1,78 +1,27 @@ # Getting Started -!!! note - ROS 2 tutorials are still under active development. +This tutorial series covers writing ROS 2 software for Stretch. ROS 2 programs can be written in a variety of programming languages, but this series uses Python. We'll write programs that enable Stretch to navigate autonomously in its environment, manipulate objects with Stretch's gripper, perceive its environment, and much more. ## Prerequisites -1. A Stretch RE1 or Stretch 2 robot, turned on and connected to a keyboard, mouse, and monitor - - Alternatively, setup [untethered operation](https://docs.hello-robot.com/0.2/stretch-tutorials/getting_started/untethered_operation/). This avoids the HDMI/USB cables getting pulled while the robot is moving. -2. Running the Ubuntu 20.04 software stack - - All Stretch 2 robots ship with Ubuntu 20.04, however RE1s had shipped with Ubuntu 18.04 until summer 2022. RE1 users should run `lsb_release -sd` in a terminal and confirm "Ubuntu 20.04.5 LTS" or similar is printed out. If you are running Ubuntu 18.04, follow the [upgrade guide](https://docs.hello-robot.com/0.2/stretch-install/docs/robot_install/). -3. Already went through the [Start Coding section of the Getting Started guide](../getting_started/quick_start_guide_re2.md#start-coding) (hello_robot_xbox_teleop must not be running in the background) -## Switching to ROS2 -It's recommended that ROS1 and ROS2 systems not run at the same time. Therefore, the default installation starts with ROS1 enabled and ROS2 disabled. This is configured in the "STRETCH BASHRC SETUP", which you can see by running `gedit ~/.bashrc` in a terminal and scrolling to the bottom. - -![](./images/bashrc_setup_noetic.png) - -We will disable ROS1 by commenting out the ROS1 related lines by adding '#' in front of them, and enable ROS2 by uncommenting the ROS2 related lines by deleting the '#' in front of them. The result will look like: - -![](./images/bashrc_setup_galactic.png) - -Save this configuration using **Ctrl + S**. Close out of the current terminal and open a new one. ROS2 is now enabled! - -## Refreshing the ROS2 workspace -While Stretch ROS2 is in beta, there will be frequent updates to the ROS2 software. Therefore, it makes sense to refresh the ROS2 software to the latest available release. In the ROS and ROS2 world, software is organized into "ROS Workspaces", where packages can be developed, compiled, and be made available to run from the command line. We are going to refresh the ROS2 workspace, which is called "~/ament_ws" and available in the home directory. Follow the [Create a new ROS Workspace guide](https://docs.hello-robot.com/0.2/stretch-install/docs/ros_workspace/) to run the `stretch_create_ament_workspace.sh` script. This will delete the existing "~/ament_ws", create a new one with all of the required ROS2 packages for Stretch, and compile it. Also we need to take into account that building the workspace is different in ROS2, we need to type colcon build instead of catkin make for it to work. - -## Testing Keyboard Teleop -We can test whether the ROS2 workspace was enabled successfully by testing out the ROS2 drivers package, called "stretch_core", with keyboard teleop. In one terminal, we'll launch Stretch's ROS2 drivers using: - -```{.bash .shell-prompt} -ros2 launch stretch_core stretch_driver.launch.py -``` - -In the second terminal, launch the keyboard teleop node using: -```{.bash .shell-prompt} -ros2 run stretch_core keyboard_teleop -``` - -The following menu will be outputted to the terminal and you can press a key to move the corresponding joint on the robot. When you're ready to exit, press **Ctrl + C**. - -```{.bash .no-copy} -[INFO] [1672878953.011453154] [keyboard_teleop]: keyboard_teleop started -[INFO] [1672878953.041154084] [keyboard_teleop]: Node keyboard_teleop connected to /stop_the_robot service. ----------- 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 - -------------------------------------------- -``` - -ROS2 is setup! Move onto the next tutorial: [Follow Joint Trajectory Commands](follow_joint_trajectory.md). +Ensure that: + + 1. Your Stretch has the latest robot distribution installed + - These tutorials were written for the latest robot distribution. Take a look at the [Distributions & Roadmap](../../../software/distributions/) guide to identify your current distribution and upgrade if necessary. + 2. You are comfortable developing with Stretch + - If you've never developed with Stretch before or are new to programming, check out the [Developing with Stretch](../../developing/basics/) tutorial series. In particular, the [Using ROS 2 with Stretch](#TODO) tutorial from that series is a good resource for those new to ROS 2. + + diff --git a/ros2/robot_drivers.md b/ros2/robot_drivers.md new file mode 100644 index 0000000..90df82d --- /dev/null +++ b/ros2/robot_drivers.md @@ -0,0 +1,118 @@ +# Robot Drivers + +This tutorial introduces the ROS2 drivers for Stretch and its sensors. These drivers reside in the `stretch_core` package, which is part of a suite of ROS2 packages available open-source [on Github](https://github.com/hello-robot/stretch_ros2/tree/humble/stretch_core#overview). + +## Stretch Driver + +The robot's driver is called "Stretch Driver". You can use it to send motion commands and read joint info. The command to launch Stretch Driver is: + +```{.bash .shell-prompt .copy} +ros2 launch stretch_core stretch_driver.launch.py rviz:=True +``` + + + +### Modes + +Stretch Driver has a few modes that change how the driver behaves. They are: + + - **Position:** The default and simplest mode. In this mode, you can control every joint on the robot using position commands. For example, you could move the telescoping arm 25cm out by sending the driver a command of 0.25m for the "joint_arm" joint. Two kinds of position commands are available for the mobile base: translation and rotation, with joint names "translate_mobile_base" and "rotate_mobile_base". They are mutually exlusive and these joints have no limits since the wheels can spin continuously. + - Position commands are tracked by a trapezoidal motion profile. + - Position commands are contact sensitive. This is helpful for manipulating objects in the world. For example, Stretch can [open a cabinet](https://youtu.be/SXgj9be3PdM) by reaching out with the telescoping arm and detecting contact with the door and its handle. + - Position commands are preemptable, so you can issue a new position command before the previous one has finished executing and the robot will smoothly transition to executing the new command. This feature is helpful for reactive control (e.g visual servo-ing). + - **Navigation:** In this mode, every joint behaves identically to "position" mode except for the mobile base, which takes velocity commands. + - Velocity control of the base is a common way to move mobile robots around. For example, Nav2 is a piece of software that uses this mode to navigate Stretch within its environment. + - Velocity control has the potential to cause unsafe "running away" behavior if your program were to command a velocity motion and neglect to stop the motion later. Stretch has a few safety features to prevent this "running away" behavior. The driver has a 0.5 second timeout, which means that if the driver doesn't receive a new command within 0.5s, the base will stop smoothly. Additionally, the firmware has a 1 second timeout for the wheels, which means that even if the robot's onboard computer were to crash, the robot will stop if the firmware doesn't receive a new command within 1 second. + - **Trajectory:** In this mode, every joint follows a trajectory that is modeled as a spline. The key benefit of this mode is control over the timing at which the robot achieves positions (a.k.a waypoints), enabling smooth and coordinated motion through a preplanned trajectory. + - Trajectory commands are contact sensitive. + - The waypoints in trajectory commands are preemptable. + - **Homing:** This is the mode reported by the driver when a homing sequence is happening. While this mode is active, no commands will be accepted by the driver and the mode cannot be switched. After the robot has completed its 30 second homing sequence, it will return to the mode it was in before. + - **Stowing:** This is the mode reported by the driver when a stowing sequence is happening. While this mode is active, no commands will be accepted by the driver and this mode cannot be switched. After the robot has completed its stowing sequence, it will return to the mode it was in before. + - **Runstopped:** This is the mode reported by the driver when the robot is in runstop. You can runstop Stretch by pressing the runstop button (i.e. the glowing white button in Stretch's head). While this mode is active, no commands will be accepted by the driver and the mode cannot be switched. After the robot has been taken out of runstop, it will return to the mode it was in before, or "position" mode if the driver was launched while the robot was runstopped. + +The driver publishes its current mode at the `/stretch/mode` topic, so you can see the driver's current mode using: + +```{.bash .shell-prompt .copy} +ros2 topic echo /stretch/mode +# TODO - include output +``` + +### Keyboard Teleop + +The keyboard teleop node is an easy way to send position commands. First, switch the driver into "position" mode using the `/stetch/switch_to_position_mode` service: + +```{.bash .shell-prompt .copy} +ros2 service call /stretch/switch_to_position_mode +# TODO - verify command and include output +``` + +Then, start the keyboard teleop node: + +```{.bash .shell-prompt .copy} +ros2 run stretch_core keyboard_teleop +``` + +### Joints & Ranges + +You can read the robot's current joint state by echo-ing the `/stretch/joint_states` topic: + +```{.bash .shell-prompt .copy} +ros2 topic echo /stretch/joint_states +# TODO - verify output +header: + seq: 70999 + stamp: + secs: 1420 + nsecs: 2000000 + frame_id: '' +name: [joint_arm_l0, joint_arm_l1, joint_arm_l2, joint_arm_l3, joint_gripper_finger_left, + joint_gripper_finger_right, joint_head_pan, joint_head_tilt, joint_left_wheel, joint_lift, + joint_right_wheel, joint_wrist_yaw] +position: [-1.6137320244357253e-08, -2.9392484829061376e-07, -2.8036125938539207e-07, -2.056847528567165e-07, -2.0518734302754638e-06, -5.98271107676851e-06, 2.9291786329821434e-07, 1.3802900147297237e-06, 0.08154086954434359, 1.4361499260374905e-07, 0.4139061738340768, 9.32603306580404e-07] +velocity: [0.00015598730463972836, -0.00029395074514369584, -0.0002803845454217379, 1.322424459109634e-05, -0.00035084643762840415, 0.0012164337445918797, 0.0002138814988808099, 0.00010419792027496809, 4.0575263146426684e-05, 0.00022487596895736357, -0.0007751929074042957, 0.0002451588607332439] +effort: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0] +--- +``` + +To stop the stream of joint states, press ++ctrl+c++. The position, velocity, and effort arrays match the length of the joint names array, so each joint's state is found by indexing into the arrays at the same index that the joint has in the joint names array. E.g. "joint_wrist_yaw" has position 9.32603306580404e-07, velocity 0.0002451588607332439, and effort 0.0. + +### Motion Profiles + + - Position commands are tracked in the firmware by a trapezoidal motion profile, and specifing the optional velocity and acceleration in [JointTrajectoryPoint](https://docs.ros.org/en/noetic/api/trajectory_msgs/html/msg/JointTrajectoryPoint.html) changes the shape of the trapezoid. More details about the motion profile [in the tutorial](https://docs.hello-robot.com/0.2/stretch-tutorials/ros1/follow_joint_trajectory/). + +### Contact Sensitivity + + - In order to specify contact thresholds for a position command, the optional effort in [JointTrajectoryPoint](https://docs.ros.org/en/noetic/api/trajectory_msgs/html/msg/JointTrajectoryPoint.html) is misused to mean a threshold for the effort the robot will apply while executing the position command. + +### Preemption + +### Other Services + +```{.bash .shell-prompt .copy} +ros2 service call /stretch/home_the_robot +ros2 service call /stretch/stow_the_robot +ros2 service call /stretch/stop_the_robot +# TODO - verify commands and include outputs +``` + +## Lidar Driver + +Rplidar Spinning Lidar + +## Camera Drivers + +Realsense Cameras + +### Head Camera + +### Eye in Hand Camera + +### Fisheye Navigation Camera + +## Mic Array Driver + +Respeaker Microphone Array + +## IMUs + +## Cliff Sensors diff --git a/ros2/writing_nodes.md b/ros2/writing_nodes.md new file mode 100644 index 0000000..7b019a2 --- /dev/null +++ b/ros2/writing_nodes.md @@ -0,0 +1,5 @@ +# Writing Nodes + +TODO + +You would publish [geometry_msgs/Twist](https://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Twist.html) messages to the [/stretch/cmd_vel topic](#TODO). Since Twist messages are generalized to robots that can move with velocity in any direction, only the `Twist.linear.x` (translational velocity) and `Twist.angular.z` (rotational velocity) fields apply for differential drive mobile bases. diff --git a/tutorial_template.md b/tutorial_template.md deleted file mode 100644 index aeb7045..0000000 --- a/tutorial_template.md +++ /dev/null @@ -1,104 +0,0 @@ -# Motivation -The aim of this document is to be the starting point for generating new ROS tutorials and to maintain consistency in structure and tone across the documentation. It starts off by formalizing the key objectives and then goes on to templatize the structure and tone that we should adopt going forward. - -## Objectives -1. **Be inclusive of all levels of understanding** - start from the basics and link relevant external content to be concise yet informative -2. **Reinforce that getting started with Stretch is a breeze** - use easy to understand vocab and a friendly tone to encourage readers -3. **Encourage users to read other tutorials** - wherever possible, link other tutorials from the documentation to convey completeness and complexity -4. **Have a clear flow** - start with the theory, show with GIFs what to expect, and then breakdown the code - -What follows can be considered the template. - -# Major Topic -In this tutorial, we will work with Stretch to explore *the main theme of tutorial* using *primary module* and also learn how to achieve *secondory theme*. If you want to know more about *any previously covered topic* on Stretch and how to get it up and running, we recommend visiting the previous tutorials on [*link to topic*]() and [*link to topic*](). - -*Motivation for the problem the topic solves*. The great thing about Stretch is that it comes preloaded with software that makes it a breeze to achieve *theme of the tutorial*. - -By the end of this tutorial, we will have a clear idea about how *first minor topic* works and how to use it to achieve *second minor topic* with Stretch. Let's jump in! - -## First Minor Topic Title -[PyTorch](https://pytorch.org/) is an open source end-to-end machine learning framework that makes many pretrained production quality neural networks available for general use. In this tutorial we will use the YOLOv5s model trained on the COCO dataset. - -[YOLOv5](https://github.com/ultralytics/yolov5) is a popular object detection model that divides a supplied image into a grid and detects objects in each cell of the grid recursively. The YOLOv5s model that we have deployed on Stretch has been pretrained on the [COCO dataset](https://cocodataset.org/#home) which allows Stretch to detect a wide range of day to day objects. However, that’s not all, in this demo we want to go a step further and use this extremely versatile object detection model to extract useful information about the scene. - -## Second Minor Topic Title -Now, let’s use what we have learned so far to upgrade the collision avoidance demo in a way that Stretch is able to scan an entire room autonomously without bumping into things or people. To account for dynamic obstacles getting too close to the robot, we will define a keepout distance of 0.4 m - detections below this value stop the robot. To keep Stretch from getting too close to static obstacles, we will define another variable called turning distance of 0.75 m - frontal detections below this value make Stretch turn to the left until it sees a clear path ahead. - -Building up on this, let's implement a simple logic for obstacle avoidance. The logic can be broken down into three steps: -1. If the minimum value from the frontal scans is greater than 0.75 m, then continue to move forward -2. If the minimum value from the frontal scans is less than 0.75 m, then turn to the right until this is no longer true -3. If the minimum value from the overall scans is less than 0.4 m, then stop the robot - -## Third Minor Topic Title -*If a tutorial covers more than two minor topics, it might be a good idea to break it down into multiple tutorials* - -## Warning -Running this tutorial on Stretch might result in *harm to robot, humans or the surrounding environment*. Please ensure *these conditions*. We recommend *taking these actions* to ensure safe operation. - -## See It In Action -Go ahead and execute the following commands to run the demo and visualize the result in RViz: -Terminal 1: -```{.bash .shell-prompt} -Enter first command here -``` - -Terminal 2: -```{.bash .shell-prompt} -Enter second command here -``` - -*Enter GIF to show robot behavior* -

- -

- -*Enter GIF to show robot and sensor visualization in RViz* -

- -

- -## Code Breakdown -Now, let's jump into the code to see how things work under the hood. Follow along [*link to code*]() to have a look at the entire script. - -We make use of two separate Python classes for this demo. The FrameListener class is derived from the Node class and is the place where we compute the TF transformations. For an explantion of this class, you can refer to the [TF listener](https://docs.hello-robot.com/0.2/stretch-tutorials/ros2/example_10/) tutorial. -```python -class FrameListener(Node): -``` - -The AlignToAruco class is where we command Stretch to the pose goal. This class is derived from the FrameListener class so that they can both share the node instance. -```python -class AlignToAruco(FrameListener): -``` - -The constructor initializes the Joint trajectory action client. It also initializes the attribute called offset that determines the end distance between the marker and the robot. -```python - def __init__(self, node, offset=0.75): - self.trans_base = TransformStamped() - self.trans_camera = TransformStamped() - self.joint_state = JointState() - self.offset = offset - self.node = node - - self.trajectory_client = ActionClient(self.node, FollowJointTrajectory, '/stretch_controller/follow_joint_trajectory') - server_reached = self.trajectory_client.wait_for_server(timeout_sec=60.0) - if not server_reached: - self.node.get_logger().error('Unable to connect to arm action server. Timeout exceeded.') - sys.exit() -``` - -The apply_to_image() method passes the stream of RGB images from the realsense camera to the YOLOv5s model and returns detections in the form of a dictionary consisting of class_id, label, confidence and bouding box coordinates. The last part is exactly what we need for further computations. -```python - def apply_to_image(self, rgb_image, draw_output=False): - results = self.model(rgb_image) - - ... - - if draw_output: - output_image = rgb_image.copy() - for detection_dict in results: - self.draw_detection(output_image, detection_dict) - - return results, output_image -``` - -*Motivate users to play with the code or continue exploring more topics*. Now go ahead and experiment with a few more pretrained models using PyTorch or OpenVINO on Stretch. If you are feeling extra motivated, try creating your own neural networks and training them. Stretch is ready to deploy them! \ No newline at end of file