README.md

 1. DetNetWiFi-ns3 framework overview

This repository holds the ns-3 DetNetWiFi simulation framework for wireless/wired deterministic networks developed by fortiss.

The framework holds the following components:

* Modelling of TSN endpoints and TSN enabled switches interconnected to TSN WLAN regions. Multiple TSN end-points interconnected to 2 TSN-enabled switches; a switch interconnects to a TSN WLAN region. See TSNWiFi example. On the wired part, integrates a Time-aware Shaper based on the [code of Krummacker et al](https://www.researchgate.net/profile/Dennis-Krummacker/publication/348431501_TSN_Simulation_Time-Aware_Shaper_implemented_in_ns-3/links/5ffec2c0299bf140888ff7cd/TSN-Simulation-Time-Aware-Shaper-implemented-in-ns-3.pdf).

* TWT-based time-aware scheduling as described in ([Documentation, Proposal for Time Aware Scheduling](https://git.fortiss.org/iiot_external/detnetwifi-ns3/-/blob/main/Documentation/IEEENOMS_TSNWiFi_Schneider_Sofia_Kovatsch.pdf). See also the  [Youtube video](https://www.youtube.com/watch?v=J2Hy3X61ts8)

* Timing Model providing support for Clocks per node. This block provides individual node clocks, to model synchronisation aspects. On the wired region, each node can therefore synchronise its own local clock to the IEEE 1588 Grandmaster clock residing on one of the switches. Each of the wireless nodes also contains a local clock.

* Fine Time Measurement protocol based synchronisation, as  [Documentation, Fine time Measurement protocol based synchronization](https://git.fortiss.org/iiot_external/detnetwifi-ns3/-/blob/main/Documentation/TSNWiFi_TimeSync-7.pdf). The framework holds the FTM-PTP synchronisation proposal developed in the context of the fortiss project TSNWiFi. The FTM code (synchronisation) has been adapted from the TU Berlin FTM code for localization, available here: https://github.com/tkn-tub/wifi-ftm-ns3. 

* Examples: Examples are available under [ns-3.34/scratch/](https://git.fortiss.org/iiot_external/detnetwifi-ns3/-/tree/main/ns-3.34/scratch). [TSNWiFi.cc](https://git.fortiss.org/iiot_external/detnetwifi-ns3/-/tree/main/ns-3.34/scratch/TSNWifi) holds an example with 1 TSN wired region interconnected to 1 WTSN region. [DetNetWiFi.cc](hhttps://git.fortiss.org/iiot_external/detnetwifi-ns3/-/tree/main/ns-3.34/scratch/DetNetWifi_Scenario1) holds an example for OBSS WTSN regions.

* [Documentation](./Documentation). Tutorials on the framework; scientific publications, etc.



# 2. How to Install

DetNetWiFi can run on ns-3.34 (original, rf. to section 2.1) or ns-3.36 (rf. to section 2.2)


## 2.1 Running with ns-3.34 
The instructions to install ns-3 and ns-3-DCE are derived from: https://www.nsnam.org/docs/dce/manual/html/getting-started.html. We rely on bake, a new tool in ns. See https://www.nsnam.org/wiki/Installation#Installation_with_Bake


For Ubuntu 20.04, please check the steps here: https://karimmd.github.io/post/tutorial/ns3_installation/ to ensure an adequate use of dependencies.


### 2.1.1 Copy DetNetWiFi for ns-3.34

git clone https://git.fortiss.org/iiot_external/detnetwifi-ns3.git


- Move to ns-3.34 folder
- Type        ./waf configure --cxx-standard=-std=c++17 in command window
- Then,  type ./waf build 
- It is recommended to update the g++ compiler version to 8 or above before installation


### 2.2.1 OPTIONAL: Install and Test iPerf with ns-3 (Requires Ubuntu 18.04 and ns-3 DCE)
- iPerf can be used to model traffic accordingly to the TSN Traffic profiles are provided in deliverable D2.1 (https://sharepoint.fortiss.org/projects/detnetwifi/Shared%20Documents/Deliverables/D2.1/DetNetWiFi_DeliverableD2.1.pdf?d=w069686d7410c480bb1acf3840d1a57e0)

- run first the example for iPerf in ns-3-dce:

cd source/ns-3-dce

./waf --run dce-iperf 

OR

./waf --run iperf-example

- we have tested iPerf 3 (v3.1), with the following add-ons:

I. https://github.com/RichardWithnell/iperf/tree/dce
Added compatibility with DCE

II. https://github.com/woody77/iperf/tree/pacing_timer
Added pacing functionality

I. is the main repository, copy only "pacing" functionality from II. 

File changes:
* cjson.c
* iperf_api.c
* iperf_api.h
* iperf.h
* iperf_util.c
* iperf_udp.c
* iperf_tcp.c
* iperf_locale.c

Note: 
* Search for "pacing" in II and add all the required code to I.
* WIP: Parallel streams, function only with 1 stream now.

./configure CFLAGS="-g -U_FORTIFY_SOURCE -fPIC" LDFLAGS="-pie -rdynamic" --with-pic --disable-shared --disable-static --without-openssl

make 

## 2.2 Running with ns-3.36 (Testbed in Ubuntu 22.04)

Check:  https://www.nsnam.com/2022/06/ns3-installation-in-ubuntu-2204.html


Dependencies:
sudo apt install g++ python3 python3-dev pkg-config sqlite3 cmake python3-setuptools git qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools gir1.2-goocanvas-2.0 python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython3 openmpi-bin openmpi-common openmpi-doc libopenmpi-dev autoconf cvs bzr unrar gsl-bin libgsl-dev libgslcblas0 wireshark tcpdump sqlite sqlite3 libsqlite3-dev  libxml2 libxml2-dev libc6-dev libc6-dev-i386 libclang-dev llvm-dev automake python3-pip libxml2 libxml2-dev libboost-all-dev 

Download ns3-36-1 from https://www.nsnam.org/docs/release/3.36/tutorial/singlehtml/index.html

Change into the ns-3.36 directory:

cd ns-allinone-3.36.1/ns-3.36.1
./ns3 configure --enable-examples –enable-tests
./ns3 build
./test.py

### 2.2.1 Install and run DetNetWiFi

We advise downloading the code to a separate folder, and then copying the respective directories to the ns-3.36 source.

On your folder:

git clone https://git.fortiss.org/iiot/ns3-detnetwifi-framework/ns3-36-detnetwifi.git

Copy the content in your folder to ns-allinone-3.36.1/ns-3.36-1/src (clock, tsnwifi, core, network, wifi and tsn) and replace the scratch folder with the existing folder to run the examples.

Configure and build ns3:
https://www.nsnam.org/docs/tutorial/html/getting-started.html
./ns3 configure --enable-tests --enable-examples
./ns3 build


# 3. Run the ns-3 DetNetWiFi Examples

The folders provided represent models or some changes to files.
In tsnwifi, you have different files to test detnetwifi under examples.


We provide an example, the DetNetWiFiScenario1 example, which is based on the modelling of the DetNetWiFi demonstrator. Currently the model considers 1 TSN wired region and 2 OBSSs.

For ns-3 logging, etc., check https://www.nsnam.org/docs/release/3.7/tutorial/tutorial_21.html

## 3.1 TSNWiFi.cc
- The TSNWiFi example, available in [scratch/TSNWiFi](https://git.fortiss.org/iiot/detnetwifi-ns3/-/tree/main/ns-3.34/scratch/TSNWifi), provides a basic TSN wired/wireless scenario interconnecting 1 wired TSN region with 1 WTSN region.

cd <yourpath>/ns3-34/

export NS_LOG=UdpEchoClientApplication=level_all

./waf --run scratch/TSNWiFi/TSNWifi.cc

## 3.2 DetNetWiFi.cc
- The DetNetWiFi_Scenario1.cc example, available in [scratch/DetNetWifi_Scenario1](https://git.fortiss.org/iiot/detnetwifi-ns3/-/tree/main/ns-3.34/scratch/DetNetWifi_Scenario1), provides an OBSS scenario with 2 APs (2 BSSs) and multiple STAs.

cd <yourpath>/ns3-34/

./waf --run DetNetWifi_Scenario1

# 4. Creating a new Example Scenario

On your local repository, Call your Scenario DetNetWiFi_Scenariox.cc

* create a folder under ns-3.34/scratch/DetNetWiFi_Scenariox/
* ensure adequate commenting and authoring in accordance with the fortiss IIOT rules (check the internal wiki)
* Check .gitignore on the folder scratch, and ensure your directory is visible!



# Credits
* Overall code check-up: Rute C. Sofia, Sugandh Huthanahally Mohan
* Time synchronisation aspects, FTM, time model: Sugandh Huthanally Mohan
* Initial Scheduling, TAS integration, TWT aspects: Chitiphat Chongaroonngamsaeng
* Frame preemption validation: Chitiphat Chongaroonngamsaeng
* Multi-AP co-OFDMA coordination: Ahmed Ansari, Manel Khelifi
* Multi-AP adaptive scheduling aspects: Chitiphat Chongaroonngamsaeng, Sugandh Huthanahally Mohan, Ahmed Ansari