From 44c01e79eb44869b50039ecd6a66380f66b5415f Mon Sep 17 00:00:00 2001 From: Alessandro Aimi Date: Thu, 8 Aug 2024 11:54:31 +0200 Subject: [PATCH] README.md: minor clarifications + formatting --- README.md | 87 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 46 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 0174043daa..27854b04aa 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# LoRaWAN ns-3 module # +# LoRaWAN ns-3 module [![CI](https://github.com/signetlabdei/lorawan/actions/workflows/per-commit.yml/badge.svg)](https://github.com/signetlabdei/lorawan/actions) [![codecov](https://codecov.io/gh/signetlabdei/lorawan/graph/badge.svg?token=EVBlTb4LgQ)](https://codecov.io/gh/signetlabdei/lorawan) @@ -7,13 +7,15 @@ This is an [ns-3](https://www.nsnam.org "ns-3 Website") module that can be used to perform simulations of a [LoRaWAN](https://lora-alliance.org/about-lorawan "LoRa Alliance") network. -[Model Description](https://signetlabdei.github.io/lorawan/models/build/html/lorawan.html). +Quick links: -[API Documentation](https://signetlabdei.github.io/lorawan/html/d5/d00/group__lorawan.html). +* [Simulation Model Overview](https://signetlabdei.github.io/lorawan/models/build/html/lorawan.html) -## Getting started ## +* [API Documentation](https://signetlabdei.github.io/lorawan/html/d5/d00/group__lorawan.html) -### Prerequisites ### +## 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: @@ -27,11 +29,11 @@ Otherwise please directly refer to the [prerequisites section of the ns-3 instal Then, you need to: -1. Clone the ns-3 codebase, +1. Clone the main ns-3 codebase, 2. Clone this repository inside the `src` directory therein, and -3. Checkout the latest ns-3 version supported by this module. +3. Checkout the current ns-3 version supported by this module. -You can use the following all-in-one command: +To install this module at the latest commit, you can use the following all-in-one command: ```bash git clone https://gitlab.com/nsnam/ns-3-dev.git && cd ns-3-dev && @@ -39,7 +41,9 @@ git clone https://github.com/signetlabdei/lorawan src/lorawan && tag=$(< src/lorawan/NS3-VERSION) && tag=${tag#release } && git checkout $tag -b $tag ``` -### Compilation ### +**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: @@ -72,54 +76,55 @@ If other tests fail or crash, consider filing an issue. [^1]: This is due to [a bug in the current ns-3 version](https://gitlab.com/nsnam/ns-3-dev/-/issues/965) 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 ## +## 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` +* `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). -## Contributing ## - -Refer to the [contribution guidelines](.github/CONTRIBUTING.md) for information -about how to contribute to this module. - -## Documentation ## +## Documentation -For a description of the foundational models of this module, refer to `doc/lorawan.rst`. +* [Simulation Model Overview](https://signetlabdei.github.io/lorawan/models/build/html/lorawan.html): A description of the foundational models of this module (source file located at `doc/lorawan.rst`). +* [API Documentation](https://signetlabdei.github.io/lorawan/html/d5/d00/group__lorawan.html): documentation of all classes, member functions and variables generated from Doxygen comments in the source code. Other useful documentation sources: -- [ns-3 tutorial](https://www.nsnam.org/docs/tutorial/html/ "ns-3 Tutorial"): start here if you are new to ns-3! -- [ns-3 manual](https://www.nsnam.org/docs/manual/html/ "ns-3 Manual"): overview of the fundamental tools and abstractions in ns-3. -- The LoRaWAN specification can be requested at the [LoRa Alliance - website](http://www.lora-alliance.org) +* [Ns-3 tutorial](https://www.nsnam.org/docs/tutorial/html/ "ns-3 Tutorial"): **Start here if you are new to ns-3!** +* [Ns-3 manual](https://www.nsnam.org/docs/manual/html/ "ns-3 Manual"): Overview of the fundamental tools and abstractions in ns-3. +* The LoRaWAN specification can be downloaded at the [LoRa Alliance + website](http://www.lora-alliance.org). -## Getting help ## +## Getting help To discuss and get help on how to use this module, you can open an issue here. -## Authors ## +## Contributing + +Refer to the [contribution guidelines](.github/CONTRIBUTING.md) for information +about how to contribute to this module. + +## Authors -- Davide Magrin -- Martina Capuzzo -- Stefano Romagnolo -- Michele Luvisotto +* Davide Magrin +* Martina Capuzzo +* Stefano Romagnolo +* Michele Luvisotto -## License ## +## 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 ## +## Acknowledgments and relevant publications The initial version of this code was developed as part of a master's thesis at the [University of Padova](https://unipd.it "Unipd homepage"), under the @@ -128,13 +133,13 @@ of Marco Centenaro. Publications: -- D. Magrin, M. Capuzzo and A. Zanella, "A Thorough Study of LoRaWAN Performance Under Different +* 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](http://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=8863372&isnumber=6702522). -- M. Capuzzo, D. Magrin and A. Zanella, "Confirmed traffic in LoRaWAN: Pitfalls +* 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](https://ieeexplore.ieee.org/abstract/document/8407095). -- D. Magrin, M. Centenaro and L. Vangelista, "Performance evaluation of LoRa +* 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](http://ieeexplore.ieee.org/document/7996384/). -- Network level performances of a LoRa system (Master thesis). [Link](http://tesi.cab.unipd.it/53740/1/dissertation.pdf). +* Network level performances of a LoRa system (Master thesis). [Link](http://tesi.cab.unipd.it/53740/1/dissertation.pdf).