Routing Protocol for Low-Power and Lossy Networks

(RPL)
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.
 The objective functions
o Optimize or constrain the routing metrics that are used to form the
routes and hence help in choosing the best route.
o 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.
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.

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
~/contiki-2.7/core/net/rpl/rpl-of0.c
~/contiki-2.7/core/net/rpl/rpl-mrhof.c
~/contiki-2.7/tools/cooja
Related Files and Functions
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

RPL_CONF_STATS

/* RPL_CONF_STATS */
#ifndef RPL_CONF_STATS
#define RPL_CONF_STATS 0
#endif

Here RPL Configuration statistics are disabled. To enable we need it to set to 1.

RPL_DAG_MC

/* 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

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

/* RPL_CONF_OF */
#ifdef RPL_CONF_OF
#define RPL_OF RPL_CONF_OF
#else
#define RPL_OF rpl_mrhof
#endif

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

#ifdef RPL_CONF_LEAF_ONLY
#define RPL_LEAF_ONLY RPL_CONF_LEAF_ONLY
#else
#define RPL_LEAF_ONLY 0
#endif

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

#ifndef RPL_CONF_INIT_LINK_METRIC
#define RPL_INIT_LINK_METRIC 5
#else
#define RPL_INIT_LINK_METRIC RPL_CONF_INIT_LINK_METRIC
#endif

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-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)

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;
}

 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)

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;
}
}

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)

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;
}
}

 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)

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 */
}

 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() to compare the path metrics of the two parents.
neighbor_link_callback(rpl_parent_t *p, int status, int numtx)

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;
}
}

 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)

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;
}

 This is similar to the 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 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)
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;

}

 This is similar tto the best_parent() function earlier which compares the two parents
and returns the best one.
 Here 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.
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

The above figure shows a sample network topology which can be used.
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:

 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:
Note: You can refer to Cooja Simulator for an introduction to Cooja.

 Run Cooja

Go to your Contiki folder(contiki-2.7) and then go to /tools/cooja directory

Run the command sudo ant run to open up a cooja GUI.

$ 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).
The following screen will pop up.

 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.
The new simulation created will open up multiple windows as shown.
  Add Sink Mote
 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.

 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.
Compile the code and create many motes of this type according to the topology.
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.

 Add Communication Links

 Add two communication links between each set of nodes so that the communication
can be bidirectional.
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.

 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.
 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.
 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.

 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.
You can use these messages saved in file to make observations and plot
graphs according to the objective of your experiment.

****************