diff --git a/source/_static/fetch_ros_ntwk.png b/source/_static/fetch_ros_ntwk.png new file mode 100644 index 0000000..4d3393f Binary files /dev/null and b/source/_static/fetch_ros_ntwk.png differ diff --git a/source/computer.rst b/source/computer.rst index 14db926..0406411 100644 --- a/source/computer.rst +++ b/source/computer.rst @@ -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 @@ -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 `_. Clock Synchronization --------------------- diff --git a/source/index.rst b/source/index.rst index ad768df..61eba55 100644 --- a/source/index.rst +++ b/source/index.rst @@ -13,6 +13,7 @@ Fetch & Freight Manual robot_hardware computer care_and_feeding + indigo_to_melodic Tutorials --------- diff --git a/source/indigo_to_melodic.rst b/source/indigo_to_melodic.rst new file mode 100644 index 0000000..652a64e --- /dev/null +++ b/source/indigo_to_melodic.rst @@ -0,0 +1,196 @@ +ROS Melodic + Ubuntu 18.04 +========================== + +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. + +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 +#. Network hardware configuration (for troubleshooting) + +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), this file may be useful for reference:: + + 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. +#. 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.1). Install Ubuntu + 18.04 on the robot. + For help booting from USB, see `Accessing Boot Menu on Fetch Robots`_. +#. Install ROS Melodic by following the instructions `on the ROS Wiki `_. + We start from the ROS-Base setup, via the ``ros-melodic-ros-base`` package. +#. **NOTE**: at a later time, Fetch will host and recommend a 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 + + - 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 dpkg -i $ROBOTTYPE-melodic-config.deb + +#. 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/ + +#. Power cycle the robot:: + + sudo /sbin/reboot + + +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, unrunstop the robot. + +#. The gripper should now have power, so we should be able to ping it:: + + ping 10.42.42.44 # gripper + +#. 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. + +#. At this point the robot is probably working fine and is ready for use! + +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 `_. + - Ensure that these packages are included in your path (e.g. + ``rospack find fetch_description`` returns a path) + +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 +---------- + +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 `_. + +The most likely problem you may encounter after getting 18.04 installed is if these two +ports are "swapped". 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 (less + optimal solution). + + +Changes from +Manually creates udev rules and updates grub boot arguments to ensure +consistent network device naming across different hardware. Uses +netplan to set static IP for internal robot communications. + + +Accessing Boot Menu on Fetch Robots ++++++++++++++++++++++++++++++++++++ +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). + +- 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.