LoRaWAN ns-3 module

This is an ns-3 module that can be used to perform simulations of a LoRaWAN network.

Quick links:

Getting started

Prerequisites

To run simulations using this module, you first need to install ns-3. If you are on Ubuntu/Debian/Mint, you can install the minimal required packages as follows:

sudo apt install g++ python3 cmake ninja-build git ccache

Otherwise please directly refer to the prerequisites section of the ns-3 installation page.

Note: While the ccache package is not strictly required, it is highly recommended. It can significantly enhance future compilation times by saving tens of minutes, albeit with a higher disk space cost of approximately 5GB. This disk space usage can be eventually reduced through a setting.

Then, you need to:

Clone the main ns-3 codebase,
Clone this repository inside the src directory therein, and
Checkout the current ns-3 version supported by this module.

To install this module at the latest commit, you can use the following all-in-one command:

git clone https://gitlab.com/nsnam/ns-3-dev.git && cd ns-3-dev &&
git clone https://github.com/signetlabdei/lorawan src/lorawan &&
tag=$(< src/lorawan/NS3-VERSION) && tag=${tag#release } && git checkout $tag -b $tag

Note: When switching to any previous commit, including the latest release, always make sure to also checkout ns-3 to the correct version (NS3-VERSION file at the root of this repository) supported at that point in time.

Compilation

Ns-3 adopts a development-oriented philosophy. Before you can run anything, you'll need to compile the ns-3 code. You have two options:

Compile ns-3 as a whole: Make all simulation modules available by configuring and building as follows (ensure you are in the ns-3-dev folder!):
```
./ns3 configure --enable-tests --enable-examples &&
./ns3 build
```
Focus exclusively on the lorawan module: To expedite the compilation process, as it can take more than 30/40 minutes on slow hardware, change the configuration as follows:
```
./ns3 clean &&
./ns3 configure --enable-tests --enable-examples --enable-modules lorawan &&
./ns3 build
```
The first line ensures you start from a clean build state.

Finally, ensure tests run smoothly with:

./test.py

If the script reports that all tests passed or that just three-gpp-propagation-loss-model failed¹, you are good to go.

If other tests fail or crash, consider filing an issue.

Usage examples

The module includes the following examples:

simple-network-example
complete-network-example
network-server-example
adr-example
aloha-throughput
frame-counter-update
lora-energy-model-example
parallel-reception-example

Examples can be run via the ./ns3 run example-name command (refer to ./ns3 run --help for more options).

Documentation

Simulation Model Overview: A description of the foundational models of this module (source file located at doc/lorawan.rst).
API Documentation: documentation of all classes, member functions and variables generated from Doxygen comments in the source code.

Getting help

To discuss and get help on how to use this module, you can open an issue here.

Contributing

Refer to the contribution guidelines for information about how to contribute to this module.

Authors

Davide Magrin
Martina Capuzzo
Stefano Romagnolo
Michele Luvisotto

License

This software is licensed under the terms of the GNU GPLv2 (the same license that is used by ns-3). See the LICENSE.md file for more details.

Acknowledgments and relevant publications

The initial version of this code was developed as part of a master's thesis at the University of Padova, under the supervision of Prof. Lorenzo Vangelista, Prof. Michele Zorzi and with the help of Marco Centenaro.

Publications:

D. Magrin, M. Capuzzo and A. Zanella, "A Thorough Study of LoRaWAN Performance Under Different Parameter Settings," in IEEE Internet of Things Journal. 2019. Link.
M. Capuzzo, D. Magrin and A. Zanella, "Confirmed traffic in LoRaWAN: Pitfalls and countermeasures," 2018 17th Annual Mediterranean Ad Hoc Networking Workshop (Med-Hoc-Net), Capri, 2018. Link.
D. Magrin, M. Centenaro and L. Vangelista, "Performance evaluation of LoRa networks in a smart city scenario," 2017 IEEE International Conference On Communications (ICC), Paris, 2017. Link.
Network level performances of a LoRa system (Master thesis). Link.

This is due to a bug in the current ns-3 version when restricting compilation to the lorawan module and its dependencies. If you need to use the three-gpp-propagation-loss-model, you can solve this by compiling ns-3 as a whole or with the --enable-modules "lorawan;applications" option to reduce compilation time. ↩