Difference between revisions of "Cognitive Robotics - Software Installation Guide"

From David Vernon's Wiki
Jump to: navigation, search
Line 1: Line 1:
 +
The cognitive robotics course uses the CRAM cognitive architecture (Cognitive Robot Abstract Machine) and ROS (Robot Operating System) on Ubuntu. 
 +
 +
The CRAM [http://cram-system.org/installation Installation] page states that the recommended setup is Ubuntu 16.04 with ROS Kinetic.  However, CRAM research has already moved to an Ubuntu 18.04 with ROS Melodic.
 +
 +
For this reason, we support two software installations:
  
 
[[Cognitive Robotics - Software Installation Guide 16.04]] <BR>
 
[[Cognitive Robotics - Software Installation Guide 16.04]] <BR>
 
[[Cognitive Robotics - Software Installation Guide 18.04]] <BR>
 
[[Cognitive Robotics - Software Installation Guide 18.04]] <BR>
__TOC__
 
This page provides a step-by-step guide to installing the tools, utilities, and example software for  [http://www.vernon.eu/RPP.htm Robotics: Principles and Practice] with robot simulators and physical robots on Ubuntu 16.04 with ROS.
 
 
 
<span style="color:#FF0000">Please follow these instructions exactly as they are stated.</span>
 
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 16.04 virtual machine (VM) with everything pre-installed.
 
* Option B: install all the required tools and utilities directly on a computer running Ubuntu 16.04.
 
 
We cover both in the following, starting with Option A.
 
 
 
 
= Option A: Install the VirtualBox Ubuntu 16.04 Virtual Machine =
 
 
== Install VirtualBox ==
 
I assume that you are running Windows 10 Pro.  Please let me know if you are running a different operating system. For completeness, I have included instructions for 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 <span style="color:#0000AA">Windows hosts</span> to download the installation file. 
 
 
 
[[File:VirtualBox_Download.jpg]]
 
 
 
Double click on the downloaded file (<code>VirtualBox-6.1.26-145957-Win.exe</code> at time of writing) and follow the instructions.
 
 
To run a VM on Windows 10 you need to enable hardware virtualization in BIOS.  Unfortunately, the steps to steps to access BIOS and enable virtualization from the BIOS depends on the PC manufacturer. Normally, BIOS settings can be accessed using the function keys during a restart, i.e. when booting your PC.  Try F1, F2, F3, F8, F10, or F12. On some PCs, it’s the ESC, or Delete key. Restart your PC, tap the key about twice per second as soon as the screen turns on. Look for '''Advanced''', '''Advanced Mode''', or '''Configuration''' on the BIOS screen.  Now look for the setting which has 'Virtualization' is its name and turn it on. Here are some commonly used names: 'Intel Virtualization Technology', 'AMD-V', '''Hyper-V''', '''VT-X''', '''Vanderpool''', and '''SVM'''. Enable it.  Now that virtualization support is enabled in the BIOS, you need to enable it on Windows 10. Restart your PC and press the Windows key to get the Search box. Type “turn windows features on or off” and click on it to open it. Scroll down and check the box next to '''Hyper-V'''. Click '''OK'''. Windows will install the necessary files to enable virtualization. You'll then be asked to reboot the PC. Click '''Restart Now'''. (This is a synopsis of a [https://mashtips.com/enable-virtualization-windows-10/ longer tutorial] on enabling virtualization on Windows 10).
 
 
=== 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 <span style="color:#0000AA">All supported platforms</span> to download the VirtualBox Extension Pack.  This is needed to provide access to USB devices such as the iRobot Create 2 mobile robot, the Lynxmotion AL5D robot manipulator, and the webcam we will use later in the course.
 
 
Double click on the downloaded file (<code>Oracle_VM_VirtualBox_Extension_Pack-6.1.26.vbox-extpack</code> at time of writing) and follow the instructions.
 
 
 
[[File:VirtualBox_Extension_Pack.jpg]]
 
 
 
 
== VirtualBox Setup ==
 
'''Step 1: Download the Virtual Disk Image'''
 
 
The virtual disk image <code>rpp-vm.vdi</code> can be downloaded from [http://www.vernon.eu/downloads/rpp-vm.vdi here]. It contains a VirtualBox virtual machine with Ubuntu 16.04, ROS Kinetic, and example code pre-installed. Store it in some convenient, easily-identified folder.  Note that it is a large file (9.3 GB) so it will take some time to download.  If you can arrange it, it might be helpful if one student downloads it and then shares it with other students using a memory stick.
 
 
 
'''Step 2: Launch VirtualBox'''
 
 
In VirtualBox, you first need to create a new virtual machine. Click on the '''New''' button.
 
 
 
[[File:VirtualBox_Configuration_1.jpg]]
 
 
 
Usually the guided menu will open. Change to expert mode,
 
 
 
[[File:VirtualBox_Configuration_2.jpg]]
 
 
 
'''Step 3: Configure and create the virtual machine'''
 
 
In the expert menu:
 
 
* Set the name to <code>rpp-vm</code>
 
* 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'''
 
 
 
[[File:VirtualBox_Configuration_3.jpg]]
 
 
 
Using the button on the right, open the file explorer, click '''Add''', browse to where you stored <code>rpp-vm.vdi</code>, and select the virtual disk image.
 
 
 
[[File:VirtualBox_Add_Disk_Image.jpg]]
 
 
 
Finally, click '''Create'''.
 
 
 
[[File:VirtualBox_Configuration_3.jpg]]
 
 
 
 
'''Step 4: Configure the settings'''
 
 
Choose the newly created virtual machine and click on '''Settings'''.
 
 
 
[[File:VirtualBox_Configuration_4.jpg]]
 
 
 
Click on '''System''' and '''Processor''' and choose how many processor cores you want to allocate to the VM. Here, we have allocated four cores.
 
 
 
[[File:VirtualBox_Configuration_5.jpg]]
 
 
 
'''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.
 
 
 
[[File:VirtualBox_Configuration_6.jpg]]
 
 
 
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.
 
 
 
[[File:VirtualBox_Configuration_7.jpg]]
 
 
 
The device for the iRobot Create 2 mobile robot is <code>FTDI FT231X USB UART [1000]</code>.
 
 
The device for the Lynxmotion AL5D robot manipulator is <code>FTDI FT232R USB UART [0600]</code>.
 
 
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 <code>rpp-vm</code> 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 16.04).  To do this, we need to enable Shared Clipboard and Drag’n’Drop functionality between Guest and Host Machine.
 
 
Choose the <code>rpp-vm</code> 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.jpg]]
 
 
 
 
Everything is set up and the virtual machine can now be started. When Ubuntu 16.04 boots, enter the password <code>rpp</code>, if asked.
 
 
= Option B: Install Required Tools and Utilities on a Computer running Ubuntu 16.04 =
 
 
 
== Install Ubuntu 16.04 ==
 
 
If you don't already have it, install Ubuntu 16.04
 
 
You can get an Ubuntu 16.04 image [https://releases.ubuntu.com/xenial/ here].
 
 
There is a tutorial on installing Ubuntu 16.04 alongside Windows 10 (dual boot) [https://www.askaswiss.com/2017/01/how-to-install-ubuntu-16-04-alongside-windows-10-dual-boot.html here].
 
 
Disclaimer: I have not validated this tutorial. If you know of a better one, please tell me
 
 
 
== Install ROS Kinetic ==
 
 
Open a web browser, e.g. Firefox, so that you can follow the installation instructions here http://wiki.ros.org/kinetic/Installation/Ubuntu
 
 
Open a terminal by typing <code>ctrl-alt-t</code>.
 
 
To open another terminal in a tab in the same window, type <code>ctrl-shift-t</code> 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 <code>return</code>.
 
 
Note, to copy from the browser use by <code>ctrl-c</code> or <code>cmd-c</code>. However, to paste them to the terminal use <code>shift-ctrl-v</code> (or right click and select paste). 
 
 
 
Skip Step 1 of the installation and do the steps shown.
 
 
 
[[File:ROS_1.jpg]]
 
 
[[File:ROS_2.jpg]]
 
 
[[File:ROS_3.jpg]]
 
 
[[File:ROS_4.jpg]]
 
 
 
 
== 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
 
 
 
[[File:Lynxmotion_1.jpg]]
 
 
 
If a terminal is not already open, open one by typing <code>ctrl-alt-t</code>.
 
 
Copy and paste the installation commands from the browser to the terminal and execute them by entering <code>return</code>.
 
 
Note again, to copy from the browser use by <code>ctrl-c</code> or <code>cmd-c</code>. However, to paste them to the terminal use <code>shift-ctrl-v</code> (or right click and select paste). 
 
 
 
[[File:Lynxmotion_2.jpg]]
 
 
 
<span style="color:#FF0000">One final thing. Do the following:</span>
 
 
  source devel/setup.bash
 
  echo "source $HOME/workspace/ros/devel/setup.bash" >> ~/.bashrc
 
 
The first line will allow you to use <code>roscd</code> to change the directory to <code>~/workspace/ros/dev</code>.
 
 
The second line adds this to your <code>.bashrc</code> 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 <code>ctrl-alt-t</code>.
 
 
Copy and paste the installation commands from the browser to the terminal and execute them by entering <code>return</code>.
 
 
Note again, to copy from the browser use by <code>ctrl-c</code> or <code>cmd-c</code>. However, to paste them to the terminal use <code>shift-ctrl-v</code> (or right click and select paste). 
 
 
[[File:examples_1.jpg]]
 
 
 
[[File:examples_2.jpg]]
 
 
 
 
== Install the iRobot Create 2 ROS Package ==
 
 
We will use the <code>create_robot</code> 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 <nowiki>https://github.com/autonomylab/create_robot.git

</nowiki>
 
  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.  <span style="color:#FF0000">Don’t ignore this otherwise you’ll get an error when running the launch file.</span> (see [[#Setup the Connection to the iRobot Create 2 Mobile Robot | 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 <code>rpp-vm</code> VM, don't forget to enable access to the USB ports; see Step 5 of [[#VirtualBox Setup | 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 <code>rpp-vm</code> 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 <code>rpp-vm</code> 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 | 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 <code>FTDI FT232R USB UART [0600]</code>.
 
** 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 <code>rpp-vm</code> 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.
+
The 18.04 guide is under development.  Please do not use it.  '''Use the 16.04 guide instead.'''
  
 
----
 
----
 
Back to [[Cognitive Robotics]]
 
Back to [[Cognitive Robotics]]

Revision as of 06:26, 13 January 2022

The cognitive robotics course uses the CRAM cognitive architecture (Cognitive Robot Abstract Machine) and ROS (Robot Operating System) on Ubuntu.

The CRAM Installation page states that the recommended setup is Ubuntu 16.04 with ROS Kinetic. However, CRAM research has already moved to an Ubuntu 18.04 with ROS Melodic.

For this reason, we support two software installations:

Cognitive Robotics - Software Installation Guide 16.04
Cognitive Robotics - Software Installation Guide 18.04

The 18.04 guide is under development. Please do not use it. Use the 16.04 guide instead.


Back to Cognitive Robotics