add mkdocs org

2 years ago · d6fc818fa1
--- a/docs/extra.css
+++ b/docs/extra.css
@ -0,0 +1,33 @@
 [data-md-color-primary=hello-robot-light]{
  --md-primary-fg-color: #122837;
  --md-primary-fg-color--light: hsla(0,0%, 100%, 0.7);
  --md-primary-fg-color--dark: hsla(0, 0%, 0%, 0.07);
  --md-primary-bg-color: hsla(341, 85%, 89%, 1.0);
  --md-typeset-a-color: #0550b3;
  --md-code-hl-number-color: hsla(196, 86%, 29%, 1);
 }
 [data-md-color-primary=hello-robot-dark]{
  --md-primary-fg-color: #122837;
  --md-primary-fg-color--light: hsla(0,0%, 100%, 0.7);
  --md-primary-fg-color--dark: hsla(0, 0%, 0%, 0.07);
  --md-primary-bg-color: hsla(341, 85%, 89%, 1.0);
  --md-typeset-a-color: hsla(341, 85%, 89%, 1.0);
  --md-code-hl-number-color: hsla(196, 86%, 29%, 1);
 }


 [data-md-color-scheme="slate"] {
  --md-hue: 210; /* [0, 360] */
 }

 /*
 Tables set to 100% width
 */

 .md-typeset__table {
    min-width: 100%;
 }

 .md-typeset table:not([class]) {
    display: table;
 }
--- a/docs/getting_started/quick_start_guide.md
+++ b/docs/getting_started/quick_start_guide.md
@ -0,0 +1,226 @@
 # Stretch RE1: Quick Start Guide

 Congratulations on your Stretch RE1! This guide will get you started with your new robot. 

 ## Safety

 Stretch has the potential to cause harm if not properly used. All users should review the [Stretch Safety Guide](robot_safety_guide.md) before operating the robot.

 ## Unboxing

 Please watch the [Stretch Unboxing Video](https://youtu.be/O-6VrqqGlig).

 ## Robot Tour

 A few items you'll want to know about before getting started.

 ### Power

 The entire robot powers up and down with the On/Off switch. When powering down, we recommend selecting 'Power Off' from the Ubuntu Desktop prior to hitting the Off switch



 ![](./images/trunk_rs.png)

 The provided battery charger can be plugged and unplugged at any time during operation. Stretch uses the following charger modes:

 | Mode    | Function                                                     |
 | ------- | ------------------------------------------------------------ |
 | STANDBY | Charger not charging the robot                               |
 | 12V AGM | Charging while robot is powered down                         |
 | SUPPLY  | 1) Power the robot during tethered use<br/>2) Repair damaged batteries. |
 | REPAIR  | Repair damaged batteries.                                    |

 Please review the [Battery Maintenance Guide](./battery_maintenance_guide.md) for proper care and charging of Stretch batteries. 

 ![](./images/NOCO_Genius10_UI_rs.png)

 ### Runstop

 The illuminated button on the head is its Runstop. Just tap it, you'll hear a beep and it will start flashing. This will pause motion of the primary robot joints during operation. This can be useful if the robot makes an unsafe motion, or if you just want to free up the robot motors while you roll it around.

 To allow motion once again, hold the button down for two seconds. After the beep, motion can resume.

 ![](./images/runstop_rs.png)

 ### Safe Handling

 Like any robot, it is possible to break Stretch if you're not careful. Use common sense when applying forces to its joints, transporting it, etc. 

 The [Stretch Unpowered Best Practices Video](https://youtu.be/mQdOGEksdYM) provides a quick overview of how to work with the robot.

 **Things that won't hurt the robot**:

 * Manually push and pull the arm (when the motor isn't holding a position).
 * Manually raise and lower the lift (when the motor isn't holding a position).
 * Manually tilt and roll the base around (when the motors aren't holding a position).
 * Pick up and carry Stretch (while holding it by the mast, two people for safety).

 **Things to be mindful of**:

 * Manually moving the head and wrist. They will move but they want to go at their own speed.
 * The arm will slowly descend when the robot is powered off. If the arm is retracted it may rest the tool on the base. If desired to hold the arm up when un-powered, the provided 'clip-clamp' can be clipped onto the mast below the shoulder to support it. 

 **Things that can hurt the robot**: 

 * Driving the wrist and gripper into the base. When the arm and wrist are stowed it is possible to collide the two.
 * Getting the gripper stuck on something and then driving the arm, lift, or base. 
 * Laying the robot down with it weight on its camera.
 * Trying to ride on the robot, getting it wet, etc. (eg, common sense)

 ## Hello World Demo

 Stretch comes ready to run out of the box. The Xbox Teleoperation demo will let you quickly test out the robot capabilities by teleoperating it with an Xbox Controller. 

 ![](./images/xbox.png)

 **Note**: You will find the USB Dongle already plugged into the the USB port of the base trunk.

 To start the demo after unboxing:

 * Remove the 'trunk' cover and power on the robot
 * Wait for about 45 seconds. You will hear the Ubuntu startup sound, followed by two beeps (indicating the demo is running). 
 * Hit the Connect button on the controller. The upper two LEDs of the ring will illuminate.
 * Hit the Home Robot button. Stretch will go through its homing calibration routine. 
  * **Note**: make sure the space around the robot is clear before running the Home function


 You're ready to go! A few things to try:

 * Hit the Stow Robot button. The robot will assume the stow pose.
 * Practice driving the robot around. 
 * Pull the Fast Base trigger while driving. When stowed, it will make Stretch drive faster
 * Manually stop the arm or lift from moving to make it stop upon contact.
 * Try picking up your cellphone from the floor 
 * Try grasping cup from a counter top
 * Try delivering an object to a person

 If you're done, hold down the Shutdown PC button for 2 seconds. This will cause the PC to turn off. You can then power down the robot. Or proceed to the next step...

 Now that you're familiar with the robot, take a minute to watch the [Stretch Powered Best Practices Video](https://youtu.be/iEaapHNfEWA).



 ## Get Plugged In

 Let's get plugged in.

 * Remove the 'trunk' cover and power on the robot if its 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_guide.md) can be found here.

 Stretch is configured to run the XBox Controller demo in the background at startup. To run your own code you'll need kill off this process so that it doesn't contend with your code.

 ```console
 $ pkill -f stretch_xbox*
 ```

 While you're at it, disable this autoboot feature. You can always turn it back on later. 

 Search for 'Startup' from Ubuntu Activities. Uncheck the box for 'hello_robot_xbox_teleop' 



 ![](./images/xbox_off_rs.png)



 Now open up a Terminal. From the command line, first verify that that all of the hardware is present and happy

 ```console
 $ stretch_robot_system_check.py
 ```

 You may see a few joints reported in red because they haven't yet been calibrated. If so, home the robot

 ```console
 $ stretch_robot_home.py
 ```

 Once the robot has homed, let's write some quick test code:

 ```console
 $ ipython
 Python 2.7.17 (default, Apr 15 2020, 17:20:14)
 ...
 ```

 Now let's move the robot around using the Robot API. Try typing in these interactive commands at the iPython prompt:

 ```python
 import stretch_body.robot
 robot=stretch_body.robot.Robot()
 robot.startup()

 robot.stow()

 robot.arm.move_to(0.25)
 robot.push_command()

 robot.arm.move_to(0.0)
 robot.push_command()

 robot.lift.move_to(0.4)
 robot.push_command()

 robot.pretty_print()

 robot.lift.pretty_print()

 robot.head.pose('tool')
 robot.head.pose('ahead')

 robot.end_of_arm.move_to('wrist_yaw',0)

 robot.end_of_arm.move_to('stretch_gripper',50)
 robot.end_of_arm.move_to('stretch_gripper',-50)

 robot.stow()
 robot.stop()
 ```



 ## Change Credentials

 Finally, we recommend that you change the login credentials for the default user, hello-robot. 

 ```console
 $ sudo passwd hello-robot
 ```

 If you'd like to setup a new user account, check out the [Stretch Installation Guide](https://github.com/hello-robot/stretch_install/blob/master/README.md). In a lab setting, it's useful for lab members to have their own user accounts to run experiments.

 ## Power Down

 The recommended power down procedure is

 1. Place a clamp on the mast below the shoulder to prevent 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://github.com/hello-robot/stretch_ros/tree/master/stretch_demos).

 That's it. Happy coding!

 ------
 <div align="center"> All materials are Copyright 2020 by Hello Robot Inc. The Stretch RE1 robot has patents pending</div>
--- a/docs/getting_started/troubleshooting_guide.md
+++ b/docs/getting_started/troubleshooting_guide.md
@ -0,0 +1,58 @@
 # Stretch RE1: Troubleshooting Guide

 This guide covers common issues and ways to resolve them. Please check the [Hello Robot Forum](https://forum.hello-robot.com) for additional topics not covered here.

 ## XBox teleoperation is not working 

 The provided Easy SMX wireless controller can accidentally be placed in the wrong mode. The mode is indicated by the round illuminated ring (shown as Connect below). The top 2 LEDs only should be illuminated. If a different LED pattern is shown then the button mapping expected by [stretch_xbox_controller_teleop.py](https://github.com/hello-robot/stretch_body/blob/master/tools/bin/stretch_xbox_controller_teleop.py0) will be incorrect.

 To set the controller into the correct mode:

 - Hold the center button down for 5s. It will switch modes. Release.
 - Repeat until top half of ring (upper two lights) are 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

 Please review the troubleshooting section of the [Battery Maintenance Guide](./battery_maintenance_guide.md).

 ## RPC Transport Errors (Stretch doesn't respond to commands)

 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 [Robot](https://github.com/hello-robot/stretch_body/blob/master/body/stretch_body/robot.py)  manages communications with the robot hardware and it doesn't support multiple writes to the USB devices.

 These errors can appear as

 ```
 Transport RX Error on RPC_ACK_SEND_BLOCK_MORE False 0 102
 ---- Debug Exception
 --------------- New RPC -------------------------
 Framer sent RPC_START_NEW_RPC
 ...
 ```

 or as

 ```
 IOError(None): None
 ...
 ```

 To check if a 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.

 ```console
 $ 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)

 ------
 <div align="center"> All materials are Copyright 2020 by Hello Robot Inc. The Stretch RE1 robot has patents pending</div>
--- a/docs/getting_started/untethered_operation.md
+++ b/docs/getting_started/untethered_operation.md
@ -0,0 +1,143 @@

 # Untethered Operation

 As a mobile manipulator, the Stretch RE1 can only go so far when tethered to the monitor, keyboard, and mouse setup. This guide will explain three methods of setting up the Stretch RE1 for untethered usage.

 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 the Stretch RE1 is tethered to the monitor, keyboard, and mouse setup, first verify that the robot is connected to the wireless network then install Vino VNC server using the following command:

 ```console
 $ 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.

 ```console
 $ 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 is 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 an 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 is often slow. In this method, we will use SSH and X Server to accomplish the same a bit faster. SSH stands for Secure Shell, enabling one to remotely use the terminal (shell) of another machine. X Server is used on many Unix variants to render the Windowed GUI of applications. With SSH and X Server, it is possible to render a Windowed GUI of an application running on the robot on your computer's screen.

 The first step is to identify the robot's IP address on the local network. While the Stretch RE1 is tethered to the monitor, keyboard, and mouse, verify that the robot is connected to a wireless network. Then, open a terminal and run `ifconfig`, which will print out the network information of the machine. In the wireless section (typically named wlp2s0), look for something that looks like "inet 10.0.0.15". The four numbers represent the IP address of the robot on the local network. Using any other machine on the same local network, I can SSH into the robot using this IP address. Take note of the username and password of the robot. The default combo is printed on papers that came in the tools box alongside the robot.

 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.

 ```console
 $ ssh -X username@ip-address
 ```

 Now that you're SSH-ed into the robot, you can disconnect any wires from the robot. You can accomplish any of the same tasks through the terminal. For example, you can type in `ipython` and interact with the robot using Stretch Body, as explained in the [Getting Started Guide](quick_start_guide.md#start-coding).

 Furthermore, Windowed GUI applications that would have displayed on the monitor will now display on your SSH-ed machine. For example, we can open Rviz to visualize what the robot is seeing. Open two terminals and SSH into the robot as explained above. In the first, run `roslaunch stretch_core stretch_driver.launch`. You should see some information print out in the terminal. In the second, run `rviz`. A window will pop up and information about the robot can be visualized by clicking on `Add -> RobotModel` and `Add -> By Topic -> /Scan`. Additional information on how to use ROS tools can be found in [ROS's tutorials](http://wiki.ros.org/ROS/Tutorials) or in our [Stretch ROS guides](README.md#ros-interface).

 #### 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:
 ```console
 $ scp ./filename username@ip-address:~/path/to/put/it/
 ```

 To copy the files from the robot to your computer, run the reverse:
 ```console
 $ 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 the Stretch RE1 and you already have ROS installed on your Ubuntu computer, then there is an easier way of using Rviz than the method described in [SSH & X Server](#ssh-x-server). In the ROS world, this concept is known as "remote master".

 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:

 ```console
 $ 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:

 ```console
 $ 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 setup 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. In the 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 in 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 a number of way to improve 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 address 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:

 ```console
 $ ssh-keygen -t ed25519 -f <key_filepath_without_extension> -C "<some comment>"
 ```

 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:

 ```console
 $ ssh-copy-id -i <key_filepath_without_extension> username@ip-address
 ```

 This requires you to know the username and ip-address of the robot. Instructions on how to find this information is found in the [SSH & X Server](#ssh-x-server) section. You may now SSH into the robot as normal, and no prompt for the robot's password will appear.

 ------
 <div align="center"> All materials are Copyright 2020 by Hello Robot Inc. The Stretch RE1 robot has patents pending</div>
--- a/docs/getting_started/updating_software.md
+++ b/docs/getting_started/updating_software.md
@ -0,0 +1,77 @@
 # Updating Stretch Software

 Stretch's software is improved with new features and bug fixes with each update. In this guide, we cover when and how to update the various software components on your Stretch RE1.

 ## When to Update

 We develop our software publicly on Github, allowing anyone to follow/propose the development of a code feature or bug fix. While we wholeheartedly welcome collaboration on Github, it is not necessary to be active on Github to follow our software releases. We announce every major release of software on our [forum](https://forum.hello-robot.com/c/announcements). These are stable releases with code that has been extensively tested on many Stretch RE1s. To be notified of new releases, create an account on the forum and click the bell icon in the top left of the [announcements section](https://forum.hello-robot.com/c/announcements/6). The forum is also available to report issues and ask questions about any of our software packages.

 ## How to Update

 Each Stretch RE1 is shipped with firmware, a Python SDK, and ROS packages developed specifically for Stretch. At the moment, there are three separate processes for updating each of these components.

 ### Stretch ROS

 Stretch ROS is the [Robot Operating System](https://www.ros.org/about-ros/) (ROS) interface to the robot. Many robotics developers find ROS useful to bootstrap their robotics software developments. You may update it using the following commands:

 ```console
 $ roscd stretch_core
 $ git pull
 ```

 ### Stretch Body

 Stretch Body is the Python SDK to the robot. It abstracts away the low level details of communication with the embedded devices and provides an intuitive API to working with the robot. You may update it using the following commands:

 ```console
 $ 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
 ```

 ### 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:

 ```console
 $ RE1_firmware_updater.py --status
 ```

 This script will automatically determine what version is currently running on the robot and provide a recommendation for a next step. Follow the next steps provided by the firmware updater script.

 ### Ubuntu

 The operating system upon which Stretch RE1 is built is called Ubuntu. This operating system provides the underlying packages that power Stretch's software packages. Furthermore, users of Stretch depend on this operating system and the underlying packages to develop software on Stretch. Therefore, it is important to keep the OS and these underlying packages up to date. In the command line, run the following command:

 ```console
 $ 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:

 ```
 ----------------
 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 to each other. There is a protocol mismatch preventing communication between the two. Simply run the following script and follow its recommendations to upgrade/downgrade the firmware as necessary to match the protocol level of Stretch Body.

 ```console
 $ RE1_firmware_updater.py --status
 ```

 ------
 <div align="center"> All materials are Copyright 2020 by Hello Robot Inc. The Stretch RE1 robot has patents pending</div>
--- a/docs/robot_safety_guide.md
+++ b/docs/robot_safety_guide.md
@ -0,0 +1,211 @@
 # Robot Safety Guide

 ![](./images/warning_rs.png)

 The Stretch RE1 is a potentially dangerous machine with safety hazards. **If improperly used it can cause injury or death.** 

 * **All users must carefully read the following safety information prior to 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 RE1 (“Stretch”) is 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 the home 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. It is essential that researchers use Stretch carefully to avoid damage, injury, or death. Here, we list a number of safety hazards that researchers must consider prior to use and during use of 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. Prior to 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 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 50.5lb, 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 wrist and tool have sharp edges that can cause lacerations or punctures to 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 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 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 injury 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 contacts 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 shoulder, indicating potential pinch point between rollers and mast.

 ![](./images/hand_crush_rs.png)





 Top of 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.

 **NOTE: 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:

 <table>
  <tr>
    <td>Action</td>
    <td>Runstop State</td>
    <td>Button Illumination</td>
  </tr>
  <tr>
    <td>Robot startup</td>
    <td>Motion enabled</td>
    <td>Solid</td>
  </tr>
  <tr>
    <td>Tap runstop button</td>
    <td>Motion disabled</td>
    <td>Flashing at 1Hz</td>
  </tr>
  <tr>
    <td>Hold down runstop button for >2s</td>
    <td>Motion enabled</td>
    <td>Solid</td>
  </tr>
 </table>


 ## Safety Hazard Details

 ### Sharp Edges

 Stretch RE1 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 moderate or fast speed and hits a bump, threshold, or other change in floor property.
 *  The arm is raised up high and pushes or pulls on the environment with sufficient force.
 *  The robot drives over a drop-off such as a stair or curb.

 **NOTE: 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)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -0,0 +1,115 @@
 site_name: Stretch Tutorials
 site_url: https://docs.hello-robot.com/stretch_tutorials
 site_description: "Hello Robot Stretch Tutorials"
 copyright: 'Copyright &copy; 2022 Hello Robot Inc'
 site_author: Hello Robot Inc
 use_directory_urls: True
 docs_dir: .
 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:
  - ./docs/extra.css

 markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.inlinehilite
  - pymdownx.keys
  - admonition

 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 <link rel="canonical">; `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:
  - Overview: README.md
  - Getting Started:
      - Quick Start: getting_started/quick_start_guide.md
      - Robot Safety: getting_started/robot_safety_guide.md
      - Best Practices: getting_started/best_practices.md
      - Untethered Operation: getting_started/untethered_operation.md
      - Updating Software: getting_started/updating_software.md
  - Stretch Body:
    - Basics:
      - Commanding Joint Motion: Foo.md
  - ROS1:
    - Basics:
      - Getting Started: getting_started.md
      - Gazebo Basics:  gazebo_basics.md
      - Teleoperating Stretch: teleoperating_stretch.md
      - Internal State of Stretch: internal_state_of_stretch.md
      - RViz Basics: rviz_basics.md
      - Navigation Stack: navigation_stack.md
      - MoveIt! Basics: moveit_basics.md
      - Follow Joint Trajectory Commands: follow_joint_trajectory.md
      - FUNMAP: foo.md
      - Perception: foo.md
      - Microphone Array: foo.md
      - ROS testing: foo.md
      - Other Nav Stack Features: foo.md
    - Other Examples:
      - Teleoperate Stretch with a Node: example_1.md
      - Filter Laser Scans: example_2.md
      - Mobile Base Collision Avoidance: example_3.md
      - Give Stretch a Balloon: example_4.md
      - Print Joint States: example_5.md
      - Store Effort Values: example_6.md
  - ROS2:
    - Nav Stack: foo.md