search

signetlabdei / lorawan

An ns-3 module for simulation of LoRaWAN networks
GNU General Public License v2.0
182 stars 130 forks source link
lora lora-alliance lorawan network-analysis network-simulator simulation

readme

LoRaWAN ns-3 module

CI codecov

This is an ns-3 module that can be used to perform simulations of a [LoRaWAN](https://lora-alliance.org/about-lorawan "LoRa Alliance") 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:

  1. Clone the main ns-3 codebase,
  2. Clone this repository inside the src directory therein, and
  3. 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:

  1. 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

  2. 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[^1], you are good to go.

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

[^1]: 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.

Usage examples

The module includes the following examples:

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

Documentation

Other useful documentation sources:

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

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: