Contiki - User contributions [en]

EE 652 projects

2015-01-02T00:13:30Z

Ashwinit:

EE 652 2014 Projects

== Scheduling algorithms for IEEE 802.15.4e networks - Pedro ==

'''Repository''': http://neptune.usc.edu:8081/pdasilva/tsch-schedulers/

'''Description''':

''How to compile'': gcc -std=gnu99 -o Scheduling util/*.c graphs/*.c mcc/*.c tasa/*.c main.c

''How to execute'': ./Scheduling <sink_id> <algorithm>

where: <sink_id> = Sink identification (starting at 0) and <algorithm> = 0 if MCC and 1 if TASA

''Output'': you will find files ext_schedule.h and topology.c, which should be used according to the project report

The execution will consider data/prr55.txt file as input for PRR statistics. You need to create the file with tree description before running TASA. You can easily do that first running MCC for a given sink id (e.g. 3) and then running TASA for the same sink id.

== Heat Diffusion Routing Algorithm Contiki Implementation - Pradipta ==
'''Repository''': http://neptune.usc.edu:8081/pradipta/heat-diffusion.git

'''Description''':
This is a contiki implementation of the Heat Diffusion algorithm proposed by Reza Banirazi, Edmond A. Jonckheere, Bhaskar Krishnamachari in '''“Heat-Diffusion: Pareto optimal dynamic routing for time-varying wireless networks“, International Conference on Computer Communications (INFOCOM), 2014'''. Heat Diffusion routing is a new multi-hop wireless network routing protocol which is similar to Back-Pressure routing based on concepts of heat diffusion in classical physics

== Backpressure Control Protocol on IPv6 stack of Contiki - Mrunal and Chhavi ==

'''Repository''': https://github.com/chhavikapoor/EE652_Final

Use the branch final_project from the repository.

Follow the README-BCP in the final_project repository to simulate the implementation of BCP on IPv6 stack in COOJA.

'''Description''':

BCP is an implementation of dynamic backpressure routing in which the routing and forwarding decisions are made on per packet basis that takes into consideration the backpressure weight of each of its neighbors. The ubiquitous use of TCP/IP protocol suite in web applications, peer to peer networking over the internet etc motivated us to implement the Backpressure Collection Protocol on the IPv6 Stack of Contiki. We implemented a functional version of BCP on the IPv6 stack of Contiki OS.
In our implementation, BCP Sink by default has the node_id = 1.

== Modifications to RPL for Mobility - Pratyush Deshpande, Gopi Marella and Abhilash Hegde ==

'''Repository''': https://github.com/pratyush18/contiki-new.git

'''Description''':

Routing Protocol for Low power and lossy networks (RPL) has been recently adopted IETF routing protocol standard for low power wireless sensor networks and Internet of Things applications. Originally RPL is designed for static networks with no support for mobility. But, several IoT applications involve mobile nodes and thus there is a need to modify RPL for supporting mobile node scenarios. In RPL, routing takes place by formationof Destination Oriented Acyclic Graph (DODAG). Several control messages like DODAG Information Objects (DIOs), DODAG Information Solicitation and DODAG Advertisement Objects (DAOs) are exchanged for the DODAG formation. These control messages propagate throughout the network and collaboratively work to form the DODAG. The
control messages in RPL are controlled by several timers. These control message timers need to be modified for mobile node scenarios. The timers need to be optimized based on mobility of nodes in the network. In this paper we have modified the existing implementation of RPL protocol in Contiki Operating system to improve its performance for scenarios where mobile nodes are involved. We have also developed a test-bed for simulating mobile nodes in COOJA simulator and evaluating performance metrics like Packet delivery ratio, Power consumption and Average latency per packet.

== LOADng for Contiki- Jiahao Liang, Zhikun Liu and Haimo Bai ==

'''Repository''': https://github.com/jiahaoliang/EE652_LOADng

'''Description''':

The LLN On-demand Ad hoc Distance-vector Routing Protocol - Next Generation (LOADng) is a routing protocol, derived from AODV and extended for use in Low power Lossy Networks (LLNs). A reactive protocol, the basic operations of LOAD include generation of Route Requests (RREQs) by a router (originator) for when discovering a route to a destination, forwarding of such RREQs until they reach the destination router, generation of Route Replies (RREPs) upon receipt of a RREQ by the destination, and forwarding of these RREPs towards the originator.

== Location based query and data aggregation using RPL in ContikiOS- Ashwini Telang, Yash Goyal and Subhashini Sundaresan ==

'''Repository''': https://github.com/ashwinit/652Final

'''Description''':

Wireless sensor network has several automation applications in different industrial, urban and commercial settings which demand data collection from a group of nodes, data aggregation can be suitable in these cases to conserve the limited energy reserves on the nodes. In this paper we model routing mechanism based on location hierarchy and compare it with the existing implementation of RPL in Contiki. The tool used to evaluate the performance of the model is Cooja simulator. We have tested for two different topologies with respect to the performance metrics such as ETX, Latency and number of packets forwarded for both multicast and unicast queries. The result shows that the location based query and data aggregation models gives better performance in hierarchical location based topologies in which the sub-branches do not interfere.

EE 652 projects

2015-01-01T23:56:47Z

Ashwinit:

EE 652 2014 Projects

== Scheduling algorithms for IEEE 802.15.4e networks - Pedro ==

'''Repository''': http://neptune.usc.edu:8081/pdasilva/tsch-schedulers/

'''Description''':

''How to compile'': gcc -std=gnu99 -o Scheduling util/*.c graphs/*.c mcc/*.c tasa/*.c main.c

''How to execute'': ./Scheduling <sink_id> <algorithm>

where: <sink_id> = Sink identification (starting at 0) and <algorithm> = 0 if MCC and 1 if TASA

''Output'': you will find files ext_schedule.h and topology.c, which should be used according to the project report

The execution will consider data/prr55.txt file as input for PRR statistics. You need to create the file with tree description before running TASA. You can easily do that first running MCC for a given sink id (e.g. 3) and then running TASA for the same sink id.

== Heat Diffusion Routing Algorithm Contiki Implementation - Pradipta ==
'''Repository''': http://neptune.usc.edu:8081/pradipta/heat-diffusion.git

'''Description''':
This is a contiki implementation of the Heat Diffusion algorithm proposed by Reza Banirazi, Edmond A. Jonckheere, Bhaskar Krishnamachari in '''“Heat-Diffusion: Pareto optimal dynamic routing for time-varying wireless networks“, International Conference on Computer Communications (INFOCOM), 2014'''. Heat Diffusion routing is a new multi-hop wireless network routing protocol which is similar to Back-Pressure routing based on concepts of heat diffusion in classical physics

== Backpressure Control Protocol on IPv6 stack of Contiki - Mrunal and Chhavi ==

'''Repository''': https://github.com/chhavikapoor/EE652_Final

Use the branch final_project from the repository.

Follow the README-BCP in the final_project repository to simulate the implementation of BCP on IPv6 stack in COOJA.

'''Description''':

BCP is an implementation of dynamic backpressure routing in which the routing and forwarding decisions are made on per packet basis that takes into consideration the backpressure weight of each of its neighbors. The ubiquitous use of TCP/IP protocol suite in web applications, peer to peer networking over the internet etc motivated us to implement the Backpressure Collection Protocol on the IPv6 Stack of Contiki. We implemented a functional version of BCP on the IPv6 stack of Contiki OS.
In our implementation, BCP Sink by default has the node_id = 1.

== Modifications to RPL for Mobility - Pratyush Deshpande, Gopi Marella and Abhilash Hegde ==

'''Repository''': https://github.com/pratyush18/contiki-new.git

'''Description''':

Routing Protocol for Low power and lossy networks (RPL) has been recently adopted IETF routing protocol standard for low power wireless sensor networks and Internet of Things applications. Originally RPL is designed for static networks with no support for mobility. But, several IoT applications involve mobile nodes and thus there is a need to modify RPL for supporting mobile node scenarios. In RPL, routing takes place by formationof Destination Oriented Acyclic Graph (DODAG). Several control messages like DODAG Information Objects (DIOs), DODAG Information Solicitation and DODAG Advertisement Objects (DAOs) are exchanged for the DODAG formation. These control messages propagate throughout the network and collaboratively work to form the DODAG. The
control messages in RPL are controlled by several timers. These control message timers need to be modified for mobile node scenarios. The timers need to be optimized based on mobility of nodes in the network. In this paper we have modified the existing implementation of RPL protocol in Contiki Operating system to improve its performance for scenarios where mobile nodes are involved. We have also developed a test-bed for simulating mobile nodes in COOJA simulator and evaluating performance metrics like Packet delivery ratio, Power consumption and Average latency per packet.

== LOADng for Contiki- Jiahao Liang, Zhikun Liu and Haimo Bai ==

'''Repository''': https://github.com/jiahaoliang/EE652_LOADng

'''Description''':

The LLN On-demand Ad hoc Distance-vector Routing Protocol - Next Generation (LOADng) is a routing protocol, derived from AODV and extended for use in Low power Lossy Networks (LLNs). A reactive protocol, the basic operations of LOAD include generation of Route Requests (RREQs) by a router (originator) for when discovering a route to a destination, forwarding of such RREQs until they reach the destination router, generation of Route Replies (RREPs) upon receipt of a RREQ by the destination, and forwarding of these RREPs towards the originator.

== Location based query and data aggregation using RPL in ContikiOS- Ashwini Telang, Yash Goyal and Subhashini Sundaresan ==

'''Repository''':

'''Description''':

Wireless sensor network has several automation applications in different industrial, urban and commercial settings which demand data collection from a group of nodes, data aggregation can be suitable in these cases to conserve the limited energy reserves on the nodes. In this paper we model routing mechanism based on location hierarchy and compare it with the existing implementation of RPL in Contiki. The tool used to evaluate the performance of the model is Cooja simulator. We have tested for two different topologies with respect to the performance metrics such as ETX, Latency and number of packets forwarded for both multicast and unicast queries. The result shows that the location based query and data aggregation models gives better performance in hierarchical location based topologies in which the sub-branches do not interfere.

EE 652 projects

2015-01-01T23:55:24Z

Ashwinit:

EE 652 projects

2015-01-01T23:54:08Z

Ashwinit:

Contiki tutorials

2014-11-09T20:14:55Z

Ashwinit:

[[Main_Page | Back to Main Page]]

== List of Tutorials ==

Completed
# [[Installation]]
# [[Hello World]]
# [[Broadcast Example]]
# [[Collect View]]
# [[Contiki build system]]
# [[Interfacing with Python]]
# [[Sensor acquisition]] (light, temperature, humidity)

Need review
# [[Timers]] Tim, Leo
# [[CFS-Coffee]] Kevin

Starting
# [[Tutornet]] Pedro, Kwame
# [[Cooja Simulator]] (Getting started, debugging) Pedro
# [[Network Stack]] Yash
# [[CSMA]] Tim, Leo
# [[RSS measurement]]
# [[RPL objective function & simulation using DGRM model in cooja ]] Ashwini Telang
# [[RPL UDP]] Jiahao Liang
# [[MAC protocols in ContikiOS]] Pedro
# [[RPL Border Router]] Chhavi
# [[REST example running on Cooja and Sky motes]] Mrunal Muni
# [[Trickle library]] Subhashini Sundaresan
# [[Packetbuffer Basics]] Pradipta
# [[Antelope(Database Management System) - Contiki]] Gopi Krishna
# [[Mobility of Nodes in Cooja]] Pratyush Deshpande
# [[Contiki Shell]] Abhilash Nagaraj Hegde
# [[Contiki Coffee File System]] Zhikun Liu
# [[Contiki Programming Guide]] Haimo Bai
# [[Analyse of a real 6LoWPAN network using a Contiki-based sniffer module]] Yash Goyal





<pre style="color: red">Be sure to include references in your tutorials, especially if you quote material from other sites!</pre>

RPL objective function & simulation using DGRM model in cooja

2014-11-09T10:11:09Z

Ashwinit: /* Example scenario for objective function modification */

[[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. 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 ====
<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-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. 
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:SampleNetTopologyone.png|border|500px|center|Sample Network Topology]] 
The above figure shows a sample topology which can be used. 
An objective function basically uses a link metric and has function which subject to a contraint tries to choose the best path for routing.
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 '''API for RPL Objective function''' 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. 
An example for modifying the objective function can be for '''''Load Balancing application'''''. The new objective function should be such that it should choose a route that minimizes the ETX and if there are multiple routes with same ETX or having ETX in a predefined range then it should minimize the maximum number of packets forwarded by any one of these routes. This means that any one node is not burdened with the load of forwarding packets while other nodes are under utilized. 
One approach to this problem is to define a completely new objective function as described earlier. Another approach is to modify the already present rpl-mhrof.c file. As this OF already uses the minimum ETX part of the problem we just have to implement the load balancing part. The load balancing comes in to picture when a child has multiple routes i.e. parents. Hence the best parent function shouhld be modified accordingly. 
Another example could be to choose the '''''shortest path with nodes using minimum energy'''''. Here the objective function should be such that it first identifies the nodes using minimum energy or within a range and then use minimum hops to reach the destination using these nodes. This can have an application in situation where a node has to quickly send its data without burdening a node which is deficient of energy. 
In this scenario the objective function using energy metric which is already present in the current implementation of rpl-mhrof,c can be used with additional logic for choosing minimum hop count while choosing a parent. 
Other scenarios which necessitate a new or modified objective function can be based on different link metrics such as throughput, link quality level, latency etc. 

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

== References ==
RFC 6550 RPL: IPv6 Routing Protocol for Low-Power and Lossy Networks 
RFC 6552 Objective Function Zero for the Routing Protocol for Low-Power and Lossy Networks (RPL) 
RFC 6719 MRHOF: The Minimum Rank with Hysteresis Objective Function 
[http://home.deib.polimi.it/cesana/teaching/IoT/papers/routing/RPL.pdf] IPSO Alliance RPL April 2011 
[http://dunkels.com/adam/ko11contikirpl.pdf] ContikiRPL 
[https://github.com/contiki-os/contiki/tree/release-2-7 https://github.com/contiki-os/contiki/tree/release-2-7] Github branch of ContikiOS-2.7 

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

RPL objective function & simulation using DGRM model in cooja

2014-11-09T10:08:54Z

Ashwinit: /* References */

[[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. 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 ====
<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-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. 
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:SampleNetTopologyone.png|border|500px|center|Sample Network Topology]] 
The above figure shows a sample topology which can be used. 
An objective function basically uses a link metric and has function which subject to a contraint tries to choose the best path for routing.
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:</nowiki> 
* 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. 
An example for modifying the objective function can be for '''''Load Balancing application'''''. The new objective function should be such that it should choose a route that minimizes the ETX and if there are multiple routes with same ETX or having ETX in a predefined range then it should minimize the maximum number of packets forwarded by any one of these routes. This means that any one node is not burdened with the load of forwarding packets while other nodes are under utilized. 
One approach to this problem is to define a completely new objective function as described earlier. Another approach is to modify the already present rpl-mhrof.c file. As this OF already uses the minimum ETX part of the problem we just have to implement the load balancing part. The load balancing comes in to picture when a child has multiple routes i.e. parents. Hence the best parent function shouhld be modified accordingly. 
Another example could be to choose the '''''shortest path with nodes using minimum energy'''''. Here the objective function should be such that it first identifies the nodes using minimum energy or within a range and then use minimum hops to reach the destination using these nodes. This can have an application in situation where a node has to quickly send its data without burdening a node which is deficient of energy. 
In this scenario the objective function using energy metric which is already present in the current implementation of rpl-mhrof,c can be used with additional logic for choosing minimum hop count while choosing a parent. 
Other scenarios which necessitate a new or modified objective function can be based on different link metrics such as throughput, link quality level, latency etc. 

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

== References ==
RFC 6550 RPL: IPv6 Routing Protocol for Low-Power and Lossy Networks 
RFC 6552 Objective Function Zero for the Routing Protocol for Low-Power and Lossy Networks (RPL) 
RFC 6719 MRHOF: The Minimum Rank with Hysteresis Objective Function 
[http://home.deib.polimi.it/cesana/teaching/IoT/papers/routing/RPL.pdf] IPSO Alliance RPL April 2011 
[http://dunkels.com/adam/ko11contikirpl.pdf] ContikiRPL 
[https://github.com/contiki-os/contiki/tree/release-2-7 https://github.com/contiki-os/contiki/tree/release-2-7] Github branch of ContikiOS-2.7 

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

RPL objective function & simulation using DGRM model in cooja

2014-11-09T10:08:22Z

Ashwinit: /* References */

[[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. 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 ====
<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-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. 
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:SampleNetTopologyone.png|border|500px|center|Sample Network Topology]] 
The above figure shows a sample topology which can be used. 
An objective function basically uses a link metric and has function which subject to a contraint tries to choose the best path for routing.
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:</nowiki> 
* 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. 
An example for modifying the objective function can be for '''''Load Balancing application'''''. The new objective function should be such that it should choose a route that minimizes the ETX and if there are multiple routes with same ETX or having ETX in a predefined range then it should minimize the maximum number of packets forwarded by any one of these routes. This means that any one node is not burdened with the load of forwarding packets while other nodes are under utilized. 
One approach to this problem is to define a completely new objective function as described earlier. Another approach is to modify the already present rpl-mhrof.c file. As this OF already uses the minimum ETX part of the problem we just have to implement the load balancing part. The load balancing comes in to picture when a child has multiple routes i.e. parents. Hence the best parent function shouhld be modified accordingly. 
Another example could be to choose the '''''shortest path with nodes using minimum energy'''''. Here the objective function should be such that it first identifies the nodes using minimum energy or within a range and then use minimum hops to reach the destination using these nodes. This can have an application in situation where a node has to quickly send its data without burdening a node which is deficient of energy. 
In this scenario the objective function using energy metric which is already present in the current implementation of rpl-mhrof,c can be used with additional logic for choosing minimum hop count while choosing a parent. 
Other scenarios which necessitate a new or modified objective function can be based on different link metrics such as throughput, link quality level, latency etc. 

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

== References ==
RFC 6550 RPL: IPv6 Routing Protocol for Low-Power and Lossy Networks 
RFC 6552 Objective Function Zero for the Routing Protocol for Low-Power and Lossy Networks (RPL) 
RFC 6719 MRHOF: The Minimum Rank with Hysteresis Objective Function 
[http://home.deib.polimi.it/cesana/teaching/IoT/papers/routing/RPL.pdf] IPSO Alliance RPL April 2011 
[http://dunkels.com/adam/ko11contikirpl.pdf] ContikiRPL 
[https://github.com/contiki-os/contiki/tree/release-2-7 https://github.com/contiki-os/contiki/tree/release-2-7] Githhub branch of ContikiOS-2.7 

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

RPL objective function & simulation using DGRM model in cooja

2014-11-09T10:07:54Z

Ashwinit: /* References */

[[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. 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 ====
<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-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. 
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:SampleNetTopologyone.png|border|500px|center|Sample Network Topology]] 
The above figure shows a sample topology which can be used. 
An objective function basically uses a link metric and has function which subject to a contraint tries to choose the best path for routing.
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:</nowiki> 
* 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. 
An example for modifying the objective function can be for '''''Load Balancing application'''''. The new objective function should be such that it should choose a route that minimizes the ETX and if there are multiple routes with same ETX or having ETX in a predefined range then it should minimize the maximum number of packets forwarded by any one of these routes. This means that any one node is not burdened with the load of forwarding packets while other nodes are under utilized. 
One approach to this problem is to define a completely new objective function as described earlier. Another approach is to modify the already present rpl-mhrof.c file. As this OF already uses the minimum ETX part of the problem we just have to implement the load balancing part. The load balancing comes in to picture when a child has multiple routes i.e. parents. Hence the best parent function shouhld be modified accordingly. 
Another example could be to choose the '''''shortest path with nodes using minimum energy'''''. Here the objective function should be such that it first identifies the nodes using minimum energy or within a range and then use minimum hops to reach the destination using these nodes. This can have an application in situation where a node has to quickly send its data without burdening a node which is deficient of energy. 
In this scenario the objective function using energy metric which is already present in the current implementation of rpl-mhrof,c can be used with additional logic for choosing minimum hop count while choosing a parent. 
Other scenarios which necessitate a new or modified objective function can be based on different link metrics such as throughput, link quality level, latency etc. 

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

== References ==
RFC 6550 RPL: IPv6 Routing Protocol for Low-Power and Lossy Networks 
RFC 6552 Objective Function Zero for the Routing Protocol for Low-Power and Lossy Networks (RPL) 
RFC 6719 MRHOF: The Minimum Rank with Hysteresis Objective Function 
[http://home.deib.polimi.it/cesana/teaching/IoT/papers/routing/RPL.pdf] IPSO Alliance RPL April 2011 
[http://dunkels.com/adam/ko11contikirpl.pdf] ContikiRPL
[https://github.com/contiki-os/contiki/tree/release-2-7] Githhub branch of ContikiOS-2.7

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

RPL objective function & simulation using DGRM model in cooja

2014-11-09T10:03:31Z

Ashwinit: /* Example scenario for objective function modification */

[[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. 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 ====
<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-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. 
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:SampleNetTopologyone.png|border|500px|center|Sample Network Topology]] 
The above figure shows a sample topology which can be used. 
An objective function basically uses a link metric and has function which subject to a contraint tries to choose the best path for routing.
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:</nowiki> 
* 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. 
An example for modifying the objective function can be for '''''Load Balancing application'''''. The new objective function should be such that it should choose a route that minimizes the ETX and if there are multiple routes with same ETX or having ETX in a predefined range then it should minimize the maximum number of packets forwarded by any one of these routes. This means that any one node is not burdened with the load of forwarding packets while other nodes are under utilized. 
One approach to this problem is to define a completely new objective function as described earlier. Another approach is to modify the already present rpl-mhrof.c file. As this OF already uses the minimum ETX part of the problem we just have to implement the load balancing part. The load balancing comes in to picture when a child has multiple routes i.e. parents. Hence the best parent function shouhld be modified accordingly. 
Another example could be to choose the '''''shortest path with nodes using minimum energy'''''. Here the objective function should be such that it first identifies the nodes using minimum energy or within a range and then use minimum hops to reach the destination using these nodes. This can have an application in situation where a node has to quickly send its data without burdening a node which is deficient of energy. 
In this scenario the objective function using energy metric which is already present in the current implementation of rpl-mhrof,c can be used with additional logic for choosing minimum hop count while choosing a parent. 
Other scenarios which necessitate a new or modified objective function can be based on different link metrics such as throughput, link quality level, latency etc. 

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

RPL objective function & simulation using DGRM model in cooja

2014-11-09T10:02:10Z

Ashwinit: /* Example scenario for objective function modification */

[[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. 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 ====
<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-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. 
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:SampleNetTopologyone.png|border|500px|center|Sample Network Topology]] 
The above figure shows a sample topology which can be used. 
An objective function basically uses a link metric and has function which subject to a contraint tries to choose the best path for routing.
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:</nowiki> 
* 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. 
An example for modifying the objective function can be for Load Balancing application. The new objective function should be such that it should choose a route that minimizes the ETX and if there are multiple routes with same ETX or having ETX in a predefined range then it should minimize the maximum number of packets forwarded by any one of these routes. This means that any one node is not burdened with the load of forwarding packets while other nodes are under utilized. 
One approach to this problem is to define a completely new objective function as described earlier. Another approach is to modify the already present rpl-mhrof.c file. As this OF already uses the minimum ETX part of the problem we just have to implement the load balancing part. The load balancing comes in to picture when a child has multiple routes i.e. parents. Hence the best parent function shouhld be modified accordingly. 
Another example could be to choose the shortest path with nodes using minimum energy. Here the objective function should be such that it first identifies the nodes using minimum energy or within a range and then use minimum hops to reach the destination using these nodes. This can have an application in situation where a node has to quickly send its data without burdening a node which is deficient of energy. 
In this scenario the objective function using energy metric which is already present in the current implementation of rpl-mhrof,c can be used with additional logic for choosing minimum hop count while choosing a parent. 
Other scenarios which necessitate a new or modified objective function can be based on different link metrics such as throughput, link quality level, latency etc. 

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

RPL objective function & simulation using DGRM model in cooja

2014-11-09T09:50:50Z

Ashwinit: /* Example scenario for objective function modification */

[[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. 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 ====
<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-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. 
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:SampleNetTopologyone.png|border|500px|center|Sample Network Topology]] 
The above figure shows a sample topology which can be used. 
An objective function basically uses a link metric and has function which subject to a contraint tries to choose the best path for routing.
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. 
An example for modifying the objective function can be for Load Balancing application. The new objective function should be such that it should choose a route that minimizes the ETX and if there are multiple routes with same ETX or having ETX in a predefined range then it should minimize the maximum number of packets forwarded by any one of these routes. This means that any one node is not burdened with the load of forwarding packets while other nodes are under utilized. 
One approach to this problem is to define a completely new objective function as described earlier. Another approach is to modify the already present rpl-mhrof.c file. As this OF already uses the minimum ETX part of the problem we just have to implement the load balancing part. The load balancing comes in to picture when a child has multiple routes i.e. parents. Hence the best parent function shouhld be modified accordingly. 
Another example could be to choose the shortest path with nodes using minimum energy. Here the objective function should be such that it first identifies the nodes using minimum energy or within a range and then use minimum hops to reach the destination using these nodes. This can have an application in situation where a node has to quickly send its data without burdening a node which is deficient of energy. 
In this scenario the objective function using energy metric which is already present in the current implementation of rpl-mhrof,c can be used with additional logic for choosing minimum hop count while choosing a parent. 
Other scenarios which necessitate a new or modified objective function can be based on different link metrics such as throughput, link quality level, latency etc.

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

RPL objective function & simulation using DGRM model in cooja

2014-11-09T09:49:56Z

Ashwinit: /* Example scenario for objective function modification */

[[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. 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 ====
<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-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. 
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:SampleNetTopologyone.png|border|500px|center|Sample Network Topology]] 
The above figure shows a sample topology which can be used. 
An objective function basically uses a link metric and has function which subject to a contraint tries to choose the best path for routing.
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. 
An example for modifying the objective function can be for Load Balancing application. The new objective function should be such that it should choose a route that minimizes the ETX and if there are multiple routes with same ETX or having ETX in a predefined range then it should minimize the maximum number of packets forwarded by any one of these routes. This means that any one node is not burdened with the load of forwarding packets while other nodes are under utilized. 
One approach to this problem is to define a completely new objective function as described earlier. Another approach is to modify the already present rpl-mhrof.c file. As this OF already uses the minimum ETX part of the problem we just have to implement the load balancing part. The load balancing comes in to picture when a child has multiple routes i.e. parents. Hence the best parent function shouhld be modified accordingly. 
Another problem could be to choose the shortest path with nodes using minimum energy. Here the objective function should be such that it first identifies the nodes using minimum energy or within a range and then use minimum hops to reach the destination using these nodes. This can have an application in situation where a node has to quickly send its data without burdening a node which is deficient of energy. 
In this scenario the objective function using energy metric which is already present in the current implementation of rpl-mhrof,c can be used with additional logic for choosing minimum hop count while choosing a parent. 
Other scenarios which necessitate a new or modified objective function can be based on different link metrics such as throughput, link quality level, latency etc.

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

File:SampleNetTopologyone.png

2014-11-09T09:42:29Z

Ashwinit:

RPL objective function & simulation using DGRM model in cooja

2014-11-09T09:13:59Z

Ashwinit: /* Example scenario for objective function modification */

[[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. 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 ====
<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-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. 
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]] 
The above figure shows a sample topology which can be used. 
An objective function basically uses a link metric and has function which subject to a contraint tries to choose the best path for routing.
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

RPL objective function modification and simulation in cooja

2014-11-09T09:07:08Z

Ashwinit: /* Example scenario for objective function modification */

[[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. 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 ====
<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-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. 
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]] 
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

RPL objective function & simulation using DGRM model in cooja

2014-11-09T09:06:47Z

Ashwinit: Created page with " Back to Contiki Tutorials __TOC__ == Introduction == The Routing Protocol for Low-Power and Lossy Networks (RPL) builds a Destination Oriented Direct..."

[[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. 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 ====
<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-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. 
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]] 
The above figure shows a sample 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

Contiki tutorials

2014-11-09T09:05:38Z

Ashwinit: /* List of Tutorials */

[[Main_Page | Back to Main Page]]

== List of Tutorials ==

Completed
# [[Installation]]
# [[Hello World]]
# [[Broadcast Example]]
# [[Collect View]]
# [[Contiki build system]]
# [[Interfacing with Python]]
# [[Sensor acquisition]] (light, temperature, humidity)

Need review
# [[Timers]] Tim, Leo
# [[CFS-Coffee]] Kevin

Starting
# [[Tutornet]] Pedro, Kwame
# [[Cooja Simulator]] (Getting started, debugging) Pedro
# [[Network Stack]] Yash
# [[CSMA]] Tim, Leo
# [[RSS measurement]]
# [[RPL objective function & simulation using DGRM model in cooja ]] Ashwini Telang
# [[RPL UDP]] Jiahao Liang
# [[MAC protocols in ContikiOS]] Pedro
# [[RPL Border Router]] Chhavi
# [[REST example running on Cooja and Sky motes]] Mrunal Muni
# [[Trickle library]] Subhashini Sundaresan
# [[Packetbuffer Basics]] Pradipta
# [[Antelope(Database Management System) - Contiki]] Gopi Krishna
# [[Mobility of Nodes in Cooja]] Pratyush Deshpande
# [[Contiki Shell]] Abhilash Nagaraj Hegde
# [[Contiki Coffee File System]] Zhikun Liu
# [[Contiki Programming Guide]] Haimo Bai
# [[Analyse of a real 6LoWPAN network using a Contiki-based sniffer module]] Yash Goyal




<pre style="color: red">Be sure to include references in your tutorials, especially if you quote material from other sites!</pre>

RPL objective function modification and simulation in cooja

2014-11-09T09:00:52Z

Ashwinit: /* Example scenario for objective function modification */

[[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. 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 ====
<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-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. 
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]] 
The above figure shows a sample 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

RPL objective function modification and simulation in cooja

2014-11-09T08:59:31Z

Ashwinit: /* Example scenario for objective function modification */

[[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. 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 ====
<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-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. 
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]] 

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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

RPL objective function modification and simulation in cooja

2014-11-09T08:26:31Z

Ashwinit: /* best_parent(rpl_parent_t *p1, rpl_parent_t *p2) */

[[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. 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 ====
<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-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. 
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]]

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

File:BestParents.png

2014-11-09T08:24:58Z

Ashwinit:

RPL objective function modification and simulation in cooja

2014-11-09T08:17:18Z

Ashwinit: /* calculate_rank(rpl_parent_t *p, rpl_rank_t base_rank) */

[[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. 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 ====
<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-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:BestParent.png|frame|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. 
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]]

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

RPL objective function modification and simulation in cooja

2014-11-09T08:15:42Z

Ashwinit: /* calculate_rank(rpl_parent_t *p, rpl_rank_t base_rank) */

[[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. 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 ====
<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-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|frame|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:BestParent.png|frame|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. 
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]]

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

File:CalculateRank.png

2014-11-09T08:15:10Z

Ashwinit:

File:CalcRank.png

2014-11-09T08:13:33Z

Ashwinit: Ashwinit uploaded a new version of "File:CalcRank.png"

File:CalcRank.png

2014-11-09T08:12:51Z

Ashwinit: Ashwinit uploaded a new version of "File:CalcRank.png"

File:CalcRank.png

2014-11-09T08:11:59Z

Ashwinit: Ashwinit uploaded a new version of "File:CalcRank.png"

File:SampleNetTopology.png

2014-11-09T08:02:20Z

Ashwinit: Ashwinit uploaded a new version of "File:SampleNetTopology.png"

RPL objective function modification and simulation in cooja

2014-11-09T07:59:04Z

Ashwinit: /* Example scenario for objective function modification */

[[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. 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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]]

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

RPL objective function modification and simulation in cooja

2014-11-09T07:58:35Z

Ashwinit: /* Example scenario for objective function modification */

[[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. 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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|frame|center|Sample Network Topology]]

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

File:SampleNetTopology.png

2014-11-09T07:57:37Z

Ashwinit: Ashwinit uploaded a new version of "File:SampleNetTopology.png"

File:SampleNetTopology.png

2014-11-09T07:56:17Z

Ashwinit:

RPL objective function modification and simulation in cooja

2014-11-09T07:27:53Z

Ashwinit: /* Related Files and Functions */

[[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. 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ==

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

RPL objective function modification and simulation in cooja

2014-11-09T07:26:44Z

Ashwinit: /* You Will learn */

[[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. 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

RPL objective function modification and simulation in cooja

2014-11-09T07:24:49Z

Ashwinit:

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== 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. 
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. 

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

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

RPL objective function modification and simulation in cooja

2014-11-09T07:23:13Z

Ashwinit: /* Cooja Simulation using DGRM model */

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== 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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


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

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

RPL objective function modification and simulation in cooja

2014-11-09T07:12:00Z

Ashwinit: /* References */

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== Cooja Simulation using DGRM model ==
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


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

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

RPL objective function modification and simulation in cooja

2014-11-09T07:11:39Z

Ashwinit: /* References */

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== Cooja Simulation using DGRM model ==
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


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

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

RPL objective function modification and simulation in cooja

2014-11-09T07:00:15Z

Ashwinit: /* References */

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== Cooja Simulation using DGRM model ==
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== References ==
RFC 6550 RPL: IPv6 Routing Protocol for Low-Power and Lossy Networks 
RFC 6719 MRHOF: The Minimum Rank with Hysteresis Objective Function 

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

RPL objective function modification and simulation in cooja

2014-11-09T06:44:46Z

Ashwinit: /* Source Code and used Directories */

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== Cooja Simulation using DGRM model ==
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== References ==

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

RPL objective function modification and simulation in cooja

2014-11-09T06:44:28Z

Ashwinit: /* Source Code and used Directories */

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing RPL objective function
* Simulation in Cooja using DGRM model

== Source Code and used 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== Cooja Simulation using DGRM model ==
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== References ==

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

RPL objective function modification and simulation in cooja

2014-11-09T06:44:01Z

Ashwinit: /* Source Code */

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing RPL objective function
* Simulation in Cooja using DGRM model

== Source Code and used 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== Cooja Simulation using DGRM model ==
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== References ==

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

RPL objective function modification and simulation in cooja

2014-11-09T06:39:27Z

Ashwinit:

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing RPL objective function
* Simulation in Cooja using DGRM model

== Source Code ==

== 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== Cooja Simulation using DGRM model ==
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== References ==

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

RPL objective function modification and simulation in cooja

2014-11-09T06:38:06Z

Ashwinit: /* Related Files and Functions */

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing RPL objective function
* Simulation in Cooja using DGRM model

== 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 ====
<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-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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== Cooja Simulation using DGRM model ==
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== References ==

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

RPL objective function modification and simulation in cooja

2014-11-09T06:36:31Z

Ashwinit: /* Related Files and Functions */

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing RPL objective function
* Simulation in Cooja using DGRM model

== 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 ====
<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.c ===
This file has contiki implementation of RPL-IPv6 Routing Protocol for Low-Power and Lossy Networks (IETF RFC 6550).
<source lang = c>
void
rpl_link_neighbor_callback(const rimeaddr_t *addr, int status, int numtx)
{
uip_ipaddr_t ipaddr;
rpl_parent_t *parent;
rpl_instance_t *instance;
rpl_instance_t *end;

uip_ip6addr(&ipaddr, 0xfe80, 0, 0, 0, 0, 0, 0, 0);
uip_ds6_set_addr_iid(&ipaddr, (uip_lladdr_t *)addr);

for(instance = &instance_table[0], end = instance + RPL_MAX_INSTANCES; instance < end; ++instance) {
if(instance->used == 1 ) {
parent = rpl_find_parent_any_dag(instance, &ipaddr);
if(parent != NULL) {
/* Trigger DAG rank recalculation. */
PRINTF("RPL: rpl_link_neighbor_callback triggering update\n");
parent->updated = 1;
if(instance->of->neighbor_link_callback != NULL) {
instance->of->neighbor_link_callback(parent, status, numtx);
}
}
}
}
}
</source>




=== 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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== Cooja Simulation using DGRM model ==
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== References ==

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

RPL objective function modification and simulation in cooja

2014-11-09T06:35:02Z

Ashwinit: /* Cooja Simulation using DGRM model */

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing RPL objective function
* Simulation in Cooja using DGRM model

== Related Files and Functions ==




Some of the important files that have the gist of RPL are rpl-config.h, rpl-dag.c, 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 ====
<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.c ===
This file has contiki implementation of RPL-IPv6 Routing Protocol for Low-Power and Lossy Networks (IETF RFC 6550).
<source lang = c>
void
rpl_link_neighbor_callback(const rimeaddr_t *addr, int status, int numtx)
{
uip_ipaddr_t ipaddr;
rpl_parent_t *parent;
rpl_instance_t *instance;
rpl_instance_t *end;

uip_ip6addr(&ipaddr, 0xfe80, 0, 0, 0, 0, 0, 0, 0);
uip_ds6_set_addr_iid(&ipaddr, (uip_lladdr_t *)addr);

for(instance = &instance_table[0], end = instance + RPL_MAX_INSTANCES; instance < end; ++instance) {
if(instance->used == 1 ) {
parent = rpl_find_parent_any_dag(instance, &ipaddr);
if(parent != NULL) {
/* Trigger DAG rank recalculation. */
PRINTF("RPL: rpl_link_neighbor_callback triggering update\n");
parent->updated = 1;
if(instance->of->neighbor_link_callback != NULL) {
instance->of->neighbor_link_callback(parent, status, numtx);
}
}
}
}
}
</source>

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

=== 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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== Cooja Simulation using DGRM model ==
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 
[[File:Simu3.png|border|500px|center]] 
*'''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. 
[[File:Simu4.png|border|300px|center]] 
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. 


== References ==

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

RPL objective function modification and simulation in cooja

2014-11-09T06:31:49Z

Ashwinit: /* neighbor_link_callback(rpl_parent_t *p, int status, int numtx) */

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing RPL objective function
* Simulation in Cooja using DGRM model

== Related Files and Functions ==




Some of the important files that have the gist of RPL are rpl-config.h, rpl-dag.c, 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 ====
<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.c ===
This file has contiki implementation of RPL-IPv6 Routing Protocol for Low-Power and Lossy Networks (IETF RFC 6550).
<source lang = c>
void
rpl_link_neighbor_callback(const rimeaddr_t *addr, int status, int numtx)
{
uip_ipaddr_t ipaddr;
rpl_parent_t *parent;
rpl_instance_t *instance;
rpl_instance_t *end;

uip_ip6addr(&ipaddr, 0xfe80, 0, 0, 0, 0, 0, 0, 0);
uip_ds6_set_addr_iid(&ipaddr, (uip_lladdr_t *)addr);

for(instance = &instance_table[0], end = instance + RPL_MAX_INSTANCES; instance < end; ++instance) {
if(instance->used == 1 ) {
parent = rpl_find_parent_any_dag(instance, &ipaddr);
if(parent != NULL) {
/* Trigger DAG rank recalculation. */
PRINTF("RPL: rpl_link_neighbor_callback triggering update\n");
parent->updated = 1;
if(instance->of->neighbor_link_callback != NULL) {
instance->of->neighbor_link_callback(parent, status, numtx);
}
}
}
}
}
</source>

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

=== 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:CalcRank.png|frame|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:BestParent.png|frame|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. 
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 ===

== Cooja Simulation using DGRM model ==
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 

*'''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'''
[[File:Simu4.png|border|250px|right]]
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. 


== References ==

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

RPL objective function modification and simulation in cooja

2014-11-09T06:26:16Z

Ashwinit: /* best_parent(rpl_parent_t *p1, rpl_parent_t *p2) */

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing RPL objective function
* Simulation in Cooja using DGRM model

== Related Files and Functions ==




Some of the important files that have the gist of RPL are rpl-config.h, rpl-dag.c, 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 ====
<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.c ===
This file has contiki implementation of RPL-IPv6 Routing Protocol for Low-Power and Lossy Networks (IETF RFC 6550).
<source lang = c>
void
rpl_link_neighbor_callback(const rimeaddr_t *addr, int status, int numtx)
{
uip_ipaddr_t ipaddr;
rpl_parent_t *parent;
rpl_instance_t *instance;
rpl_instance_t *end;

uip_ip6addr(&ipaddr, 0xfe80, 0, 0, 0, 0, 0, 0, 0);
uip_ds6_set_addr_iid(&ipaddr, (uip_lladdr_t *)addr);

for(instance = &instance_table[0], end = instance + RPL_MAX_INSTANCES; instance < end; ++instance) {
if(instance->used == 1 ) {
parent = rpl_find_parent_any_dag(instance, &ipaddr);
if(parent != NULL) {
/* Trigger DAG rank recalculation. */
PRINTF("RPL: rpl_link_neighbor_callback triggering update\n");
parent->updated = 1;
if(instance->of->neighbor_link_callback != NULL) {
instance->of->neighbor_link_callback(parent, status, numtx);
}
}
}
}
}
</source>

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

=== 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:CalcRank.png|frame|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:BestParent.png|frame|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.

==== 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. 
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 ===

== Cooja Simulation using DGRM model ==
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 

*'''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'''
[[File:Simu4.png|border|250px|right]]
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. 


== References ==

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

RPL objective function modification and simulation in cooja

2014-11-09T06:24:27Z

Ashwinit: /* best_parent(rpl_parent_t *p1, rpl_parent_t *p2) */

[[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. The following are explained in this tutorial:
* Different RPL related functions and their working
* Modifying an existing RPL objective function
* Simulation in Cooja using DGRM model

== Related Files and Functions ==




Some of the important files that have the gist of RPL are rpl-config.h, rpl-dag.c, 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 ====
<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.c ===
This file has contiki implementation of RPL-IPv6 Routing Protocol for Low-Power and Lossy Networks (IETF RFC 6550).
<source lang = c>
void
rpl_link_neighbor_callback(const rimeaddr_t *addr, int status, int numtx)
{
uip_ipaddr_t ipaddr;
rpl_parent_t *parent;
rpl_instance_t *instance;
rpl_instance_t *end;

uip_ip6addr(&ipaddr, 0xfe80, 0, 0, 0, 0, 0, 0, 0);
uip_ds6_set_addr_iid(&ipaddr, (uip_lladdr_t *)addr);

for(instance = &instance_table[0], end = instance + RPL_MAX_INSTANCES; instance < end; ++instance) {
if(instance->used == 1 ) {
parent = rpl_find_parent_any_dag(instance, &ipaddr);
if(parent != NULL) {
/* Trigger DAG rank recalculation. */
PRINTF("RPL: rpl_link_neighbor_callback triggering update\n");
parent->updated = 1;
if(instance->of->neighbor_link_callback != NULL) {
instance->of->neighbor_link_callback(parent, status, numtx);
}
}
}
}
}
</source>

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

=== 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:CalcRank.png|frame|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:BestParent.png|frame|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.

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

== Cooja Simulation using DGRM model ==
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. 
[[File:NewSimuScn1.jpg|border|500px|center]] 
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. 
[[File:Simu2.png|border|600px|center]] 
*'''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. 

*'''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'''
[[File:Simu4.png|border|250px|right]]
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. 


== References ==

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