====== ROS ======

===== ROS Installation =====

==== Easy way ====

  - **Choose a distribution** from the one available [[http://wiki.ros.org/Distributions|here]]
  - Make sure you got **the right Ubuntu release** for the ROS distribution you chose, check that [[http://www.ros.org/reps/rep-0003.html|here]]
  - **Follow the install step** from the ROS website for the ROS distribution you chose ([[http://wiki.ros.org/indigo/Installation/Ubuntu|to install ROS Indigo for example]])

==== Other installations ====

ROS can be install from source and on other operating systems, a list for ROS Indigo is available [[http://wiki.ros.org/indigo/Installation|here]].

===== ROS Configuration =====

Once you have install ROS, you need [[http://wiki.ros.org/ROS/Tutorials/InstallingandConfiguringROSEnvironment|to create a caktin work space and to build it]]. After that you should setup you terminal to access all ROS features, so add these few lines to your bashrc.
<code bash>
# ROS Config

# Source ROS Config files
source /opt/ros/<distro>/setup.bash

mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/
catkin_make
source devel/setup.bash

# Choose editor for rosed command
export EDITOR="subl"

# Force ROS package database to update
rospack list > /dev/null

# Force rqt plugin database to update
rm -f .config/ros.org/rqt_gui.ini
</code>
You must replace <distro> by the name of the ROS distribution you installed previously. The environment variable EDITOR show which editor you want to use when you call the ROS command : rosed. The rospack line force ROS to update is package list and **make all new package available to auto completion tab**.

===== How to create a ROS Package =====
Here is a simple way to create an empty ros package, follow the instructions.
<code bash>
cd ~/catkin_ws/src
catkin_create_pkg NamePackage Dependency1 Dependency2
cd ..
catkin_make
source ../.bashrc
</code>
If you choose to create a package where you will use c++, **don't forget to add roscpp as dependency**. It will create a more custom CMakeList and it will be easier (The same things is true for Python with rospy).
===== How to install a ROS Package =====
To install new package use apt-get, for example for web_video_server package type this in a terminal :
<code bash>
sudo apt-get install ros-indigo-web-video-server
</code>
Once apt-get finished, don't forget to source bashrc.
<code bash>
source ~/.bashrc
</code>

===== Some ROS Package =====

You can have the whole list [[http://www.ros.org/browse/list.php|here]]
  * [[http://www.ros.org/browse/details.php?distro=indigo&name=gazebo_ros_pkgs|gazebo_ros_pkgs]] : software suite to communicate between ROS and GAZEBO
  * [[http://www.ros.org/browse/details.php?distro=indigo&name=image_view|image_view]] : display a camera flux
  * [[http://www.ros.org/browse/details.php?distro=indigo&name=ros_control|ros_control]] : robot control management
  * [[http://www.ros.org/browse/details.php?distro=indigo&name=robot_state_publisher|robot_state_publisher]] : publish the 3D poses of the robot links
  * [[http://www.ros.org/browse/details.php?distro=indigo&name=rosbridge_server|rosbridge_server]] : allow to access to ROS using Javascript on a web server
  * [[http://www.ros.org/browse/details.php?distro=indigo&name=turtlesim|turtlesim]] : first ROS tutorial
  * [[http://www.ros.org/browse/details.php?distro=indigo&name=web_video_server|web_video_server]] : give a remote access to all video topic

===== Useful commands =====
==== Navigate throught ROS file system ====
  * [[http://wiki.ros.org/rospack|rospack]] : info on ROS packages
  * [[http://wiki.ros.org/rosbash#roscd|roscd]] : go into a ROS package directory
  * [[http://wiki.ros.org/rosbash#rosls|rosls]] : list a ROS package directory content
  * [[http://wiki.ros.org/rosbash#rosed|rosed]] : edit a ROS package file

==== Launching ROS ====
  * [[http://wiki.ros.org/roscore|roscore]] : start ROS Master, ROS Parameter Server, log node
  * [[http://wiki.ros.org/rosbash#rosrun|rosrun]] : start a ROS node
  * [[http://wiki.ros.org/roslaunch|roslaunch]] : start multiple nodes
==== Getting information ====
  * [[http://wiki.ros.org/rostopic|rostopic]] : info on topics
  * [[http://wiki.ros.org/rosnode|rosnode]] : info on nodes
  * [[http://wiki.ros.org/rosmsg|rosmsg]] : info on messages
  * [[http://wiki.ros.org/rqt_graph|rqt_graph]] : show all the nodes and theirs connections


See also the [[http://download.ros.org/downloads/ROScheatsheet.pdf|ROS Cheat Sheet]].

===== Launch files =====
The launch files are use to start multiple nodes at once. They use an [[http://wiki.ros.org/roslaunch/XML|XML format]].


===== Description of the robot =====

**ROS** and **GAZEBO** don't use same files to describe robots. **GAZEBO** is a stand alone and use **SDF** files whereas **ROS** use **URDF** files. They are both XML file.

  * [[http://wiki.ros.org/urdf/XML|URDF Specifications]]
  * [[http://sdformat.org/spec|SDF Specifications]]


===== GAZEBO Simulator =====
ROS and GAZEBO can work together only if you pick **the right version for each of them**, see [[http://gazebosim.org/tutorials?tut=ros_wrapper_versions&cat=connect_ros|this]] for more information. For example, ROS Indigo work only with GAZEBO V2.


GAZEBO is a stand alone now, but it can still communicate with ROS thanks to gazebo_ros_pkgs. Install it.
<code bash>
sudo apt-get install ros-indigo-gazebo-ros-pkgs
</code>
In order for GAZEBO to work, you need to add some lines to your bashrc.
<code bash>
# Gazebo Config
source /usr/share/gazebo/setup.sh 
source /usr/share/gazebo-2.2/setup.sh
</code>
You can now launch gazebo with ROS. Start ROS Master in a terminal.
<code bash>
roscore
</code>
In an other terminal, start gazebo with gazebo_ros.
<code bash>
rosrun gazebo_ros gazebo
</code>
You can now use GAZEBO with ROS. For more information about the gazebo_ros_pkgs install check that [[http://gazebosim.org/tutorials?tut=ros_installing&cat=connect_ros|link]].


===== URDF Integration in GAZEBO =====
==== Setup the file hierarchy ====

We are going to implement a simple robot in URDF and then spawn it into GAZEBO.
Let's call it MYROBOT.

First let's create all the packages.
<code bash>
cd ~/catkin_ws/src
catkin_create_pkg MYROBOT_description
catkin_create_pkg MYROBOT_gazebo
source ~/.bashrc
</code>

The file hierarchy for our packages should be like this. Catkin_create_pkg only create package.xml and CMakeLists.txt, you have too create the rest by your own.
<code>
../catkin_ws/src
    /MYROBOT_description
        package.xml
        CMakeLists.txt
        /urdf
            MYROBOT.urdf
        /meshes
            mesh1.dae
            mesh2.dae
            ...
        /materials
        /cad
    /MYROBOT_gazebo
        package.xml
        CMakeLists.txt
        /launch
            MYROBOT.launch
        /worlds
            MYROBOT.world
        /models
            world_object1.dae
            world_object2.stl
            world_object3.urdf
        /materials
        /plugins
</code>
More information [[http://gazebosim.org/tutorials/?tut=ros_roslaunch|there]].

==== Create the URDF file ====

Create the file according with [[http://wiki.ros.org/urdf/XML|URDF Specifications]].
Once you have created the file, you can check it with this command.
<code bash>
check_urdf MYROBOT.urdf
</code>
You can also print it as a graph to have a better view of your model.
<code bash>
urdf_to_graphiz MYROBOT.urdf
</code>
For more information see [[http://wiki.ros.org/urdf|URDF Package Documentation]].

In order to be GAZEBO compatible, you URDF file [[http://gazebosim.org/tutorials?tut=ros_urdf&cat=connect_ros|must set <inertia> element within each <link> element]].

==== Create the Launch file ====
Create MYROBOT.launch and paste this.
<code xml>
<launch>
  <!-- We resume the logic in empty_world.launch, changing only the name of the world to be launched -->
  <include file="$(find gazebo_ros)/launch/empty_world.launch">
    <arg name="world_name" value="$(find MYROBOT_gazebo)/worlds/MYROBOT.world"/>
    <!-- more default parameters can be changed here -->
  </include>
</launch>
</code>
For a deep understanding of this launch file you can check /opt/ros/indigo/share/gazebo_ros/launch/empty_world.launch in your computer (It's the default path if you didn't touch anything) and read [[http://wiki.ros.org/roslaunch/XML|.launch Specifications]].

==== Create the World file ====
Eventually, create MYROBOT.world and paste this.
<code xml>
<?xml version="1.0" ?>
<sdf version="1.4">
  <world name="default">
    <include>
      <uri>model://ground_plane</uri>
    </include>
    <include>
      <uri>model://sun</uri>
    </include>
    <include>
      <uri>model://gas_station</uri>
      <name>gas_station</name>
      <pose>-2.0 7.0 0 0 0 0</pose>
    </include>
  </world>
</sdf>
</code>
Check the [[http://sdformat.org/spec|SDF Specifications]] for further explanations.

==== Launching our world ====
We can now launch the world.
<code bash>
roslaunch MYROBOT_gazebo MYROBOT.launch
</code>

==== Spawning MYROBOT in GAZEBO ====
Add this line to MYROBOT.launch.
<code xml>
<!-- Spawn a robot into Gazebo -->
  <node name="spawn_urdf" pkg="gazebo_ros" type="spawn_model" args="-file `rospack find MYROBOT_description`/urdf/MYROBOT.urdf -urdf -model 'MYROBOT'" />
</code>
Relaunch MYROBOT.launch. MYROBOT should be in GAZEBO.

==== Improve URDF file using XACRO ====
Xacro (XML Macros) is an XML macro language, it allows you to use variables, math operations and [[http://wiki.ros.org/xacro|other features]].

First, make sure that you have Xacro package install on your computer.
<code bash>
sudo apt-get install ros-indigo-xacro
</code>

Then you need to make a modification in your MYROBOT.urdf.
<code xml>
<robot name="MYROBOT">
   <!-- #### Random Robot Code -->
</robot>
</code>
Become.
<code xml>
<?xml version="1.0"?>
<robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="MYROBOT">
   <!-- #### Random Robot Code -->
</robot>
</code>

Finally, change the file extension by .xacro, it's just to remind you, that it's not an URDF file anymore. You can from now on add [[http://wiki.ros.org/urdf/Tutorials/Using%20Xacro%20to%20Clean%20Up%20a%20URDF%20File|variables and stuffs]].

In order to use xacro file, we need to translate it in urdf again. One way to do that is by adding this lines at the top of your MYROBOT.launch.

<code xml>
<!-- ##### loading parameters ##### -->
<!-- This line convert the xacro file into urdf and stock it in ROS Parameter Server under the name /MYROBOT/robot_description -->
 <param name="/MYROBOT/robot_description" command="$(find xacro)/xacro.py '$(find MYROBOT_description)/urdf/MYROBOT.xacro'" />
</code>

And change the line that spawn MYROBOT in GAZEBO simulator.
<code xml>
<!-- Spawn a robot into Gazebo -->
<!-- We just change the argument file by param, to indicate that the URDF description file is in the ROS parameters server -->
 <node name="spawn_urdf" pkg="gazebo_ros" type="spawn_model" args="-param /MYROBOT/robot_description -urdf -model 'MYROBOT'" />
</code>

You can relaunch your launch file now.

==== Recapitulation ====
The robot description go on further transformations.
|              ^ Xacro -> Urdf        ^ Urdf -> Sdf        ^
^ Command Used   | xacro.py          | gzsdf        |
^ When   | Loading robot description in ROS parameters server   | Spawning robot in GAZEBO simulator        |

You can use gzsdf command to see the sdf file generated by GAZEBO when you spawn MYROBOT, useful for debugging.
==== <gazebo> One more thing </gazebo> ====

You can add the gazebo tag to specify gazebo properties in your URDF/XACRO file. The common way to do it, is to create a MYROBOT.gazebo in MYROBOT_description/urdf. You should put all the gazebo tag in this file and then include it in your MYROBOT.xacro using this line.
<code xml>
<!-- Include -->
  <xacro:include filename="$(find MYROBOT_description)/urdf/MYROBOT.gazebo" />
</code>
[[http://gazebosim.org/tutorials/?tut=ros_urdf|Here]] is a tutorial using <gazebo> </gazebo>.

Thus the file hierarchy look like this now.
<code>
../catkin_ws/src
    /MYROBOT_description
        package.xml
        CMakeLists.txt
        /urdf
            MYROBOT.xacro
            MYROBOT.gazebo
    /MYROBOT_gazebo
        package.xml
        CMakeLists.txt
        /launch
            MYROBOT.launch
        /worlds
            MYROBOT.world
</code>
===== GAZEBO plugins in ROS =====

With the GAZEBO plugins, you can access sensors data and motor control using ROS messages and services.
The plugins are added using the <gazebo> tag. You can find how adding plugins and a list of all plugins available in gazebo_plugins package [[http://gazebosim.org/tutorials?tut=ros_gzplugins&cat=connect_ros|here]].


For more information you can go to the [[http://dev.quimesis.be/wiki/doku.php?id=gazebo_plugin|QuimWiki GAZEBO plugin overview page]].
===== ROS_Control =====

==== Overview ====
According to its creator, ROS_Control allows you to lower the ROS entry barrier to the driver level. It allow you to focus only on drivers and high level application. ROS_Control is made up by two elements, **controllers** and **a robot hardware abstraction**. They are linked by **hardware interface**. There is a picture.

{{roscontrol.png}}

This image is from the following presentation.

  * [[http://roscon.ros.org/2014/wp-content/uploads/2014/07/ros_control_an_overview.pdf|Slides ros_control_an_overview]]
  * [[https://vimeo.com/107507546|Video ros_control_an_overview]]

==== Setup your URDF file ====
You need to add in MYROBOT.xacro some transmission elements. One for each **hardware interfaces** you will use. Check the [[http://wiki.ros.org/urdf/XML/Transmission|Transmission xml specifications]].

<code xml>
<transmission name="MYTRANS">
	<type>transmission_interface/SimpleTransmission</type>
	<joint name="MYJOINT">
		<hardwareInterface>VelocityJointInterface</hardwareInterface>
	</joint>
	<actuator name="MYACT">
		<mechanicalReduction>1</mechanicalReduction>
	</actuator>
</transmission>
</code>

**MYJOINT** refer to one of your robot joints already define. They must have the **same name**. See the [[http://wiki.ros.org/urdf/XML/joint|Joint Specifications]] if you have forgot. The full **transmission type list** is available [[http://docs.ros.org/api/transmission_interface/html/c++/group__transmission__types.html|here]] and the full **hardwareInterface list** [[http://wiki.ros.org/ros_control#Hardware_Interfaces|there]] and [[http://docs.ros.org/api/hardware_interface/html/c++/namespacehardware__interface.html|over there]].


==== Create the Robot Hardware Abstraction ====

First make sure you have install ros control.

Then you need to create a new package with the **roscpp** and the **controller_manager** dependencies.

<code bath>
catkin_create_pkg MYPACKAGE roscpp controller_manager
</code>

Then paste the following code in src/MY_SUPER_CPP.cpp
<code c++>
#include <hardware_interface/joint_command_interface.h>
#include <hardware_interface/joint_state_interface.h>
#include <hardware_interface/robot_hw.h>
#include <iostream>
#include <fstream>
#include <unistd.h>
#include <controller_manager/controller_manager.h>
#include <string>
#include <transmission_interface/simple_transmission.h>
#include <transmission_interface/transmission_interface.h>

#include "ros/ros.h"


using namespace transmission_interface;

class MyRobot : public hardware_interface::RobotHW
{
public:
  MyRobot()
  {
    //HardWare Interfaces
    //connect and register the joint state interface
    hardware_interface::JointStateHandle state_handle_a("MYJOINT", &j_pos[0], &j_vel[0], &j_eff[0]);
    jnt_state_interface.registerHandle(state_handle_a);

    registerInterface(&jnt_state_interface);

    //connect and register the joint position interface
    hardware_interface::JointHandle vel_handle_a(jnt_state_interface.getHandle("MYJOINT"), &j_cmd_vel[0]);
    jnt_vel_interface.registerHandle(vel_handle_a);

    registerInterface(&jnt_vel_interface);
  }

  void write(){
  }

  void read(){
  }

private:
  //Hardware Interfaces
  hardware_interface::JointStateInterface jnt_state_interface;
  hardware_interface::VelocityJointInterface jnt_vel_interface;

  double j_pos[1];
  double j_vel[1];
  double j_eff[1];

  double j_cmd_pos[1];
  double j_cmd_vel[1];
  double j_cmd_eff[1];
};


main(int argc, char **argv)
{
  ros::init(argc, argv, "MYPACKAGE_NODE");

  ros::AsyncSpinner spinner(1);
  spinner.start();

  MyRobot robot;

  ros::NodeHandle n;
  controller_manager::ControllerManager cm(&robot);

  ros::Duration period(2);

  while(ros::ok()){

    ROS_INFO("loop");
    robot.read();
    cm.update(ros::Time::now(),period);
    robot.write();

    usleep(500000);
    //period.sleep();
  }
}
</code>

There are several things to care in this file. First in the MYROBOT Constructor, you can notice the **"MYJOINT"**, it's there that we point out witch joint is connected to witch hardware interfaces. Furthermore, always in the MYROBOT Constructor, you have **jnt_state_interface** and **jnt_vel_interface**. The first one is there to give to controllers the states of MYJOINT. The Second one is there to get back the velocity command send by the controller. One should note that the joint name and the hardware interface type should be the same as describe in your transmission element in MYROBOT.xacro. [[https://github.com/ros-controls/ros_control/wiki|For more informations]].

==== Choose a controller ====
You can find and leverage a lot of controllers write by the ROS Community in the [[http://wiki.ros.org/ros_controllers|ros_controller package]]. In order for the controller to be **compatible** with MYROBOT.xacro and our Robot Hardware Abstraction file you should make sure that the **hardware interfaces** that the controller use are **define in both files**.

To understand the next example we will assume that you have create a package name MYROBOT_control with two sub-directories config and launch.
==== Summary ====
In your URDF file, take care : **MYJOINT** and **MYINTERFACE**.
<code xml>
<transmission name="MYTRANS">
	<type>transmission_interface/SimpleTransmission</type>
	<joint name="MYJOINT">
		<hardwareInterface>MYINTERFACE</hardwareInterface>
	</joint>
	<actuator name="MYACT">
		<mechanicalReduction>1</mechanicalReduction>
	</actuator>
</transmission>
</code>
In your Robot Hardware Abstraction, take care : **MYJOINT** and **MYINTERFACE**. 
<code c++>
//HardWare Interfaces
//connect and register the joint state interface
hardware_interface::JointStateHandle state_handle_a("MYJOINT", &j_pos[0], &j_vel[0], &j_eff[0]);
jnt_state_interface.registerHandle(state_handle_a);
 
registerInterface(&jnt_state_interface);
 
//connect and register the joint position interface
hardware_interface::JointHandle my_handle_a(jnt_state_interface.getHandle("MYJOINT"), &j_cmd[0]);
my_interface.registerHandle(my_handle_a);
</code>
<code c++>
//Hardware Interfaces
hardware_interface::JointStateInterface jnt_state_interface;
hardware_interface::MYINTERFACE my_interface;
</code>
In your config file in MYROBOT_control/config/MYROBOT_config.yaml, take care : **MYJOINT**. For **MYINTERFACE**, we should choose a VelocityJointInterface, because diff_drive_controller/DiffDriveController need two VelocityJointInterface.
<code yaml>
MYROBOT:
    mobile_base_controller:
        type: "diff_drive_controller/DiffDriveController"
        left_wheel: 'MYJOINT'
        right_wheel: 'MYOTHERJOINT'
        pose_covariance_diagonal: [0.001, 0.001, 1000000.0, 1000000.0, 1000000.0, 1000.0]
        twist_covariance_diagonal: [0.001, 0.001, 1000000.0, 1000000.0, 1000000.0, 1000.0]
</code>
In your launch file in MYROBOT_control/launch/MYROBOT_control.launch.
<code xml>
  <!-- Load joint controller configurations from YAML file to parameter server -->
<rosparam file="$(find MYROBOT_control)/config/MYROBOT_config.yaml" command="load"/>

  <!--  load the HardwareInterface-->
<node name="hwInterface" pkg="test_hardware_interface" type="test_hardware_interface" ns="/MYROBOT"/>

  <!-- load the controllers -->
<node name="controller_spawner" pkg="controller_manager" type="spawner" ns="/MYROBOT" args="mobile_base_controller"/>
</code>


==== Gazebo with ros_control ====

You can use ros_control with GAZEBO, there is a tutorial [[http://gazebosim.org/tutorials?tut=ros_control&cat=connect_ros|here]]. In this case, you don't need anymore your Robot Hardware Abstraction. GAZEBO come with his own Robot Hardware Abstraction. Add this to MYROBOT.gazebo.
<code xml>
<gazebo>
  <plugin name="gazebo_ros_control" filename="libgazebo_ros_control.so">
    <robotNamespace>/MYROBOT</robotNamespace>
  </plugin>
</gazebo>
</code>

==== Ros_control debug tool ====
You can install a rqt plugin named [[http://wiki.ros.org/rqt_controller_manager|rqt_controller_manager]].
<code bash>
sudo apt-get install ros-indigo-rqt-controller-manager
</code>
Don't forget to add this line to your .bashrc.
<code bash>
# Force rqt plugin database to update
rm -f .config/ros.org/rqt_gui.ini
</code>

===== References =====

Interesting links :

  * [[http://wiki.ros.org/ROS/Tutorials|Tutorials ROS]]
  * [[http://wiki.ros.org/urdf/Tutorials|Tutorials URDF]]
  * [[http://gazebosim.org/tutorials|Tutorials GAZEBO]]
  * [[http://gazebosim.org/tutorials?cat=connect_ros|Connection between ROS and GAZEBO]]
  * [[http://www.gazebosim.org/tutorials/?tut=ros_control|ROS Control in Gazebo]]
  * [[http://wiki.ros.org/roslibjs|The Standard ROS JavaScript Library]]
  * [[http://docs.ros.org/api/|Api ROS]]
  * [[http://wiki.ros.org/|Wiki ROS]]
  * [[http://docs.ros.org/api/catkin/html/index.html|Catkin ROS Doc]]
  * [[http://www.cse.sc.edu/~jokane/agitr/agitr-letter.pdf|A Gentle Introduction to ROS]]
  * [[http://www.ros.org/reps/rep-0142.html|ROS Indigo Metapackages List]]