Chapter1_URDF.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# ROS-Industrial MicroCourse"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Chapter 1: Create an URDF for an Industrial Robot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:green;color:white;\">SUMMARY</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Estimated time of completion: <b>30 min</b><br><br>\n",
    "This Unit is an introduction to creating an URDF file for an industrial robot. You will go trough some basic steps on how to create an URDF file for an industrial robot."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:green;color:white;\">END OF SUMMARY</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Building the URDF"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Unified Robot Description Format (URDF) is an XML format that is used to represent a robot model. The URDF file of a robot is the file that describes everything about it. From the visual part and how it looks, to the physical part such as the collision data or the inertia data. URDF files are widely used for representing robots in regular ROS systems. In the case of ROS-Industrial, they are also used for representing industrial robots, but with some peculiarities that we are going to check during this Chapter."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Keep in mind that you are not going to learn the fundamentals about URDF files during this Course. If you are interested in learning more about URDF, you can have a look at the ROS Wiki Tutorials (http://wiki.ros.org/urdf/Tutorials) or at the <b>TF ROS 101 Course</b> from the Robot Ignite Academy."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Anyways, I think the best way you have in order to understand what the URDF file is, is to actually visualize one. So let's do it!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:#EE9023;color:white;\">Demo 1.1</p>\n",
    "<br>\n",
    "a) Execute the following command in order to visualize the URDF file of the simulated robot.\n",
    "<table style=\"float:left;background: #407EAF\">\n",
    "<tr>\n",
    "<th>\n",
    "Execute in WebShell #1\n",
    "</th>\n",
    "</tr>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "rosrun rviz rviz"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "b) Now, just click on the \"Add\" button, select the RobotModel option, and select \"base_link\" as your Fixed Frame. You will now be able to visualize your URDF file!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div style=\"text-align: left\">\n",
    "<img src=\"img/add_rviz.png\" width=\"250\" style=\"float: left; margin: 0px 0px 15px 15px;\"/>\n",
    "<img src=\"img/robotmodel.png\" width=\"300\" style=\"float: left; margin: 0px 0px 15px 15px;\"/>\n",
    "<img src=\"img/base_link.png\" width=\"250\" style=\"float: left; margin: 0px 0px 15px 15px;\"/>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:#AE0202;color:white;\">Expected Result for Demo 1.1</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"img/robotcell_rviz.png\" width=\"600\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:#EE9023;color:white;\">End of Demo 1.1</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, you have been able to visualize the robot model because it is fully described in its corresponding URDF file. Actually, the robot you've visualized is the one that is in the simulation. And... what you are going to do in this Chapter, is to build yourself an URDF file that describes a robot like the one you are seeing in the simulation window. Not all of it, of course, because there is not enough time to explain all of it, but you are going to build a part of it, and you'll see some peculiarities that should be taken into account when building the URDF file for an industrial robot based on ROS-Industrial. So... let's go!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first thing you are going to do is to build the \"workcell\" that contains the robotic arm. For that, you'll need to follow the next Exercise."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:#EE9023;color:white;\">Exercise 1.1</p>\n",
    "<br>\n",
    "a) Create a new package named <b><i>my_robot_description</i></b>. Inide this package, create a new folder named <b><i>urdf</i></b>.\n",
    "<br><br>\n",
    "b) Inside the urdf folder, create a file named <b><i>my_robot.urdf</i></b>. Write into this file the following basic structure:"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "<?xml version=\"1.0\" ?>\n",
    "<robot name=\"my_robot\" xmlns:xacro=\"http://ros.org/wiki/xacro\">\n",
    "</robot>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "c) Add a world and a camera frame as virtual links."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "<link name=\"world\"/>\n",
    "<link name=\"camera_frame\"/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "d) Add a table frame, specifying both the visual and the collision tags. Here you can see an example of a very basic box-shaped table."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "<link name=\"table\">\n",
    "    <visual>\n",
    "      <geometry>\n",
    "        <box size=\"1 1 0.05\"/>\n",
    "      </geometry>\n",
    "    </visual>\n",
    "    <collision>\n",
    "      <geometry>\n",
    "        <box size=\"1 1 0.05\"/>\n",
    "      </geometry>\n",
    "    </collision>\n",
    "</link>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "e) Add two joints to connect both the table and the camera links to the world link."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "<joint name=\"world_to_table\" type=\"fixed\">\n",
    "  <parent link=\"world\"/>\n",
    "  <child link=\"table\"/>\n",
    "  <origin xyz=\"0 0 0.5\" rpy=\"0 0 0\"/>\n",
    "</joint>\n",
    "\n",
    "<joint name=\"world_to_camera\" type=\"fixed\">\n",
    "  <parent link=\"world\"/>\n",
    "  <child link=\"camera_frame\"/>\n",
    "  <origin xyz=\"0 0 1.0\" rpy=\"0 1.571 0\"/>\n",
    "</joint>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table style=\"float:left;\">\n",
    "<tr>\n",
    "<th>\n",
    "<p style=\"background:#3B8F10;color:white;\">Notes for Exercise 1.1</p>\n",
    "<br>\n",
    "<span style=\"color:orange\">Note 1: </span>In the exmple URDF file, we are adding a <i>camera_frame</i> because it is a common practice to have a camera in industrial environments such as this. But keep in mind that concerning this Course, you are not going to use it.\n",
    "<br>\n",
    "</th>\n",
    "</tr>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:#AE0202;color:white;\">Expected Result for Exercise 1.1</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Example of complete URDF file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "<?xml version=\"1.0\" ?>\n",
    "\n",
    "<robot name=\"myrobot\" xmlns:xacro=\"http://ros.org/wiki/xacro\">\n",
    "\n",
    "    <link name=\"world\"/>\n",
    "\n",
    "  <link name=\"table\">\n",
    "    <visual>\n",
    "      <geometry>\n",
    "        <box size=\"1 1 0.05\"/>\n",
    "      </geometry>\n",
    "    </visual>\n",
    "    <collision>\n",
    "      <geometry>\n",
    "        <box size=\"1 1 0.05\"/>\n",
    "      </geometry>\n",
    "    </collision>\n",
    "  </link>\n",
    "\n",
    "  <link name=\"camera_frame\"/>\n",
    "\n",
    "  <joint name=\"world_to_table\" type=\"fixed\">\n",
    "    <parent link=\"world\"/>\n",
    "    <child link=\"table\"/>\n",
    "    <origin xyz=\"0 0 0.5\" rpy=\"0 0 0\"/>\n",
    "  </joint>\n",
    "\n",
    "  <joint name=\"world_to_camera\" type=\"fixed\">\n",
    "    <parent link=\"world\"/>\n",
    "    <child link=\"camera_frame\"/>\n",
    "    <origin xyz=\"0 0 1.0\" rpy=\"0 1.571 0\"/>\n",
    "  </joint>\n",
    "\n",
    "</robot>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:#EE9023;color:white;\">End of Exercise 1.1</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, now we have setted up an environment, containing a very basic table. But... where is the robot?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In a regular case, you could define the robot in this same urdf file, just by adding the corresponding links and joints. Just as you did with the table, but with a little bit more of complexity. In ROS-Industrial, though, it is recommended to use xacro macros for this. But now... what is Xacro? Let's have a look!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Building the Xacro"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Xacro is a macro language which, basically, allows you to load URDF contents in a very easy and clean way. The URDF file you defined in the previous exercise was very easy and simple, but this is not usually like this. Real environments are usually complex, they include robots, etc... and defining all this links and joints in a single URDF file can become a nightmare."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "By using xacro, you can just call a macro that will automatically load a predefined URDF content into your file, keeping the file clean and easy to read, and also allowing to reuse that code as many times as you want."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To better understand how this works, we will add a robot to the previously created environment by using a xacro macro. So... let's go!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:#EE9023;color:white;\">Exercise 1.2</p>\n",
    "<br>\n",
    "a) Rename the <b><i>my_robot.urdf</i></b> file you created in the previous exercise to <b><i>my_robot.xacro</i></b>. \n",
    "<br><br>\n",
    "b) Include into your file the xacro macro that loads the Motoman robot. You can find this xacro macro in the sia10f_description package."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "<xacro:include filename=\"$(find sia10f_description)/urdf/sia10f_macro.xacro\" />"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "c) So, you have now included the macro file that contains the definition of the robot. But you still haven't created the robot itself. To do this, you need to call the macro file in the following way:"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "<xacro:motoman_sia10f prefix=\"\"/>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "d) Finally, add a fixed joint that connects the robot to the table you created previously."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "<joint name=\"table_to_robot\" type=\"fixed\">\n",
    "  <parent link=\"table\"/>\n",
    "  <child link=\"base_link\"/>\n",
    "  <origin xyz=\"0 0 0\" rpy=\"0 0 0\"/>\n",
    "</joint>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "e) Create a new directory in your package called <i><b>launch</b></i>. Inside this launch directory, create a new file named <i><b>myrobot.launch</b></i>. Copy the following content into this file:"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "<launch>\n",
    "  <arg name=\"gui\" default=\"true\"/>\n",
    "  <param name=\"robot_description\" command=\"$(find xacro)/xacro --inorder '$(find my_robot_description)/urdf/my_robot.xacro'\" />\n",
    "  <node name=\"rviz\" pkg=\"rviz\" type=\"rviz\" if=\"$(arg gui)\"/>\n",
    "</launch>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, you are loading your xacro file to the robot_description parameter, and launching Rviz. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "f) Execute the launch file you've just created."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<table style=\"float:left;background: #407EAF\">\n",
    "<tr>\n",
    "<th>\n",
    "Execute in WebShell #1\n",
    "</th>\n",
    "</tr>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "roslaunch my_robot_description myrobot.launch"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "g) Now, just click on the \"Add\" button, select the RobotModel option, and select \"base_link\" as your Fixed Frame. You will now be able to visualize your URDF file!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div style=\"text-align: left\">\n",
    "<img src=\"img/add_rviz.png\" width=\"250\" style=\"float: left; margin: 0px 0px 15px 15px;\"/>\n",
    "<img src=\"img/robotmodel.png\" width=\"300\" style=\"float: left; margin: 0px 0px 15px 15px;\"/>\n",
    "<img src=\"img/base_link.png\" width=\"250\" style=\"float: left; margin: 0px 0px 15px 15px;\"/>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:#AE0202;color:white;\">Expected Result for Exercise 1.2</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"img/full_robot_rviz2.png\" width=\"600\" />"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "<?xml version=\"1.0\" ?>\n",
    "\n",
    "<robot name=\"myrobot\" xmlns:xacro=\"http://ros.org/wiki/xacro\">\n",
    "    \n",
    "    <xacro:include filename=\"$(find sia10f_description)/urdf/sia10f_macro.xacro\" />\n",
    "    <xacro:motoman_sia10f prefix=\"\"/>\n",
    "\n",
    "    <link name=\"world\"/>\n",
    "\n",
    "  <link name=\"table\">\n",
    "    <visual>\n",
    "      <geometry>\n",
    "        <box size=\"0.6 0.6 0.05\"/>\n",
    "      </geometry>\n",
    "    </visual>\n",
    "    <collision>\n",
    "      <geometry>\n",
    "        <box size=\"0.6 0.6 0.05\"/>\n",
    "      </geometry>\n",
    "    </collision>\n",
    "  </link>\n",
    "\n",
    "  <link name=\"camera_frame\"/>\n",
    "\n",
    "  <joint name=\"world_to_table\" type=\"fixed\">\n",
    "    <parent link=\"world\"/>\n",
    "    <child link=\"table\"/>\n",
    "    <origin xyz=\"0 0 0.5\" rpy=\"0 0 0\"/>\n",
    "  </joint>\n",
    "\n",
    "  <joint name=\"world_to_camera\" type=\"fixed\">\n",
    "    <parent link=\"world\"/>\n",
    "    <child link=\"camera_frame\"/>\n",
    "    <origin xyz=\"0 0 1.0\" rpy=\"0 1.571 0\"/>\n",
    "  </joint>\n",
    "  \n",
    "  <joint name=\"table_to_robot\" type=\"fixed\">\n",
    "    <parent link=\"table\"/>\n",
    "    <child link=\"base_link\"/>\n",
    "    <origin xyz=\"0 0 0\" rpy=\"0 0 0\"/>\n",
    "  </joint>\n",
    "\n",
    "</robot>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:#EE9023;color:white;\">End of Exercise 1.2</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:red;color:white;\">IMPORTANT NOTE</p>\n",
    "<br>\n",
    "Once you are done, execute the following command in order to reset the <i>robot_description</i> parameter."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "roslaunch urdf_tutorial reset_robot_description.launch"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:red;color:white;\">IMPORTANT NOTE</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"background:purple;color:white;\">IMPORTANT REMARK</p>\n",
    "<br>\n",
    "You have probably noticed that there appear some errors regarding TFs in RViz.\n",
    "<img src=\"img/tfs_error.png\" width=\"250\" />\n",
    "<br>\n",
    "Can you guess why this is happening? Well, this is happening because you haven't published any TF for your robot. You have created the structure of it with the URDF file, but in order to have a full operational robot, you would need to also publish it's TFs. But you may ask... then why some TFs are working fine? Well, that's because they are being published by the simulation you have launched, which contains the same robot of your URDF file.\n",
    "<br><br>\n",
    "Anyways, in this Course we are not going to focus on TFs, so that's why you are not publishing any. If you are interested in learning how to publish TFs for your robot, you should take a look to the <b>TF ROS 101</b> Course from the <a href=\"http://www.theconstructsim.com/construct-learn-develop-robots-using-ros/robotigniteacademy_learnros/\" target=\"_blank\">Robot Ignite Academy</a>. But as I said, concerning this Course, you don't have to worry about TFs, because you will be provided with fully functional simulations.\n",
    "<p style=\"background:purple;color:white;\">IMPORTANT REMARK</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you have seen, Xacro macros make very easy the task of adding a robot to any URDF file. But actually, you can load any kind of URDF code by using this method. For instance, you could also add a gripper to the robot very easily. You'll just have to find a xacro macro that defines a gripper and add it to your robot just as you've seen with the previous Exercise. This way, it makes very easy to switch between different end-effectors (grippers, articulated hands...) for your robot. You could even also change the robot you are using by just modifying a few lines!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Well, so now that you already have built your whole industrial environment, let's create a MoveIt package for it!"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python [Root]",
   "language": "python",
   "name": "Python [Root]"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}