View source for RPL objective function modification and simulation in cooja

[[Contiki_tutorials | Back to Contiki Tutorials]]

__TOC__

== Introduction ==
The Routing Protocol for Low-Power and Lossy Networks (RPL) builds a Destination Oriented Directed Acyclic Graph (DODAG) using the Objective Function (OF). The Objective Function uses routing metrics to form the DODAG based on some algorithm or calculation formula. Basically the objective functions optimize or constrain the routing metrics that are used to form the routes and hence help in choosing the best route. There could be many objective functions in operation on the same node and mesh network because deployments vary greatly with different objectives and a single mesh network may need to carry traffic with very different requirements of path quality.

The Contiki implementation of RPL, there are 2 objective functions, but by default it uses the one that minimizes the ETX values. But the same cannot be the best routing strategy in all routing scenarios. Hence there arises a need to modify the objective function accordingly to accommodate any additional constraints or to achieve a different objective.

== You Will learn ==
The basic assumption of this tutorial is that you know the working of the Routing Protocol for Low-Power and Lossy Networks (RPL). Here the Contiki OS 2.7v implementation of RPL is used and explained.<br> The following are explained in this tutorial:
* Different RPL related functions and their working
* Example scenarios and modification of RPL Objective Function
* Simulation in Cooja using DGRM model

== Source Code and Directories ==
~/contiki-2.7/core/net/rpl/rpl-conf.h<br>
~/contiki-2.7/core/net/rpl/rpl-of0.c<br>
~/contiki-2.7/core/net/rpl/rpl-mrhof.c<br>
~/contiki-2.7/tools/cooja<br>

== Related Files and Functions ==
<!-- File name, Location path, important variables, important functions -->
<!-- link between the files which function is called by whom -->
<!-- example problem statement and topology -->
<!-- how modification is made i.e. in which part of code and how it affects i.e. logic -->
Some of the important files that have the gist of RPL are rpl-config.h, rpl-of0.c, rpl-mhrof.c. However only some of the important functions in these files are mentioned here.

=== rpl-config.h ===

<!--=== Function call hierarchy during each function description === -->
==== RPL_CONF_STATS ====
<source lang=c>
/* RPL_CONF_STATS */
#ifndef RPL_CONF_STATS
#define RPL_CONF_STATS 0
#endif 
</source>
Here RPL Configuration statistics are disabled. To enable we need it to set to 1.

==== RPL_DAG_MC ====
<source lang=c>
/* RPL_CONF_DAG_MC */
#ifdef RPL_CONF_DAG_MC
#define RPL_DAG_MC RPL_CONF_DAG_MC
#else
#define RPL_DAG_MC RPL_DAG_MC_NONE
#endif 
</source>

Here RPL metric container of the type using ETX and ENERGY are supported. However if you develop an objective function and an associated metric container can be supported.

==== RPL_OF ====
<source lang=c>
/* RPL_CONF_OF */
#ifdef RPL_CONF_OF
#define RPL_OF RPL_CONF_OF
#else
#define RPL_OF rpl_mrhof
#endif 
</source>

'''The RPL_CONF_OF parameter configures the RPL objective function.''' ETX is the default objective function here. This should be defined to be the name of an rpl_of object linked into the system image, e.g., rpl_of0. Here you can also define it to be your own developed Objective function. 

==== RPL_LEAF_ONLY ====
<source lang=c>
#ifdef RPL_CONF_LEAF_ONLY
#define RPL_LEAF_ONLY RPL_CONF_LEAF_ONLY
#else
#define RPL_LEAF_ONLY 0
#endif
</source>

The node should stay as a leaf node or not is decided by this value.(as mentioned in draft-ietf-roll-rpl-19#section-8.5)

==== RPL_INIT_LINK_METRIC ====
<source lang=c>
#ifndef RPL_CONF_INIT_LINK_METRIC
#define RPL_INIT_LINK_METRIC        5
#else
#define RPL_INIT_LINK_METRIC        RPL_CONF_INIT_LINK_METRIC
#endif
</source>

This is the initial metric attributed to the link when ETX is unknown. It can be changed to any desirable value. Further as we will see we will set this value to 1.

<!--=== rpl-dag.c ===-->
<!--This file has logic for Directed Acyclic Graphs in RPL.-->
<!--=== rpl.c ===-->

=== rpl-of0.c ===
An implementation of RPL's objective function 0 is in this file.

==== calculate_rank(rpl_parent_t *p, rpl_rank_t base_rank)====
[[File:CalculateRank.png|border|300px|right|If parent is NULL then base_rank is incremented by a default increment else it uses information about parent to increment the base_rank.]]
<source lang=c>
static rpl_rank_t
 calculate_rank(rpl_parent_t *p, rpl_rank_t base_rank)
 {
  rpl_rank_t increment;
  if(base_rank == 0) {
    if(p == NULL) {
      return INFINITE_RANK;
    }
    base_rank = p->rank;
  }

  increment = p != NULL ?
                p->dag->instance->min_hoprankinc :
                DEFAULT_RANK_INCREMENT;

  if((rpl_rank_t)(base_rank + increment) < base_rank) {
    PRINTF("RPL: OF0 rank %d incremented to infinite rank due to wrapping\n",
        base_rank);
    return INFINITE_RANK;
  }
  return base_rank + increment;
 }
</source>
Here rank of a node is calculated. The rank of the node is based on its parents rank and base rank. If the base rank is zero and the node has no parent then the rank of the node is infinite. If the base rank is zero and parent is present then the base rank becomes equal to the parent rank. If the base rank is not zero, then depending if the parent is present or not the increment becomes min_hoprankinc of the parent in the DAG instance or DEFAULT_RANK_INCREMENT. In short if Parent is NULL then base_rank is incremented by a default increment else it uses information about parent to increment the base_rank. In the last part, if the calculated new rank is less than the base rank then the new rank becomes infinity due to wrapping around. The new calculated rank is equal to the base rank added with the increment.

==== best_dag(rpl_dag_t *d1, rpl_dag_t *d2) ====
<source lang=c>
static rpl_dag_t *
best_dag(rpl_dag_t *d1, rpl_dag_t *d2)
{
  if(d1->grounded) {
    if (!d2->grounded) {
      return d1;
    }
  } else if(d2->grounded) {
    return d2;
  }

  if(d1->preference < d2->preference) {
    return d2;
  } else {
    if(d1->preference > d2->preference) {
      return d1;
    }
  }

  if(d2->rank < d1->rank) {
    return d2;
  } else {
    return d1;
  }
}
</source>

This function compares two DAGs and returns the best of the Two DAGs (passed as input d1 and d2)according to the Objective function. There are 3 criteria to find the best DAG here. The first one is to find if the DAG is grounded. Second is the preference metric of each DAG. The third one is the rank of each DAG.

==== best_parent(rpl_parent_t *p1, rpl_parent_t *p2) ====
[[File:BestParents.png|border|500px|right|Child c1 chooses Parent p1 according to OF.]]
<source lang=c>
static rpl_parent_t *
best_parent(rpl_parent_t *p1, rpl_parent_t *p2)
{
  rpl_rank_t r1, r2;
  rpl_dag_t *dag;
  
  PRINTF("RPL: Comparing parent ");
  PRINT6ADDR(rpl_get_parent_ipaddr(p1));
  PRINTF(" (confidence %d, rank %d) with parent ",
        p1->link_metric, p1->rank);
  PRINT6ADDR(rpl_get_parent_ipaddr(p2));
  PRINTF(" (confidence %d, rank %d)\n",
        p2->link_metric, p2->rank);


  r1 = DAG_RANK(p1->rank, p1->dag->instance) * RPL_MIN_HOPRANKINC  +
         p1->link_metric;
  r2 = DAG_RANK(p2->rank, p1->dag->instance) * RPL_MIN_HOPRANKINC  +
         p2->link_metric;

  dag = (rpl_dag_t *)p1->dag; /* Both parents must be in the same DAG. */
  if(r1 < r2 + MIN_DIFFERENCE &&
     r1 > r2 - MIN_DIFFERENCE) {
    return dag->preferred_parent;
  } else if(r1 < r2) {
    return p1;
  } else {
    return p2;
  }
}
</source>

This function compares two parents and returns the best one according to the Objective function. Here the parents are compared based on their rank and the ETX value of that parent. This is one of the important functions, since the route formation is based on this after choosing the best DAG.

=== rpl-mhrof.c ===
The Minimum Rank with Hysteresis Objective Function (MRHOF) is implemented in this file. The objective function uses ETX as routing metric and it also has stubs for energy metric.

==== calculate_path_metric(rpl_parent_t *p) ====
<source lang=c>
static rpl_path_metric_t
calculate_path_metric(rpl_parent_t *p)
{
  if(p == NULL) {
    return MAX_PATH_COST * RPL_DAG_MC_ETX_DIVISOR;
  }

#if RPL_DAG_MC == RPL_DAG_MC_NONE
  return p->rank + (uint16_t)p->link_metric;
#elif RPL_DAG_MC == RPL_DAG_MC_ETX
  return p->mc.obj.etx + (uint16_t)p->link_metric;
#elif RPL_DAG_MC == RPL_DAG_MC_ENERGY
  return p->mc.obj.energy.energy_est + (uint16_t)p->link_metric;
#else
#error "Unsupported RPL_DAG_MC configured. See rpl.h."
#endif /* RPL_DAG_MC */
}
</source>

Here path metric is calculated according to the OF. If no parent is present then a default metric which is calculated based on Maximum Path Cost is used. If no OF is mentioned then path metric is sum of rank( and link metric. For OF based on ETX, it is sum of ETX measured (p->mc.obj.etx) and link metric. Similarly if the OF is based on Energy then energy value (p->mc.obj.energy.energy_est) is added to the link metric. This function is called by [[#best_parent.28rpl_parent_t_.2Ap1.2C_rpl_parent_t_.2Ap2.29_2|best_parent()]] to compare the path metrics of the two parents.

==== neighbor_link_callback(rpl_parent_t *p, int status, int numtx) ====
<source lang=c>
static void
neighbor_link_callback(rpl_parent_t *p, int status, int numtx)
{
  uint16_t recorded_etx = p->link_metric;
  uint16_t packet_etx = numtx * RPL_DAG_MC_ETX_DIVISOR;
  uint16_t new_etx;

  /* Do not penalize the ETX when collisions or transmission errors occur. */
  if(status == MAC_TX_OK || status == MAC_TX_NOACK) {
    if(status == MAC_TX_NOACK) {
      packet_etx = MAX_LINK_METRIC * RPL_DAG_MC_ETX_DIVISOR;
    }

    new_etx = ((uint32_t)recorded_etx * ETX_ALPHA +
               (uint32_t)packet_etx * (ETX_SCALE - ETX_ALPHA)) / ETX_SCALE;

    PRINTF("RPL: ETX changed from %u to %u (packet ETX = %u)\n",
        (unsigned)(recorded_etx / RPL_DAG_MC_ETX_DIVISOR),
        (unsigned)(new_etx  / RPL_DAG_MC_ETX_DIVISOR),
        (unsigned)(packet_etx / RPL_DAG_MC_ETX_DIVISOR));
    p->link_metric = new_etx;
  }
}
</source>

This function receives link-layer neighbor information. The parameter status is set either to 0 or 1. The numetx parameter specifies the current ETX(estimated transmissions) for the neighbor. The recorded ETX is the link_metric and packet ETX is the numetx parameter passed to the function. The new_etx is calculated based on the formula using both the recorded and packet ETX values. The link_metric is updated with the new ETX value.

==== calculate_rank(rpl_parent_t *p, rpl_rank_t base_rank) ====
<source lang=c>
static rpl_rank_t
calculate_rank(rpl_parent_t *p, rpl_rank_t base_rank)
{
  rpl_rank_t new_rank;
  rpl_rank_t rank_increase;

  if(p == NULL) {
    if(base_rank == 0) {
      return INFINITE_RANK;
    }
    rank_increase = RPL_INIT_LINK_METRIC * RPL_DAG_MC_ETX_DIVISOR;
  } else {
    rank_increase = p->link_metric;
    if(base_rank == 0) {
      base_rank = p->rank;
    }
  }

  if(INFINITE_RANK - base_rank < rank_increase) {
    /* Reached the maximum rank. */
    new_rank = INFINITE_RANK;
  } else {
   /* Calculate the rank based on the new rank information from DIO or
      stored otherwise. */
    new_rank = base_rank + rank_increase;
  }

  return new_rank;
}
</source>

This is similar to the [[#calculate_rank.28rpl_parent_t_.2Ap.2C_rpl_rank_t_base_rank.29|calculate_rank()]] function explained earlier but with a slight difference. In this OF, the rank_increase is the increment which is equal to [[#RPL_INIT_LINK_METRIC|RPL_INIT_LINK_METRIC]] if parent = NULL. Else it is equal to the link_metric. The new rank is the increment added to the base rank.

==== best_parent(rpl_parent_t *p1, rpl_parent_t *p2) ====
<source lang=c>
static rpl_parent_t *
best_parent(rpl_parent_t *p1, rpl_parent_t *p2)
{
  rpl_dag_t *dag;
  rpl_path_metric_t min_diff;
  rpl_path_metric_t p1_metric;
  rpl_path_metric_t p2_metric;

  dag = p1->dag; /* Both parents are in the same DAG. */

  min_diff = RPL_DAG_MC_ETX_DIVISOR /
             PARENT_SWITCH_THRESHOLD_DIV;

  p1_metric = calculate_path_metric(p1);
  p2_metric = calculate_path_metric(p2);

  /* Maintain stability of the preferred parent in case of similar ranks. */
  if(p1 == dag->preferred_parent || p2 == dag->preferred_parent) {
    if(p1_metric < p2_metric + min_diff &&
       p1_metric > p2_metric - min_diff) {
      PRINTF("RPL: MRHOF hysteresis: %u <= %u <= %u\n",
             p2_metric - min_diff,
             p1_metric,
             p2_metric + min_diff);
      return dag->preferred_parent;
    }
  }

  return p1_metric < p2_metric ? p1 : p2;
}
</source>

This is similar tto the [[#best_parent.28rpl_parent_t_.2Ap1.2C_rpl_parent_t_.2Ap2.29|best_parent()]] function earlier which compares the two parents and returns the best one. Here [[#calculate_path_metric.28rpl_parent_t_.2Ap.29 |path metric]] calculated for each parent is the basis for comparison. First it is checked if any of the parent is set as the preferred parent in the DAG formed and if so then it is chosen as the best parent (based on the MRHOF hysteresis RFC 6719). Otherwise, the two calculated metrics are compared and the parent with the lower metric is the best parent. In this OF, a switch is made to that minimum Rank path only if it is shorter (in terms of path cost) than the current path by at least a given threshold.  This second mechanism is called "hysteresis" (RFC 6719).Here the PARENT_SWITCH_THRESHOLD_DIV is defined to be 2.<br>
This parent selection occurs in the following cases 
* during the initial formation of the network or
* when path cost to the neighboring nodes changes or 
* a new node appears in the neighborhood of the node

== Example scenario for objective function modification ==
[[File:SampleNetTopology.png|border|500px|center|Sample Network Topology]]<br>
The above figure shows a sample network topology which can be used.<br>
To define a completely new Objective Function file(without modifying the existing one) the following functions must be defined in them. Also the makefile should be accordingly modified and care should be taken that your new file should not run into compilation and linking errors. Some of the RPL API functions are:<br>
* reset(dag): Resets the objective function state for a specific DAG. This function is called when doing a global repair on the DAG.
* neighbor_link_callback(parent, status, etx): Receives link-layer neighbor information.
* best_parent(parent1, parent2): Compares two parents and returns the best one, according to the OF.
* best_dag(dag1, dag2): Compares two DAGs and returns the best one, according to the OF.
* calculate_rank(parent, base_rank): Calculates a rank value using the parent rank and a base rank.
* update_metric_container(dag): Updates the metric container for outgoing DIOs in a certain DAG. If the objective function of the DAG does not use metric containers, the function should set the object type to RPL_DAG_MC_NONE.

== Cooja Simulation using DGRM model ==
The DGRM model is used since it is easier to change the link reception rate. Also it is easier to form a link between two desired nodes excluding the others.
The following are the steps to form a new simulation:<br>
'''''Note:''''' You can refer to [[Cooja Simulator]] for an introduction to Cooja.<br>
*'''Run Cooja'''
Go to your Contiki folder(contiki-2.7) and then go to /tools/cooja directory<br> Run the command sudo ant run to open up a cooja GUI.<br>
 $ cd contiki-2.7/tools/cooja
 $ sudo ant run
*'''Start a New Simulation'''
Choose a ''New Simulation'' from the File drop down menu (or alternatively can do Ctrl+N).<br>The following screen will pop up.<br>
[[File:NewSimuScn1.jpg|border|500px|center]]<br>
Give a name to your simulation in the ''Simulation Name'' field. 
Choose the '''Directed Graph Radio Medium(DGRM)''' from the drop down menu for the ''Radio Medium'' under '''Advanced Settings'''.
Click on the ''Create'' button. <br>
The new simulation created will open up multiple windows as shown.<br>
[[File:Simu2.png|border|600px|center]]<br>
*'''Add Sink Mote'''
<!-- [[File:Simu3.png|border|500px|right]]-->
Add a mote of the type Sink. Here udp-sink code from the rpl-collect example (''/examples/ipv6/rpl-collect/'') is being used. However you can upload any code you want to implement according to your application. Click on ''Compile'' button. A ''Create'' button will appear on successful compilation which adds number of motes as desired in the network. Here only one sink is used. <br>
[[File:Simu3.png|border|500px|center]]<br>
*'''Add Sender Motes'''
Add a mote of the type Sink. Here udp-sender code from the rpl-collect example (''/examples/ipv6/rpl-collect/'') is being used. However you can upload any code you want to implement according to your application. <br>
Compile the code and create many <!--how many?????--> motes of this type according to the topology.<br>
'''''Note:''''' Placement of the mote does not matter here. You can place your motes anywhere in the graph. Since this is different than the distance model, we make explicit links between the motes for communication, hence distance between them makes no difference.<br> <br>

*'''Add Communication Links'''
<!-- [[File:Simu4.png|border|250px|right]]-->
Add two communication links between each set of nodes so that the communication can be bidirectional.<br> Click on Tools->DGRM Links... This will open a DGRM Configurator Dialog box. Click on Add. Select source and destination nodes and again click on add. This will add a unidirectional link from the source to destination node. For a bidirectional link you need to add one more link with source and destination nodes switched. You can add multiple links in this way. After adding the links close the dialog box.<br>
[[File:Simu4.png|border|300px|center]]<br>
You can change other parameters of the link such as ''RX ratio, RSSI, LQI'' and ''Delay'' according to your application. These parameters affect the individual link quality eg. ''RX ratio'' affect the ETX values. So to test your application under various Link Quality conditions these parameters can be changed. <br>

Also you can Delete an existing one using the remove option. The Import option helps in importing any data file which already has these link connections and parameters specified in it. <br>

*'''Run Simulation'''
Run the simulation by using the ''Start'' option in the ''Simulation Control'' window. This will initiate the motes and allocate all with a new Rime address and other initialization processes. <br>

*'''Watch Output'''
The motes output and debug messages can be seen in the ''Motes Output'' window. You can filter the output based on the node ''ID:node_id'' to watch a particular node. You can also watch particular debug messages by filtering them. The other useful functions of the ''Motes Output'' are ''File, Edit'' and ''View''. The ''File'' option helps in saving the output to a file. The ''Edit'' has the option of copying the output - either full or a particular selected messages. You can also clear the messages using the ''Clear all messages'' option.<br>
You can use these messages saved in file to make observations and plot graphs according to the objective of your experiment.<br>
<!-- Use one or two figures showing graph formation -->

== General Issues ==
While running cooja be sure to run as sudo ant run since running only ant run might throw up some errors since it might not be able to access some files.<br>
If the network is huge or ETX values are large, it might take a while for the packets from the leaf node to reach the root sink node. Hence you might have to run the simulation for a long time.<br>


== References ==
RFC 6550 RPL: IPv6 Routing Protocol for Low-Power and Lossy Networks<br>
RFC 6552 Objective Function Zero for the Routing Protocol for Low-Power and Lossy Networks (RPL)<br>
RFC 6719 MRHOF: The Minimum Rank with Hysteresis Objective Function <br>
[http://home.deib.polimi.it/cesana/teaching/IoT/papers/routing/RPL.pdf] IPSO Alliance RPL April 2011<br>
[http://dunkels.com/adam/ko11contikirpl.pdf] ContikiRPL



Edited by - Ashwini Telang <br> <br>
[[Contiki_tutorials | Back to Contiki Tutorials]]