If you just want to create scenarios using the emulator, and you are not interested in tinkering with it, we refer you to a quicker installation running the emulator image with Docker Compose.
This is a traffic emulator for the Chirpstack server stack.
This software can be used to simulate in real-time multiple devices and gateways sharing a radio channel with very high flexibility in terms of possible configurations. LoRaWAN traffic is then UDP-encapsulated by gateways and forwarded outside the simulation. If a Chirpstack network server is in place, it will think the traffic is coming from a real network. All Class A MAC primitives used in the UE868 region are supported: radio transmission parameters of simulated devices can be changed by the downlink LoRaWAN traffic of the real server.
The code is an extension of the ns-3 LoRaWAN module. In addition to what is provided by the original LoRaWAN module, the following changes/additions were made:
- A gateway application implementing the UDP forwarder protocol running on real gateways
- An helper to register devices and gateways in the server using the included REST API
- Cryptographyc libraries to compute the Meassage Integrity Code (MIC) and encryption of packets for devices to be recognised by the server
- The
elora-exampleto show a complete usage of the traffic generator - Many improvements and corrections of features of the original module, such that traffic could be transparently be accepted by the server
To use this simulator you need to know the following:
- The ChirpStack server needs to be running somewhere (reachable by the simulation via network)
- The simulator works as is with the default configuration of Chirpstark v4 on
localhost:8080. It has been tested with the docker-compose installation of the server. To test a distributed version of the setup, the server/port address needs to be changed inelora-example, and ChirpStack needs to be set up such that a Gateway Bridge container remains co-located on the same machine of the ELoRa process - An authentification token needs to be generated in the server (API keys section), and needs to be copy-pasted in
elora-example
If not already, install the libcurl development library in your linux distribution (libcurl4-gnutls-dev on Ubuntu, curl-dev on Alpine).
Clone ns-3, clone this repository inside the contrib directory, checkout the right commit, and patch ns-3 using the provided patch file with 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/Orange-OpenSource/elora.git contrib/elora &&
tag=$(< contrib/elora/NS3-VERSION) && tag=${tag#release } && git checkout $tag -b $tag &&
patch -p1 -s < contrib/elora/ns-3-dev.patchMake sure you are in the ns-3-dev directory, then configure and build ns-3 with the following all-in-one command:
./ns3 configure -d debug --enable-examples &&
./ns3 buildThe elora module extends the code of the original lorawan ns-3 module, thus the two modules are in conflict if they are built together. If you also have the original lorawan module installed (either in the contrib or src directory), run ./ns3 clean and add the --enable-modules elora option to the ./ns3 configure command above to avoid building both.
The module includes the following example:
elora-example
Examples can be run via the ./ns3 run --enable-sudo "elora-example [options]" command.
Options can be retrived with ./ns3 run "elora-example --help".
For a description of the module, refer to doc/lorawan.rst (currently not up to date with all functionalities).
For more information on how to use the underlying LoRaWAN module refer also to the original ns-3 repository.
- ns-3 tutorial
- ns-3 manual
- The LoRaWAN specification can be found on the LoRa Alliance website
Code copyright 2022-2023 Orange.
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.
If you need any help, feel free to open an issue here.