Bridging Worlds: A Guide to Co-Simulating Autonomous Vehicles with CARLA and NS-3

Visualization of an urban environment in the CARLA simulator​

The future of transportation is connected. Vehicles will talk to each other (V2V) and to infrastructure (V2I), sharing data about speed, position, and intent to create a safer, more efficient road network. This technology, known as Vehicle-to-Everything (V2X), promises to prevent accidents and reduce traffic jams.

But how do we test these complex systems before deploying them on real roads? Real-world testing is expensive, potentially dangerous, and difficult to reproduce. The answer lies in simulation.

I found that while we have great tools for simulating vehicle physics and sensors, like CARLA, and powerful tools for simulating network protocols, like NS-3, there was a lack of a simple, modern, and easy-to-use bridge to make them work together.

This led me to create carla-ns3-co-simulation, an open-source framework that links these two worlds. In this article, I’ll briefly explain how it works, who can benefit from it, and how you can run your first co-simulation in minutes.

The Challenge: Two Simulators, One Goal

To accurately test a connected vehicle system, you need to simulate two things simultaneously:

1. The Physical World: How cars move, accelerate, turn, and perceive their environment with sensors.
2. The Network World: How wireless signals travel between cars, what data they contain, and how factors like distance or congestion affect communication.

CARLA is a king in the physical world. It’s an open-source simulator built on Unreal Engine that provides stunningly realistic 3D environments, vehicle physics, and a whole suite of sensors (cameras, LiDAR, GNSS).

NS-3 is a leading discrete-event network simulator. It’s the go-to tool for academic and industrial research on network protocols, from Wi-Fi to 5G and, importantly for us, the IEEE 802.11p standard used in V2V communications.

The problem? CARLA doesn’t know how to simulate network packets, and NS-3 doesn’t know how to drive a car. My project serves as the crucial link between them.

Why Build Another Bridge? The Co-Simulation Landscape

I’m not the first person to try and connect these worlds. During my research, I analyzed several existing frameworks, including CARLANeT, Eclipse MOSAIC, Cartery, and various solutions based on the Robot Operating System (ROS). While powerful, I encountered several recurring challenges:

• Outdated and Unmaintained: Many projects were proof-of-concepts that are no longer actively supported, making them difficult to use with modern versions of CARLA or NS-3.
• Overly Complex Dependencies: Some solutions require large, heavy frameworks like ROS or OMNeT++, which adds significant setup overhead and a steep learning curve if you only want to connect CARLA and NS-3.
• Incomplete or Unstable: Some frameworks were still under heavy development with key features (like the CARLA integration) not yet publicly available. In some cases, I simply couldn’t get the examples to run due to their complexity.

This created a clear need for a solution with a different set of priorities:

• Simplicity: A lightweight bridge with minimal dependencies.
• Modernity: Built to work with recent, stable versions of CARLA and NS-3.
• Accessibility: Easy to install and run, with clear documentation and automated setup scripts.

That’s why I built carla-ns3-co-simulation. It focuses on one thing and does it well: connecting CARLA and NS-3 in the most straightforward way possible.

How carla-ns3-co-simulation Works

The architecture is designed for simplicity and modularity. It consists of three main components:

carla-ns3-co-simulation component diagram

1. CARLA Simulator: Runs the 3D environment and manages vehicle movement and physics.
2. NS-3 Script (C++): Manages the network nodes (representing the vehicles) and simulates the V2V communication, specifically the broadcasting of Cooperative Awareness Messages (CAM).
3. Co-Simulation Manager (Python): This is the heart of the project. This Python script connects to CARLA and spawns vehicles. In a loop, it fetches the real-time position, velocity, and heading of each vehicle from CARLA. It then sends this data over a simple TCP socket to the running NS-3 script. NS-3 uses this data to update the physical location of its network nodes, ensuring the network simulation accurately reflects the traffic simulation.

This continuous loop allows the network simulation in NS-3 to be driven by the realistic vehicle behavior generated in CARLA.

Who Is This For?

I built this tool with a few key groups in mind: Researchers: Studying the performance of V2X protocols (like ETSI ITS-G5) in realistic, dynamic traffic scenarios. Students: Working on bachelor’s or master’s theses in autonomous driving, smart cities, or vehicular networks (VANETs). Developers & Hobbyists: Prototyping new connected vehicle applications, such as cooperative cruise control or collision avoidance systems, in a safe and repeatable environment.

Getting Started: Your First Co-Simulation

I’ve put a lot of effort into making the setup as painless as possible. You’ll need a Linux machine (Ubuntu 22.04 recommended) with a decent NVIDIA GPU.

Step 1: Get the Code

First, clone the repository from GitHub:

git clone https://github.com/TechOctopus/carla-ns3-co-simulation.git
cd carla-ns3-co-simulation

Step 2: Install Dependencies

I’ve included two simple scripts to handle the installation. The first installs system dependencies and Python packages. The second downloads and builds NS-3 with the required custom modules.

# Install system and Python dependencies
./installdependences.sh

# Download and build NS-3 (this will take some time!)
./installns3.sh

Step 3: Run the Simulation!

Running the simulation requires three terminals tabs.

Terminal 1: Start CARLA You need to have CARLA 0.9.15 installed. You can download it from the official GitHub releases. Once downloaded, run it:

# Navigate to your CARLA installation directory
./CarlaUE4.sh

A window with the CARLA environment should appear.

Terminal 2: Start the NS-3 Listener This script starts the network simulation, which will wait for the Python manager to connect.

cd ns-allinone-3.44/ns-3.44

# Run simul
./ns3 run scratch/vanet/main.cc -- --simTime=300.0

You’ll see a message saying it’s waiting for a connection.

Terminal 3: Start the Co-Simulation Manager This is the final step that kicks everything off!

# From the carla-ns3-co-simulation directory
python3 main.py

You will now see vehicles spawning in the CARLA window and log messages appearing in all three terminals as the simulation runs.

[embed]To see it all in action, check out this short video demonstration

What You Get: The Simulation Output

Once the simulation is complete (it runs for 10 seconds by default), check the temp/ directory. You’ll find:

1. co-simulation.log: A complete log of the simulation run.
2. vehicle_data.json: A file containing the timestamped position, speed, and heading of every vehicle throughout the simulation.
3. PCAP Files: For each vehicle, a .pcap file is generated (e.g., carla-vanet-0–0.pcap). You can open these in Wireshark to analyze the simulated network traffic and inspect the CAM packets.
4. Plots: In the temp/plots directory, you’ll find PDF graphs visualizing the vehicle trajectories, speeds, and headings.

An example of the trajectory plot generated by the simulation.

Conclusion

carla-ns3-co-simulation provides a solid, accessible foundation for anyone looking to explore the fascinating world of connected vehicles. It automates the complex setup process and provides a clear and extensible framework for future work.

My goal is to continue developing this project. Future plans include deeper integration of ETSI standards (like DENM messages), support for more CARLA sensors, and compatibility with newer versions of the simulators.

I encourage you to try it out! Fork the repository, experiment with the code, and feel free to open issues or contribute. Let’s simulate the future of driving, together.