- Premium Pixels shares awesome design resources and tutorials. Its header features a cool pixel logo that changes on hover. Its header features a cool pixel logo that changes on hover. Take a look, you might find useful mockups, UI element sets, or other resources for your next project as well.
- The custom header mockup design is then replicated in their multi mount welding fixture. This multi mount welding fixture is a system Stainless Headers Mfg. Developed years ago to rapidly accommodate any custom header design. This allows GP Headers to fabricate and weld a set of custom headers that fits your very application perfectly.
- Making an excellent website header design is very important. That's because the website header is the first place that your visitors will probably look in order to decide if your site can really be useful for their needs. With this in mind, the header design needs to be very appealing, enabling the visitor to operate your website easily.
- Find CHEVROLET S10 Hedman Hedders 68540 Hedman Specialty and Engine Swap Headers and get Free Shipping on Orders Over $99 at Summit Racing! Headers are widely believed to be one of the best performance values available today-so why put stock manifolds on your trick ride? After dropping a different engine into your project vehicle, help it produce more horsepower and fuel economy with these.
Precompiled headers (PCH) are a performance feature supported by some compilers to compile a stable body of code, and store the compiled state of the code in a binary file. During subsequent compilations, the compiler will load the stored state, and continue compiling the specified file. Each subsequent compilation is faster because the stable code does not need to be recompiled.
qmake supports the use of precompiled headers on some platforms and build environments, including:
- Windows
- nmake
- Visual Studio projects (VS 2008 and later)
- macOS, iOS, tvOS, and watchOS
- Makefile
- Xcode
- Unix
- GCC 3.4 and above
- clang
Author will need to provide all images and information for the design of your header. Author name / site name to be used for Header Design; Author tagline (if applicable) Small description of what you are looking for in the design of your banner; Any images you want used in your design; Dimensions for the size of banner design; NOTE.
Adding Precompiled Headers to Your Project
The precompiled header must contain code which is stable and static throughout your project. A typical precompiled header might look like this:
Note: A precompiled header file needs to separate C includes from C++ includes, since the precompiled header file for C files may not contain C++ code.
Project Options
To make your project use precompiled headers, you only need to define the PRECOMPILED_HEADER variable in your project file:
qmake will handle the rest, to ensure the creation and use of the precompiled header file. You do not need to include the precompiled header file in HEADERS, as qmake will do this if the configuration supports precompiled headers.
The MSVC and g++ specs targeting Windows enable precompile_header by default.
Using this option, you may trigger conditional blocks in your project file to add settings when using precompiled headers. For example:
To use the precompiled header also for C files on MSVC nmake target, add precompile_header_c to the CONFIG variable. If the header is used also for C++ and it contains C++ keywords/includes, enclose them with #ifdef __cplusplus).
Notes on Possible Issues
On some platforms, the file name suffix for precompiled header files is the same as that for other object files. For example, the following declarations may cause two different object files with the same name to be generated:
To avoid potential conflicts like these, give distinctive names to header files that will be precompiled.
Example Project
You can find the following source code in the examples/qmake/precompile directory in the Qt distribution:
mydialog.ui
The following image displays the mydialog.ui file in Qt Creator Design mode. You can view the code in the Edit mode.
stable.h
myobject.h
myobject.cpp
util.cpp
main.cpp
precompile.pro
© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
This module contains a series of classes and examples aimed at modeling themodulation and medium access technology of a LoRaWAN network. Thanks to a simpleunderlying physical layer model and to the regulations imposed on traffic in theunlicensed bands this technology operates on, this module can supportsimulations featuring a large number of devices that access the wireless channelinfrequently.
The following parts of this documentation first outline how the technology worksand then describe how it was translated into a system of classes in order tosimulate a LoRaWAN system.
Technology¶
LoRaWAN is a Low Power Wide Area Network (LPWAN) technology built on the LoRamodulation. This technology allows a large number of devices to communicatewirelessly over long distances (in the order of 5-15 km, depending on thepropagation environment) at low data rates. The typical scenario in which thistechnology is expected to be employed is that of an IoT network, where devicesneed to communicate sparsely and only need short payloads to transmitsome information coming from, typically, a sensor.
LoRa¶
The basis of LoRaWAN is the proprietary Long Range (LoRa) modulation, owned bySemtech. This modulation, based on Chirp Spread Spectrum (CSS), spreads a signalover a certain band by leveraging a chirp signal that scans the availablebandwidth linearly.
One of the key parameters of the modulation is the Spreading Factor (SF): thisvalue, ranging from 7 to 12, expresses how much a packet is spread in time(i.e., how long it takes for a chirp to complete a complete scan of theavailable bandwidth). Transmissions using a low SF need a lower Time on Air(ToA) (assuming the same bandwidth) than packets using SF values closer to 12.The advantage of using higher SFs is in the increased sensitivity of thereceiver: as an example, a transmission using SF7 that cannot be detected by aLoRa receiver may be correctly demodulated if performed using SF12. Anotherkey feature of the modulation is the quasi-orthogonality between transmissionsusing different SF values: even if two packets overlap in time, a receiver maystill be able to demodulate one of the packets, assuming that they are usingdifferent SF and that some restrictions on their reciprocal power are respected.
More details on how the modulation works can be found in[semtech2015modulation] (an official document explaining the modulation) and in[knight2016reversing] (a reverse engineering of the modulation by Matt Knight).
LoRaWAN¶
The LoRa Alliance first defined the LoRaWAN standard in [lorawanstandard],with the objective of creating a medium access scheme and a set of networkmanagement policies that leverage the properties of the modulation to achievegood network performance at a low price in the complexity of the devices.
The topology of a LoRaWAN network is represented in the figureTopology of the LoRaWAN architecture., where dotted lines represent a LoRa wireless link whilesolid lines are other kinds of high throughput, high reliability connections. Itcan be seen that there are three kinds of devices in a LoRaWAN network: EndDevices (EDs), Gateways (GWs) and a Network Server (NS). End Devices are basicnetwork nodes: typically inexpensive, they are constrained by low computationalcapabilities and are usually powered by a battery. Gateways are high-end, mainspowered devices that are tasked with collecting the data transmitted by EndDevices leveraging the LoRa modulation. After a packet is correctly received, itis forwarded to the Network Server via a link with high reliability and speed.The Network Server functions as a sink for data coming from all devices, and asa controller of the network that can leverage some MAC commands to changetransmission settings in the End Devices.
End Devices of the most basic type are defined as Class A devices, and arecurrently the only kind of device supported by this module. Class A devicesperform transmission in a totally asynchronous way, and open two receive windowsof fixed duration after each transmission to allow the Network Server totransmit acknowledgments or MAC commands.
Another important characteristic of the standard is that it is defined to workon unlicensed bands in various regions, which usually subject transmitters toregulations on duty cycle. This fact will be explained in greater detail in theMAC layer model section of this document.
Module design¶
This module comprises two main models: one for the LoRa PHY layer that needs torepresent LoRa chips and the behavior of LoRa transmissions, and one for theLoRaWAN MAC layer, that needs to behave according to the officialspecifications.
To represent these two models, the module features two generic LoraPhy andLorawanMac base classes. These classes are then extended by classes thatmodel the peculiarities of the two wireless network devices: the End Device (ED)and the Gateway (GW). So, the PHY layers can be modeled by use ofEndDeviceLoraPhy and GatewayLoraPhy classes, while objects of classEndDeviceLorawanMac, ClassAEndDeviceLorawanMac, and GatewayLorawanMacare used to represent the MAC layer. A NetworkServer application can also beinstalled on a node that will then administer the wireless network through theGW's forwarding application, Forwarder, which leverages the gateway's LoRacommunication capabilities to forward to End Devices the Network Server'spackets.
PHY layer model¶
The model for the PHY layer needs to take into account the two key factors ofLoRa, sensitivity and orthogonality, to decide whether a transmission isreceived correctly or not. Besides, it also needs to be aware of how the chipsimplementing the modulation work, and of their architecture.
Link model¶
The link model takes into account three main components to determine theperformance of a LoRa transmission:
Data about device sensitivity taken from device datasheets;
A model to account for the interference between different LoRa transmissions;
A series of assumptions regarding this interference model.
In this section, we will describe each portion of the model with a particularfocus on its implementation in the code.
The LoraChannel class is used to interconnect the LoRa PHY layers of alldevices wishing to communicate using this technology. The class holds a list ofconnected PHY layers, and notifies them about incoming transmissions, followingthe same paradigm of other Channel classes in ns-3.
PHY layers that are connected to the channel expose a public StartReceivemethod that allows the channel to start reception at a certain PHY. At thispoint, these PHY classes rely on a LoraInterferenceHelper object to keeptrack of all incoming packets, both as potentially desirable packets and asinterference. Once the channel notifies the PHY layer of the incoming packet,the PHY informs its LoraInterferenceHelper right away of the incomingtransmission. After this, if a PHY fills certain prerequisites, it can lock onthe incoming packet for reception. In order to do so:
The receiver must be idle (in STANDBY state) when the
StartReceivefunction is called; Exit pathwatermelon gaming headset.The packet receive power must be above a sensitivity threshold;
The receiver must be listening on the correct frequency;
The receiver must be listening for the correct SF.
The sensitivity threshold that is currently implemented can be seen below(values in dBm):
After the PHY layer locks on the incoming packet, it schedules an EndReceivefunction call after the packet duration. The reception power is considered to beconstant throughout the packet reception process. When reception ends,EndReceive calls the IsDestroyedByInterference method of the PHY'sinstance of LoraInterferenceHelper to determine whether the packet is lostdue to interference.
The IsDestroyedByInterference function compares the desired packet'sreception power with the interference energy of packets that overlap with it ona SF basis, and compares the obtained SIR value against the isolation matrixthat was tabulated in [goursaud2015dedicated] and reproduced below. Forexample, if the desired packet is using SF7, and it is (even partially)overlapped to two packets using SF10, the desired signal's energy (computed asthe product of reception power and signal duration) is compared to the summedenergy of the two interferers (computed as the product of the interferer's powerat the receiver and overlap time). The ratio between the desired and theinterference energy from each spreading factor (considered separately) is thencompared to the table below, in which rows identify the desired signal's SF,while columns represent the interfering SF that is currently being considered.If the SIR is above the tabulated threshold, the packet is received correctlyand forwarded to the MAC layer.
A full description of the link layer model can also be found in[magrin2017performance] and in [magrin2017thesis].
Gateway model¶
The chip installed on LoRa GWs needs special attention because of itsarchitecture: since it is characterized by the presence of 8 parallel receivepaths, it can receive multiple packets in parallel [sx1301]. Thisbehavior is represented in the simulator through a ReceptionPath object thatbehaves as an EndDeviceLoraPhy, locking into incoming packets and comparingthem to others to determine correct reception by using the gateway'sLoraInterferenceHelper instance. A GatewayLoraPhy, then, is essentiallya manager of this collection of ReceptionPath objects. Upon arrival of apacket, the gateway picks a free reception path (if there are any), marks it asoccupied and locks it into the incoming packet. Once the scheduledEndReceive method is executed, the gateway's LoraInterferenceHelper(which contains information used by all ReceptionPaths) is queried, and itis decided whether the packet is correctly received or not.
Some further assumptions on the collaboration behavior of these reception pathswere made to establish a consistent model despite the SX1301 gateway chipdatasheet not going into full detail on how the chip administers the availablereception paths:
Receive paths can be configured to listen for incoming packets on anyfrequency;
Receive paths can be allocated freely on the available frequencies;
Receive paths don't need to be pre-configured to listen for a certainspreading factor (thus, point 4 of the prerequisites stated above for EndDevices doesn't apply);
If a packet is incoming and multiple receive paths are listening for the samechannel, only one locks into the incoming packet;
If all reception paths listening on a channel are locked into an incomingpacket and another packet arrives, the new packet is immediately marked aslost.
MAC layer model¶
The MAC models contained in this module aim at implementing the LoRaWANstandard. To facilitate this task, a series of side classes were created tohandle headers, MAC commands, logical channels and duty cycle computations.Furthermore, a simplified version of a Network Server (NS) is also provided inthe form of an application that can be installed on a ns-3Node andconnected to the GWs via a PointToPoint link to also simulate a backbonechannel.
Headers, MAC commands and addressing system¶
The packet structure defined by the LoRaWAN standard is implemented through twoclasses that extend the Header class: LorawanMacHeader andLoraFrameHeader. In particular, LoraFrameHeader can include MAC commandsby leveraging the MacCommand and LoraDeviceAddress classes, that areused to make serialization, deserialization and interpretation of MAC commandsand the LoRaWAN address system easier.
MAC commands are implemented by extending the MacCommand class. Each childclass is used to define a set of command variables, methods to serialize anddeserialize the commands inside a LoraFrameHeader, and callbacks to the MAClayer to perform actions. This structure can facilitate the implementation andtesting of custom MAC commands, as allowed by the specification.
The LoraDeviceAddress class is used to represent the address of a LoRaWANED, and to handle serialization and deserialization.
Logical channels and duty cycle¶
Since LoRaWAN operates in unlicensed bands that are subject to restrictions onduty cycle, a series of objects were created to keep track of availabletransmission time and limit transmission at the MAC layer in case the layersabove aren't aware of these limitations. A LogicalLoraChannelHelper isassigned to each LorawanMac instance, and is tasked with keeping track of allavailable logical channels (which can be added and modified with MAC commands,and are represented by the LogicalLoraChannel class) and is aware of thesub-band they are in (through instances of the SubBand class).
Additionally, in order to enforce duty cycle limitations, this object alsoregisters all transmissions that are performed on each channel, and can bequeried by the LorawanMac instance to know the next time in which transmissionwill be possible according to the regulation. If a transmission of duration is performed by the device on a channel where the duty cycleexpressed in fractional form is , the time the device needs tostay off is computed according to the following formula:
This time is kept track of on a sub band basis, so that if two channels areunder the same regulation, a transmission on one of them will also block theother one.
The Network Server¶
The NetworkServer is an application which is running on a node that isconnected to the simulation GWs. The GWs forward incoming LoRa packets to theNS, and expect to be given packets to transmit in the downlink to EDs by the NS.In order to keep track of all players in the network, the NS keeps two lists ofDeviceStatus and GatewayStatus objects, which represent the currentstatus of each ED and GW in the network, respectively. These objects are used tokeep track of downlink packets that will need to be sent during the ED's receivewindows, and they also hold pointers to the Mac layer instances of each GW. Thisis done in order to be able to perform queries on the gateway's current dutycycle limitations and always forward downlink packets to gateways that will beable to transmit the packet in the LoRa network. The current iteration of theNetwork Server only sends downlink packets to devices that require anacknowledgment, ignoring the contents of the packet and of MAC commands it maycontain. Transmission is performed on the first receive window wheneverpossible, and the second receive window is used only when no more resources areavailable to leverage the first chance to respond to the device. More complexand realistic NS behaviors are definitely possible, however they also come at acomplexity cost that is non-negligible.
Scope and Limitations¶
Since this is still a first version of the module, a few caveats are listedbelow.
Inter-protocol interference¶
Since the LoraChannel class can only be connected to LoRa PHY layers, themodel is currently unable to account for interference by other technologies.
It's expected that it will become possible, in the future, to handleinter-protocol interference by leveraging the SpectrumChannel class, oncemore accurate models of how interference affects LoRa signals become available.
Inter-channel interference¶
Headers Mac Designs For Mac
Interference between partially overlapping channels is not checked for.Furthermore, there currently is no model to account for interference betweensignals using different bandwidths.
Network Server¶
The current implementation of the Network Server tries to provide a generalstructure to handle EDs and GWs in a network, but still lacks some possiblycomplex code to simulate advanced features like different Adaptive Data Rate(ADR) algorithms, responding to the ED's MAC commands and supporting joinprocedures. Other limitations of the Network Server is that it doesn't employ aprotocol to communicate with the Gateways (since no official ones exist), andthat it informs the gateway in real time about downlink messages it needs tosend (in other words, no 'booking' of the gateway resource is done in advance,and downlink packets take priority over incoming packets at the gateway).
As of now, the Network Server implementation should be considered as anexperimental feature, prone to yet undiscovered bugs.
Device Classes¶
Currently, only Class A End Devices are supported.
Regional parameters¶
Since LoRaWAN parameters like default channel lineup and MAC commandinterpretations vary based on the operational region of the network,LorawanMacHelper includes methods to specify the region. While the currentimplementation is predisposed to support different configurations of the networkbased on the region it's meant to be operating in, currently only the EU regionusing the 868 MHz sub band is supported.
MAC layer details¶
Some details that are not crucial for the evaluation of the system performanceof a network still need to be implemented. These include:
Frame counters, both at the End Devices and at the Network Server'sDeviceStatus
Proper setting of ADR flags (no ADR mechanism is implemented still)
Join procedure management (both at the NS and at the EDs)
Usage¶
A typical usage of the model follows some typical ns-3 paradigms, like theusage of helpers to configure a complex network. This section illustrates thesetup of a LoRaWAN network using the module and some other side classes thatweren't described in the previous sections because they are mainly used toconfigure the network.
Helpers¶
The lorawan module features helpers to configure the PHY and MAC layers on alarge number of devices. The two layers are split in two different classes,LorawanMacHelper and LoraPhyHelper, which can be leveraged by aLoraHelper object to fully configure a LoRa device (both for EDs and forGWs). Since the helpers are general purpose (i.e., they can be used both for EDand GW configuration), it is necessary to specify the device type via theSetDeviceType method before the Install method can be called.
The LorawanMacHelper also exposes a method to set up the Spreading Factors usedby the devices participating in the network automatically, based on the channelconditions and on the placement of devices and gateways. This procedure iscontained in the static method SetSpreadingFactorsUp, and works by trying tominimize the time-on-air of packets, thus assigning the lowest possiblespreading factor such that reception by at least one gateway is still possible.It should be noted that this is an heuristic, and that it doesn't guarantee thatthe SF distribution is optimal for the best possible operation of the network.In fact, finding such a distribution based on the network scenario is still anopen challenge.
Attributes¶
Headers Mac Designs Images
Currently, the following attributes are available:
IntervalandPacketSizeinPeriodicSenderdetermine the intervalbetween packet sends of the application, and the size of the packets that aregenerated by the application.
Trace Sources¶
Various trace sources can be used to keep track of events throughout thesimulation, mainly regarding the lifetime of a packet. At the PHY layer, thefollowing trace sources are exposed:
In
LoraPhy(bothEndDeviceLoraPhyandGatewayLoraPhy):StartSending, fired when a PHY layer begins transmitting a packet;PhyRxBegin, fired when a PHY layer becomes locked on a packet;PhyRxEnd, fired when a PHY's reception of a packet ends;ReceivedPacket, fired when a packet is correctly received;LostPacketBecauseInterference, fired when a packet is lost because ofinterference from other transmissions;LostPacketBecauseUnderSensitivity, fired when a PHY cannot lock on apacket because it's being received with a power below the device sensitivity;
In
EndDeviceLoraPhy:LoraPacketBecauseWrongFrequencyis fired when an incoming packet isusing a frequency that is different from that on which the PHY is listening;LoraPacketBecauseWrongSpreadingFactoris fired when an incoming packetis using a SF that is different from that for which the PHY is listening;EndDeviceStateis used to keep track of the state of the device's PHYlayer.
In
GatewayLoraPhy:LostPacketBecauseNoMoreReceiversis fired when a packet is lost becauseno more receive paths are available to lock onto the incoming packet;OccupiedReceptionPathsis used to keep track of the number of occupiedreception paths out of the 8 that are available at the gateway;
In
LorawanMac(bothEndDeviceLorawanMacandGatewayLorawanMac):CannotSendBecauseDutyCycleis used to keep track of the number of when apacket coming from the application layer cannot be sent on any of theavailable channels because of duty cycle limitations;
In
EndDeviceLorawanMac:DataRatekeeps track of the data rate that is employed by the device;LastKnownLinkMarginkeeps track of the last link margin of this device'suplink transmissions; This information is gathered through theLinkCheckMAC commands;LastKnownGatewayCountkeeps track of the last known number of gatewaysthat this device is able to reach; This information is gathered through theLinkCheckMAC commands;AggregatedDutyCyclekeeps track of the currently set aggregated dutycycle limitations;
PacketSentinLoraChannelis fired when a packet is sent on the channel;
Examples¶
simple-lorawan-network-example¶
This example is used to showcase how wireless communication between a device anda gateway happens: one LoRa ED is configured to send a packet, and a GW receivesit. When logging is enabled, the various steps that are needed to send a packetfrom the APP layer of an ED to the MAC layer of a GW can be observed.
network-server-example¶
This example builds on the simple-lorawan-network-example to add a NetworkServer and multiple EDs and GWs to the scenario. This example works as ashowcase for how communication between the End Devices and the Network Serverhappens.
complete-lorawan-network-example¶
This example shows how to configure a whole LoRaWAN network using the ns-3lorawan module. A big network featuring several thousand devices and tens ofgateways is built, and each device is equipped with a PeriodicSenderapplication that periodically sends a packet to the NetworkServer through theGateways. The example keeps track of the sent and received packets, and computessome statistics at the end of the simulation. No Network Server is used in thissimulation, since performance metrics are collected through the GW trace sourcesand packets don't require an acknowledgment.
Tests¶
Tests are contained in the lorawan-test-suite.cc file. The tests currentlycover the following classes:
The receiver must be listening on the correct frequency;
The receiver must be listening for the correct SF.
The sensitivity threshold that is currently implemented can be seen below(values in dBm):
After the PHY layer locks on the incoming packet, it schedules an EndReceivefunction call after the packet duration. The reception power is considered to beconstant throughout the packet reception process. When reception ends,EndReceive calls the IsDestroyedByInterference method of the PHY'sinstance of LoraInterferenceHelper to determine whether the packet is lostdue to interference.
The IsDestroyedByInterference function compares the desired packet'sreception power with the interference energy of packets that overlap with it ona SF basis, and compares the obtained SIR value against the isolation matrixthat was tabulated in [goursaud2015dedicated] and reproduced below. Forexample, if the desired packet is using SF7, and it is (even partially)overlapped to two packets using SF10, the desired signal's energy (computed asthe product of reception power and signal duration) is compared to the summedenergy of the two interferers (computed as the product of the interferer's powerat the receiver and overlap time). The ratio between the desired and theinterference energy from each spreading factor (considered separately) is thencompared to the table below, in which rows identify the desired signal's SF,while columns represent the interfering SF that is currently being considered.If the SIR is above the tabulated threshold, the packet is received correctlyand forwarded to the MAC layer.
A full description of the link layer model can also be found in[magrin2017performance] and in [magrin2017thesis].
Gateway model¶
The chip installed on LoRa GWs needs special attention because of itsarchitecture: since it is characterized by the presence of 8 parallel receivepaths, it can receive multiple packets in parallel [sx1301]. Thisbehavior is represented in the simulator through a ReceptionPath object thatbehaves as an EndDeviceLoraPhy, locking into incoming packets and comparingthem to others to determine correct reception by using the gateway'sLoraInterferenceHelper instance. A GatewayLoraPhy, then, is essentiallya manager of this collection of ReceptionPath objects. Upon arrival of apacket, the gateway picks a free reception path (if there are any), marks it asoccupied and locks it into the incoming packet. Once the scheduledEndReceive method is executed, the gateway's LoraInterferenceHelper(which contains information used by all ReceptionPaths) is queried, and itis decided whether the packet is correctly received or not.
Some further assumptions on the collaboration behavior of these reception pathswere made to establish a consistent model despite the SX1301 gateway chipdatasheet not going into full detail on how the chip administers the availablereception paths:
Receive paths can be configured to listen for incoming packets on anyfrequency;
Receive paths can be allocated freely on the available frequencies;
Receive paths don't need to be pre-configured to listen for a certainspreading factor (thus, point 4 of the prerequisites stated above for EndDevices doesn't apply);
If a packet is incoming and multiple receive paths are listening for the samechannel, only one locks into the incoming packet;
If all reception paths listening on a channel are locked into an incomingpacket and another packet arrives, the new packet is immediately marked aslost.
MAC layer model¶
The MAC models contained in this module aim at implementing the LoRaWANstandard. To facilitate this task, a series of side classes were created tohandle headers, MAC commands, logical channels and duty cycle computations.Furthermore, a simplified version of a Network Server (NS) is also provided inthe form of an application that can be installed on a ns-3Node andconnected to the GWs via a PointToPoint link to also simulate a backbonechannel.
Headers, MAC commands and addressing system¶
The packet structure defined by the LoRaWAN standard is implemented through twoclasses that extend the Header class: LorawanMacHeader andLoraFrameHeader. In particular, LoraFrameHeader can include MAC commandsby leveraging the MacCommand and LoraDeviceAddress classes, that areused to make serialization, deserialization and interpretation of MAC commandsand the LoRaWAN address system easier.
MAC commands are implemented by extending the MacCommand class. Each childclass is used to define a set of command variables, methods to serialize anddeserialize the commands inside a LoraFrameHeader, and callbacks to the MAClayer to perform actions. This structure can facilitate the implementation andtesting of custom MAC commands, as allowed by the specification.
The LoraDeviceAddress class is used to represent the address of a LoRaWANED, and to handle serialization and deserialization.
Logical channels and duty cycle¶
Since LoRaWAN operates in unlicensed bands that are subject to restrictions onduty cycle, a series of objects were created to keep track of availabletransmission time and limit transmission at the MAC layer in case the layersabove aren't aware of these limitations. A LogicalLoraChannelHelper isassigned to each LorawanMac instance, and is tasked with keeping track of allavailable logical channels (which can be added and modified with MAC commands,and are represented by the LogicalLoraChannel class) and is aware of thesub-band they are in (through instances of the SubBand class).
Additionally, in order to enforce duty cycle limitations, this object alsoregisters all transmissions that are performed on each channel, and can bequeried by the LorawanMac instance to know the next time in which transmissionwill be possible according to the regulation. If a transmission of duration is performed by the device on a channel where the duty cycleexpressed in fractional form is , the time the device needs tostay off is computed according to the following formula:
This time is kept track of on a sub band basis, so that if two channels areunder the same regulation, a transmission on one of them will also block theother one.
The Network Server¶
The NetworkServer is an application which is running on a node that isconnected to the simulation GWs. The GWs forward incoming LoRa packets to theNS, and expect to be given packets to transmit in the downlink to EDs by the NS.In order to keep track of all players in the network, the NS keeps two lists ofDeviceStatus and GatewayStatus objects, which represent the currentstatus of each ED and GW in the network, respectively. These objects are used tokeep track of downlink packets that will need to be sent during the ED's receivewindows, and they also hold pointers to the Mac layer instances of each GW. Thisis done in order to be able to perform queries on the gateway's current dutycycle limitations and always forward downlink packets to gateways that will beable to transmit the packet in the LoRa network. The current iteration of theNetwork Server only sends downlink packets to devices that require anacknowledgment, ignoring the contents of the packet and of MAC commands it maycontain. Transmission is performed on the first receive window wheneverpossible, and the second receive window is used only when no more resources areavailable to leverage the first chance to respond to the device. More complexand realistic NS behaviors are definitely possible, however they also come at acomplexity cost that is non-negligible.
Scope and Limitations¶
Since this is still a first version of the module, a few caveats are listedbelow.
Inter-protocol interference¶
Since the LoraChannel class can only be connected to LoRa PHY layers, themodel is currently unable to account for interference by other technologies.
It's expected that it will become possible, in the future, to handleinter-protocol interference by leveraging the SpectrumChannel class, oncemore accurate models of how interference affects LoRa signals become available.
Inter-channel interference¶
Headers Mac Designs For Mac
Interference between partially overlapping channels is not checked for.Furthermore, there currently is no model to account for interference betweensignals using different bandwidths.
Network Server¶
The current implementation of the Network Server tries to provide a generalstructure to handle EDs and GWs in a network, but still lacks some possiblycomplex code to simulate advanced features like different Adaptive Data Rate(ADR) algorithms, responding to the ED's MAC commands and supporting joinprocedures. Other limitations of the Network Server is that it doesn't employ aprotocol to communicate with the Gateways (since no official ones exist), andthat it informs the gateway in real time about downlink messages it needs tosend (in other words, no 'booking' of the gateway resource is done in advance,and downlink packets take priority over incoming packets at the gateway).
As of now, the Network Server implementation should be considered as anexperimental feature, prone to yet undiscovered bugs.
Device Classes¶
Currently, only Class A End Devices are supported.
Regional parameters¶
Since LoRaWAN parameters like default channel lineup and MAC commandinterpretations vary based on the operational region of the network,LorawanMacHelper includes methods to specify the region. While the currentimplementation is predisposed to support different configurations of the networkbased on the region it's meant to be operating in, currently only the EU regionusing the 868 MHz sub band is supported.
MAC layer details¶
Some details that are not crucial for the evaluation of the system performanceof a network still need to be implemented. These include:
Frame counters, both at the End Devices and at the Network Server'sDeviceStatus
Proper setting of ADR flags (no ADR mechanism is implemented still)
Join procedure management (both at the NS and at the EDs)
Usage¶
A typical usage of the model follows some typical ns-3 paradigms, like theusage of helpers to configure a complex network. This section illustrates thesetup of a LoRaWAN network using the module and some other side classes thatweren't described in the previous sections because they are mainly used toconfigure the network.
Helpers¶
The lorawan module features helpers to configure the PHY and MAC layers on alarge number of devices. The two layers are split in two different classes,LorawanMacHelper and LoraPhyHelper, which can be leveraged by aLoraHelper object to fully configure a LoRa device (both for EDs and forGWs). Since the helpers are general purpose (i.e., they can be used both for EDand GW configuration), it is necessary to specify the device type via theSetDeviceType method before the Install method can be called.
The LorawanMacHelper also exposes a method to set up the Spreading Factors usedby the devices participating in the network automatically, based on the channelconditions and on the placement of devices and gateways. This procedure iscontained in the static method SetSpreadingFactorsUp, and works by trying tominimize the time-on-air of packets, thus assigning the lowest possiblespreading factor such that reception by at least one gateway is still possible.It should be noted that this is an heuristic, and that it doesn't guarantee thatthe SF distribution is optimal for the best possible operation of the network.In fact, finding such a distribution based on the network scenario is still anopen challenge.
Attributes¶
Headers Mac Designs Images
Currently, the following attributes are available:
IntervalandPacketSizeinPeriodicSenderdetermine the intervalbetween packet sends of the application, and the size of the packets that aregenerated by the application.
Trace Sources¶
Various trace sources can be used to keep track of events throughout thesimulation, mainly regarding the lifetime of a packet. At the PHY layer, thefollowing trace sources are exposed:
In
LoraPhy(bothEndDeviceLoraPhyandGatewayLoraPhy):StartSending, fired when a PHY layer begins transmitting a packet;PhyRxBegin, fired when a PHY layer becomes locked on a packet;PhyRxEnd, fired when a PHY's reception of a packet ends;ReceivedPacket, fired when a packet is correctly received;LostPacketBecauseInterference, fired when a packet is lost because ofinterference from other transmissions;LostPacketBecauseUnderSensitivity, fired when a PHY cannot lock on apacket because it's being received with a power below the device sensitivity;
In
EndDeviceLoraPhy:LoraPacketBecauseWrongFrequencyis fired when an incoming packet isusing a frequency that is different from that on which the PHY is listening;LoraPacketBecauseWrongSpreadingFactoris fired when an incoming packetis using a SF that is different from that for which the PHY is listening;EndDeviceStateis used to keep track of the state of the device's PHYlayer.
In
GatewayLoraPhy:LostPacketBecauseNoMoreReceiversis fired when a packet is lost becauseno more receive paths are available to lock onto the incoming packet;OccupiedReceptionPathsis used to keep track of the number of occupiedreception paths out of the 8 that are available at the gateway;
In
LorawanMac(bothEndDeviceLorawanMacandGatewayLorawanMac):CannotSendBecauseDutyCycleis used to keep track of the number of when apacket coming from the application layer cannot be sent on any of theavailable channels because of duty cycle limitations;
In
EndDeviceLorawanMac:DataRatekeeps track of the data rate that is employed by the device;LastKnownLinkMarginkeeps track of the last link margin of this device'suplink transmissions; This information is gathered through theLinkCheckMAC commands;LastKnownGatewayCountkeeps track of the last known number of gatewaysthat this device is able to reach; This information is gathered through theLinkCheckMAC commands;AggregatedDutyCyclekeeps track of the currently set aggregated dutycycle limitations;
PacketSentinLoraChannelis fired when a packet is sent on the channel;
Examples¶
simple-lorawan-network-example¶
This example is used to showcase how wireless communication between a device anda gateway happens: one LoRa ED is configured to send a packet, and a GW receivesit. When logging is enabled, the various steps that are needed to send a packetfrom the APP layer of an ED to the MAC layer of a GW can be observed.
network-server-example¶
This example builds on the simple-lorawan-network-example to add a NetworkServer and multiple EDs and GWs to the scenario. This example works as ashowcase for how communication between the End Devices and the Network Serverhappens.
complete-lorawan-network-example¶
This example shows how to configure a whole LoRaWAN network using the ns-3lorawan module. A big network featuring several thousand devices and tens ofgateways is built, and each device is equipped with a PeriodicSenderapplication that periodically sends a packet to the NetworkServer through theGateways. The example keeps track of the sent and received packets, and computessome statistics at the end of the simulation. No Network Server is used in thissimulation, since performance metrics are collected through the GW trace sourcesand packets don't require an acknowledgment.
Tests¶
Tests are contained in the lorawan-test-suite.cc file. The tests currentlycover the following classes:
LoraInterferenceHelperLoraDeviceAddressandLoraDeviceAddressHelperLoraFrameHeaderandLorawanMacHeaderReceivePathandGatewayLoraPhyLogicalLoraChannelandLogicalLoraChannelHelperLoraPhyEndDeviceLoraPhyandLoraChannel
References¶
D. Magrin, M. Centenaro and L. Vangelista,Performance Evaluation of LoRa Networks in a SmartCity Scenario, in Proc. of the IEEE InternationalConference on Communications, May 2017.
D. Magrin, Network level performances of a LoRa system,December 2016. Available:http://tesi.cab.unipd.it/53740/
Semtech, SX1301 Datasheet.
C. Goursaud, J. M. Gorce, Dedicated networks forIoT: PHY/MAC state of the art and challenges, EAIendorsed transactions on Internet of Things, 2015.
Semtech Corporation, AN1200.22 LoRa ModulationBasics, May 2015, Online. Available:http://www.semtech.com/images/datasheet/an1200.22.pdf
Mac Designs Newport Ri
Mac Designs Carmel In
M. Knight, Reversing LoRa, Online. Available:https://github.com/matt-knight/research
N. Sornin, M. Luis, T. Eirich, T. Kramp, and O. Hersent,LoRaWAN Specifications, LoRa Alliance, Tech. Rep., 2015.
