#Kinematics Tool Guide for the ME449 Robotic Manipulation Class - Virtual Machine (Mac, Windows)
##1. Overview This documentation is intended to get a user set-up with the kinematics tool for the ME449 Robotic Manipulation class on a Windows or Mac. ###What does the tool do?### The tool provides a simple solution to visualize a stationary forward kinematics problem or animate the a robot's reference trajectory. A description of the robot in URDF (Unified Robot Description Format) is always needed to render an image. The URDFs for both robots used in this class have been provided. Additional required input for successful forward kinematics visualization or trajectory animation is a corresponding .yaml file containing one set of joint angles or a corresponding .csv (comma separated value) file containing the reference trajectory, respectively.
###What Operating System (OS) does the tool run on?### The tool benefits from a popular collection of software frameworks for robot software development called Robot Operating System [(ROS)] (http://www.ros.org/), which typically runs on top of a Linux operating system. To simplify the set-up process for a user running any major OS (i.e. Windows, Mac) a version of this animation tool was designed to be used with a virtualized Linux OS. Virtualization allows the user to run an instance of Linux (Guest) in a separate window of their original OS (Host). We will use VirtualBox - a free virtualization software by Oracle.
###How should I proceed with this documentation?### The rest of this document will:
-
help you set-up your virtual machine (VM) (Note: allocate ample time for this step, as you may have to do some hardware or OS-version specific trouble-shooting on your own).
-
provide you with instructions and demos on how to use it, as well as a means to update the tool if updates or fixes are released throughout the quarter.
##2. Virtualization on Windows or Mac ###Guest OS: Username me449-student , Password: 449###
-
Download VirtualBox v.5.06 here for Windows or here for Mac. Install the software.
-
Download the Extension Pack here. From the VirtualBox window make sure the extension pack installed successfully by navigating to File->Preferences, select 'Extensions' and verify that 'Oracle VM VirtualBox Extension Pack' is listed under Extension Packages. DO NOT PROCEED UNLESS YOU HAVE COMPLETED THIS STEP SUCCESSFULLY.
-
Download the me449-vm.ova VM image that has been customized specifically for this animation tool here.
-
Navigate back to VirtualBox, select File->Import Appliance and select the me449-vm.ova image from your download destination.
-
If an me449-vm icon now appears on the left side of your VirtualBox window, then you have successfully set-up your VM. Double click the icon or select it then navigate to the start button to launch your Linux VM. As soon as you start-up your virtual machine, run the me449_kinematics_update script from your desktop described in the next section.
-
Jump to the user instructions section to start using the tool.
##3. User Instructions and Demos The kinematics tool, as well as the VM set-up was designed to be as simple as possible, which is why everything you need is placed on your desktop.
###What's on my desktop?### Desktop Icons
-
The 'student_files' folder is where ALL your files should go (!!!IMPORTANT!!! Any data located outside this folder will be lost the next time you run the update script, always keep all your files in this folder).
-
The 'demos' folder contains files (URDF descriptions, .csv trajectory files and .yaml joint angle files) for 2 robots that you will launch easily later in this section: Universal Robot's UR5 and Barrett Technology's WAM Arm.
-
The 'vm_client' folder is a dummy folder that you could configure to share files with your host OS. Alternatively, you can share files with your host OS using a USB thumb drive, which is easier to configure. (This is very well documented on the web and you will have to set this up yourself).
-
'me449_forward_kinematics' is the launcher for the tool's stationary forward kinematics visualization GUI.
-
'me449_kinematics_animator' is the launcher for the tool's trajectory animation GUI.
-
'me449_kinematics_update' is an update script that you will run when new updates are released. Remember this replaces all your files outside the 'student_files' directory. On the bright side, if you break something unintentionally, simply run the update script to restore.
###How do I use the forward kinematics tool?###
Finally, you should be all set to start the forward kinematics tool. First let's check-out one of the demos.
Launch 'me449_forward_kinematics' by double clicking. Browse the .urdf file from demos/universal_ur5/ur5_robot.urdf, then browse the .yaml file from demos/universal_ur5/ur5_home.yaml to see the forward kinematics in the home position, or demos/universal_ur5/ur5_example.yaml for an arbitrary set of joint angles. Select 'Launch Forward Kinematics'. Some of ROS' fancy animation tools should fire-up and a stationary visualization of the robot, as well as slider bars to modify the joint angles should appear. You can also enter specific joint angles in the text boxes next to the slider bars. Note that you need to press enter after entering each angle. Use your scroll-wheel to zoom; move the mouse while pressing the scroll-wheel to pan; left click and move your mouse to rotate. Similarly, launch the demo for the Barrett WAM arm.
To view the forward kinematics for your own set of joint angles, simply create a <Your_File_Name>.yaml file that follows the same format as the example.yaml file for the particular robot that you are using. In Step 2 of the launching process, navigate to your file instead of the example.yaml file. Alternatively, you can interactively input your joint angles directly into the GUI's text boxes.
To exit ROS, navigate to the Terminal that opened up in the background and type 'control-C' on Windows/Linux or 'cmd-c' on a Mac.
###How do I use the animation tool?###
The trajectory animation tool is very similar to the forward kinematics tool and can be launched by double clicking the 'me449_kinematics_animator' icon. Launch the demos in the same manner as with the forward kinematics, but choose a corresponding jointstates.csv file to load entire trajectories instead of a single set of .yaml joint angles. The animator will fire up ROS and loop through the trajectory that was provided in the .csv file.
To launch your own animation you need to provide a .csv trajectory file of your own (i.e. generated from MATLAB or Mathematica). Do not modify the demo .csv trajectory files, as these will get overwritten next time you run an update. Open one of the .csv files to study its format and naming conventions: The first column must indicate the time steps and must be labeled as 'time'. The other column labels must correspond to the joint names found in your URDF (same as in the demo .csv files) and indicate trajectories for each joint of the robotic manipulator. Remember to keep all your files in the student_files folder that is located on your desktop.
###Hiding the many frames from your animation:###
If you are bothered by the many frames attached to the robot's links, you can easily hide a frame by unchecking it from the expandable [drop down menu] (https://gist.github.com/sherifm/ba54c406c4f4ae140594#file-rviz_frames-png) on the left hand side. At the time of writing, there was no simple way of configuring the frames to be hidden by default.
##4. Making Screenshots on Mac or Windows for Your Homeworks##
In your homeworks, you are asked to turn in screenshots of your animations. Here are two tips:
-
It should be much easier for you to make the screenshots from your host OS. Both Windows and Mac have their native screenshot tools. See here for Windows and here for Mac. On Windows, PicPick is also a great third-party tool.
-
If you find the animation to be looping too quickly for you to make live screenshots, try copying a few sets of joint angles from your .csv trajectory into individual .yaml files and launching the stationary forward kinematics tool using those angles. That way you can give yourself plenty of time to make the screenshot.
##5. Using the Animation Tool with Linux## Kudos if you are running Linux or you choose to be adventurous and try it out 🍻, however we will assume you know your Linux System and will only provide rough guidelines, due to the many version-specific issues. You have two options:
-
If you have experience in ROS, you will want to install the needed packages into your own workspace. Follow these guidelines for using the tool natively on Linux and ROS!
-
Though it's unlikely, you may want to run the tool on a virtual machine using a Linux host (i.e. if you're running a non-ROS compatible version of Linux or if you want to sandbox this tool from the rest of your OS). Analogous to the Windows/Mac section of this tutorial, figure out how to install the me449-vm using VirtualBox on your Linux computer. Here is a tip that could save you some debugging effort: Do not use Linux' Advanced Packaging Tool (apt-get) to install VirtualBox or the guest additions (at least for Ubuntu 14.04 they don't work!). Instead, use the VirtualBox Linux download section to find the appropriate distribution (i.e .deb).
##6. Where can I Get Help?##
For questions related to the tool itself (launching, bugs, file structure etc.), feel free to reach out to me - Sherif Mostafa - at sherifmostafa2015@u.northwestern.edu. I will do my best to reply to you as soon as possible, or set-up a meeting to help you out. I will publish videos to this write-up answering the most re-occuring questions.
If you're having problems with setting-up the virtual machine, I'm afraid you will have to figure those out on your own, or switch to the MATLAB alternative tool! Virtual Machine problems are very hardware and OS-version specific, such that I will not be able to provide any help. Google is your best friend.
###Good luck everyone :)###
