View source for Software Update - v1.2.0

<noinclude>{{Template:Parent header|parent=Software Update}}</noinclude>

This document provides instructions on updating the software on your Baxter Research Robot to 'rsdk_1.2.0'. All updates and downgrades starting from RSDK 1.1.0 now require the <code>rethink-updater</code> tool installed on the robot itself. This process is therefore run over SSH with the <code>ruser</code> login. 

A list of release changes can be found [[Release Changes|here]].

=== Prerequisites ===
You will need:
* A Baxter Research Robot running SDK v1.1.0 or SDK v1.1.1
* USB drive (FAT32 formatted, at least 1GB)
* Update Files from the [[Rethink FTP]]
* Workstation with SSH installed

'''Note:''' These instructions are for updating ''from 1.1.0 or 1.1.1'' to 1.2.0.  If updating from version 1.0.0, you should follow the instructions at: [[Software Update - v1.1.0]].

=== Backup "ruser" home directory ===  
Users are instructed to make a complete copy of the data in the '''ruser's''' home directory onboard the robot to an external machine prior to upgrading from 1.1.x to 1.2.0.  This is due to an update in this release which allows us Rethink to factory reset the robots during service.

== Instructions ==
=== I. Download Update Files ===
# '''Download''' the Update files from the Rethink FTP Service - [[Rethink_FTP]].
#: Your organization's Point-Of-Contact (POC) will receive an email notice, granting access to the new Update folder, and allowing them to create credentials upon first login.  ''[[Software Update - v1.1.1#ftp-access|More Info]]''
#:'''Note:''' If you do not have access to the Rethink FTP, simply send a request to the '''[mailto:RSDK.Support@rethinkrobotics.com rsdk.support@rethinkrobotics.com]''' email with your contact information, and we will gladly provide access.
#* From the 'Baxter Research Robot 1.2.0 Software' folder:  
#*:    Download the compressed gzip file: <code>rethink-update-rsdk_1.2.0.tar.gz</code>
#:
# '''Unzip''' the Update Files
#: <source lang="bash">
    $ mkdir updates
    $ tar xvfz rethink-update-rsdk_1.2.0.tar.gz -C updates/
    $ cd updates
</source>
#:
# '''Copy''' the update files onto a USB flash drive
#* You may use a normal File Browser or any other method to '''copy all the files onto a USB drive'''.
#* Make sure the USB flash drive is formatted as a FAT32 partition.
#* The files should all be placed in the top-level directory of the USB drive (i.e. not in a sub-folder).
#: <source lang="bash">
    #on the USB drive
    $ ls 
    rethink-rsdk-1.2.0-update.obf
    rethink-rsdk-1.2.0-update.gpg
</source>
# Safely eject the flash drive.

=== II. Robot Software Version Check ===
# Turn on Baxter.
# Start an [[RSDK Shell]] on your development workstation.
#: Make sure you have edited the [[baxter.sh]] script file for your ROS_IP or ROS_HOSTNAME.
#: <source lang="bash">
    $ cd ~/ros_ws
    $ ./baxter.sh
</source>
# Check the Software Version
#: You can check the [[Software Version]] of your robot using the following command:
#: <source lang="bash">
    $ rosparam get /rethink/software_version
    1.1.1.171
</source>
#* ''Note, you can update to v1.2.0 from either v1.1.0 or v1.1.1''

=== III. Run the Updater over SSH ===
Starting from RSDK 1.1.0 all upgrade/downgrade procedures happen over a terminal running <code>SSH</code> as <code>ruser</code>.
#  Allow robot to fully boot.
#  Attach any '''Rethink Electric Grippers''' to the robot's arms.
#: ''Attaching grippers during the update will enable the automatic update of the Gripper Firmware. Otherwise, you will have to do it by hand.''
#  Plug the USB drive into the '''USB port on Baxter's torso'''.
#  '''Wait''' ~30 seconds for the system to recognize and verify the drive.
#  <code>SSH</code> into your robot as <code>ruser</code>
#:   <source lang="bash">
    $ ssh ruser@<your_robots_hostname_or_ip>
   </source>
#  ''(Over <code>SSH</code>)'' Find the version string for the update Update Primer (Version <code>1.2.0.57</code> here) using the [[Software Update|Software Update Tool]]:
# Use the <code>--list</code> argument to the <code>rethink-updater</code> tool to list the available updates Baxter found on the USB drive.
#: <source lang="bash">
    ruser@<your_robots_hostname_or_ip> ~ $ rethink-updater --list
    Version                       
    1.2.0.57                   
</source>
# Now, to start the actual update process, run the <code>rethink-updater</code> tool again, this time using the <code>--update</code> argument followed by the '''''Version''''' found in the last step for Version <code>1.2.0.57</code>.
#: <source lang="bash">
    ruser@<your_robots_hostname_or_ip> ~ $ rethink-updater --update 1.2.0.57
</source>
#: Verify that you have plugged in Baxter's electric grippers, and hit the <code>Enter</code> key when prompted.
# This starts the verification and unpacking of the update payload.  The status will be printed out as it goes through the required steps, ending in a notification that the robot system will reboot to finish updating.  
#* '''NOTE: During this step, a bunch of text will scroll through on Baxter's screen.'''  This is a good thing and shows that the update is progressing.  
#* Once finished, Baxter reboots to the new software and finalizes the update. 
# Back on your workstation in a <code>baxter.sh</code> sourced terminal, confirm the New Software Version by running:
#:   <source lang="bash">
    [baxter- http://hostname_or_ip:11311] ~ $ rosparam get /rethink/software_version
    1.2.0.57
   </source>
# You should see <code>1.2.0.57</code> reported back.  Congratulations, you have updated your Baxter!

=== IV.  Updating the SDK on the Workstation (git repo) ===
Along with updating the software on the robot to version rsdk_1.2.0, you will want to update your Workstation-side SDK software from the git repository to the corresponding v1.2.0.

To do this, follow the [[Workstation Update|Workstation Update Instructions]].  If this is not the latest version you should use the Instructions for [[Workstation Update#Updating to a Specifc Version|Updating to a Specific Version]] using tag <code>v1.2.0</code>.

*; [[Workstation Update|Workstation Update Instructions]]

== FTP Access ==
Use the login credentials provided to your organization's Point-Of-Contact (POC). Updates to the Robot Software are distributed via the Rethink FTP Service - [http://hostedftp.com Hosted~FTP~].  Your organization's Point-Of-Contact (POC) will receive an email, notifying them of the new update folder, and allowing them to sign-in using their email address. ''Note: When a new release occurs, POC's will be granted access to the Hosted~FTP~ via their email address.  Credentials are created upon first time sign-in.''

== Troubleshooting ==
For common issues specific to using software update with Baxter, check out the [[Software Update - Troubleshooting|Troubleshooting page]].

===== Problems after Reboot =====
Rebooting after an update can take a few minutes while the controller boards are flashed with new firmware.  If you have any problems after reboot - such as the 'Halo' light on Baxter's head flashing Red, or the robot not fully booting with the Green light, even after a significant wait (~10 minutes) - you should try a hard power-cycle:
* Hit the Power Button on Baxter's side to perform a full power-off shutdown of Baxter.
* Once all the lights and fans are off and Baxter is completely shutdown, hit the Power Button again to turn Baxter back on.