Cognitive Robotics - Software Installation Guide

The guide is under development ... Do not use it yet.

This page provides a step-by-step guide to installing the tools, utilities, and example software for Cognitive Robotics using Ubuntu 18.04, ROS Melodic, and the CRAM cognitive architecture.

Please follow these instructions exactly as they are stated. Do not be tempted to skip through them, assuming that you will be able to figure it out yourself. You might, but it is more likely you will miss something small but important and it won't work as required. Take your time, follow these instructions carefully, and everything will work.

There are two options:

• Option A: install the VirtualBox Ubuntu 18.04 virtual machine (VM) with everything pre-installed.
• Option B: install all the required tools and utilities directly on a computer running Ubuntu 18.04.

We cover both in the following, starting with Option A.

Option A: Install the VirtualBox Ubuntu 18.04 Virtual Machine

Install VirtualBox

There follows instructions for Windows, Mac OS, and Ubuntu (in case you already have Ubuntu but want to use the VM instead of installing all the required tools and utilities).

Windows

Open the VirtualBox Download page at https://www.virtualbox.org/wiki/Downloads and select Windows hosts to download the installation file.

Double click on the downloaded file (VirtualBox-7.0.12-159484-Win.exe at time of writing) and follow the instructions.

MacOS

Download the .dmg installer for OS X systems, execute the file and follow the instructions.

If the VirtualBox installer fails as it is completing the installation, it is probably a problem with a security setting. Go to System Preferences > Security & Privacy. Click the lock to make changes (if necessary). Click the Allow button at the bottom and re-run the installer.

Ubuntu Linux

You can install VirtualBox via the Ubuntu Software Center or through command line as follows.

 sudo apt update
 sudo apt install virtualbox

Install the VirtualBox Extension Pack

Select All supported platforms to download the VirtualBox Extension Pack. This is needed to provide access to USB devices such as the Lynxmotion AL5D robot manipulator, iRobot Create 2 mobile robot, and webcams.

Double click on the downloaded file (Oracle_VM_VirtualBox_Extension_Pack-7.0.12.vbox-extpack at time of writing) and follow the instructions.

VirtualBox Setup

Step 1: Copy the Virtual Disk Image

The virtual disk image cram-vm.vdi contains a VirtualBox virtual machine with Ubuntu 18.04, ROS Melodic, and example code pre-installed. It will be distributed it on a physical disk. Copy it to some convenient, easily-identified folder.

Step 2: Launch VirtualBox

In VirtualBox, you first need to create a new virtual machine. Click on the New button.

If a window with the guided menu open, change to expert mode,

Step 3: Configure and create the virtual machine

In the expert menu:

• Set the name to rpp-vm
• Select Linux for the operating system type
• Select Ubuntu (64-bit) for the operating system version
• Set the VM's memory size (RAM); choose 4096 MB or more if your PC's capacity allows; we set it to 8192 MB in the screenshot
• Select Use an existing virtual hard disk file

Using the button on the right, open the file explorer, click Add, browse to where you stored rpp-vm.vdi, and select the virtual disk image.

File:VirtualBox Add Disk Image.png

Finally, click Create.

Step 4: Configure the settings

Choose the newly created virtual machine and click on Settings.

Click on System and Processor and choose how many processor cores you want to allocate to the VM. Here, we have allocated four cores.

Step 5: Enable USB devices Choose the newly created VM and click on Ports. Click on USB and select USB 2.0. Choose the device you want to add from the list by clicking the connector icon with the green cross at the right hand side. Notice that none of the devices you want to add are in the list.

This is because the device needs to be connected before it can be added. Here is what you would see if the iRobot Create 2 mobile robot was connected. You can skip this part for now, but remember to do it when you want to use any USB device later in the course.

The device for the Lynxmotion AL5D robot manipulator is FTDI FT232R USB UART [0600].

The device for the iRobot Create 2 mobile robot is FTDI FT231X USB UART [1000].

Note: if your host operating system is Ubuntu, you should also enter the following in a terminal of your host machine and then restart the cram-vm virtual machine:

 $ sudo adduser $USER vboxsf  

Step 6: Enable Host OS to Guest OS Copy and Paste

When doing exercises and assignments, you may wish to copy text from the host OS (Windows 10, probably) to the guest OS (Ubuntu 18.04). To do this, we need to enable Shared Clipboard and Drag’n’Drop functionality between Guest and Host Machine.

However, before you do that, you need to install Guest Additions in the virtual machine. So, if you haven't already done so, go ahead and start the virtual machine and log in. The password is cram.

Select Devices from the menu and select the Insert Guest Additions CD Image option. Click Run when prompted and follow the instructions. If you are asked for the password, it is cram. Press return when asked.

Now, power off your Ubuntu guest OS.

Choose the rpp-vm virtual machine and click on Settings.

Click on General and Advanced and select Shared Clipboard and choose the Bidirectional option.

File:Install-Virtualbox-Guest-Additions 2.png

When you restart the virtual machine, double check that the copy and paste, and the drag and drop functionalities are enabled.

Click on Devices and Shared Clipboard and choose the Bidirectional option.

Now, click on Devices and Drag and Drop and choose the Bidirectional option.

Everything is set up and the virtual machine can now be started. When Ubuntu 18.04 boots, enter the password cram, if asked.

Option B: Install Required Tools and Utilities on a Computer running Ubuntu 18.04

Install Ubuntu 18.04

If you don't already have it, install Ubuntu 18.04

You can get an Ubuntu 18.04 image here.

Install ROS Melodic

Open a web browser, e.g. Firefox, so that you can follow the installation instructions here http://wiki.ros.org/melodic/Installation/Ubuntu

Open a terminal by typing ctrl-alt-t.

To open another terminal in a tab in the same window, type ctrl-shift-t in an existing terminal. This will be useful later when we need to have several terminal open to run ROS software.

Copy and paste the ROS installation commands from the browser to the terminal and execute them by entering return.

Note, to copy from the browser use by ctrl-c or cmd-c. However, to paste them to the terminal use shift-ctrl-v (or right click and select paste).

Skip Step 1 of the installation and do the steps shown.

Install the Lynxmotion AL5D Gazebo Simulator ROS Package

If your web browser, e.g. Firefox, is not already open, open it so that you can follow the installation instructions here https://github.com/cognitive-robotics-course/lynxmotion_al5d_description

If a terminal is not already open, open one by typing ctrl-alt-t.

Copy and paste the installation commands from the browser to the terminal and execute them by entering return.

Note again, to copy from the browser use by ctrl-c or cmd-c. However, to paste them to the terminal use shift-ctrl-v (or right click and select paste).

If you encounter an error when installing this software during the sudo apt-get update and sudo apt-get install ... steps, it may be that the ROS GPG Key has expired (see [1]).

To fix this do

 curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -

and then re-run the sudo apt-get update and <sudo apt-get install ... </code> and following commands again.

One final thing. Do the following:

 source devel/setup.bash
 echo "source $HOME/workspace/ros/devel/setup.bash" >> ~/.bashrc

The first line will allow you to use roscd to change the directory to ~/workspace/ros/dev.

The second line adds this to your .bashrc file so that you don't have to source the ROS environment every time you open a new terminal.

Install the Example Programs ROS Package

This is a package of programs for Modules 2, 3, 4, and 5.

If your web browser, e.g. Firefox, is not already open, open it so that you can follow the installation instructions here https://github.com/cognitive-robotics-course/coro_examples

If a terminal is not already open, open one by typing ctrl-alt-t.

Copy and paste the installation commands from the browser to the terminal and execute them by entering return.

Note again, to copy from the browser use by ctrl-c or cmd-c. However, to paste them to the terminal use shift-ctrl-v (or right click and select paste).

Install the iRobot Create 2 ROS Package

We will use the create_robot ROS package from Autonomy Lab, Simon Fraser University, to interface with the iRobot Create 2 mobile robot: https://github.com/AutonomyLab/create_robot.

To install this package, follow these instructions.

Step 1: Install Prerequisites

 sudo apt-get install python-rosdep python-catkin-tools

Step 2: Install and Compile the Package

 roscd     # cd ~/workspace/ros/devel
 cd ../src # cd ~/workspace/ros/src
 git clone https://github.com/autonomylab/create_robot.git


 cd ..     # cd ~/workspace/ros
 rosdep update  --include-eol-distros
 rosdep install --from-paths src --ignore-src -r -y


 catkin_make 


Step 3: Set USB Permissions


In order to connect to Create over USB, ensure your user is in the dialout group

 sudo usermod -a -G dialout rpp

Recall that the superuser password is rpp.

Power down your PC and power it back up again for the permissions to take effect. Don’t ignore this otherwise you’ll get an error when running the launch file. (see Setup the Connection to the iRobot Create 2 Mobile Robot).

Accessing Physical Devices

For completeness, here are the instructions to access the iRobot Create 2 mobile robot and the Lynxmotion AL5D robot manipulator. Instructions for a USB camera will be added later. You can carry out these instructions when you have access to the robots and cameras in the lab.

If you are using the rpp-vm VM, don't forget to enable access to the USB ports; see Step 5 of VirtualBox Setup in Option A above.

Setup the Connection to the iRobot Create 2 Mobile Robot

1. Connect your computer to Create's 7-pin serial port.

2. Switch on the Create 2 by pressing the “Clean” button; it should light up green if the Create 2 is charged. If it lights up flashing amber, it needs to be charged first.


3. Open a terminal and launch the launch file

 roslaunch create_bringup create_2.launch

The green light in the "Clean" button will turn off.

4. Check that everything is working, as follows.

Open a new terminal.

List the topics.

 rostopic list

Check that the bumpers are working.

 rostopic echo /bumper

Check that the motor control is working.

 rostopic pub -1 /cmd_vel geometry_msgs/Twist -- '[0.1, 0.0, 0.0]' '[0.0, 0.0, 0.5]'
 rostopic pub /cmd_vel geometry_msgs/Twist -r 1 -- '[0.1, 0.0, 0.0]' '[0.0, 0.0, -0.5]'
 rostopic pub -r 10 /cmd_vel geometry_msgs/Twist  '{linear:  {x: 0.1, y: 0.0, z: 0.0}, angular: {x: 0.0,y: 0.0,z: 0.0}}'

5. Trouble shooting: if the robot does not move, do the following (recall that the superuser password is rpp).

 sudo usermod -a -G dialout rpp

• Power down the virtual machine (or PC if you are running Ubuntu natively) and power it back up again for the permissions to take effect.

• Check that the device is connected by inspecting the message produced by the following command or by clicking on the small blue USB connector icon at the bottom of the Ubuntu window.

 dmesg | grep -i FTDI

• If are using the rpp-vm virtual machine and your host operating system is Ubuntu, you should also enter the following in a terminal of your host machine and then restart the virtual machine:

 $ sudo adduser $USER vboxsf

• If the virtual machine displays blank black screen, try pressing CTRL + F on your keyboard. It should then display the content.

Setup the Connection to the Lynxmotion AL5D Robot Manipulator

1. Switch on the robot.

2. Connect your laptop to the robot controller using the USB cable.

3. If you are using the rpp-vm VM, and if you have not already done so, add the robot controller USB device to the list of registered USB devices.

• You can do this by following the instructions in Step 5: Enable USB Devices of VirtualBox Setup in Option A above.
• Alternatively, select Devices on the top VirtualBox menu bar, then select USB from the drop-down menu, and then select USB Settings from the second drop-down menu.
  • Choose the device you want to add from the list by clicking the connector icon with the green cross at the right hand side. The device for the Lynxmotion controller is FTDI FT232R USB UART [0600].
  • Ensure the box on the left of this USB Device Filter is ticked.

4. Check that everything is working, as follows.

• Open a new terminal and run the following command. Joint 0, i.e. the joint at the base of the robot, should rotate to the centre position.

 echo "#0P1610S250" > "/dev/ttyUSB0" % setpoint 1610 for joint 0 at speed 250

5.Trouble shooting: if the robot does not move, do the following (recall that the superuser password is rpp).

 sudo usermod -a -G dialout rpp

• Power down the virtual machine (or PC if you are running Ubuntu natively) and power it back up again for the permissions to take effect.

• Check that the device is connected by inspecting the message produced by the following command or by clicking on the small blue USB connector icon at the bottom of the Ubuntu window.

 dmesg | grep -i FTDI

• If are using the rpp-vm virtual machine and your host operating system is Ubuntu, you should also enter the following in a terminal of your host machine and then restart the virtual machine:

 $ sudo adduser $USER vboxsf  

• Repeat Step 4.

• If the virtual machine displays blank black screen, try pressing CTRL + F on your keyboard. It should then display the content.

---

Back to Cognitive Robotics Back to Robotics: Principles and Practice