Difference between revisions of "RoutesMobilityModel"

From Nsnam
Jump to: navigation, search
(Project Overview)
 
(19 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{TOC}}
 
{{TOC}}
= Project Overview  =
+
= Overview  =
* Student:  [mailto:1090678@isep.ipp.pt Tiago Cerqueira]
+
[[File:Mobility_100Nodes.png|frame|Visualization of a mobility trace generated automatically for 1000 nodes]]
* Mentors:  [mailto:tomh@tomh.org Tom Henderson] and [mailto:scarpen@ncsu.edu Scott Carpenter]
+
[[File:Mobility_100Nodes_WithMap.png|frame|The mobility trace above, with the underlying real-world road network]]
* On-Site mentor [mailto:michele.albano@gmail.com Michele Albano]
+
Mobility trace generation in ns-3 is done either by using the Mobility module included in NS-3 or by importing mobility traces generated by third party programs in a compatible format. The Mobility module included in ns-3 gives programmers the building blocks to create simple or complex traces, but is hindered by the fact that creating complex traces using the current module alone takes too long, even for simulations with just a couple of mobility capable nodes. As for mobility traces generated by third party programs, such as SUMO, they can involve too much work for their generation, especially when the researcher's interest - and expertise - is more on the data communication than on the traffic simulation. Using the Google Maps API it is possible to generate complex mobility traces, simply by providing a start and end point.
* Abstract: Mobility trace generation in ns-3 is done either by using the Mobility module included in NS-3 or by importing mobility traces generated by third party programs in a compatible format. The Mobility module included in ns-3 gives programmers the building blocks to create simple or complex traces, but is hindered by the fact that creating complex traces using the current module alone takes too long, even for simulations with just a couple of mobility capable nodes. As for mobility traces generated by third party programs, such as SUMO, they can involve too much work for their generation, especially when the researcher's interest - and expertise - is more on the data communication than on the traffic simulation. Using the Google Maps API it is possible to generate complex mobility traces, simply by providing a start and end point. Since the API is robust, well documented and supported, it can be assumed it will be available in the future.
+
* About me: I'm a bachelor's student, currently doing an internship at CISTER (Research Center in Real-Time and Embedded Computing Systems) as part of my course's curriculum, where I'm working closely with ns-3. As part of my internship, I’ll be working closely with VANET simulations in ns-3.
+
  
= Approach =
+
The RoutesMobilityModel generates realistic mobility traces by querying the Google Maps Directions API and requesting directions between two (or more) points. The information obtained from the Google Maps services, used in tandem with the ns3::WaypointMobilityModel, allows the simulator to generate realistic mobility traces based on real-world locations and road networks. The purpose of this module is to bridge the gap between the highly complex but realistic SUMO and the synthetic mobility models available in ns-3.  
I plan to download a mobility trace as the XML output of the Google Maps Directions API. This API provides its user with an encoded polyline string, which can be easily transformed into geographical coordinates. These, in turn, can be transformed into Cartesian coordinates for use with the NS-3 mobility module. I plan to use in particular ns3::Waypoint and ns3::WaypointMobilityModule classes to import the data contained in the XML trace into the simulator.
+
I plan to allow easy integration for other APIs, if needed, but I'm not going to implement it in this project.
+
I will also provide examples with different wireless technologies, such as LTE and 802.11p/WAVE.
+
  
= Deliverables =
+
This module was developed during the Summer Mentorship Program of 2014.
I plan to add classes to the Mobility model to contact the Google API and parse the information received into geographical coordinates. By converting those coordinates to Cartesian coordinates it is then possible to create mobility waypoints
+
 
It is also possible to provide a rough simulation for the speed at which a node can travel between given waypoints, by considering the speed limits in the tract for a car, and using default values for cycling, walking, and public transportation.
+
The RoutesMobilityModel module relies on the module ns3::WaypointMobilityModel in order to import the mobility routes retrieved from the external information services. Our module creates ns3::Waypoints that model the routes used to travel between two (or more) real world locations, and later on they are interpreted as the waypoints the vehicles move through during the simulation.
= Plan =
+
Each Milestone includes a period of half a week dedicated to test that milestone.
+
* First and second week – Design the application and further study its implementation
+
* Third and fourth weeks – Implement the design skeleton and implement methods for specifying the information to access and to convert that information to a format that NS-3 can understand
+
* Fifth and sixth weeks – Implement methods for converting the information given by Google Maps into waypoints in order to generate a trace based on the Google Maps route. Develop an algorithm to set up reasonable values for the speed of the car/person between two waypoints.
+
* Seventh and eight weeks – Perform exhaustive testing to the functionalities implemented.
+
* Ninth and tenth weeks – Correct existing bugs and prepare patch
+
= Code repository =
+
My code can be found [https://bitbucket.org/TiagoCerqueira/routesmobilitymodel here]
+
= Status Reports =
+
Per agreement with my mentors, I opted for status reports instead of weekly reviews.
+
The idea behind these code reviews is to post one once I accomplish a milestone.
+
== First Status Report ==
+
I set my first milestone as being able to generate a mobility trace given real world start and endpoints (street names, for example), from the ns3 simulation environment.
+
=== Notes ===
+
The ns3::WaypointMobilityModel works by adding ns3::Waypoints to a dequeue sequentially.
+
  
The Google Maps Directions service, however, provides an XML that contains the following concepts:
+
The Google Maps Directions service provides an XML that contains the following concepts:
 
* Leg - A Leg is a list of Steps. Legs only occur if the user specifies a Waypoint (A to B, passing through C)
 
* Leg - A Leg is a list of Steps. Legs only occur if the user specifies a Waypoint (A to B, passing through C)
 
* Step - A Step contains Points encoded in a polyline
 
* Step - A Step contains Points encoded in a polyline
 
* Point - A latitude/longitude set
 
* Point - A latitude/longitude set
  
To create a mobility trace, my module uses a list of Legs, each one containing a list of Steps and these, in turn, with a list of points.
+
The information retrieved from the Google Maps Directions API contains, among other information, a polyline for each step of the route requested. It also contains the duration (the time it would take to go from the beginning to the end) for the step. The module decodes the polyline, thus creating a list of geographical coordinates, which are, in turn, converted to Cartesian coordinates. In order to model the speed of a node, implemented by setting the times for the ns3::Waypoints, we distributed the duration of the step in proportion to the distance traveled between two waypoints.
  
At the time, the ns3::WaypointMobilityModel defines a journey as an ordered (by time) sequence of ns3::Waypoints.
+
This module empowers the user to generate realistic mobility traces for entire node containers, using different transportation methods (driving, walking, cycling and public transportation), with little to no effort.
My module defines journey as a list of Legs, with each Leg having a list of Steps and each Step with a list of Points.
+
[[File:Overview_RoutesMobilityModel.png|Overview of the module|center]]
=== Module Design ===
+
In order to provide a robust module, it was crucial to design it in such a way that it could be possible to add support for other APIs (such as the OpenStreetMaps's). To achieve this, the Strategy design pattern was used.
+
  
=== Use Cases ===
+
The image above depicts a simple use case of this module, the generation of mobility trace for a single node.
I identified the following use cases:
+
  
==== Create mobility trace for a node ====
+
The module described in this page provides an interface to convert information from a travel planning service.  Currently, only the Google Maps services are implemented however the module was built in order to accommodate different travel planning services, such as OpenStreetMaps, and locations databases. To this end, the Strategy software design pattern was used in the module design.
*Name: Create mobility trace for a node
+
*Actors: User
+
*Description: The user is able to request the module to generate a mobility trace for a single node, based on a given real world route.
+
  
*Preconditions:
+
== Authors ==
# The user has internet access
+
* [mailto:tiago.miguel43@gmail.com Tiago Cerqueira]
# The user possesses a valid API key
+
* [mailto:michele.albano@gmail.com Michele Albano]
# The Google Maps Directions service identifies correctly the start and endpoint provided
+
  
==== Create mobility traces for various nodes ====
+
== Documentation ==
* Name: Create mobility traces for various nodes
+
This module has been documented using Doxygen and UML. The UML diagrams for the current release are shown below.
* Actors: User
+
Additional documentation was created using sphynx, which documents the module in further detail. This documentation will be available in the ns-3 models documentation once the module is released.
* Description: The user is able to request the module to generate a mobility trace for a fixed number of nodes, based on a real world route.
+
<gallery>
*Preconditions:
+
File:RoutesMobilityModel_class_diagram.jpeg|Class diagram
# The user has internet access
+
File:RoutesMobilityModel_UC.jpg|Use Case diagram
# The user possesses a valid API key
+
File:ChooseRouteSD.jpg|Sequence diagram for the "Create mobility trace for a single node" use case
# The user provides a list or an array of start and endpoint tokens correctly
+
File:ChooseRoute(NodeContainer_nodeContainer,_double_lat,_double_lng,_double_radius).png|Sequence diagram for the "Automatic creation of mobility traces for a node container" use case
# The user provides the same number of start and endpoint tokens as nodes in the node container  
+
</gallery>
# The Google Maps Directions service identifies correctly the start and endpoint provided
+
  
==== Automatic creation of mobility traces for a node container ====
+
= Code repository =
* Name: Automatic creation of mobility traces for a node container
+
My code can be found here: https://bitbucket.org/TiagoCerqueira/routesmobilitymodel . This includes a ready-to-use version of ns-3.23 with my module.
* Actors: User
+
* Description: The user is able to request the module to generate a mobility trace for various nodes, based on a real world route.
+
  
This use case will require further study as how to implement it in a way that it is able to generate mobility traces for all nodes in a numerous node container (1000 nodes, for example).
+
Additionally, the user can also download a [https://bitbucket.org/TiagoCerqueira/routesmobilitymodel/downloads/mobility-service-interface.tar.gz stable release of the module]. To use it, the user must then copy the folder to the src/ folder of ns-3.
  
I'm planning on using the Google Maps Places service to generate the start and endpoint tokens required, but due to a few limitations of the service, I'll need to find a workaround to support numerous node containers.
+
= Current implementation =
 +
== Features ==
  
For this iteration, this feature was not implemented
+
* Capable of generating mobility for single nodes or for entire node containers without size restriction
=== Summary ===
+
* Allows the user to select different methods of transportation for the mobility traces (driving, walking, cycling and public transportation
In summary, these past weeks I achieved the following:
+
* Allows the user to specify a departure time
* Designed the module
+
* Is capable of generating mobility online, by contacting the Google Maps API, or offline, by importing cached responses in the filesystem. The Google Maps APIs ToS states that the users must not cache the response data for more than 30 days. Doing so is a direct violation of the ToS
* Coded the classes responsible for performing the API request and treat the information received into a format ns3 can understand
+
* Coded use cases: "Create mobility trace for a node" and "Create mobility traces for various nodes"
+
* Documented the application using Doxygen and with UML Diagrams
+
Bellow, you can view the class diagram, the use case diagram and the sequence diagram for the "Create mobility trace for a node" use case.
+
<gallery>
+
File:RoutesMobilityModel_Class_Diagram.jpeg|Class diagram
+
File:Use_Case_diagram.jpeg|Use Case diagram
+
File:Sequence_diagram.jpeg|Sequence diagram
+
</gallery>
+
== Second Status Report ==
+
For this second status report, my milestones where: Providing an offline mode to the module, automatic generation of mobility traces for a node container of any size, the ability to redirect a node to a different destination dynamically and implementing error handling and logging.
+
  
=== A few notes on the Google Maps Places API ===
+
== Limitations ==
The Google Maps Places API was chosen to provide the module with start and endpoints. The idea was to use this huge database to gather a huge number of start and endpoints and use this in conjunction with the previously developed functionalities.
+
  
Unfortunately, due to a limitation of the API, only 60 addresses can be returned in a single search. In order to achieve automatic generation of mobility traces for a node container of any size, the user must input a list with tokens of latitude and longitude.
+
This module possesses a couple of limitations:
  
Another approach might be to use every address of those 60 addresses and creates mobility traces using every one of them as start and endpoints. This would generate mobility traces for 3540 nodes, but the mobility trace might be too geographically compact, and the nodes would essentially keep traveling using many of the same streets/freeways, etc. This was not implemented at this time, but could be implemented in the future.
+
* Currently, no proper serialization is implemented and, hence, it's not possible to run the exact same mobility between simulations
 +
* The module takes a long time to parse XML responses. This effect is only felt when dealing with large node containers (300+ nodes).
 +
* No bidirectional coupling between data layer and the mobility, which means that the data communications do not affect the mobility
 +
* Traffic information is only available with the paid version of the Google Maps Places API
  
=== Changes to the Module Design ===
+
== Dependencies ==
In order to allow the addition of other sources of information of real-world places, I used the Strategy Design Pattern.
+
This module is dependent of the following libraries:
To perform automatic generation of mobility traces for an entire node container, I had to add the following classes to my model:
+
* libcurlpp
ns3::PlacesApiConnect - An interface for the connection of an API with real-world locations.
+
* Xerces-C++
ns3::GoogleMapsPlacesApiConnect - An implementation of the above interface, responsible for performing the connection to the Google Maps Places service
+
* GeographicLib
ns3::Place - A logical representation of a real-world location.
+
ns3::SaxPlacesHandler - The parser responsible for parsing the information retrieved from the Google Maps Places service
+
  
=== Changes to the Use Cases ===
+
== Tests ==
For this status report, I'm adding a couple of use case suggestions made by my mentors.
+
==== Create mobility trace for nodes ====
+
*Name: Create mobility trace for a node
+
*Actors: User
+
*Description: The user is able to request the module to generate a mobility trace for a single node, based on a given real world route.
+
  
*Preconditions:
+
In order to provide the users with a reliable module, the team developed a test case to test for the time placement of waypoints and the conversion between geographical and cartesian coordinates. The code is available in the test folder of the module.
# The user has internet access
+
# The user possesses a valid API key
+
# The Google Maps Directions service identifies correctly the start and endpoint provided
+
  
==== Automatic creation of mobility traces for a node container ====
+
== Examples ==
* Name: Automatic creation of mobility traces for a node container
+
* Actors: User
+
* Description: The user is able to request the module to generate a mobility trace for various nodes, based on a real world route.
+
*Preconditions:
+
# The user has internet access
+
# The user possesses a valid API key
+
# The user provides the correct coordinates
+
  
==== Create a mobility trace for a node using a local XML file ====
+
Three examples are provided, available under the examples folder of the module:
* Name: Create a mobility trace for a node using a local XML file
+
* Actors: User
+
* Description: The user is able to generate a mobility trace based on a XML file downloaded to the local filesystem.
+
* Preconditions:
+
# The file exists and is valid
+
  
==== Create mobility traces with dynamic node redirections ====
+
* routes-mobility-example.cc - This example illustrates basic usage of this module, generating mobility for a few nodes
* Name: Create mobility traces with dynamic node redirections
+
* routes-automatic-example.cc - This example shows the user how to generate mobility for entire node containers, by specifying a real-world area to generate mobility.
* Actors: User
+
* routes-offline-example.cc - This example illustrates how a user can load travel planning information previously downloaded.
* Description: The user is able to generate a mobility trace for a node that, at a specified point in time, is redirected to another destination.
+
* Preconditions:
+
# The user has internet access.
+
# The user has provided valid start and endpoints. The redirection address must also be valid.
+
# The Google Maps Directions service identifies correctly the start point, the end point and the redirection address.
+
  
=== Summary ===
+
= Installing the RoutesMobilityModel =
In summary, these past few weeks I've achieved the following:
+
This tutorial is concerned with the installation of the RoutesMobilityModel and its dependencies in a ns-3 installation. The steps described in the tutorial were successfully applied to ns-3.23 and ns-3.24.1. A video version of this tutorial can be found [https://www.youtube.com/watch?v=4o2G8msX37M here]:
* Implemented every use case mentioned, such as node redirection, automatic mobility trace generation and an offline mode.
+
* Documented every function introduced with Doxygen
+
* Implemented error handling
+
* Implemented logging
+
* Updated UML documentation
+
  
=== Documentation ===
+
The RoutesMobilityModel depends on curlpp, xerces-cpp and GeographicLib. If the Linux distribution offers packages for these libraries, as is the case for example in Ubuntu, it is sufficient to install the three packages, and it is possible to skip directly to the last step.
In addition to the Doxygen documentation, the existing UML documentation was updated to include the new functionalities.
+
Bellow, you can view the final class diagram, the final use case diagram, the sequence diagram for the "Create mobility trace for a single node" use case and the sequence diagram for the "Automatic creation of mobility traces for a node container" use case.
+
<gallery>
+
File:RoutesMobilityModel_class_diagram.jpeg|Class diagram
+
File:RoutesMobilityModel_UC.jpg|Use Case diagram
+
File:ChooseRouteSD.jpg|Sequence diagram for the "Create mobility trace for a single node" use case
+
File:ChooseRoute(NodeContainer_nodeContainer,_double_lat,_double_lng,_double_radius).png|Sequence diagram for the "Automatic creation of mobility traces for a node container" use case
+
</gallery>
+
  
== Dependencies ==
+
The first step, whose commands depend on the Linux distribution in use, regard the installation of packages needed to compile curlpp, xerces-cpp and GeographicLib.
This module is dependent of the following libraries:
+
The packages to be installed are:
* libcurlpp
+
  autoconf
* Xerces-C++
+
  libtool
* GeographicLib
+
  libboost-dev
 +
  libcurl4-openssl-dev
 +
 
 +
The next step is to install the GeographicLib. This is the library responsible for performing the conversions between Geographical coordinates and Cartesian coordinates
 +
 +
  wget http://downloads.sourceforge.net/project/geographiclib/distrib/GeographicLib-1.44.tar.gz
 +
  tar xvfz GeographicLib-1.44.tar.gz
 +
  ./configure
 +
  make
 +
  sudo make install
 +
 
 +
 
 +
After that we need to install the curlpp library, which is responsible for querying the Google Maps APIs, through HTTP.
 +
  wget https://github.com/jpbarrette/curlpp/archive/v0.7.3.tar.gz -O curlpp_v0.7.3
 +
  tar xvfz curlpp_v0.7.3
 +
  ./autogen.sh
 +
  ./configure
 +
  make
 +
  sudo make install
 +
 
 +
Finally, it's time to install the xerces-cpp library, which is the library responsible for parsing the XML responses from Google
 +
  wget http://mirrors.fe.up.pt/pub/apache//xerces/c/3/sources/xerces-c-3.1.2.tar.gz
 +
  tar xvfz xerces-c-3.1.2.tar.gz
 +
  ./configure
 +
  make
 +
  sudo make install
 +
 
 +
Afterwards, the compiled libraries have to be added to the "path":
 +
Add these two lines to ~/.bashrc (or ~/.bash_profile, in some distributions).
 +
  LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib:/usr/lib:/usr/lib/x86_64-linux-gnu/
 +
  export LD_LIBRARY_PATH;
 +
In some distributions, the paths may vary slightly. The user should first run the ldconfig command, in order to determine where the libraries are installed.
 +
For example: ldconfig -p | grep $(LIBRARY)
 +
Finally, for the changes to take effect, the user should run:
 +
  source ~/.bashrc (or source ~/.bash_profile)
 +
 
 +
Installation of the RoutesMobilityModel module itself:
 +
 
 +
If the system does not have a working ns-3 installation, it is necessary to download and uncompress it, creating for example a "ns-3.24" directory.
 +
Download the module from the project's repository (https://bitbucket.org/TiagoCerqueira/routesmobilitymodel) and move it to ns-3's src/ folder:
 +
  wget https://bitbucket.org/TiagoCerqueira/routesmobilitymodel/downloads/mobility-service-interface.tar.gz
 +
  tar xvfz mobility-service-interface.tar.gz
 +
  mv mobility-service-interface.tar.gz ns-3.24/src
 +
 
 +
Since the module uses the Google Maps APIs to compute the node's path, the user must provide a valid API key. It's easy to do and free, for basic usage. Detailed instructions are provided with the module's documentation, in the file mobility-service-interface/doc/mobility-service-interface.rst
 +
 
 +
Afterwards, we add the API key to the file mobility-service-interface/conf/api-key.txt (create if necessary).
 +
 
 +
Finally, it's a matter of configure/build/run an example:
 +
  ./waf configure --enable-examples
 +
  ./waf build
 +
  ./waf --run mobility-service-interface/examples/routes-mobility-example
 +
 
 +
= Future Work =
 +
 
 +
* Implementation of proper serialization is one of the team's top priorities and should be included in the next release. This will empower users to repeat simulations using the same mobility.
 +
 
 +
* Implementing bidirectional coupling is another goal of the team, however, it will require further study to implement.
 +
 
 +
= Further Reading =
 +
 
 +
* [http://dl.acm.org/citation.cfm?id=2756515 T. Cerqueira, M. Albano, “RoutesMobilityModel: easy realistic mobility simulation using external information services”, Workshop on ns-3 (WNS3 ‘15), May 13th, 2015, pp. 40-46, Castelldefels, Spain. DOI: 10.1145/2756509.2756515]. A draft version of the paper can be found [http://www.cister.isep.ipp.pt/docs/routesmobilitymodel__easy_realistic_mobility_simulation_using_external_information_services/1060/attach.pdf here]
 +
* The Doxygen and module documentation <!-- add link here! -->
 +
* [https://www.nsnam.org/wp-content/uploads/2015/03/routesmobilitymodel_wns3_V1.pdf WNS3 2015 presentation slides]
 +
*[https://www.nsnam.org/mediawiki/index.php?title=RoutesMobilityModel&oldid=9272 SummerMentorshipProgram page]

Latest revision as of 17:03, 7 January 2016

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

Overview

Visualization of a mobility trace generated automatically for 1000 nodes
The mobility trace above, with the underlying real-world road network

Mobility trace generation in ns-3 is done either by using the Mobility module included in NS-3 or by importing mobility traces generated by third party programs in a compatible format. The Mobility module included in ns-3 gives programmers the building blocks to create simple or complex traces, but is hindered by the fact that creating complex traces using the current module alone takes too long, even for simulations with just a couple of mobility capable nodes. As for mobility traces generated by third party programs, such as SUMO, they can involve too much work for their generation, especially when the researcher's interest - and expertise - is more on the data communication than on the traffic simulation. Using the Google Maps API it is possible to generate complex mobility traces, simply by providing a start and end point.

The RoutesMobilityModel generates realistic mobility traces by querying the Google Maps Directions API and requesting directions between two (or more) points. The information obtained from the Google Maps services, used in tandem with the ns3::WaypointMobilityModel, allows the simulator to generate realistic mobility traces based on real-world locations and road networks. The purpose of this module is to bridge the gap between the highly complex but realistic SUMO and the synthetic mobility models available in ns-3.

This module was developed during the Summer Mentorship Program of 2014.

The RoutesMobilityModel module relies on the module ns3::WaypointMobilityModel in order to import the mobility routes retrieved from the external information services. Our module creates ns3::Waypoints that model the routes used to travel between two (or more) real world locations, and later on they are interpreted as the waypoints the vehicles move through during the simulation.

The Google Maps Directions service provides an XML that contains the following concepts:

  • Leg - A Leg is a list of Steps. Legs only occur if the user specifies a Waypoint (A to B, passing through C)
  • Step - A Step contains Points encoded in a polyline
  • Point - A latitude/longitude set

The information retrieved from the Google Maps Directions API contains, among other information, a polyline for each step of the route requested. It also contains the duration (the time it would take to go from the beginning to the end) for the step. The module decodes the polyline, thus creating a list of geographical coordinates, which are, in turn, converted to Cartesian coordinates. In order to model the speed of a node, implemented by setting the times for the ns3::Waypoints, we distributed the duration of the step in proportion to the distance traveled between two waypoints.

This module empowers the user to generate realistic mobility traces for entire node containers, using different transportation methods (driving, walking, cycling and public transportation), with little to no effort.

Overview of the module

The image above depicts a simple use case of this module, the generation of mobility trace for a single node.

The module described in this page provides an interface to convert information from a travel planning service. Currently, only the Google Maps services are implemented however the module was built in order to accommodate different travel planning services, such as OpenStreetMaps, and locations databases. To this end, the Strategy software design pattern was used in the module design.

Authors

Documentation

This module has been documented using Doxygen and UML. The UML diagrams for the current release are shown below. Additional documentation was created using sphynx, which documents the module in further detail. This documentation will be available in the ns-3 models documentation once the module is released.

Code repository

My code can be found here: https://bitbucket.org/TiagoCerqueira/routesmobilitymodel . This includes a ready-to-use version of ns-3.23 with my module.

Additionally, the user can also download a stable release of the module. To use it, the user must then copy the folder to the src/ folder of ns-3.

Current implementation

Features

  • Capable of generating mobility for single nodes or for entire node containers without size restriction
  • Allows the user to select different methods of transportation for the mobility traces (driving, walking, cycling and public transportation
  • Allows the user to specify a departure time
  • Is capable of generating mobility online, by contacting the Google Maps API, or offline, by importing cached responses in the filesystem. The Google Maps APIs ToS states that the users must not cache the response data for more than 30 days. Doing so is a direct violation of the ToS

Limitations

This module possesses a couple of limitations:

  • Currently, no proper serialization is implemented and, hence, it's not possible to run the exact same mobility between simulations
  • The module takes a long time to parse XML responses. This effect is only felt when dealing with large node containers (300+ nodes).
  • No bidirectional coupling between data layer and the mobility, which means that the data communications do not affect the mobility
  • Traffic information is only available with the paid version of the Google Maps Places API

Dependencies

This module is dependent of the following libraries:

  • libcurlpp
  • Xerces-C++
  • GeographicLib

Tests

In order to provide the users with a reliable module, the team developed a test case to test for the time placement of waypoints and the conversion between geographical and cartesian coordinates. The code is available in the test folder of the module.

Examples

Three examples are provided, available under the examples folder of the module:

  • routes-mobility-example.cc - This example illustrates basic usage of this module, generating mobility for a few nodes
  • routes-automatic-example.cc - This example shows the user how to generate mobility for entire node containers, by specifying a real-world area to generate mobility.
  • routes-offline-example.cc - This example illustrates how a user can load travel planning information previously downloaded.

Installing the RoutesMobilityModel

This tutorial is concerned with the installation of the RoutesMobilityModel and its dependencies in a ns-3 installation. The steps described in the tutorial were successfully applied to ns-3.23 and ns-3.24.1. A video version of this tutorial can be found here:

The RoutesMobilityModel depends on curlpp, xerces-cpp and GeographicLib. If the Linux distribution offers packages for these libraries, as is the case for example in Ubuntu, it is sufficient to install the three packages, and it is possible to skip directly to the last step.

The first step, whose commands depend on the Linux distribution in use, regard the installation of packages needed to compile curlpp, xerces-cpp and GeographicLib. The packages to be installed are:

 autoconf
 libtool
 libboost-dev
 libcurl4-openssl-dev

The next step is to install the GeographicLib. This is the library responsible for performing the conversions between Geographical coordinates and Cartesian coordinates

 wget http://downloads.sourceforge.net/project/geographiclib/distrib/GeographicLib-1.44.tar.gz
 tar xvfz GeographicLib-1.44.tar.gz
 ./configure
 make
 sudo make install


After that we need to install the curlpp library, which is responsible for querying the Google Maps APIs, through HTTP.

  wget https://github.com/jpbarrette/curlpp/archive/v0.7.3.tar.gz -O curlpp_v0.7.3
  tar xvfz curlpp_v0.7.3
  ./autogen.sh
  ./configure
  make
  sudo make install

Finally, it's time to install the xerces-cpp library, which is the library responsible for parsing the XML responses from Google

  wget http://mirrors.fe.up.pt/pub/apache//xerces/c/3/sources/xerces-c-3.1.2.tar.gz
  tar xvfz xerces-c-3.1.2.tar.gz
  ./configure
  make
  sudo make install

Afterwards, the compiled libraries have to be added to the "path": Add these two lines to ~/.bashrc (or ~/.bash_profile, in some distributions).

  LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib:/usr/lib:/usr/lib/x86_64-linux-gnu/
  export LD_LIBRARY_PATH;

In some distributions, the paths may vary slightly. The user should first run the ldconfig command, in order to determine where the libraries are installed. For example: ldconfig -p | grep $(LIBRARY) Finally, for the changes to take effect, the user should run:

  source ~/.bashrc (or source ~/.bash_profile)

Installation of the RoutesMobilityModel module itself:

If the system does not have a working ns-3 installation, it is necessary to download and uncompress it, creating for example a "ns-3.24" directory. Download the module from the project's repository (https://bitbucket.org/TiagoCerqueira/routesmobilitymodel) and move it to ns-3's src/ folder:

  wget https://bitbucket.org/TiagoCerqueira/routesmobilitymodel/downloads/mobility-service-interface.tar.gz
  tar xvfz mobility-service-interface.tar.gz
  mv mobility-service-interface.tar.gz ns-3.24/src

Since the module uses the Google Maps APIs to compute the node's path, the user must provide a valid API key. It's easy to do and free, for basic usage. Detailed instructions are provided with the module's documentation, in the file mobility-service-interface/doc/mobility-service-interface.rst

Afterwards, we add the API key to the file mobility-service-interface/conf/api-key.txt (create if necessary).

Finally, it's a matter of configure/build/run an example:

  ./waf configure --enable-examples
  ./waf build
  ./waf --run mobility-service-interface/examples/routes-mobility-example

Future Work

  • Implementation of proper serialization is one of the team's top priorities and should be included in the next release. This will empower users to repeat simulations using the same mobility.
  • Implementing bidirectional coupling is another goal of the team, however, it will require further study to implement.

Further Reading