UNetyEmu: Unity-based simulator for aerial and non-aerial vehicles with network emulator integration

UNetyEmu is a novel simulation framework combining Unity and Mininet-WiFi, enabling realistic multi-vehicle experiments with both aerial and ground mobility alongside network emulation. Researchers can study smart city applications like 5G vehicular communication, edge computing, and UAV coordination. By integrating Unity’s 3D simulation and Mininet-WiFi’s real-time network emulation, UNetyEmu provides an environment for evaluating UAV navigation, network performance, and collaborative autonomy in urban settings.

Readme structure

This repository is structured as follows, according to the files generated by a Unity project:

• Assets : Files and resources used to create scenarios, objects, algorithms, etc.
  • DepthCameraImages : Folder used to store the depth camera sensor captures.
  • MissionsLogs : Folder used to save .csv files with different indicators during drone flight (position, altitude, orientation, speed, battery level, current status, etc.).
  • Models : Folder where the 3D models used in the scenes are stored, together with their materials and textures.
  • Resources : Folder that contains information about animations, prefabs models, user interface, and above all the configurable JSON files for the instantiation of the drones in the scenes.
  • Scenes : The three scenes available in UNetyEmu.
  • Scripts : Folder that stores all the C# Scripts used in the scenes, as well as the Python Scripts for plotting the results, and the Mininet-Wifi configuration files.
    • Algorithms : Algorithms designed for drone flight such as path planning and obstacle avoidance.
    • CameraSettings : Scripts that control the movement of the main camera within Unity scenes.
    • Controllers : PID controller for flight dynamics.
    • GeneralManagementScripts : Scripts for the simulation of a logistics center for package delivery using drones.
    • GeneralSettings : Essential configuration script to obtain the information of the drones that will be instantiated in the scenes.
    • GetFeatures : Components created to access the physical characteristics of the drone (unladen weight, estimated flight time, initial battery level, motor thrust, etc.)
    • Network : Folder that contains the base station representation and communication scripts inside Unity.
      • mininet : Python scripts to run from Mininet-Wifi and test the connection to the network emulator
    • PlayersDynamics : Scripts designed to simulate the dynamics of a drone.
    • Sensors : Scripts designed to simulate a 360-degree LiDAR sensor and depth camera.
  • TextMesh Pro : Unity folder created by one of the packages.
  • Tree_Textures : Unity folder created by one of the packages.
• ImagesDoc : Images used in the documentation of UNetyEmu
• Packages : Used Unity packages.
• ProjectSettings : Unity folder that contains the project configurations.
• .gitignore : Description of folders and files ignored when using GitHub
• Assembly-CSharp-Editor.csproj : Unity file that contains references and settings for scripts running in the project
• Assembly-CSharp.csproj : Unity file that handles scripts that are located in any folder called Editor inside of the project
• LICENSE : Apache License 2.0
• README : This current file that shows the requirements for evaluation mentioned in SBRC25.

Ribbons considered (Selos Considerados)

The ribbons considered are: "Artefatos Disponíveis (SeloD)", "Artefatos Funcionais (SeloF)", and "Experimentos Reprodutíveis (SeloR)".

Basic information

In order to take advantage of all the network features of Mininet-Wifi on Linux, and also to take advantage of the compatibility and optimization of Unity on Windows, UNetyEmu uses both operating systems. Therefore, we use Unity on Windows 11, and Mininet-Wifi in a virtual machine with Lubuntu 20.04.

In this first version of UNetyEmu, we present three different scenarios. The scenarios include a simple version to discover different features of UNetyEmu (such as different types of drones, different sensors, different algorithms), to a complex one covering a logistical packet delivery scenario using the Mininet-Wifi network emulator.

Dependencies

The First and Second Scenarios do not use network emulation, so you simply need to:

• Unity account (Free accounts for personal or student use)
  • Unity Hub
    • Unity 2022.3.22f1 (Tested version of the editor)
• Python (Tested on 3.13.1) or Python from the Microsoft Store
  • Pip 21.2.3 (or higher) (Make sure the PATH environment variable knows it)
    • [Pandas] (pip install pandas)
    • [Seaborn] (pip install seaborn)
    • [Matplotlib] (pip install matplotlib)
    • [Numpy] (pip install numpy)

For the Third Scenario we show the integration with Mininet-Wifi, so you also need the following:

• VirtualBox 7.1.4 (Only tested on Windows)
• Mininet-WiFi (Pre-configured Virtual Machine image)
• .NET SDK 9.0 (Required for integration with VSCode and Unity libraries)
• Scapy
• Npcap 1.8 (or higher)
• WinPcap

To help understand the algorithms and codes created in UNetyEmu, we recommend using:

• VSCode with the following extensions:
  • Unity
  • C# Dev Kit
  • C#
  • .NET Install Tool
  • Python
  • Pylance
  • Rainbow CSV

Security concerns

The execution of this artifact is risk-free for evaluators. UNetyEmu uses as its core operation, documented frameworks and openly available online such as Unity and Mininet-Wifi.

Installation

To install UNetyEmu and run the first two scenarios, follow the next subsections:

• Getting started with Unity
• UNetyEmu Basic Setup using Unity

To run the third scenario, follow, in addition to the subsections mentioned above, those related to Mininet-Wifi. In other words, follow the next subsections:

• Getting started with Unity
• UNetyEmu Basic Setup using Unity
• Getting started with Mininet-Wifi
• UNetyEmu Basic Setup using Mininet-Wifi.

Getting started with Unity

1. Before anything, make sure you create or have access to a Unity account. Unity has free plans for student (post-secondary and high school) or personal use;

2. Download, install and open Unity Hub. You will need to Sign in with your user account;

3. If this is your first time in Unity Hub, you will probably see a recommendation to install the latest version of Unity that we don't need it, therefore, simply select Skip installation;

5. Go to Preferences and make sure you have activated your license to be able to install the correct version of the Unity Editor and correctly load the UNetyEmu project;

6. Now, go to Installs -> Install Editor -> Archive and click on the link download archive, this will open a website with all versions of the Unity Editor available for download;

7. Search for version 2022.3.22f1 and select the Install button on the website, this will redirect to Unity Hub;

8. Continue with the installation of the Unity Editor and wait for it to finish. Now, you are ready to load the UNetyEmu project in Unity Hub using the Unity Editor just installed. If you had any problems with the installation of the Unity Editor, follow the Unity installation manual.

UNetyEmu Basic Setup using Unity

1. Downloaded the file UNetyEmu.zip related to our proposal or cloned the repository https://github.com/intrig-unicamp/UNetyEmu;

2. Open Unity Hub, go to Projects -> Add -> Add project from disk;

3. Find the UNetyEmu folder, and select Open;

NOTE: Unity needs the whole folder named UNetyEmu to open the project correctly

4. Once the project has been loaded, select it once to open;

5. Wait for Unity to open the project;

6. If this is the first time you open a Unity project, you will notice that Unity Editor contains important toolbars and windows. On the left side is the Hierarchy, in the center are the Scene and Game windows, while on the right side is the Inspector. Also, at the bottom left are the Project folders and to the right is the Console, where messages will be displayed during the simulation of the scenarios;

If you find any messages about rebuilding libraries or .meta files, don't worry, you can simply disregard them and click on the Clear button in the Console;

7. In the Projects window, find the Assets / Scenes folder. Here you will find the three scenarios available in UNetyEmu.

Getting started with Mininet-Wifi

This setup process consists of performing different configuration steps so that network emulation really happens when communicating Unity in Windows with Mininet-Wifi in Linux using a VM. Therefore, we will detail what to do in each operating system [Windows] and [Linux VM].

[Windows] Import the Mininet-WiFi VM image

The Mininet-WiFi VM image is around 7.4GB and is currently named as mn-wifi-vm.ova. To import it, do the following:

1. Install and open the Oracle VirtualBox Manager;

2. Go to File -> Import Appliance;

3. Find and open the mn-wifi-vm.ova file. Select Finish and wait for the appliance to be imported;

[Windows] Configure network adapters in the Mininet-Wifi VM

After we import mn-wifi-vm.ova:

4. Go to Settings -> Network in VirtualBox;

5. Set Adapter 1 to Bridged Mode and Promiscous Mode: Allow All;

6. Then, add Adapter 2 as Host-Only Mode and Promiscuous Mode: Allow All;

Some users reported there might be a bug in VirtualBox regarding the number of virtual adapters being limited to 1. To fix this, follow this link. In addition, if the VM is not running and is saved, you will need to start the mn-wifi VM. Then, right click on the VM and select Stop -> Power Off. You cannot add a network adapter in the saved state.

7. Check which network adapter is the Host-Only Network. For instance, in the image below it is 192.168.56.1/24;

[Windows] Configure persistent rules

8. Given the Host-Only Network's IP, find and run PowerShell as administrator and add a persistent rule to forward traffic directly through Adapter 1 in the VM;

route -p add 10.0.0.0 mask 255.0.0.0 192.168.56.101 metric 1

9. Do the same to allow traffic through Docker built-in interface at the VM;

route -p add 172.17.0.0 mask 255.0.0.0 192.168.56.101 metric 1

10. Make sure your route print looks like this for IPv4 rules;

NOTE: 192.168.56.101 is the IP of the Host-Only Adapter. Make sure you replace the rules with the correct IP if it differs from the guidelines.

[Linux VM] Run Mininet-Wifi VM

11. Start the Mininet-Wifi VM. Open a terminal, and run;

ifconfig

12. Identify which interface is Bridged and Host-Only;

We already identified the Host-Only Network (Step 7) as 192.168.56.1/24. Consequently, enp0s8 is the Host-Only virtual interface (Adapter 2) where most of the traffic will go through after we install the routing rules on the Host-side - i.e., where Unity is running -, while enp0s3 is the Bridge Adapter (Adapter 1)

[Windows] Set the correct adapter to dynamically retrieve the Bridge IP

13. Since Adapter 1 is the Bridge and Adapter 2 is the Host-Only. We need to open the C# Script UNetyEmu/Assets/Scripts/Network/BaseStationMininetWifi.cs and simply make sure that the adapterIndex variable is set to 1 (Adapter 2), because the iteractive messages to Mininet-Wifi follow a specific route through this adapter. Also, make sure that the vmName variable matches with the virtual machine name;

[Windows] Configure Windows Firewall

14. Besides the routing configuration at the host (Unity-side), we have to EITHER a. disable the firewall or b. create inbound/outbound rules;

[Windows] a. Disable the Firewall for private networks

15. Search for: Windows Defender Firewall with Advanced Security, and click on Windows Defender Firewall Properties

16. Change the Firewall state to Off, then select Apply and then Ok;

NOTE: When you have finished using UNetyEmu, do not forget to re-enable the Firewall.

[Windows] b. Create inbound/outbound rules

15. Search for: Windows Defender Firewall with Advanced Security. We are going to create rules for both inbound and outbound, for both TCP and UDP, allowing traffic on all ports;

16. Select Inbound Rules, and then New rule

17. Rule Type as Port;

18. For simplicity, make all ports available;

NOTE: Remember that this process is for both TCP and UDP and in both cases inbound and outbound rules are created.

19. Mark to Allow the connection;

20. Uncheck Public and keep Domain and Private checked (for security reasons);

21. Name the rule as Allow All TCP From VM. Repeat the procedure for Outbound rules, and name it as Allow All TCP to VM;

NOTE: Consider all the steps were made sucessfully in order for the simulation to work!

UNetyEmu Basic Setup using Mininet-Wifi

Once all the initial configurations are finished to correctly use the Mininet-Wifi network emulator, we are going to copy the necessary UNetyEmu files inside the virtual machine.

1. Copy all scripts from UNetyEmu\Assets\Scripts\Network\mininet to a folder in the the VM;

2. Make sure the script remove_running_containers.sh, which is among the copied files, has permission to execute:

sudo chmod +x remove_running_containers.sh

Sometimes the substring '\r' ends up being copied along with the script, preventing it from being correctly recognized. To avoid this, you can apply a filter with sed - e.g., sed -i 's/\r$//' remove_running_containers.sh

3. Run the following command to remove any open containers:

sudo ./remove_running_containers.sh

Now, you are ready to run the Third Scenario Demo.

Minimum test

For a minimum test of UNetyEmu operation, we will run the First Scenario Demo and we will check the PID controller designed for the drone flight dynamics.

First Scenario Demo

In the Projects window, find the Assets / Scenes and open the First Scenario scene by double clicking.

As you can see, this scenario shows a small environment with buildings, trees, and static objects. A blue DronePad marks the drone's starting position and orientation, while the red DronePads indicate landing targets.

Run the simulation by clicking the Start button above the Game window.

Once the simulation has started, the Main Camera will zoom in on a drone that has been instantiated on the blue DronePad. Click anywhere inside the Game window. Then, you can use the arrows on your keyboard to move the drone's target position (white sphere) up, down, left rotation and right rotation. In addition, you can use the U, J, H and K keyboard keys to move the target position forward, backward, left and right, respectively.

If the drone is moving and following the white sphere (target), congratulations you have successfully installed UNetyEmu with its preliminary features.

The following section will complement this demonstration with the use of the sensors available on the drone. In addition, we will show you how to remove some Gizmos that can disturb the view of the simulation (such as the image of the white camera that moves together with the drone).

Can you find the 5 red DronePads that are in the scene? Try to land on them. Remember that the keys on the keyboard change only the position and orientation of the target (white sphere), i.e. we do not change the position of the drone directly with the keyboard. The drone uses a PID controller to follow the target.

Experiments

UNetyEmu offers a versatile platform for assessing drone behavior, physics interactions, and network performance. This work explores three distinct scenarios that highlight different aspects of drone operations. The first scenario focuses on basic maneuvering and sensor functionality; The second extends to multi-drone coordination for tasks such as package delivery and obstacle avoidance; and third integrates network emulation, allowing for the validation of drone communication and performance under realistic network conditions. Collectively, these scenarios illustrate the potential of UNetyEmu for research in drone navigation, smart city logistics, and 5G-enabled aerial networks.

First Scenario Demo (complement to the minimum tests)

In the Scene window you can see the position and orientation of each object in the scene. In addition, the Game window shows the view of the Main Camera belonging to the scenario.

If you cannot see any objects in the Scene window, you can double-click on any object in the Hierarchy window.

This scenario showcases a 360-degree LiDAR sensor, and a depth camera sensor. In addition, we demonstrate the operation of a PID controller that allows the Drone to follow a white sphere representing its target position and orientation.

The goal of this Demo is to understand sensor functionality, PID control, and drone maneuvering by landing on red DronePads while avoiding obstacles.

Second Scenario Demo

In the Projects window, find the Assets / Scenes and open the Second Scenario scene by double clicking.

The second scenario features four blue DronePads, each hosting a drone equipped with unique sensors, algorithms, and route planning strategies. This scenario showcases UNetyEmu’s capability to simulate multiple drones with distinct behaviors simultaneously.

A logistics center assigns missions to the drones through simulated message exchanges, enabling dynamic coordination and task management. Two drones handle package deliveries, receiving pickup and drop-off locations, a predefined route, and speed/altitude constraints. They follow their assigned paths autonomously without using sensor feedback. The logistics center randomly selects pickup and delivery points.

The third drone, equipped with a depth camera, follows a predefined path while capturing images every 30 seconds. Using a 360-degree LiDAR sensor, the fourth drone follows a trajectory while performing real-time obstacle avoidance by shifting right when detecting objects.

Third Scenario Demo

In the Projects window, find the Assets / Scenes and open the Third Scenario scene by double clicking.

In Mininet-WiFi

1. Run;

sudo python mininet_topo.py

2. The script will create the topology and wait for Unity messages;

NOTE: After executing the following step on the first execution attempt, an error may occur because the image ramonfontes/socket_position:python35 is not found and, consequently, downloaded automatically. If you want to avoid this, please download the docker images manually from DockerHub with docker pull ramonfontes/socket_position:python35. Otherwise, repeat step 1 above after the automatic download procedure.

In Unity

3. Press Play in Unity:

In Mininet-WiFi

4. Observe virtual drones appearing in the VM, with its positioning being dinamically modified as they move at Unity-side

LICENSE

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/