> For the complete documentation index, see [llms.txt](https://docs.hello-robot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello-robot.com/stretch4_install/docs/robot_install.md). # 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. ## How There are a few steps to performing a new robot install: 1. Plug in charger 2. Backup robot calibration data 3. Setup the BIOS (only necessary for NUCs not previously configured by Hello Robot) 4. Install Ubuntu 5. Run the new robot installation script 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. * 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. ``` ### 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: 1. Boot into the robot's original Ubuntu partition and plug in a USB key. 2. The robot calibration data lives inside of a directory called `stretch--`, where `` is your robot model number ("re1" for a Stretch RE1, "re2" for a Stretch 2, "se3" for a Stretch 3, or "se4" for a Stretch 4), and `` 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--`. 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--`, 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--` for the next step. 3. Copy the `stretch--` 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-- /media/$USER/` from the command line, where `` and `` 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--` 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](/stretch4_install/docs/configure_bios.md). ### Install Ubuntu Choose between the following guides based on which version of Ubuntu you're installing. 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. * [Ubuntu 24.04 Installation guide](/stretch4_install/docs/install_ubuntu_24.04.md) 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: ```bash sudo apt update sudo apt install git zip network-manager ``` !!! 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: 1. Plug in the USB key that contains the backed up calibration data. 2. Copy the `stretch--` 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//stretch-- /home/$USER/` from the command line, where `` and `` 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 [Stretch4 Install](https://github.com/hello-robot/stretch4_install) repository and begin the installation process. While Stretch 4 development is happening in private, you'll need the `credential.helper` command below which uses an Hello Robot-private access token to clone our private repos: ```bash git clone https://github.com/hello-robot/stretch4_install ~/stretch4_install cd ~/stretch4_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](#troubleshooting) section below for solutions to common issues, or contact Hello Robot support via email or [the forum](https://forum.hello-robot.com/). Your robot is now set up with a new operating system! If you're new to Stretch, consider going through the [Getting Started](https://github.com/hello-robot/stretch4_install/blob/main/getting_started/hello_robot/README.md) 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](https://forum.hello-robot.com/). ### 'Expecting var HELLO\_FLEET\_ID to be undefined' error If you are seeing the following error: ``` [...] Checking ~/.bashrc doesn't already define HELLO_FLEET_ID... Expecting var HELLO_FLEET_ID to be undefined. Check end of ~/.bashrc file, delete all lines in 'STRETCH BASHRC SETUP' section, and open a new terminal. Exiting. ############################################# FAILURE. INSTALLATION DID NOT COMPLETE. [...] ``` You are performing a new robot install on a robot that has already gone through the robot install process. If this is intentional, you will need to manually delete lines that a previous robot install appended to the `~/.bashrc` dotfile. Open the `~/.bashrc` file in an editor and look near the end for a section that looks like: ``` ###################### # STRETCH BASHRC SETUP ###################### export HELLO_FLEET_PATH=/home/ubuntu/stretch_user export HELLO_FLEET_ID=stretch-re1-1000 export PATH=${PATH}:~/.local/bin export LRS_LOG_LEVEL=None #Debug source /opt/ros/noetic/setup.bash source /home/ubuntu/catkin_ws/devel/setup.bash [...] ``` Delete this section from the `~/.bashrc`. Note that it's common for other programs (e.g. Conda, Ruby) to append to your `~/.bashrc` as well, and deleting those lines accidentally can impede their functionality. Take care to only delete lines related to 'STRETCH BASHRC SETUP' section. Next, open a new terminal. Every new bash shell (i.e. the terminal you open when searching for 'Terminal' in system applications) automatically runs the commands in the `~/.bashrc` dotfile when opened, so the new terminal won't be set up with the lines that were just deleted. Now you can run a new robot install and this error should gone. ### 'Expecting stretch-yyy-xxxx to be present in the home folder' error If you are seeing the following error: ``` [...] Checking robot calibration data in home folder... Expecting robot calibration stretch-yyy-xxxx to be present in the the home folder. Exiting. ############################################# FAILURE. INSTALLATION DID NOT COMPLETE. [...] ``` The install scripts exited before performing the robot install because it was unable to find the robot's calibration data folder, 'stretch-yyy-xxxx'. Please ensure you have [backed up your robot's calibration data](#back-up-robot-calibration-data) to a USB key and copied the 'stretch-yyy-xxxx' folder to the home folder of your new partition. See the [Run the robot installation script](#run-the-robot-installation-script) section for more details. Then, run the install scripts again and the error should be gone. ### 'Repo not up-to-date' error If you are seeing the following error: ``` [...] Checking install repo is up-to-date... Repo not up-to-date. Please perform a 'git pull'. Exiting. ############################################# FAILURE. INSTALLATION DID NOT COMPLETE. [...] ``` The version of Stretch Install being used is out of date. In a terminal, go to the Stretch Install folder (should be in the home folder: `cd ~/stretch4_install`), and perform a `git pull` to pull down the latest version. If the git pull fails, ensure Stretch Install has a clean working tree using `git status`. If you see any red files, save them if important, delete Stretch Install, and reclone it. ### 'Failed to fetch' error If you are seeing the following error: ``` Install E: Failed to fetch Connection failed [IP: ] E: Unable to fetch some archives, maybe run apt-get update or try with --fix-missing? ############################################# FAILURE. INSTALLATION DID NOT COMPLETE. [...] ``` Ubuntu's system package manager, Apt, has failed to contact the server that hosts some package that the install scripts need to download. Typically, these issues are transient and waiting some time before rerunning the install script will solve the issue. ### 'dpkg returned an error code' error If you are seeing the following error: ``` Install E: Sub-process /usr/bin/dpkg returned an error code (1) ############################################# FAILURE. INSTALLATION DID NOT COMPLETE. [...] ``` Ubuntu's system package manager, Apt, has failed to complete some step of the install process for a package that the install scripts need to install. Typically, these issues are transient and waiting some time before rerunning the install script will solve the issue. If you continue to see this error, contact Hello Robot support via email or [the forum](https://forum.hello-robot.com/). ### 'Firmware protocol mismatch' error If you are seeing the following error: ``` ---------------- Firmware protocol mismatch on hello-. Protocol on board is p. Valid protocol is: p. Disabling device. Please upgrade the firmware and/or version of Stretch Body. ---------------- ``` Contact Hello Robot Support. *** All materials are Copyright 2020-2026 by Hello Robot Inc. Hello Robot and Stretch are registered trademarks. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hello-robot.com/stretch4_install/docs/robot_install.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.