February 3, 2009 README TraNS - Traffic and Network Simulation Framework A brief tutorial Laboratory for Computer Communications and Applications Ecole Polytechnique Federale de Lausanne Ada Lezama Lugo, Michal Piorkowski, Maxim Raya, Bogdan Stroe, LCA-ISC-I&C, EPFL 1. What Is TraNS? TraNS (Traffic and Network Simulation Environment) is a simulation environment that integrates both traffic and network simulators and provides a tool to build realistic simulations of Vehicular Ad-hoc NETworks (VANET). The novelty of TraNS is that information exchanged in VANET communication protocols can influence the vehicle behavior in the mobility model. For example, it is possible to model the fact that if a vehicle broadcasts information reporting an incident, some of the neighboring vehicles will slow down. TraNS is the first open-source project providing a full-blown application-centric evaluation framework for VANETs. It is developed at the Laboratory for computer Communications and Applications (LCA), School of Computer and Communication Sciences, EPFL, Switzerland. 2. Mailing List As the program is still under development and is extended regularly, we advise you to stay informed by subscribing to the TraNS mailing list: http://listes.epfl.ch/doc_en.cgi?liste=trans 3. Content The current TraNS package contains the following files: - "TraNSv1.2/bin/": Contains all necessary libraries and the TraNS jar file - "TraNSv1.2/examples/mobility_traces/": contains .tcl files with generated traces for maps of Manhattan and EPFL with 3,30 and 300 nodes. This is a set of examples for TraNS working in trace generation mode. - "TraNSv1.2/source/": Contains the source code of TraNS. - "TraNSv1.2/javadoc/": Contains the Javadoc files for the TraNS - "TraNSv1.2/examples/roadmaps/": contains the maps for Manhattan in TIGER (http://www.census.gov/geo/www/tiger/) format (TGR36061) and the corresponding .net.xml files (original and cropped) - "TraNSv1.2/examples/vehicleroutes/": contains the .rou.xml files for the Manhattan maps with 30 (generated with random routes) and 100 (generated with flows specified in the configuration.txt file) vehicles - "TraNSv1.2/examples/google_earth/": contains the .kmz files corresponding to the cropped Manhattan scenario with and without a >>Road Danger Warning<< application - "TraNSv1.2/vanet/": contains sources of two vehicular applications, namely >>Road Danger Warning<< safety application and >>Dynamic Reroute<< traffic efficiency application. For the >>Road Danger Warning<< application each vehicle that encounters some danger on the road starts broadcasting a warning message to nearby vehicles. Upon a reception of the warning message each vehicle first slows down to 5 m/s at the predefined distance to danger zone (as specified by 'Distance to start slowing down' parameter) and then it stops 100 meters before the vehicle from which it has received the warning message. For the >>Dynamic Reroute<< application each vehicle stores a table of all road segments where with each road segment an estimated current travel time is associated. Each vehicle periodically broadcasts to all nearby vehicles its own travel time on the current road segment. Upon a reception of such a message each recipient updates its table with estimated traveled times. The information maintained in the abovementioned table is then used to dynamically reroute vehicle, so that it can avoid congestion. For example if suddenly a road segment 'S' becomes very congested (travel time on 'S' -> Inf), then the vehicle approaching 'S' will change his route to a new one avoiding the traffic jam on 'S'. - "TraNSv1.2/traci/": contains the implementation of the traci client for ns2 - "TraNSv1.2/traci/tracicommands-examples/": contains the .tcl files with scenarios that test different TraCI commands, specifically 'changeRoute', 'changeTarget', 'moveNode', 'setMaxSpeed' and 'stop'. For more details on TraCI commands please check this link: http://sumo.sourceforge.net/wiki/index.php/TraCI - "TraNSv1.2/javadoc/": contains the javadoc files (we will soon provide a detailed TraNS manual) - "TraNSv1.2/logs/": TraNS provides vital information concerning events and operation in log files, which are plain ASCII text files. 4. Installation 4.a Requirements - Java Runtime Environment (Sun Microsystem's J2SE version 1.6) - XML parser: Xerces-c (Linux only - tested using version 2.7.0) - Toolkit for developing Graphical User Interfaces: FOX (Linux only - tested using version 1.4.34) - Geospatial Data Abstraction Library: GDAL (Linux only - tested using version 1.3.2) - Cartographic Projections Library: PROJ.4 (Linux only - tested using version 4.5.0) - Simulation of Urban Mobility (SUMO) Traffic Simulator. For mobility trace generation only version 0.9.8 is enough. For interactive simulation with active TraCI interface use the version from subversion repository (at least version dev-SVN-r5499) - NS2 Network Simulator at least version ns-2.32. If you want to use realistic PHY and MAC layer for VANETs we encourage you to use the ns-2.33: http://dsn.tm.uni-karlsruhe.de/Overhaul_NS-2.php 4.b Installing - SUMO installation: Download binaries, sources and additional libraries from: http://sumo.sourceforge.net/downloads/downloads.shtml For installing from sources follow the steps described in: http://sumo.sourceforge.net/wiki/index.php/LinuxBuild Comments: 1. FOX-toolkit needs to be build with openGL-support enabled: ./configure --with-opengl=yes --prefix=$HOME && make install 2. To run SUMO with the feedback loop active the TraCI module has to be enabled: ./configure --with-fox=$HOME --with-proj-gdal=$HOME --with-xerces=$HOME --enable-traci --prefix=$HOME - NS2 installation: Follow the ns-allinone-2.32 installation process described in: http://nsnam.isi.edu/nsnam/index.php/Downloading_and_installing_ns-2 4.c Configuring - TraCI Interface configuration: 1. Read the traci-readme.txt file from the "TraNSv1.2/traci" folder. 2. Copy the whole directories tcpip and traci-client into the ns-2.32 source folder. 3. Patch the ns2 environment from within your ns-2.32 source folder. Use the command: patch -p0 < traci.patch 4. Configure and make ns2 as usual. - VANET Agents configuration: 1. Copy the whole directory of "TraNSv1.2/vanet" into your ns-2.3x folder 2.a In ns-allinone-2.32/ns-2.32/common/packet.h, in the enum packet t (line 170), insert (don't forget the comma at the end) PT_VANETRBC, PT_VANETDR, 2.b If you are using ns-2.33 insert in packet.h (instead of the lines above) static const packet_t PT_VANETRBC = 61; static const packet_t PT_VANETDR = 62; static packet_t PT_NTYPE = 63; // This MUST be the LAST one 3. In the same file in the class p info (line 266), insert name_[PT_VANETRBC]="VanetRBC"; name_[PT_VANETDR]="VanetDR"; 4. In ns-allinone-2.32/ns-2.32/tcl/lib/ns-packet.tcl, in the foreach prot loop calling add-packetheader, insert (e.g. line 156) VanetRBC # Vanet protocol VanetDR # Vanet-Dynamic Reroute protocol 5. In ns-allinone-2.3x/ns-2.3x/tcl/lib/ns-default.tcl, for example at the end of the file, insert these lines (values used to initialize the parameters): # Vanet Applications defaults Agent/VanetRoadWarning set jitterFactor_ 0.005 Agent/VanetRoadWarning set slowdown_dist_ 200 Agent/VanetRoadWarning set rwm_interval_ 0.5 Agent/VanetRoadWarning set restoring_time_ 5.0 Agent/DynamicReroute set jitterFactor_ 0.005 Agent/DynamicReroute set brc_interval_ 1.0 Agent/DynamicReroute set relativeDistanceToDecisionPoint_ 0.3 6. In ns-allinone-2.3x/ns-2.3x/Makefile: in the INCLUDES part, insert (don't forget the backslash at the end) -I./vanet -I./traci-client \ And in the OBJ CC vanet/vanetrw.o vanet/vanetdr.o vanet/vanet_event_handler.o\ vanet/bounding_box.o vanet/connectedLanes_db.o\ 7. Recompile ns with the new protocol: cd ns-allinone-2.3x/ns-2.3x/ make clean make 5. Using NOTE: the current version of TraNS was tested on Fedora 6 (2.6.22.14-72.fc6) with sumo-dev-r5499 and ns2-allinone version 2.32 and 2.33 as well as on Windows XP, VISTA with sumo 0.9.8 (only mobility trace generation) - To run the project from the command line, go to the project folder and type the following: java -jar TraNSv1.2.jar - If you are planning to perform simulations using very large road networks or generate traces with a large number of vehicles type the following command: java -Xms1024m -Xmx1024m -jar TraNSv1.2.jar where -Xms is the memory size from which the application starts and -Xmx is the memory limit usage. 5.a Trace generation mode (no feedback loop; TraCI interface disabled) - To generate traces perform the following steps: 1. Select 'Generate NS2 Mobility Traces' checkbox 2. Specify 'Begin Time' and 'End Time' of the simulation 3. Specify the folder where SUMO binaries are located e.g. ~/sumo/src 4. Specify the road network file, e.g. ~/TraNSv1.2/examples/roadmaps/manhattan_crop.net.xml 5. Specify the file with vehicle routes, e.g. ~/TraNSv1.2/examples/vehicleroutes/manhattan_crop_30.rou.xml 6. Click 'Generate Traces' button 7. Verify if the newly generated scenario file for ns2 (.tcl) under ~/TraNSv1.2/examples/mobility_traces/ contains appropriate values of the following variables: tracedir, nn, x, y, sc (Check the information from the popup window which contains details on which parameters should be changed in the .tcl file) - To generate road network map from TIGER database: 1. Specify the directory where SUMO binaries are 2. Unselect button 'Existing Network File' 3. Select from drop down menu: 'Tiger Map' 4. Select TIGER prefix folder, e.g. ~/TraNS/examples/roadmaps/TGR36061 5. Click 'Generate Road Network'. The output will be written to a file 'yourmapname.net.xml' under the default forder for network files as specified in 'TraNS Preferences' - To generate road network map from ArcView map: 1. Specify the directory where SUMO binaries are 2. Unselect button 'Existing Network File' 3. Select from drop down menu: 'ArcView' 4. Select 'ArcView' prefix folder 5. Click 'Generate Road Network' The output will be written to a file 'yourmapname.net.xml' under the default forder for network files as specified in 'TraNS Preferences' - To crop a road network map: 1. Select a road network map (an existing one or a new one) 2. Visualize the original network map by clicking 'Visualize' button to get the coordinates of the bounding box that defines the cropped region (you can find the coordinates in the right bottom corner of the visualizaiton tool) 2. Check 'Crop Map' box 3. Introduce the coordinates of the bounding box 4. Click 'Generate Road Network' The output will be written to a file 'yourmapname_crop.net.xml' under the default forder for network files as specified in 'TraNS Preferences' - To rescale speed for an existing road network: 1. Select a road network map (an existing one or a new one) 2. Check 'Rescale' to new maximum allowed speed box 3. Select the new maximum speed 4. Click 'Process Road Network' The output will be written to a file 'yourmapname_rescaled.net.xml' under the default forder for network files as specified in TraNS Preferences - To generate routes from flows: 1. Specify the directory where SUMO binaries are 2. Select the radio button 'Generate Routes' 3. Select the road network file to be used e.g. ~/TraNSv1.2/examples/roadmaps/manhattan_crop.net.xml 4. Select the tab 'Routes from Flows' 5. In the table specify the flows, i.e., the flow 'ID', the edge 'From', the edge 'To', the 'Begin' time of flow, the 'End' time and the number of 'Vehicles' on that particular flow. In the current version you can specify up to 200 flows. 6. Click 'Generate Routes'. The output will be written to a file 'yourmapname.rou.xml' under the default forder for network files as specified in 'TraNS Preferences' - To generate random routes: 1. Specify the directory where SUMO binaries are 2. Select the radio button 'Generate Routes' 3. Select the road network file to be used e.g. ~/TraNSv1.2/examples/roadmaps/manhattan_crop.net.xml 4. Select the tab 'Random Routes' 5. Specify the 'End of the transient phase [s]' needed to populate road network with vehicles, e.g. 50 seconds 6. Specify the number of vehicles to be generated per second in the transient phase, e.g. 10 vehicles per second 7. Click 'Generate Routes'. The output will be written to a file 'yourmapname.rou.xml' under the default forder for network files as specified in 'TraNS Preferences' 5.b Interactvie mode (active feedback loop between ns2 and SUMO enabled through TraCI interface) - To test basic TraCI commands (changeRoute, changeTarget, moveNode, setMaxSpeed, stop): 1. Uncheck the 'Generate NS2 Mobility Traces' box 2. Select the begin and end time of the simulation 3. Specify the directory where SUMO binaries are. 4. Select the road network file to be used e.g. ~/TraNSv1.2/examples/roadmaps/manhattan_crop.net.xml 5. Select the file with vehicle routes to be used e.g. ~/TraNSv1.2/examples/vehicleroutes/manhattan_crop_30.rou.xml 6. Specify the directory where NS executable file is 7. Select the simulation file to be used e.g. ~/TraNS/traci/tracicommands-examples/changeRoute/changeRoute_manhattan_30.tcl 8. Click 'Perform Simulation' button - To test VANET application: 1. Uncheck the 'Generate NS2 Mobility Traces' box 2. Select the begin and end time of the simulation 3. Set the penetration ratio 4. Specify the directory where SUMO binaries are. 5. Select the road network file to be used e.g. ~/TraNSv1.2/examples/roadmaps/manhattan_crop.net.xml 6. Select the file with vehicle routes to be used e.g. ~/TraNSv1.2/examples/vehicleroutes/manhattan_crop_30.rou.xml 7. Specify the directory where NS executable file is 8. Specify the network parameters for NS2 simulation in Simulation Parameters module 9. Specify the which ns2 traces should be generated by checking the corresponding boxes (e.g. NAM trace) 10. Select Road Traffic Event to be triggered: Vehicle-related or Location-related Using Vehicle-related: a. Choose the vehicle generating the event b. Select the time when the vehicle is stopped c. Select the time when the vehicle starts moving Using Location-related: a. Specify the bounding box coordinates of the disabled region (travel time on the road segments that fall into the disabled region tends to Inf) b. Select the time when the region is disabled c. Select the time when the region is enabled again 11. Select VANET application >>Road Danger Warning<< or >>Dynamic Reroute<< application Using >>Road Danger Warning<< application: a. Define the broadcast period, e.g. every 1 second b. Define the jitter broadcast, e.g. 0.005 seconds c. Define the distance to the danger zone at which vehicle slows down to 5 m/s, e.g. 200 (vehicle stops 100 meters before the danger zone) d. Define the Warning Message Timeout, i.e., the time between the last warning message reception and the moment at which vehicle starts moving again at the speed before receiving the first warning message, eg. 5 seconds. Using >>Dynamic Reroute<< application: a. Define the broadcast period, e.g. every 1 second b. Define the jitter broadcast, e.g. 0.005 seconds c. Define the relative distance to the next intersection at which the decision about rerouting will be taken by a vehicle, e.g. 0.3 d. Click Perform Simulation button 5.c Visualization To visualize the simulation output user has to generate the kmz file to be able to view the output using Google Earth. Once both the road network file and the file containing the mobility trace has been generated, a user can produce a kmz file. This is possible in both operational modes (with TraCI and without). To generate a kmz file do the following: 1. Click on 'Visualize Output' 2. In the popup window select the 'Road Network File' and the 'Mobility file' 3. After clicking 'OK' the kmz is produced and automatically viewed in Google Earth. NOTE: In the current version only road network files generated using TIGER maps are supported by the visualization module. For the other formats (e.g. shapefile) the user may use the nam visualization module. 6. Acknowledgements - README by Ada Lezama Lugo, Michal Piorkowski, Maxim Raya and Bogdan Stroe - The TraCI patch for ns2 was originally developed by Axel Wegener from University of Luebeck, Germany (http://sumo.sourceforge.net/wiki/index.php/TraCI#Resources) - The VanetRBC extension for ns2 was originally developed by Daniel Jungels at EPFL, Switzerland - Google Earth is a trademark of Google Inc. 7. References @article{piorkowski07trans, title = {{TraNS: Realistic Joint Traffic and Network Simulator for VANETs}}, author = {Michal Piorkowski and Maxim Raya and Ada Lezama Lugo and Panos Papadimitratos and Matthias Grossglauser and Jean-Pierre Hubaux}, details = {http://doi.acm.org/10.1145/1374512.1374522}, journal = {ACM SIGMOBILE Mobile Computing and Communications Review}, volume = {12}, issue = {1}, month = {January}, year = {2008} }