.. _creating_a_urdf_file:

Creating a URDF File
====================

A URDF (Unified Robot Description Format) file is essential for operating a robot in the ROS
ecosystem. It provides information on the robot's kinematics, dynamics and other parameters in a
standardized format.

.. note::

   Due to the modular nature of RobCo robots, a large number of different robot configurations can
   be assembled from RobCo modules and a pre-configured URDF file cannot be provided. Instead, we
   provide `xacro <http://wiki.ros.org/xacro>`_ macros for each of the modules in our catalog. This
   way, given a robot configuration (list of module type IDs), a URDF file can be easily generated.

Finding Module Type IDs
-----------------------

Each type of RobCo module is assigned a unique numeric *module type identifier*. To find the module
type identifiers that make up the connected robot, the ``/robco_robot_composition`` topic can be
used:

.. code-block:: bash

   ros2 topic echo /robco_robot_composition

A list of module type identifiers is returned. This can be used to assemble a URDF file for the
connected robot.

.. For now, please input the returned module type IDs as a comma-separated list into
.. the following RobCo visualizer URL and open it in a browser to verify the configuration and
.. determine the type (base, drive, or link) of each module:
.. 
.. .. code-block::
.. 
..    https://visualizer.robco.de/?modules=<YOUR-MODULE-TYPE-IDS>
.. 
.. For example:
.. 
.. .. code-block::
.. 
..    https://visualizer.robco.de/?modules=106,88,89,25,85,22,85,97,801

Assembling the URDF File
------------------------

A URDF file of the following form can be created for the above robot configuration as follows:

.. code-block:: xml

   <?xml version="1.0" ?>

   <robot name="robco" xmlns:xacro="http://www.ros.org/wiki/xacro">
      <xacro:include filename="$(find robco_description)/urdf/robco_modules.xacro" />
      <xacro:include filename="$(find robco_description)/urdf/robco.ros2_control.xacro" />

      <!-- Module type IDs: 304, 301, 318, 300, 300, 8, 300, 300, 800 -->
      <xacro:robco_module_0304 name="joint0" next="joint1" />
      <xacro:robco_module_0301 name="joint1" next="link0" />
      <xacro:robco_module_0318 name="link0" next="joint2" />
      <xacro:robco_module_0300 name="joint2" next="joint3" />
      <xacro:robco_module_0300 name="joint3" next="link1" />
      <xacro:robco_module_0008 name="link1" next="joint4" />
      <xacro:robco_module_0300 name="joint4" next="joint5" />
      <xacro:robco_module_0300 name="joint5" next="tool" />
      <xacro:robco_module_0800 name="tool" />

      <!-- ros2_control setup for joints defined above -->
      <ros2_control name="RobcoRobot" type="system">
         <hardware>
            <plugin>robco_hardware/RobcoHardware</plugin>
         </hardware>
         <xacro:robco_ros2_control_joint joint_name="joint0" />
         <xacro:robco_ros2_control_joint joint_name="joint1" />
         <xacro:robco_ros2_control_joint joint_name="joint2" />
         <xacro:robco_ros2_control_joint joint_name="joint3" />
         <xacro:robco_ros2_control_joint joint_name="joint4" />
         <xacro:robco_ros2_control_joint joint_name="joint5" />
      </ros2_control>
      </robot>

Running this through ``xacro`` will expand the macros provided by the ``robco_description`` package,
with kinematics, inertia parameters and 3D models for visuals and collisions.

For more details on the provided macros and files, please see :ref:`robco_description`.