Performing a Robot Installation

Why

A fresh robot-level install should only be done under the guidance of Hello Robot Support. This guide will lead you through a robot-level install, which can be used to:

Erase the previous OS and set up Stretch with an entirely fresh software stack
Erase a corrupted OS and set up Stretch with an entirely fresh software stack
Upgrade Stretch by installing the 20.04 software stack alongside the previous OS

Each OS installs on a separate partition on the hard drive. You can create as many robot-level installs (i.e. new partitions) as will fit in your robot's 500GB hard drive.

Currently, there are two available versions of the software stack, one with Ubuntu 18.04 LTS and another with Ubuntu 20.04 LTS. Ubuntu 18.04 LTS shipped on robots until summer 2022, and included software for ROS Melodic and Python2. Ubuntu 20.04 LTS, the newest software stack, comes with ROS Noetic, Python3, and experimental ROS2 Galactic software. You can look at your robot's About page in system settings to identify which OS it is running.

How

There are a few steps to performing a new robot install:

Backup robot configuration data
Setup the BIOS (only necessary for NUCs not previously configured by Hello Robot)
Install Ubuntu 18.04 or 20.04
Run the new robot installation script

It typically takes ~2 hours to go through these steps and complete a new robot install.

Back up robot configuration data

It is a good idea to backup all valuable data beforehand. If your new robot install will replace a previous one, data from the previous robot install will be deleted. Even if your new robot install will live alongside the previous one(s), data from the previous robot install(s) can be lost.

In particular, your new robot install will require the old install's robot calibration data. The steps to copy this material from an existing install is:

Boot into the robot's original Ubuntu partition and plug in a USB key.
The robot calibration data lives inside of a directory called stretch-re<y>-<xxxx>, where <y> is your robot model number (1 or 2), and <xxxx> is your robot's serial number. There's a few versions of this directory and you will need to decide which version to backup. Each Ubuntu user has a version of this directory located at /home/$USER/stretch_user/stretch-re<y>-<xxxx>. These user versions are updated when the user runs a URDF calibration, swaps out an end effector, updates Stretch parameters, and more. There's also a system version located at /etc/hello-robot/stretch-re<y>-<xxxx>, which is likely the oldest version since it was created at Hello Robot HQ. If you're not sure which version to backup, use the version at /etc/hello-robot/stretch-re<y>-<xxxx> for the next step.
Copy the stretch-re<y>-<xxxx> directory, where <xxxx> is your robot's serial number, to a USB key.
- For example, if you're copying the system version, you can run a command similar to cp -r /etc/hello-robot/stretch-re<y>-<xxxx> /media/$USER/<USBKEY> from the command line, where <USBKEY> and <xxxx> is replaced with the mounted USB key's name and the robot's serial number, respectively.
- Or, you can open the file explorer to copy the directory.

If your previous partition is corrupted or inaccessible, contact Hello Robot support and they will be able to supply an older version of the stretch-re<y>-<xxxx> directory.

Setup the BIOS

This step can be skipped if your robot had an existing software install on it. Otherwise, follow the guide to set up the BIOS.

Install Ubuntu

Choose between the following guides based on whether you're installing Ubuntu 18.04 or Ubuntu 20.04 (see above for info on what software ships with each OS). Within these guides, you'll have the choice of whether to replace the previous OS partition or to install alongside it. If you choose to install alongside it, you'll also be able to choose the size of each partition on the hard drive.

After the Ubuntu install, the default hello-robot user account will be set up.

Run the new robot installation script

Login to the hello-robot user account on your new Ubuntu partition, open a terminal, and run:

sudo apt update
sudo apt install git zip

Note: The system may not be able to run 'apt' immediately after a reboot as the OS may be running automatic updates in the background. Typically, waiting 10-20 minutes will allow you to use 'apt' again.

Next, place the robot's calibration data in the home folder using the following steps:

Plug in the USB key that contains the backed up calibration data.
Copy the stretch-re<y>-<xxxx> directory, where <xxxx> is your robot's serial number, from the USB key into the home folder (i.e. /home/$USER/).
- For example, you can run a command similar to cp -r /media/$USER/<USBKEY>/stretch-re<y>-<xxxx> /home/$USER/ from the command line, where <USBKEY> and <xxxx> are replaced with your USB key's name and your robot's serial number, respectively.
- Or, you can open the file explorer to copy the directory.

Next, pull down the Stretch Install repository and being the installation process:

cd ~/
git clone https://github.com/hello-robot/stretch_install
cd stretch_install
git pull
./stretch_new_robot_install.sh

Once the script has started, it will ask you for your robot's serial number, Y/N confirmation, and the password. Then, the script will typically take 20-30 minutes to complete on a wired connection. Once it finishes, it should print out something similar to:

#############################################
DONE! COMPLETE THESE POST INSTALL STEPS:
 1. Perform a FULL reboot by power cycling the robot
[...]
#############################################

If it has not printed out 'DONE', then the robot install did not complete successfully. Take a look at the troubleshooting section below for solutions to common issues, or contact Hello Robot support via email or the forum.

Post install steps

Next, we'll complete the post install steps. First, in order for the many changes to take effect, the robot will need a full reboot. The steps are:

Ensure there's a clamp under the lift
Shutdown the Ubuntu OS through the GUI or use sudo shutdown -h now in the terminal
Turn the power switch in the robot's trunk to the off position (orange power LED becomes unlit)
Ensure a keyboard/monitor is plugged into the robot. When the robot powers up, you can use the keyboard to decide which OS to boot into.
Turn the power switch in the robot's trunk to the on position (orange power LED becomes lit)
Boot into the new Ubuntu partition and log in if necessary

Next, we'll ensure the robot's parameter YAML files are migrated to the new parameter management system (see https://forum.hello-robot.com/t/425/ for details).

RE1_migrate_params.py

Next, we'll ensure the robot's contact parameters are migrated to the new contact threshold system (see https://forum.hello-robot.com/t/476/ for details).

RE1_migrate_contacts.py

Next, we'll ensure the robot's firmware is upgraded to the latest available. Newer firmware unlocks new features (e.g. waypoint trajectory following, which is used in ROS2 to support MoveIt2) and fixes bugs. See the firmware releases for details.

REx_firmware_updater.py --install

Next, if your robot has the Stretch Dex Wrist, we'll configure the software to recognize it. Skip this step if you are not using the Dex Wrist.

cd ~/stretch_install
./stretch_new_dex_wrist_install.sh
REx_calibrate_guarded_contact.py --arm

Finally, execute the following to confirm the new robot install was set up successfully.

stretch_robot_system_check.py

Your robot is now configured with a new robot install! In order to set up new users on this robot install, see the Adding a New User guide.

Troubleshooting

This section provides suggestions for common errors that occur during installation. If you become stuck and don't find an answer here, please email us or contact us through the forum.