Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

First version of 18.04 upgrade documentation #60

Merged
merged 6 commits into from
Mar 8, 2019
Merged
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added source/_static/app_store.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added source/_static/fetch_ros_ntwk.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
44 changes: 40 additions & 4 deletions source/computer.rst
Original file line number Diff line number Diff line change
Expand Up @@ -48,12 +48,13 @@ same subnet.
====================== =============
Device IP Address
====================== =============
Computer eth1 10.42.42.1
Laser range finder 10.42.42.10
Mainboard 10.42.42.42
Gripper 10.42.42.43
====================== =============

There are two possible interfaces for connecting to the robot
There are two possible interfaces for external connecting to the robot
computer: the wireless interface and the wired interface. Most users
will prefer to use the wireless interface, however the access panel
also includes a Gigabit Ethernet interface for stationary tasks that
Expand All @@ -64,10 +65,45 @@ require higher bandwidth.
Never drive the robot with an Ethernet cable attached to the access panel.

Connecting the Robot to a Wireless Network
------------------------------------------

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The easiest way to configure the wireless networking is to connect a monitor,
keyboard, and mouse and use the Network Manager interface.
keyboard, and mouse and use Ubuntu's Network Manager interface.

Configuring the Robot to use a Static IP for Access Panel Ethernet
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For 14.04: Edit and uncomment the section for eth0 in ``/etc/network/interfaces``

For 18.04: Edit and uncomment the section for eth0 in ``/etc/netplan/99-fetch``

After making changes, restarting the robot will ensure changes for the ethernet
port take effect.

Troubleshooting ROS Interactions with Robot Across a Network
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
External networking with the robot is typically done to provide
an interface to various ROS capabilities. To ensure a working network setup
between robot and PC, reference the following guide to the ROS_MASTER_URI
and ROS_HOSTNAME environment variables. A key recommendation is to use hostnames
instead of IP addresses for ROS_MASTER_URI and ROS_HOSTNAME. This will minimize
issues with e.g. DHCP not being present or unexpectedly changing network behavior.

.. figure:: _static/fetch_ros_ntwk.png
:width: 100%
:align: center
:figclass: align-centered

Note that the ROS_HOSTNAME is unneeded in the case where the robot and
computer hostnames are addressable on the local network. (E.g. via DNS
or entries in the file ``/etc/hosts``)

A symptom of an incomplete setup may be that some ROS commands work, while others
do not. Commands (such as ``rostopic list``, ``rosservice list``) retrieve
information through the connection they create,
while other commands (``rostopic echo``, many components in ``rviz``) attempt
to tell the robot a location to send info to via future connections.

For a more in-depth general overview of robot-to-PC networking, see also the
`ROS Network Setup Tutorial <http://wiki.ros.org/ROS/NetworkSetup>`_.

Clock Synchronization
---------------------
Expand Down
1 change: 1 addition & 0 deletions source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ Fetch & Freight Manual
robot_hardware
computer
care_and_feeding
indigo_to_melodic

Tutorials
---------
Expand Down
250 changes: 250 additions & 0 deletions source/indigo_to_melodic.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,250 @@
ROS Melodic + Ubuntu 18.04
==========================

Fetch Robotics has recently started supporting ROS Melodic and Ubuntu 18.04 on
Fetch and Freight robots. Other than the process of upgrading a robot, there
should be minimal effect on using your robot. If you observe an issue, please
let us know via a support ticket.

Upgrading Your Robot to ROS Melodic + Ubuntu 18.04
--------------------------------------------------
.. WARNING::
Read this document in full to ensure you understand the procedures. It is
not straightforward to go back to ROS Indigo/Ubuntu 14.04 after doing this.
Ensure your colleagues are on board with doing this upgrade.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't check with my colleagues when I upgraded my Fetch 😆


This document is a procedure for replacing the contents of your robot's SSD
with an Ubuntu 18.04 install and ROS Melodic.

Before Upgrade
++++++++++++++

Back up files from the robot! There are a few categories of files to back up:

#. Calibration and other robot-specific files. By convention, these are
all in ``/etc/ros/[indigo|melodic]/``
#. Files relating to your research work
#. A record of what packages you installed for ROS Indigo
#. Udev rules created for additional hardware (e.g. sensors) added to your robot
#. Network hardware configuration (for troubleshooting)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd suggest adding /opt/ros/indigo which in case anyone is relaying on some specific version of something they've installed they'd at least have a hope of getting something working again... It wouldn't be straightforward, and I wouldn't recommend it... but it might be useful.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll suggest grabbing a record of what's in /opt/ros/indigo. Any suggestion on how to do that or is dpkg -l | grep ros-indigo > installed_indigo_packages.txt good enough?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That, and simply tar the directory...

Because only the latest version is available from the package manager, so if they've installed their own packages in /opt/ros/* or happen to be depending on a very specific version which might not be available they'd have it... but of course it's not easy to get back to the state they were in so that's why I wouldn't recommend it.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I hadn't realized how small the contents of that directory typically are. I'll make that update.

Copy link
Contributor

@moriarty moriarty Feb 15, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeh it's basically just some binarys and header files, nothing too large.

The only thing I would hate to see is if some student who's going to be presenting a thesis soon and is off working on the writing part, then goes back to the lab after the writing is done to show it / grab a video for the defense... and the were depending on whatever version was in there.
They could flash it back to trusty/indigo and un-tar the directory, clone their workspace and no need to worry about upgrading/updating to whatever is now the latest in the indigo or melodic repos


Below, we assume that after logging into the robot (e.g. via `ssh`) you back up
files to a machine named HOST with username USER.

For (1), we recommend doing::

tar -zcf fetch_robot_files.tar.gz /etc/ros/indigo/
scp fetch_robot_files.tar.gz USER@HOST:~/

For (2), this may include workspaces, logs, and training data.

For (3), you can easily record the list of packages you installed via::

dpkg -l | grep ros-indigo > installed_indigo_packages.txt

As well, you might want to record what repositories are part of your workspaces.

For (4), such files are likely located in ``/etc/udev/rules.d/``, and should be saved.

For (5), this file may be useful for reference if the install process doesn't
automatically set up networking on your robot correctly::

scp /etc/udev/rules.d/70-persistent-net.rules USER@HOST:~/$(hostname)_udev_net_rules

If you are using any additional hardware (sensors), be sure to record what network
or other hardware configuration changes were made to get them working.


18.04 Install and Installing ROS/Fetch Packages
+++++++++++++++++++++++++++++++++++++++++++++++

.. IMPORTANT::
Back up your files as described in the previous section

#. **Runstop the robot**, to avoid unexpected movement of the robot.
#. **Install Ubuntu 18.04 on the robot.** Download the latest 18.04 Ubuntu installer from http://releases.ubuntu.com/18.04/
(in these instructions we use the Desktop image, version 18.04.2).
For help booting from USB, see `Accessing Boot Menu on Fetch Robots`_.

#. We recommend keeping the same hostname for the robot, e.g. `fetch4`
#. You can create the `fetch` user, or let it be automatically created later.
(The typical password for the `fetch` user is 'robotics'.)

- After install, you may need to unblock `apt`. Do this by clicking the App Store
icon on the sidebar, which should trigger an update prompt you can close: |AppStore|
- You'll probably want to install a few convenience packages such as openssh-server
to enable SSH into your robot: ``sudo apt install openssh-server net-tools``.
erelson marked this conversation as resolved.
Show resolved Hide resolved
You might also want to install your favorite commandline text editor.

#. **Update your Ubuntu install:** ``sudo apt update && sudo apt dist-upgrade -y``
#. **Install ROS Melodic** by following the instructions `on the ROS Wiki <http://wiki.ros.org/melodic/Installation/Ubuntu>`_.
You will want to do steps 1.1 through 1.6. In writing/testing these instructions, we assume:
- You use the **ROS-Base** setup, via the ``ros-melodic-ros-base`` package.
- You're using bash, so step 1.6 for the fetch user is::

echo "source /opt/ros/melodic/setup.bash" >> ~/.bashrc
source ~/.bashrc

You can also make this apply for all new users: ``sudo su -c 'echo "source /opt/ros/melodic/setup.bash" >> /etc/bash.bashrc'``

#. **NOTE**: at a later time, Fetch may host and recommend its own mirror of ROS Melodic debians.
#. Run the following to **install Fetch research debians**:

- General packages for Fetch robots::

sudo apt install ros-melodic-fetch-calibration ros-melodic-fetch-open-auto-dock \
ros-melodic-fetch-navigation ros-melodic-fetch-tools -y

- Then install packages specific to the robot type::

export ROBOTTYPE=$(hostname | awk -F'[0-9]' '{print $1}')
# sudo apt install $ROBOTTYPE-melodic-config # pending future availability
wget https://packages.fetchrobotics.com/binaries/$ROBOTTYPE-melodic-config.deb
sudo apt install ./$ROBOTTYPE-melodic-config.deb -y

#. **Power cycle the robot**::

sudo /sbin/reboot

.. |AppStore| image:: _static/app_store.jpg

Post-install Validation
+++++++++++++++++++++++
This is a direct continuation of the previous section's procedure. It is assumed
that your robot is still runstopped.

Verify that things are working. All of the following steps assume that you are
``ssh``'d into the robot::

ssh fetch@fetchXXXX

#. Verify that calibration is installed, e.g. a date should be output if you run the command below::

fetch@fetch3:~$ calibrate_robot --date
2018-11-26 14:48:04

#. Verify that the robot can ping the mainboard and the laser::

ping 10.42.42.42 # mainboard
ping 10.42.42.10 # laser

If not, see `Ensuring robot's ethernet ports are configured correctly`_

#. Verify that the Primesense camera is working (if working with a Fetch robot)::

rostopic list head_camera | wc -l

This should output 32, if everything is working fine.

#. At this point, release the robot's runstop button.

#. The gripper should now have power, so we should be able to ping it::

ping 10.42.42.44 # gripper
erelson marked this conversation as resolved.
Show resolved Hide resolved

#. The arm's "gravity compensation" should now be working. You should be able to
freely move the arm by hand.

#. Check whether your PS3 controller pairs and controls the robot.

**Important note**: for 18.04 the robots have switched from using sixad to using
PS3joy. Some changes in behaviour you may see:

- The LEDs on the PS3 controller may continually blink, even though it is connected.
- Inputs may not be sent from the PS3 controller if the accelerometers in the
controller do not detect motion. This can result in jerky motion when using
the controller.

We are hoping to determine fixes for these in the near future.

#. At this point the robot is probably working fine and is ready for use! (Unless you
additional customizations to restore; see next step)
erelson marked this conversation as resolved.
Show resolved Hide resolved

#. If applicable, from your non-robot computer, restore the contents of
``/etc/ros/indigo`` to ``/etc/ros/melodic`` on the robot::

scp fetch_robot_files.tar.gz fetch@fetchXXX:~/
ssh fetch@fetchXXX
sudo mkdir -p /etc/ros/melodic
tar -xzf ~/fetch_robot_files.tar.gz /etc/ros/melodic/

As well, you can restore any other saved files to the robot.

This is the point at which some things may not work fully, e.g. if packages
used in ROS Indigo need updates/replacements for ROS Melodic.


Compatibility of Other Computers Used with the Robot
----------------------------------------------------

For working with a robot running ROS Melodic, we recommend using an 18.04 Ubuntu
machine that also has ROS Melodic installed.

- In order for the robot to appear correctly in RViz, you will want to:

- Ensure your computer is pointed at the packages.ros apt sources
- Install ``ros-melodic-fetch-description`` and ``ros-melodic-freight-description``
packages. Addtionally you might want to install
`ros-melodic-fetch-tools <https://github.com/fetchrobotics/fetch_tools>`_.
- Ensure that these packages are included in your path (e.g.
``rospack find fetch_description`` returns a path)
- Common gotcha on a new setup: If the robot model doesn't appear at first, you
may want to change the "Fixed frame" from e.g. 'map' to 'odom'.

Not Recommended/Supported: Upgrading from 14.04 to 18.04 (via 16.04)
--------------------------------------------------------------------
Fetch Robotics does not recommend this approach and *cannot* provide support for this.
However, if you desire to try to upgrade, the following may be helpful:

- Back up files as described above, or even the full disk if you like.
- You cannot upgrade Ubuntu directly from 14.04 to 18.04. You must first
upgrade to 16.04 first. This can take a long time.
- You should review the postinstall script for ``fetch-melodic-config``. It is not
targeted at upgrading a system, so additional tweaks may be required after
installing it.


Appendices
----------

Disk filling issue
++++++++++++++++++
Some robots may encounter an issue where Gnome3 fills the disk by spamming /var/log/syslog.
This issue has a fix that is not available via `apt` yet, but can be manually done:
https://bugs.launchpad.net/ubuntu/+source/gnome-shell/+bug/1772677/comments/63

Ensuring robot's ethernet ports are configured correctly
++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The robot has two ethernet ports on its computer. You can find more information on this
at `Computer Overview and Configuration <computer.rst>`_.

The most likely problem you may encounter after getting 18.04 installed is if these two
ports are "swapped". This will cause the robot computer to be unable to talk to the
rest of its hardware. You can fix this in software or in hardware:

- Software: Edit ``/etc/udev/rules.d/70-persistent-net.rules`` and swap ``eth0``
and ``eth1``. Restart the robot for the change to take effect.
- OR: Hardware: swap the two ethernet cables where they plug into the computer.
This shouldn't be needed, but in case you do, you should expect to find
a gray cable (internal communications) and a blue cable (external).
Typically, the blue goes to the top ethernet port, and the grey goes to the bottom.

Another issue you may encounter with 18.04 is if you are using the ethernet on the
side access panel with a DHCP setup. In some setups, the ethernet port may fail to
be assigned an IP automatically. We recommend consulting IT for help with this, if
needed.

Accessing Boot Menu on Fetch Robots
+++++++++++++++++++++++++++++++++++
You may need to access the boot menu in order to boot from a USB flash
drive and install Ubuntu 18.04. Due to different computer motherboards used in the
past, Fetch research robots may be using one of two BIOS flavors. Older robots
use an MSI branded BIOS. Newer robots use American Megatrends Inc. (AMI).

These different BIOS types activate the boot media selection menu with different keys:
- If your robot shows the MSI splash screen at boot, press F11 to access the boot menu.
- If your robot shows the black AMI splash screen at boot (this lasts for about 1 second),
press F7 to access the boot menu.

If you fail to get into the boot menu, you can restart the computer and try again.