A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
lorawan-mac.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_H
10#define LORAWAN_MAC_H
11
13#include "lora-phy.h"
14
15#include "ns3/object.h"
16#include "ns3/packet.h"
17
18#include <array>
19
20namespace ns3
21{
22namespace lorawan
23{
24
25class LoraPhy;
26
27/**
28 * \ingroup lorawan
29 *
30 * Class representing the LoRaWAN MAC layer.
31 *
32 * This class is meant to be extended differently based on whether the layer
33 * belongs to an end device or a gateway, while holding some functionality that
34 * is common to both.
35 */
36class LorawanMac : public Object
37{
38 public:
39 /**
40 * Register this type.
41 * \return The object TypeId.
42 */
43 static TypeId GetTypeId();
44
45 LorawanMac(); //!< Default constructor
46 ~LorawanMac() override; //!< Destructor
47
48 /**
49 * Matrix structure to store possible data rate value to be used by a LoRaWAN end device for
50 * listening during the RX1 receive window. It is a function of the uplink data rate and the
51 * RX1DROffset [0:5].
52 */
53 typedef std::array<std::array<uint8_t, 6>, 8> ReplyDataRateMatrix;
54
55 /**
56 * Set the underlying PHY layer.
57 *
58 * \param phy The phy layer.
59 */
60 void SetPhy(Ptr<LoraPhy> phy);
61
62 /**
63 * Get the underlying PHY layer.
64 *
65 * \return The PHY layer that this MAC is connected to.
66 */
68
69 /**
70 * Send a packet.
71 *
72 * \param packet The packet to send.
73 */
74 virtual void Send(Ptr<Packet> packet) = 0;
75
76 /**
77 * Receive a packet from the lower layer.
78 *
79 * \param packet The received packet.
80 */
81 virtual void Receive(Ptr<const Packet> packet) = 0;
82
83 /**
84 * Function called by lower layers to inform this layer that reception of a
85 * packet we were locked on failed.
86 *
87 * \param packet The packet we failed to receive.
88 */
89 virtual void FailedReception(Ptr<const Packet> packet) = 0;
90
91 /**
92 * Perform actions after sending a packet.
93 *
94 * \param packet The packet that just finished transmission.
95 */
96 virtual void TxFinished(Ptr<const Packet> packet) = 0;
97
98 /**
99 * Set the device this MAC layer is installed on.
100 *
101 * \param device The NetDevice this MAC layer will refer to.
102 */
103 void SetDevice(Ptr<NetDevice> device);
104
105 /**
106 * Get the device this MAC layer is installed on.
107 *
108 * \return The NetDevice this MAC layer will refer to.
109 */
111
112 /**
113 * Get the logical lora channel helper associated with this MAC.
114 *
115 * \return A Ptr to the instance of LogicalLoraChannelHelper that this MAC is using.
116 */
118
119 /**
120 * Set the LogicalLoraChannelHelper this MAC instance will use.
121 *
122 * \param helper A Ptr to the instance of the helper to use.
123 */
125
126 /**
127 * Get the spreading factor corresponding to a data rate, based on this MAC's region.
128 *
129 * \param dataRate The data rate we need to convert to a Spreading Factor
130 * value.
131 * \return The spreading factor that corresponds to a data rate in this MAC's region, or 0
132 * if the dataRate is not valid.
133 */
134 uint8_t GetSfFromDataRate(uint8_t dataRate);
135
136 /**
137 * Get the bandwidth corresponding to a data rate, based on this MAC's region.
138 *
139 * \param dataRate The data rate we need to convert to a bandwidth value.
140 * \return The bandwidth that corresponds to the parameter data rate in this
141 * MAC's region, or 0 if the dataRate is not valid.
142 */
143 double GetBandwidthFromDataRate(uint8_t dataRate);
144
145 /**
146 * Get the transmission power in dBm that corresponds, in this region, to the
147 * encoded 8-bit txPower.
148 *
149 * \param txPower The 8-bit encoded txPower to convert.
150 *
151 * \return The corresponding transmission power in dBm, or 0 if the encoded
152 * power was not recognized as valid.
153 */
154 double GetDbmForTxPower(uint8_t txPower);
155
156 /**
157 * Set the vector to use to check up correspondence between spreading factor and data rate.
158 *
159 * \param sfForDataRate A vector that contains at position i the spreading factor that
160 * should correspond to data rate i.
161 */
162 void SetSfForDataRate(std::vector<uint8_t> sfForDataRate);
163
164 /**
165 * Set the vector to use to check up correspondence between bandwidth and
166 * data rate.
167 *
168 * \param bandwidthForDataRate A vector that contains at position i the
169 * bandwidth that should correspond to data rate i in this MAC's region.
170 */
171 void SetBandwidthForDataRate(std::vector<double> bandwidthForDataRate);
172
173 /**
174 * Set the maximum App layer payload for a set data rate.
175 *
176 * \param maxAppPayloadForDataRate A vector that contains at position i the
177 * maximum Application layer payload that should correspond to data rate i in this
178 * MAC's region.
179 */
180 void SetMaxAppPayloadForDataRate(std::vector<uint32_t> maxAppPayloadForDataRate);
181
182 /**
183 * Set the vector to use to check up which transmission power in Dbm
184 * corresponds to a certain TxPower value in this MAC's region.
185 *
186 * \param txDbmForTxPower A vector that contains at position i the
187 * transmission power in dBm that should correspond to a TXPOWER value of i in
188 * this MAC's region.
189 */
190 void SetTxDbmForTxPower(std::vector<double> txDbmForTxPower);
191
192 /**
193 * Set the matrix to use when deciding with which data rate to respond. Region
194 * based.
195 *
196 * \param replyDataRateMatrix A matrix containing the reply DataRates, based
197 * on the sending data rate and on the value of the RX1DROffset parameter.
198 */
199 void SetReplyDataRateMatrix(ReplyDataRateMatrix replyDataRateMatrix);
200
201 /**
202 * Set the number of PHY preamble symbols this MAC is set to use.
203 *
204 * \param nPreambleSymbols The number of preamble symbols to use (typically 8).
205 */
206 void SetNPreambleSymbols(int nPreambleSymbols);
207
208 /**
209 * Get the number of PHY preamble symbols this MAC is set to use.
210 *
211 * \return The number of preamble symbols to use (typically 8).
212 */
213 int GetNPreambleSymbols() const;
214
215 protected:
216 /**
217 * The trace source that is fired when a packet cannot be sent because of duty
218 * cycle limitations.
219 */
221
222 /**
223 * Trace source that is fired when a packet reaches the MAC layer.
224 */
226
227 /**
228 * Trace source that is fired when a new APP layer packet arrives at the MAC
229 * layer.
230 */
232
233 /**
234 * The PHY instance that sits under this MAC layer.
235 */
237
238 /**
239 * The device this MAC layer is installed on.
240 */
242
243 /**
244 * The LogicalLoraChannelHelper instance that is assigned to this MAC.
245 */
247
248 /**
249 * A vector holding the spreading factor each data rate corresponds to.
250 */
251 std::vector<uint8_t> m_sfForDataRate;
252
253 /**
254 * A vector holding the bandwidth each data rate corresponds to.
255 */
256 std::vector<double> m_bandwidthForDataRate;
257
258 /**
259 * A vector holding the maximum app payload size that corresponds to a
260 * certain data rate.
261 */
262 std::vector<uint32_t> m_maxAppPayloadForDataRate;
263
264 /**
265 * The number of symbols to use in the PHY preamble.
266 */
268
269 /**
270 * A vector holding the power that corresponds to a certain TxPower value.
271 */
272 std::vector<double> m_txDbmForTxPower;
273
274 /**
275 * The matrix that decides the data rate the gateway will use in a reply based on the end
276 * device's sending data rate and on the value of the RX1DROffset parameter.
277 */
279};
280
281} // namespace lorawan
282
283} // namespace ns3
284#endif /* LORAWAN_MAC_H */
A base class which provides memory management and object aggregation.
Definition object.h:78
Smart pointer class similar to boost::intrusive_ptr.
Forward calls to a chain of Callback.
a unique identifier for an interface.
Definition type-id.h:48
Class representing the LoRaWAN MAC layer.
Definition lorawan-mac.h:37
std::vector< double > m_txDbmForTxPower
A vector holding the power that corresponds to a certain TxPower value.
TracedCallback< Ptr< const Packet > > m_cannotSendBecauseDutyCycle
The trace source that is fired when a packet cannot be sent because of duty cycle limitations.
std::vector< uint8_t > m_sfForDataRate
A vector holding the spreading factor each data rate corresponds to.
void SetSfForDataRate(std::vector< uint8_t > sfForDataRate)
Set the vector to use to check up correspondence between spreading factor and data rate.
LorawanMac()
Default constructor.
TracedCallback< Ptr< const Packet > > m_receivedPacket
Trace source that is fired when a packet reaches the MAC layer.
void SetDevice(Ptr< NetDevice > device)
Set the device this MAC layer is installed on.
virtual void FailedReception(Ptr< const Packet > packet)=0
Function called by lower layers to inform this layer that reception of a packet we were locked on fai...
std::vector< uint32_t > m_maxAppPayloadForDataRate
A vector holding the maximum app payload size that corresponds to a certain data rate.
Ptr< LogicalLoraChannelHelper > GetLogicalLoraChannelHelper()
Get the logical lora channel helper associated with this MAC.
~LorawanMac() override
Destructor.
double GetDbmForTxPower(uint8_t txPower)
Get the transmission power in dBm that corresponds, in this region, to the encoded 8-bit txPower.
void SetPhy(Ptr< LoraPhy > phy)
Set the underlying PHY layer.
uint8_t GetSfFromDataRate(uint8_t dataRate)
Get the spreading factor corresponding to a data rate, based on this MAC's region.
double GetBandwidthFromDataRate(uint8_t dataRate)
Get the bandwidth corresponding to a data rate, based on this MAC's region.
void SetTxDbmForTxPower(std::vector< double > txDbmForTxPower)
Set the vector to use to check up which transmission power in Dbm corresponds to a certain TxPower va...
virtual void Send(Ptr< Packet > packet)=0
Send a packet.
ReplyDataRateMatrix m_replyDataRateMatrix
The matrix that decides the data rate the gateway will use in a reply based on the end device's sendi...
static TypeId GetTypeId()
Register this type.
virtual void Receive(Ptr< const Packet > packet)=0
Receive a packet from the lower layer.
void SetLogicalLoraChannelHelper(Ptr< LogicalLoraChannelHelper > helper)
Set the LogicalLoraChannelHelper this MAC instance will use.
Ptr< LogicalLoraChannelHelper > m_channelHelper
The LogicalLoraChannelHelper instance that is assigned to this MAC.
int GetNPreambleSymbols() const
Get the number of PHY preamble symbols this MAC is set to use.
Ptr< LoraPhy > GetPhy()
Get the underlying PHY layer.
virtual void TxFinished(Ptr< const Packet > packet)=0
Perform actions after sending a packet.
void SetMaxAppPayloadForDataRate(std::vector< uint32_t > maxAppPayloadForDataRate)
Set the maximum App layer payload for a set data rate.
TracedCallback< Ptr< const Packet > > m_sentNewPacket
Trace source that is fired when a new APP layer packet arrives at the MAC layer.
Ptr< LoraPhy > m_phy
The PHY instance that sits under this MAC layer.
std::vector< double > m_bandwidthForDataRate
A vector holding the bandwidth each data rate corresponds to.
void SetNPreambleSymbols(int nPreambleSymbols)
Set the number of PHY preamble symbols this MAC is set to use.
void SetReplyDataRateMatrix(ReplyDataRateMatrix replyDataRateMatrix)
Set the matrix to use when deciding with which data rate to respond.
void SetBandwidthForDataRate(std::vector< double > bandwidthForDataRate)
Set the vector to use to check up correspondence between bandwidth and data rate.
Ptr< NetDevice > m_device
The device this MAC layer is installed on.
int m_nPreambleSymbols
The number of symbols to use in the PHY preamble.
Ptr< NetDevice > GetDevice()
Get the device this MAC layer is installed on.
std::array< std::array< uint8_t, 6 >, 8 > ReplyDataRateMatrix
Matrix structure to store possible data rate value to be used by a LoRaWAN end device for listening d...
Definition lorawan-mac.h:53
Every class exported by the ns3 library is enclosed in the ns3 namespace.