Difference between revisions of "Robotics: Principles and Practice - Software Installation Guide"

From David Vernon's Wiki
Jump to: navigation, search
(Created page with "This page provides a step-by-step guide to downloading, installing, and using the software required to run the robot vision and robot manipulation demonstration software [http...")
 
 
(142 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
This page provides a step-by-step guide to downloading, installing, and using the software required to run the robot vision and robot manipulation demonstration software [http://www.vernon.eu/cognitive_robotics/index.htm Introduction to Cognitive Robotics] on a physical Lynxmotion AL5D robot and a USB camera. This software runs on Windows 10.  
+
__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.
  
−
There is a separate guide for the software that runs on Ubuntu and uses robot simulators, i.e. the mobile robot, robot manipulation, robot vision, and CRAM software using ROS.
 
  
−
<span style="color:#FF0000"> 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.
+
<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.
  
  
−
=== Operating System ===
+
There are two options:
  
−
I assume you are running Windows 10.  
+
* 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.
  
−
I strongly recommend you turn off the option in Windows Explorer to hide file extensions. To do this, open File Explorer, click the View tab and click on the file name extensions checkbox so that it shows a tick. If it is ticked, you will have problems identifying certain files later on (e.g. invoking the <code>example.sln</code> solution file to launch the C++ compiler).
+
We cover both in the following, starting with Option A.
  
−
=== C/C++ Compiler ===
 
  
−
Download the Microsoft Visual C++ Express compiler, version 10.0 (also known as Visual C++ 2010 or MSVC++ 2010).  It is important to use this version; earlier versions are no longer supported by Microsoft and later versions cause problems with some libraries.
 
  
−
You can download the required installer from [http://www.vernon.eu/downloads/vc_web.exe here].
+
= Option A: Install the VirtualBox Ubuntu 16.04 Virtual Machine =
  
−
Run the installer and follow the instructions.
+
== 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).  
  
−
You will need to register Visual C++ 2010 Express to continue using beyond the initial 30-day evaluation period. To do this, from the Microsoft Visual C++ 2010 Express menu, select ''Help > Register Product''.  A pop-up will be displayed. Click on the Obtain a registration key online button.  You will then have to log in to your Microsoft account, if you have one, or create a new one, if you don't. After filling in some forms you will receive the product key which you enter into the dialogue box that popped up when you selected ''Help > Register Product''.  If you see an error message as shown below, click on the Microsoft icon on the top left corner of the page. This will redirect you to the Microsoft’s login page. Log into your Microsoft account from here and begin the process again, i.e. select ''Help > Register Product''.  For more detailed instructions, see [http://www.vernon.eu/DSA/Registration_Key_Error_Resolution.pdf here].
+
=== 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.
  
−
=== CMake ===
 
−
Download CMake binaries from [http://www.cmake.org/download/ here].  At time of writing the latest version is 3.16.2.
 
−
<!-- Download CMake 2.8.10-RC3 binaries from [https://cmake.org/files/v2.8/cmake-2.8.10-rc3-win32-x86.exe here] -->
 
  
−
You can opt for either the WIN32 installer (cmake-3.16.2-win32-x86.msi) or the Windows zip file.  The installer has the advantage that it gives you the option to update your system path automatically (which you should take by clicking the appropriate radio button during the installation process). If you choose the installer option, note that if you already have CMake version 3.4 or earlier you much uninstall it first.
+
[[File:VirtualBox_Download.jpg]]
  
−
=== OpenCV ===
 
−
Download and install OpenCV from [https://sourceforge.net/projects/opencvlibrary/files/opencv-win/2.4.10/ here]. Choose the version 2.4.10 self-installer, download it, and execute it, and extract the library to <code>C:</code> so that you have a directory <code>C:\opencv</code>.  If you have problems downloading this version from SourceForge site, you can download version 2.4.10 from [http://www.vernon.eu/downloads/opencv-2.4.10.exe here].
 
  
−
Add <code>C:\opencv\build\x86\vc10\bin</code> to the <code>PATH</code> environment variable and add a new environment variable <code>OPENCV_DIR</code> with the value <code>C:\opencv\build</code>, as follows.
+
Double click on the downloaded file (<code>VirtualBox-6.1.30-148432-Win.exe</code> at time of writing) and follow the instructions.
  
−
* From Windows 10 toolbar, select ''Settings''.   
+
It is unclear whether you need to enable hardware virtualization to use a VM on Windows.  The VirtualBox site states that it has been discontinued in VirtualBox 6.1 and it provides an 6.1 installation for Windows hosts so it seems it is not necessary.  
−
* Type ''Environment Variables''  in the ''Find a Setting'' dialogue box. This will bring up a new ''Systems Properties'' window.
+
−
* Click the ''Environment Variables ...'' button. This will bring up a new ''Environment Variables'' window.
+
−
* Select ''Path'' from ''System Variables''. Click ''Edit''.  Click ''New'' and insert <code>C:\opencv\build\x86\vc10\bin</code>. Click ''OK''. 
+
−
* Under ''User variables'', click ''New''. Insert <code>OPENCV_DIR</code> in the ''Variable name'' box and <code>C:\opencv\build</code> in the ''Variable value'' box. Click ''OK''. 
+
−
* Click ''OK'' in the ''Environment Variables'' window.
+
−
* Click ''OK'' in the ''Systems Properties'' window.
+
  
−
=== CORO Repository ===
+
If you run into problems, let me know. Then try enabling 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).
  
−
Copy the CORO repository to the <code>C:</code>  drive:
+
=== MacOS ===
 +
Download the .dmg installer for OS X systems, execute the file and follow the instructions.
  
−
* Download a zip archive with all the files from  [http://www.vernon.eu/cognitive_robotics/CORO.zip here].
+
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.
−
* Copy it to <code>C:</code> drive and unzip it so that you have a directory called <code>C:\CORO</code>.
+
  
−
<code>C:\CORO</code> has with a sub-directory structure explained in the course notes. For our purposes here, there is an  <code>C:\CORO\assignments</code>  directory and it will contain an example <code>C:\CORO\assignments\assignment0</code> sub-directory. Later on, you will generate <code>C:\CORO\assignments\assignment1</code> and <code>C:\CORO\assignments\assignment2</code>, and so on. 
+
=== Ubuntu Linux ===
 +
You can install VirtualBox via the Ubuntu Software Center or through command line as follows.
  
−
There is also a <code>C:\CORO\lectures</code> sub-directory. This has code from the lectures: the source code is in the <code>C:\CORO\lectures\src</code> sub-directory and test data is in the <code>C:\CORO\lectures\data</code> sub-directory.
+
  sudo apt update
 +
  sudo apt install virtualbox
  
−
The next step is to build a MSVC++ <code>.sln</code> solution file so that you can compile the CORO assignment0 executable. To do this, you need to run CMake against the <code>C:\CORO\assignments\assignment0</code> directory (where you will find the main <code>CMakeLists.txt</code> file).    We use <code>assignment0</code> because it is a dummy assignment but you will follow exactly the same procedure for all the real assignments.
+
== 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.
  
−
* Launch the CMake GUI from the Windows 10 toolbar.
+
Double click on the downloaded file (<code>Oracle_VM_VirtualBox_Extension_Pack-6.1.30.vbox-extpack</code> at time of writing) and follow the instructions.
  
−
* In the ''Where is the source code:'' type (or browse to)  <code>C:\CORO\assignments\assignment0</code>
 
  
−
* In the ''Where to build the binaries:'' type (or browse to) <code>C:\CORO\assignments\assignment0\build</code>
+
[[File:VirtualBox_Extension_Pack.jpg]]
  
−
* Select ''File > Delete Cache'' from the top menu (you '''must''' do this the first time in case there is an old invalid configuration in the CORO directory)
 
  
−
* Click ''Configure''
 
  
−
* Select ''Visual Studio 10 2010'' from the drop-down menu as the generator for the project
+
== VirtualBox Setup ==
 +
'''Step 1: Download the Virtual Disk Image'''
  
−
* Click ''Finish'' and watch CMake configure your project. The dialogue box will still highlighted in red, so ...
+
The virtual disk image <code>rpp-vm.vdi</code> contains a VirtualBox virtual machine with Ubuntu 16.04, ROS Kinetic, and example code pre-installed. Store it in some convenient, easily-identified folder. It is a large file (9.3 GB) so I will distribute it on a physical disk.  If you would prefer to download it, and are willing to wait three or more hours for it to download, please contact me by email (contact details can be found on my website).  
  
−
* Click ''Configure'' two more times and everything should be fine.
 
  
−
* Click ''Generate''  to create the MSVC++ <code>assignment0.sln</code> file in the <code>C:\CORO\assignments\assignment0\build</code> directory.
+
'''Step 2: Launch VirtualBox'''
 +
   
 +
In VirtualBox, you first need to create a new virtual machine. Click on the '''New''' button.
  
  
−
Now you are ready to launch MSVC++ and build the CORO assignment0 executable.
+
[[File:VirtualBox_Configuration_1.jpg]]
  
−
* Go to the <code>C:\CORO\assignments\assignment0\build</code> directory and double-click the <code>assignment0.sln</code> file.  This launches Microsoft Visual C++ 2010 Express. The first time, you may be presented with a pop-up window that asks you how you want to open the file. Select ''Microsoft Visual C++ 2010 Express'' and click on the checkbox to always use this application to open this file type.
 
  
−
* Select <code>Release</code> in the ''Solutions Configuration'' box (this is located left of centre on the toolbar and defaults to <code>Debug</code>).
+
Usually the guided menu will open. Change to expert mode,
  
−
* Select ''Build > Build Solution'' from the top menu, (if you don't see this and you see  ''Debug > Build Solution'' instead, it's probably because your IDE is set to basic settings. To change this, select ''Tools > Settings > Expert Settings'').
 
  
−
This will compile and link the programs in the the <code>C:\CORO\assignments\assignment0\src</code> sub-directory and install then in the <code>C:\CORO\assignments\assignment0\bin</code> directory.  
+
[[File:VirtualBox_Configuration_2.jpg]]
  
  
−
Check to see that the example  <code>dvernon.exe</code> executable is there.  If it is not, then select  ''Build > Configuration Manager'' from the menu and make sure the ''INSTALL'' check-box is ticked.  Now rebuild the project again. 
+
'''Step 3: Configure and create the virtual machine'''  
  
−
'''Note that you will have to tick this check-box every time you rebuild the <code>.sln</code> solution file with CMake.'''  If you don't do this, then your new executable won't be installed in the <code>bin</code> directory and you'll end up becoming very confused because none of the changes you make to your source code will be reflected in the executable you run from the <code>bin</code> directory (because its an old version from a previous compilation).
+
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'''
  
−
Good!  Now you are now ready to run the example <code>dvernon.exe</code>  application that is provided with the CORO release. To do this, double click the <code>dvernon.exe</code> executable in <code>C:\CORO\assignments\assignment0\bin</code>.  Open <code>input.txt</code> file in <code>C:\CORO\assignments\assignment0\data</code> and, after running <code>dvernon.exe</code>, open the <code>output.txt</code> file, also in the <code>C:\CORO\assignments\assignment0\data</code> directory.
 
  
 +
[[File:VirtualBox_Configuration_3.jpg]]
  
−
Try creating your own (dummy) assignment program. To do this, follow the following steps.
 
  
−
* Create a directory with your student Id, e.g.  <code>C:\CORO\assignments\assignment0\src\mystudentid</code>
+
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.
−
* Copy the source files (<code>.c, .cpp, .h</code>) and the <code>CMakeLists.txt</code> file from the <code>dvernon</code> directory to the mystudentid directory.
+
−
* Edit the <code>C:\CORO\assignments\assignment0\src\CMakeLists.txt</code> file and replace <code>ADD_SUBDIRECTORY(dvernon)</code> with <code>ADD_SUBDIRECTORY(mystudentid)</code>, where <code>mystudentid</code> is your student number. 
+
−
* Edit the <code>C:\CORO\assignments\assignment0\src\mystudentid\CMakeLists.txt</code> file and replace <code>dvernon</code> with <code>mystudentid</code>, where <code>mystudentid</code> is your student number. 
+
−
* Run CMake again. 
+
−
* Re-open the <code>assignment0.sln</code> file (remember, it's in the <code>C:\CORO\assignments\assignment0\build</code> directory).
+
−
* Your files should now be visible (and the dvernon ones will no longer be there) and you can now compile your code and install it in the <code>bin</code> directory by selecting ''Build > Build Solution'' from the top menu. 
+
−
* Make sure that the ''INSTALL'' check-box is ticked when you select ''Build > Configuration Manager'' from the menu to ensure that your executable is installed in the <code>C:\CORO\assignments\assignment0\bin</code> directory.   
+
−
* Finally, run your program in the <code>C:\CORO\assignments\assignment0\bin</code> directory. You might like to change the contents of <code>input.txt</code> in the <code>C:\CORO\assignments\assignment0\data</code> directory and re-run your program to convince yourself that everything is working properly.
+
  
  
−
For your first assignment, you will simply copy the <code>assignment0</code> directory to <code>assignment1</code> and follow a similar procedure, writing new assignment-specific code, of course.  There is just one thing you need to do: edit the <code>C:CORO\assignments\assignment1\CMakeLists.txt</code> and change the project name from <code>assignment0</code> to <code>assignment1</code>, viz:
+
[[File:VirtualBox_Add_Disk_Image.jpg]]
  
−
  ##############################################
 
−
  PROJECT(assignment0)
 
−
  ##############################################
 
  
−
becomes
+
Finally, click '''Create'''.
  
−
  ##############################################
 
−
  PROJECT(assignment1)
 
−
  ##############################################
 
  
 +
[[File:VirtualBox_Configuration_3.jpg]]
  
−
When submitting an assignment, all you have to do is submit a zipped version of your <code>mystudentid</code> directory with your three source code files.
 
  
−
The instructor simply has to unzip it and add it to the <code>src</code> directory on her or his computer, along with all the other students and her or his own solution, run CMake, launch the <code>.sln</code> file, compile, install, and check each executable in <code>bin</code> against the test data file in her or his <code>data</code> directory.  Because we build the solutions the same way, you are guaranteed that your code will compile, provided you have followed this procedure.
 
  
 +
'''Step 4: Configure the settings'''
  
−
The final step is to build a MSVC++ <code>.sln</code> solution file so that you can compile the DSA lectures executables. To do this, you need to run CMake against <code>C:\CORO\lectures</code> and <code>C:\CORO\lectures\build</code>, launch <code>C:\CORO\lectures\build\lectures.sln</code>, build the solution, making sure that the ''INSTALL'' check-box is ticked when you select ''Build > Configuration Manager'' from the menu to ensure that the demo executables are installed in the <code>C:\CORO\lectures\bin directory</code>.
+
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.
 +
 +
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 <code>rpp</code>.
 +
 +
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 <code>rpp</code>. Press <code>return</code> when asked.
 +
 +
 +
[[File:Install-Virtualbox-Guest-Additions_1.jpg]]
 +
 +
 +
Now, power off your Ubuntu guest OS.
 +
 +
 +
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]]
 +
 +
 +
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.
 +
 +
 +
[[File:Install-Virtualbox-Guest-Additions_3.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]]
 +
 +
 +
If you encounter an error when installing this software during the <code>sudo apt-get update</code> and <code> sudo apt-get install ... </code> steps, it may be that the ROS GPG Key has expired (see [https://discourse.ros.org/t/ros-gpg-key-expiration-incident/20669]).
 +
 +
To fix this do
 +
 +
  curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
 +
 +
and then re-run the <code>sudo apt-get update</code> and <sudo apt-get install ... </code> and following commands again.
 +
 +
 +
<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.
  
 
----
 
----
−
Back to [[Cognitive Robotics]]
+
Back to [[Robotics: Principles and Practice]]

Latest revision as of 23:44, 15 October 2022

This page provides a step-by-step guide to installing the tools, utilities, and example software for Robotics: Principles and Practice with robot simulators and physical robots on Ubuntu 16.04 with ROS.


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 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 Windows hosts to download the installation file.


VirtualBox Download.jpg


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

It is unclear whether you need to enable hardware virtualization to use a VM on Windows. The VirtualBox site states that it has been discontinued in VirtualBox 6.1 and it provides an 6.1 installation for Windows hosts so it seems it is not necessary.

If you run into problems, let me know. Then try enabling 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 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 All supported platforms 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 (Oracle_VM_VirtualBox_Extension_Pack-6.1.30.vbox-extpack at time of writing) and follow the instructions.


VirtualBox Extension Pack.jpg


VirtualBox Setup

Step 1: Download the Virtual Disk Image

The virtual disk image rpp-vm.vdi contains a VirtualBox virtual machine with Ubuntu 16.04, ROS Kinetic, and example code pre-installed. Store it in some convenient, easily-identified folder. It is a large file (9.3 GB) so I will distribute it on a physical disk. If you would prefer to download it, and are willing to wait three or more hours for it to download, please contact me by email (contact details can be found on my website).


Step 2: Launch VirtualBox

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


VirtualBox Configuration 1.jpg


Usually the guided menu will open. Change to expert mode,


VirtualBox Configuration 2.jpg


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


VirtualBox Configuration 3.jpg


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.


VirtualBox Add Disk Image.jpg


Finally, click Create.


VirtualBox Configuration 3.jpg


Step 4: Configure the settings

Choose the newly created virtual machine and click on Settings.


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.


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.


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.


VirtualBox Configuration 7.jpg


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

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

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 rpp-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 16.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 rpp.

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 rpp. Press return when asked.


Install-Virtualbox-Guest-Additions 1.jpg


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.


Install-Virtualbox-Guest-Additions 2.jpg


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.


Install-Virtualbox-Guest-Additions 3.jpg


Everything is set up and the virtual machine can now be started. When Ubuntu 16.04 boots, enter the password rpp, 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 here.

There is a tutorial on installing Ubuntu 16.04 alongside Windows 10 (dual boot) 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 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.


ROS 1.jpg

ROS 2.jpg

ROS 3.jpg

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


Lynxmotion 1.jpg


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).


Lynxmotion 2.jpg


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).

Examples 1.jpg


Examples 2.jpg


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 Robotics: Principles and Practice

Retrieved from "http://www.vernon.eu/w/index.php?title=Robotics:_Principles_and_Practice_-_Software_Installation_Guide&oldid=3303"