VaN3Twin

<div align="center"> <img src="img/VaN3Twin_logo_v5_blk.png" width="400"> </div>

<br/><br/>

<img src="img/docs.png" height="40">

<br/><br/>

ns-3 modules to build and simulate ETSI-compliant VANET (V2X) applications using SUMO (v-1.6.0+) and ns-3 (ns-3-dev, version supporting the NR-V2X module by CTTC), with the possibility of easily switching stack and communication technology.

It has been tested with SUMO v1.6.0, v1.7.0, v1.8.0, v1.12.0, v1.18.0 on Ubuntu 20.04 and 22.04. Back compatibility is not ensured with new versions of TraCI and Ubuntu 24.04 is not officially supported yet.

Contacts, developers, project coordination: Marco MALINVERNO [marco.malinverno1@gmail.com], Francesco RAVIGLIONE [francescorav.es483@gmail.com], Carlos Mateo RISMA CARLETTI [carlosrisma@gmail.com], Diego GASCO [diego.gasco@polito.it], Roberto PEGURRI [roberto.pegurri@mail.polimi.it], Alessandro GENOVESE [alessandro.genovese@icloud.com], Alessandro GIACCAGLINI [alessandro.giaccaglini@gmail.com], Marco RAPELLI [rapelli.m@libero.it], Francesco LINSALATA [francesco.linsalata@polimi.it], Eugenio MORO [eugenio.moro@polimi.it], Claudio CASETTI [claudio.casetti@polito.it], Carla-Fabiana CHIASSERINI [carla.chiasserini@polito.it]

This project is licensed under a GPL-2.0 License. Please see also the LICENSE file for more details.

Looking for ms-van3t?

Were you looking for <img src="img/MS-VAN3T_logo-V2_small.png" height="30"> but ended up here?

VaN3Twin now integrates the whole ms-van3t framework, and much more, keeping the same functionalities, just under a new name, and with the addition of new functionalities like the integration with a full-fledged ray-tracer!

Important: you will still find the name ms-van3t in many parts of the framework. We are in the process of renaming all the references and files, but this may take a bit of time.

VaN3Twin installation

To build the project:

• Install SUMO following the guide at https://sumo.dlr.de/wiki/Downloads

  • You can use

    sudo add-apt-repository ppa:sumo/stable
sudo apt update
sudo apt install sumo sumo-tools sumo-doc

  • Be careful: in the future the previous commands will install updated version of SUMO which are not ensured to work with this scripts (that are tested with any version from v-1.6.0 to v-1.18.0 )

  • Test sumo by opening a terminal and running "sumo-gui".

  • Possible problems:

      You may get the following error when running SUMO:
      
      "sumo-gui: symbol lookup error: /usr/lib/libgdal.so.26: undefined symbol: GEOSMakeValid_r"
    
      To solve it, remove all the reference to GEOS inside /usr/local/lib/ (do NOT do it if you need the GEOS library):
    
      "sudo rm /usr/local/lib/libgeos*"
    

• Clone this repository in your pc:

git clone https://github.com/DriveX-devs/VaN3Twin.git

• Run, from this repository either:

./sandbox_builder.sh install-dependencies -> if this is the first time you install ns-3 or VaN3Twin on your system

or

./sandbox_builder.sh -> if this is not the first time you install ns-3

This script will download the proper version of ns-3-dev and install this framework. The folder ns-3-dev will remain linked to this GitHub repository (not to the vanilla ns-3-dev one), allowing you to more easily develop updates and possibile contributions to VaN3Twin.

• Configure ns3 to build the framework with <ns3-folder>./ns3 configure --build-profile=optimized --enable-examples --enable-tests --disable-python (add here what you want to enable)" - The usage of the optimized profile allows to speed up the simulation time. This command should be launched from inside the ns-3-dev folder.

• Important: If you are compiling VaN3Twin on Ubuntu 22.04 LTS or later, you need to specify, when calling ./ns3 configure, also the --disable-werror flag

• Build ns3: ./ns3 build

Important

src/automotive/ contains all the application related files and all the source code implementing the ETSI ITS-G5 stack for vehicular communications. Inside sumo_files_v2v_map you can find the SUMO map and trace for the V2V sample application, while inside sumo_files_v2i_map you can find the SUMO map and trace for the V2I sample application. Similarly you can find the SUMO map and trace for the Traffic Manager sample application inside sumo_files_v2i_TM_map and the ones for the Emergency Vehicle Warning inside sumo_files_v2i_EVW_map

src/traci/ and src/traci-applications/ contain instead all the logic to link ns-3 and SUMO.

src/cv2x/ contains the model for C-V2X in transmission mode 4.

src/sionna/ contains the integration files for the NVIDIA-SIONNA Ray Tracing module.

The user is also encouraged to use the sumo_files_v2v_map and sumo_files_v2i_map folders to save there the SUMO-related files for his/her own applications.

The version of CAM and DENM messages (v1 or v2) can be easily switched by relying on the switch_ETSI_version.sh script. This script relies on the ns-3-dev/src/automotive/model/ASN1/currmode.txt file. Please never modify it manually or delete it!

Working with an IDE

Although not necessarily required, you can also configure an IDE in order to more comfortably work with VaN3Twin. The suggested IDEs, which has also been used for the development of VaN3Twin, are QtCreator and CLion.

QtCreator

You can find all the instructions for setting up QtCreator with ns-3 (and the same applies to VaN3Twin, as it is based on ns-3) on the official ns-3 Wiki.

QtCreator can be installed on Debian/Ubuntu with: sudo apt install qtcreator

You need also to install the libclang-common-8-dev package (the command for Debian/Ubuntu is reported below): sudo apt install libclang-common-8-dev

Not installing libclang-common-8-dev may result in QtCreator wrongly highlighting several errors and not recognizing some types, when opening any source or header file, even if the code compiles correctly.

Important: if libclang-common-8-dev is not available, you can try installing a newer version. For example, on Ubuntu 22, we verified that libclang-common-15-dev works well too.

CLion

CLion can be easily installed with the JetBrains Toolbox App.

You can find all the instructions for setting up CLion with ns-3 (and the same applies to VaN3Twin, as it is based on ns-3) on our documentation.

VaN3Twin-CARLA extension

In addition to SUMO and GPS traces VaN3Twin supports the use of CARLA for mobility and sensor perception simulation. This extension leverages the OpenCDA framework to develop an LDM module and extend the gRPC adapter devised here to be able to extract not only localization information from CARLA but also perception information from the LDM module. The developed client module on ns-3 queries the information to use it for the mobility of each of the ns-3 simulated nodes and to update the LDM module with all perception data sent over the simulated vehicular network.

System requirements

We highly recommend running VaN3Twin-CARLA on Ubuntu 20.04 (used for developing the framework) or Ubuntu 18.04, Ubuntu 22.04 is not officially supported by CARLA. If both CARLA and OpenCDA need to be installed we recommend at least 35GB of free space on your system. For smooth execution of simulation (especially if AI/ML models are leveraged for the perception simulation) we recommend using a GPU with at least 8GB of memory. The version of CARLA supported by VaN3Twin-CARLA is CARLA 0.9.12.

Installing VaN3Twin-CARLA

To be able to use VaN3Twin-CARLA, CARLA and OpenCDA need to be installed. After following the steps detailed above to build the project, from inside the ns-3-dev folder execute the switch_ms-van3t-CARLA.sh script to install all necessary dependencies. The script will try to find the path of your CARLA and OpenCDA installation to be defined in the CARLA-OpenCDA.conf file. If the user already has an installation of either CARLA or OpenCDA they should specify the path to the installation together with the path to their Python environment in the following way:

CARLA_HOME=/path/to/CARLA_0.9.12

OpenCDA_HOME=/path/to/OpenCDA

Python_Interpreter=/path/to/anaconda3/envs/msvan3t_carla/bin/python3 if using conda or Python_Interpreter=python3.7 otherwise.

In case this is the first time using either CARLA or OpenCDA, the script will install them, prompting for confirmation in each case. It is highly recommended to install OpenCDA with conda.

Once the script finishes its execution, it is recommended to build only the simulation scripts for CARLA's usage instead of the whole project (i.e., run ./ns3 build "name-of-CARLA-example" instead of ./ns3 build). This permits avoiding libraries and dependency issues coming from other parts of the simulator, so that the CARLA simulations can be properly run.

Possible issues with CARLA and OpenCDA installation

Below is a list of possible issues that can arise during the configuration and possible ways to prevent/solve them:

• In case OpenCDA was already present inside the VaN3Twin folder from previous runs of the script switch_ms-van3t-CARLA.sh, it is recommended to clean the cache of OpenCDA's folder before running again the installation script again, with the command: sudo rm -r OpenCDA/cache/.
• In case the anaconda virtual environment msvan3t_carla was already present in your system from previous runs of the script switch_ms-van3t-CARLA.sh, it is recommended to delete it before running again the installation script, with `conda remove -n msvan3t_ca