Upgrading your Operating System¶

Why¶

This guide will lead you through installing a new robot distribution, which can be used to:

Upgrade Stretch by installing a newer software stack alongside the previous OS
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

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 hard drive.

The list of supported/deprecated distributions is available in the Distributions & Roadmap guide.

How¶

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

Plug in charger & Attach clip-clamp
Backup robot calibration data
Setup the BIOS (only necessary for NUCs not previously configured by Hello Robot)
Install Ubuntu
Run the new robot installation script
Post installation steps

It typically takes ~2 hours to go through these steps. Before we get started, you'll need:

1 Stretch robot
Keyboard, Mouse, and Monitor
- Bluetooth keyboards/mouses will not work because they are not recognized by the BIOS. Use a wired USB or wireless USB dongle keyboard/mouse.
- Use a computer monitor instead of a TV. Some TVs have trouble displaying Ubuntu when rebooting.
2 USB sticks
- The first flashdrive is used to backup robot calibration data and any other important files
- The second flashdrive will contain the Ubuntu installer image. This flashdrive will need to be >8gb in capacity.
1 NOCO Genius 10 charger
1 Clip Clamp
A fast connection to the internet

Note

It's recommended that you use an Ethernet connection to the internet. You can use a slow Wifi connection if it's difficult to obtain a wired connection at your institution, but expect the install process to take longer because the scripts are downloading gigabytes of software/data to the robot.

Plug in charger & Attach clip-clamp¶

Since a new robot install can take a few hours, it's important the robot remain on the charger throughout the install. Switch the charger into SUPPLY mode and plug the charger into the robot.

Next, attach the clip-clamp below the shoulder as shown. This allows the arm to rest on the clamp during the firmware portion of the install.

Back up robot calibration 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-<yyy>-<xxxx>, where <yyy> is your robot model number ("re1" for a Stretch RE1, "re2" for a Stretch 2, or "se3" for a Stretch 3), 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-<yyy>-<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-<yyy>-<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-<yyy>-<xxxx> for the next step.
Copy the stretch-<yyy>-<xxxx> directory 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-<yyy>-<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-<yyy>-<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 which version of Ubuntu you're installing (see the Distributions & Roadmap guide 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 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-<yyy>-<xxxx> directory 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-<yyy>-<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, use git to pull down the Stretch Install repository and begin 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! INSTALLATION COMPLETED SUCCESSFULLY.
[...]
#############################################

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 off the power switch in the robot's trunk
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 on the power switch in the robot's trunk
Boot into the new Ubuntu partition and log in if necessary

Next, we'll ensure the robot's firmware is upgraded to the latest available.

REx_firmware_updater.py --install

Next, we'll configure the software for the tool attached to your robot.

stretch_configure_tool.py

Next, we'll run Stretch's homing procedure, where every joint's zero is found. This is a ~30 second procedure that must occur everytime the robot wakes up.

stretch_robot_home.py

Next, we'll calibrate the contact thresholds for the robot's arm joint.

REx_calibrate_guarded_contact.py --arm

Next, we'll remove the clip-clamp and calibrate the contact thresholds for the robot's lift joint.

REx_calibrate_guarded_contact.py --lift

Next, we'll run the system check to confirm the robot is ready to use. If you see any failures or errors, contact Hello Robot support via email or the forum.

stretch_system_check.py

Finally, this step is optional. The robot can be configured to automatically run the gamepad teleop program when it boots up. To do this, open Startup Applications and enable the "hello_robot_gamepad_teleop" program.

Your robot is now set up with a new operating system! If you're new to Stretch, consider going through the Getting Started tutorials.

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.