Create a new Application

Guide to help you create a new project using OnOrbitROS framework.

Create the new project

Download the framework following the Installation Guide. It is recommended that the new projects are located under > orbit_ws > src as occur with the examples. After installation you will find a package template, application_template, and inside you will find the configuration, launch, messages, source code, urdf and worlds folders, as well as the prepared CMakeLists file and others needed to use the framework. You can then add the files corresponding to your specific needs.

Launch file

There is a default launch file that includes:

  • Gazebo simulation parameters.
  • Launch of the orbit and orbit publisher package.
  • The world file (converting the .xacro to .world) and then loading with then the gazebo_ros launcher.
  • Spacecraft / robot URDF loaded to the param server.
  • Loads of the ROS controllers.

Modify the world

The Gazebo world of the application is located in the worlds folder of the package and includes the physic properties of the simulation environment and the models of the orbit (by default called orbitReference). It is defined as a .xacro and converted to .urdf in the launch file as it must include the laser_scan.xacro to define the matrix of rays that simulate the air drag the spacecrafts suffer. Multiple sensors can be added and their size and position must be modified so they cover all the models of the simulations, going opposite to the direction of the motion (to calculate the atmospheric drag as it is explained in Atmospheric Drag).

By default the world is set to work under zero gravity conditions and the LVLH located in the origin of the Gazebo frame of reference. Another link is created to host the atmospheric drag sensor, which is a fixed child of the LVLH in the y axis (but the distance to the origin and z value can be modified), and then that sensor can be configured to match with the specific applications. You will find the tag <!-- custom --> in the places that are specific of each application to modify them. 

<xacro:include filename="$(find ets_vii)/urdf/laser_scan.xacro"/>   <!-- Xacro for the laser sensor -->

<!--- Load Sensors -->    
  <!-- 
    Pose offset in relation to "laser_link"; 
    Configuration of the ray: lenght, number of rays, angles of the cone; 
    Configuration of the matrix of rays: x and z number and separation; 
    Topic to publish the data (coincident with the name of the URDF spacecraft model);
  -->  
<xacro:multi_laser_scan     
          x="-1.1"          
          y="3" 
          z="0.8"
          roll="0"
          pitch="0"
          yaw="-1.5708"
          visualize="true"
          samples="1"
          min_angle="-0.0"
          max_angle="0.0"
          length_ray="5"
          num_lasers_x="10"
          num_lasers_z="20"
          offset_x="0.25" 
          offset_z="0.25" 
          topic="robot"
          reference_link="etsVii_laser_link"/>

That laser scan xacro generates num_lasers_x * num_lasers_z rays in the pose x,y,z with an offset among them of offset_x and offset_z. samples indicates the amount of rays for each sensor (forming a cone of rays), and length_ray the distance length of the ray in meters. Each sensor is fixed to a link jointed to the reference_link (by default ''name_laser_link'') and topic is the name of the URDF model of the spacecraft where the sensor information will be published (which must be coincident with the spacecraft model).

Add a spacecraft

The spacecraft and robots are loaded URDFs converted from XACROS. This is the protocol Gazebo has to load the different models in the simulation where you can define the different links, joints, controllers... of the model. You can find many guides on how to defined them, as these URDF tutorials.

After creating your desired models, you must add the Gazebo OORplugin at a plugin at the end of the model as follows: 

<gazebo>
    <plugin name="gazebo_ros_control" filename="libgazebo_ros_control.so">
        <robotNamespace>/</robotNamespace>
    </plugin>

   <plugin name="Orbit_robot_pkg_plugin" filename="libOrbit_robot_pkg_plugin.so"/> 
</gazebo>

That plugin is defined under > orbit_ws > src > orbit_robot_pkg > src > Orbit_robot_pkg_plugin.cpp, and uses the header OrbitLink.h from OrbitLink.cpp. These two latter files are used to define the properties of each link of the spacecraft, both cinematically and dynamically (such as positions, torques, velocities, etc), and to apply the gravity gradient and forces generated by the relative motion to an elliptical . Then, those methods are used by the principal file, Orbit_robot_pkg_plugin.cpp, that manages the subscription to the orbital topics explained above and manages the application of those perturbations and the atmospheric drag. The script includes comments that can be checked to better understand the implementation.

Define an orbit

The orbit is declared in a .yaml file located in orbit_ws > orbit_publisher_pkg > config (by default the file is dynamic_orbit.yaml). Then that file has to be loaded in the project's launch, which by default is basic.launch or fix_basic.launch for fixed orbits, and located under orbit_ws > orbit_publisher_pkg > launch. That launch is called from the project's main package, for example for the ETS VII application is orbit_ws > ets_vii > launch > effort_controllers_wgg.launch. The information defines the LVLH in reference to the ECI.

The information from the orbit .yaml file is read by orbit_ws > orbit_publisher_pkg > src > Orbit.cpp (that uses Orbit.h header that has all the variables and methods defined). The relevant orbit information is then published in their corresponding topics from the file orbit_ws > orbit_publisher_pkg > src > orbit_publisher_pkg_node.cpp (for fixed orbits the information is published from fix_orbit_publisher_pkg_node.cpp). In case more orbital information wants to be shared with the plugin it will be published from this script.

Default Orbit Information

Orbit information declared in the .yaml file in the Simple Orbit default module:

            publish rate
            eccentricity
            semi major axis
            inclination
            rate of right ascension
            initial right ascension
            rate of argument of perigee
            initial argument of perigee
            initial mean anomaly
            time pass perigee
            time start
            angular velocity
            atmosphere angular velocity
            atmosphere air density
            drag coefficient

Published Orbit Information

Information being published in the following topics: 

            /OrbitPosition
            /OrbitVelocity
            /AtmosphereAngularVelocity
            /OrbitAirDensity
            /OrbitDragCoeffient

Add more Orbit Information

In case more orbital information is needed, it can be declared in the .yaml file, defined in Orbit.h, read by Orbit.cppand (if needed), published from orbit_publisher_pkg_node.cpp.