A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
lorawan-mac-helper.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2017 University of Padova
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Davide Magrin <magrinda@dei.unipd.it>
7 */
8
9#ifndef LORAWAN_MAC_HELPER_H
10#define LORAWAN_MAC_HELPER_H
11
12#include "ns3/class-a-end-device-lorawan-mac.h"
13#include "ns3/gateway-lorawan-mac.h"
14#include "ns3/lora-channel.h"
15#include "ns3/lora-device-address-generator.h"
16#include "ns3/lora-phy.h"
17#include "ns3/lorawan-mac.h"
18#include "ns3/net-device.h"
19#include "ns3/node-container.h"
20#include "ns3/random-variable-stream.h"
21
22namespace ns3
23{
24namespace lorawan
25{
26
27/**
28 * \ingroup lorawan
29 *
30 * Helper class for configuring and installing the LorawanMac class on devices and gateways. The
31 * user must set all parameters before calling Install on nodes.
32 */
34{
35 public:
36 /**
37 * Define the kind of device. Can be either GW (Gateway) or ED (End Device).
38 */
40 {
42 ED_A
43 };
44
45 /**
46 * Define the operational region.
47 */
61
62 LorawanMacHelper(); //!< Default constructor
63
64 /**
65 * Set an attribute of the underlying MAC object.
66 *
67 * \param name The name of the attribute to set.
68 * \param v The value of the attribute.
69 */
70 void Set(std::string name, const AttributeValue& v);
71
72 /**
73 * Set the address generator to use for creation of these nodes.
74 *
75 * \param addrGen Pointer to the address generator object.
76 */
78
79 /**
80 * Set the kind of MAC this helper will create.
81 *
82 * \param dt The device type (either gateway or end device).
83 */
84 void SetDeviceType(enum DeviceType dt);
85
86 /**
87 * Set the region in which the device is to operate.
88 *
89 * \param region The region enum value.
90 */
91 void SetRegion(enum Regions region);
92
93 /**
94 * Create the LorawanMac instance and connect it to a device.
95 *
96 * \param node The node on which we wish to create a wifi MAC.
97 * \param device The device within which this MAC will be created.
98 * \return A newly-created LorawanMac object.
99 */
101
102 /**
103 * Initialize the end devices' data rate parameter.
104 *
105 * The Data Rate (DR) of each device is set to the maximum possible for its transmissions to be
106 * correctly received by the gateway measuring the best RSSI from the device, mimicking the DR
107 * maximization part of the default online LoRaWAN Adaptive Data Rate (ADR) algorithm. Please
108 * note that a single RSSI measurement between each device and gateway pair is taken for the DR
109 * assignment, so the assignment may be suboptimal in scenarios with a time-varying channel.
110 *
111 * This function uses the following convention (EU868) to compute the transmission range:
112 *
113 * DR5 -> SF7 \n
114 * DR4 -> SF8 \n
115 * DR3 -> SF9 \n
116 * DR2 -> SF10 \n
117 * DR1 -> SF11 \n
118 * DR0 -> SF12 \n
119 *
120 *
121 * It returns a DR distribution vector with the following counters:
122 *
123 * v[0] -> number of devices using DR5 \n
124 * v[1] -> number of devices using DR4 \n
125 * v[2] -> number of devices using DR3 \n
126 * v[3] -> number of devices using DR2 \n
127 * v[4] -> number of devices using DR1 \n
128 * v[5] -> number of devices using DR0, in range of at least a gateway \n
129 * v[6] -> number of devices using DR0, out of range \n
130 *
131 * \param endDevices The end devices to configure.
132 * \param gateways The gateways to consider for RSSI measurements.
133 * \param channel The radio channel to consider for RSSI measurements.
134 * \return A vector containing the final number of devices per DR.
135 */
136 static std::vector<int> SetSpreadingFactorsUp(NodeContainer endDevices,
137 NodeContainer gateways,
138 Ptr<LoraChannel> channel);
139
140 /**
141 * Randomly initialize the end devices' data rate parameter according to the given
142 * distribution.
143 *
144 * This function expects a data rate (DR) distribution vector of length 6 filled with real
145 * numbers summing up to 1. The value at index \f$i\f$ is considered to be the fraction of
146 * devices to be assigned DR \f$5-i\f$, for example:
147 *
148 * distribution[0] == 0.2 -> fraction of devices to be assigned to DR5 \n
149 * distribution[1] == 0.1 -> fraction of devices to be assigned to DR4 \n
150 * distribution[2] == 0.1 -> fraction of devices to be assigned to DR3 \n
151 * distribution[3] == 0.1 -> fraction of devices to be assigned to DR2 \n
152 * distribution[4] == 0.2 -> fraction of devices to be assigned to DR1 \n
153 * distribution[5] == 0.3 -> fraction of devices to be assigned to DR0 \n
154 *
155 *
156 * Devices are then randomly assigned a DR following the provided distribution.
157 *
158 * It returns a DR distribution vector with the following counters:
159 *
160 * v[0] -> number of devices using DR5 \n
161 * v[1] -> number of devices using DR4 \n
162 * v[2] -> number of devices using DR3 \n
163 * v[3] -> number of devices using DR2 \n
164 * v[4] -> number of devices using DR1 \n
165 * v[5] -> number of devices using DR0 \n
166 *
167 *
168 * \param endDevices The end devices to configure.
169 * \param gateways The gateways in the network (this is only a placeholder parameter).
170 * \param distribution The distribution (probability mass function) of DR assignment.
171 * \return A vector containing the final number of devices per DR.
172 *
173 * \todo Remove unused parameter gateways.
174 */
175 static std::vector<int> SetSpreadingFactorsGivenDistribution(NodeContainer endDevices,
176 NodeContainer gateways,
177 std::vector<double> distribution);
178
179 private:
180 /**
181 * Perform region-specific configurations for the 868 MHz EU band.
182 *
183 * \param edMac Pointer to the device MAC layer to configure.
184 */
186
187 /**
188 * Perform region-specific configurations for the 868 MHz EU band.
189 *
190 * \param gwMac Pointer to the gateway MAC layer to configure.
191 */
193
194 /**
195 * Apply configurations that are common both for the GatewayLorawanMac and the
196 * ClassAEndDeviceLorawanMac classes.
197 *
198 * \param lorawanMac Pointer to the MAC layer to configure.
199 */
200 void ApplyCommonEuConfigurations(Ptr<LorawanMac> lorawanMac) const;
201
202 /**
203 * Perform region-specific configurations for the SINGLECHANNEL band.
204 *
205 * \param edMac Pointer to the device MAC layer to configure.
206 */
208
209 /**
210 * Perform region-specific configurations for the SINGLECHANNEL band.
211 *
212 * \param gwMac Pointer to the gateway MAC layer to configure.
213 */
215
216 /**
217 * Apply configurations that are common both for the GatewayLorawanMac and the
218 * ClassAEndDeviceLorawanMac classes.
219 *
220 * \param lorawanMac Pointer to the MAC layer to configure.
221 */
223
224 /**
225 * Perform region-specific configurations for the ALOHA band.
226 *
227 * \param edMac Pointer to the device MAC layer to configure.
228 */
230
231 /**
232 * Perform region-specific configurations for the ALOHA band.
233 *
234 * \param gwMac Pointer to the gateway MAC layer to configure.
235 */
237
238 /**
239 * Apply configurations that are common both for the GatewayLorawanMac and the
240 * ClassAEndDeviceLorawanMac classes.
241 *
242 * \param lorawanMac Pointer to the MAC layer to configure.
243 */
244 void ApplyCommonAlohaConfigurations(Ptr<LorawanMac> lorawanMac) const;
245
246 ObjectFactory m_mac; //!< MAC-layer object factory
247 Ptr<LoraDeviceAddressGenerator> m_addrGen; //!< Pointer to the address generator to use
248 enum DeviceType m_deviceType; //!< The kind of device to install
249 enum Regions m_region; //!< The region in which the device will operate
250};
251
252} // namespace lorawan
253
254} // namespace ns3
255#endif /* LORA_PHY_HELPER_H */
Hold a value for an Attribute.
Definition attribute.h:59
keep track of a set of node pointers.
Instantiate subclasses of ns3::Object.
Smart pointer class similar to boost::intrusive_ptr.
Helper class for configuring and installing the LorawanMac class on devices and gateways.
void ConfigureForAlohaRegion(Ptr< ClassAEndDeviceLorawanMac > edMac) const
Perform region-specific configurations for the ALOHA band.
LorawanMacHelper()
Default constructor.
void SetDeviceType(enum DeviceType dt)
Set the kind of MAC this helper will create.
void SetAddressGenerator(Ptr< LoraDeviceAddressGenerator > addrGen)
Set the address generator to use for creation of these nodes.
static std::vector< int > SetSpreadingFactorsUp(NodeContainer endDevices, NodeContainer gateways, Ptr< LoraChannel > channel)
Initialize the end devices' data rate parameter.
void ApplyCommonEuConfigurations(Ptr< LorawanMac > lorawanMac) const
Apply configurations that are common both for the GatewayLorawanMac and the ClassAEndDeviceLorawanMac...
enum Regions m_region
The region in which the device will operate.
Regions
Define the operational region.
void SetRegion(enum Regions region)
Set the region in which the device is to operate.
void Set(std::string name, const AttributeValue &v)
Set an attribute of the underlying MAC object.
ObjectFactory m_mac
MAC-layer object factory.
Ptr< LorawanMac > Create(Ptr< Node > node, Ptr< NetDevice > device) const
Create the LorawanMac instance and connect it to a device.
static std::vector< int > SetSpreadingFactorsGivenDistribution(NodeContainer endDevices, NodeContainer gateways, std::vector< double > distribution)
Randomly initialize the end devices' data rate parameter according to the given distribution.
Ptr< LoraDeviceAddressGenerator > m_addrGen
Pointer to the address generator to use.
void ConfigureForSingleChannelRegion(Ptr< ClassAEndDeviceLorawanMac > edMac) const
Perform region-specific configurations for the SINGLECHANNEL band.
void ApplyCommonSingleChannelConfigurations(Ptr< LorawanMac > lorawanMac) const
Apply configurations that are common both for the GatewayLorawanMac and the ClassAEndDeviceLorawanMac...
DeviceType
Define the kind of device.
void ApplyCommonAlohaConfigurations(Ptr< LorawanMac > lorawanMac) const
Apply configurations that are common both for the GatewayLorawanMac and the ClassAEndDeviceLorawanMac...
enum DeviceType m_deviceType
The kind of device to install.
void ConfigureForEuRegion(Ptr< ClassAEndDeviceLorawanMac > edMac) const
Perform region-specific configurations for the 868 MHz EU band.
Every class exported by the ns3 library is enclosed in the ns3 namespace.