A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
lora-frame-header.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 LORA_FRAME_HEADER_H
10#define LORA_FRAME_HEADER_H
11
12#include "lora-device-address.h"
13#include "mac-command.h"
14
15#include "ns3/header.h"
16
17namespace ns3
18{
19namespace lorawan
20{
21
22/**
23 * \ingroup lorawan
24 *
25 * This class represents the Frame header (FHDR) used in a LoraWAN network.
26 *
27 * Although the specification divides the FHDR from the FPort field, this
28 * implementation considers them as a unique entity (i.e., FPort is treated as
29 * if it were a part of FHDR).
30 *
31 * \remark Prior to using it, this class needs to be informed of whether the
32 * header is for an uplink or downlink message. This is necessary due to the
33 * fact that UL and DL messages have subtly different structure and, hence,
34 * serialization and deserialization schemes.
35 */
36class LoraFrameHeader : public Header
37{
38 public:
39 LoraFrameHeader(); //!< Default constructor
40 ~LoraFrameHeader() override; //!< Destructor
41
42 // Methods inherited from Header
43
44 /**
45 * Register this type.
46 * \return The object TypeId.
47 */
48 static TypeId GetTypeId();
49 TypeId GetInstanceTypeId() const override;
50
51 /**
52 * Return the size required for serialization of this header.
53 *
54 * \return The serialized size in bytes.
55 */
56 uint32_t GetSerializedSize() const override;
57
58 /**
59 * Serialize the header.
60 *
61 * See Page 15 of LoraWAN specification for a representation of fields.
62 *
63 * \param start A pointer to the buffer that will be filled with the
64 * serialization.
65 */
66 void Serialize(Buffer::Iterator start) const override;
67
68 /**
69 * Deserialize the contents of the buffer into a LoraFrameHeader object.
70 *
71 * \param start A pointer to the buffer we need to deserialize.
72 * \return The number of consumed bytes.
73 */
75
76 /**
77 * Print the header in a human-readable format.
78 *
79 * \param os The std::ostream on which to print the header.
80 */
81 void Print(std::ostream& os) const override;
82
83 /**
84 * State that this is an uplink message.
85 *
86 * This method needs to be called at least once before any serialization or
87 * deserialization.
88 */
89 void SetAsUplink();
90
91 /**
92 * State that this is a downlink message.
93 *
94 * This method needs to be called at least once before any serialization or
95 * deserialization.
96 */
97 void SetAsDownlink();
98
99 /**
100 * Set the FPort value.
101 *
102 * \param fPort The FPort to set.
103 */
104 void SetFPort(uint8_t fPort);
105
106 /**
107 * Get the FPort value.
108 *
109 * \return The FPort value.
110 */
111 uint8_t GetFPort() const;
112
113 /**
114 * Set the address.
115 *
116 * \param address The LoraDeviceAddress to set.
117 */
118 void SetAddress(LoraDeviceAddress address);
119
120 /**
121 * Get this header's device address value.
122 *
123 * \return The address value stored in this header.
124 */
126
127 /**
128 * Set the value of the ADR bit field.
129 *
130 * \param adr Whether or not to set the ADR bit field.
131 */
132 void SetAdr(bool adr);
133
134 /**
135 * Get the value of the ADR bit field.
136 *
137 * \return True if the ADR bit is set, false otherwise.
138 */
139 bool GetAdr() const;
140
141 /**
142 * Set the value of the ADRACKReq bit field.
143 *
144 * \param adrAckReq Whether or not to set the ADRACKReq bit field.
145 */
146 void SetAdrAckReq(bool adrAckReq);
147
148 /**
149 * Get the value of the ADRACKReq bit field.
150 *
151 * \return True if the ADRACKReq bit is set, false otherwise.
152 */
153 bool GetAdrAckReq() const;
154
155 /**
156 * Set the value of the ACK bit field.
157 *
158 * \param ack Whether or not to set the ACK bit.
159 */
160 void SetAck(bool ack);
161
162 /**
163 * Get the value of the ACK bit field.
164 *
165 * \return True if the ACK bit is set, false otherwise.
166 */
167 bool GetAck() const;
168
169 /**
170 * Set the value of the FPending bit field.
171 *
172 * \param fPending Whether or not to set the FPending bit.
173 */
174 void SetFPending(bool fPending);
175
176 /**
177 * Get the value of the FPending bit field.
178 *
179 * \return True if the FPending bit is set, false otherwise.
180 */
181 bool GetFPending() const;
182
183 /**
184 * Get the FOptsLen value.
185 *
186 * \remark This value cannot be set since it's directly extracted from the
187 * number and kind of MAC commands.
188 *
189 * \return The FOptsLen value.
190 */
191 uint8_t GetFOptsLen() const;
192
193 /**
194 * Set the FCnt value.
195 *
196 * \param fCnt The FCnt to set.
197 */
198 void SetFCnt(uint16_t fCnt);
199 /**
200 * Get the FCnt value.
201 *
202 * \return The FCnt value.
203 */
204 uint16_t GetFCnt() const;
205
206 /**
207 * Return a pointer to the first MacCommand of type T, or 0 if no such MacCommand exists
208 * in this header.
209 *
210 * \return A pointer to a MacCommand of type T.
211 */
212 template <typename T>
213 inline Ptr<T> GetMacCommand();
214
215 /**
216 * Add a LinkCheckReq command.
217 */
218 void AddLinkCheckReq();
219
220 /**
221 * Add a LinkCheckAns command.
222 *
223 * \param margin The demodulation margin the LinkCheckReq packet was received with.
224 * \param gwCnt The number of gateways the LinkCheckReq packet was received by.
225 */
226 void AddLinkCheckAns(uint8_t margin, uint8_t gwCnt);
227
228 /**
229 * Add a LinkAdrReq command.
230 *
231 * \param dataRate The data rate at which the receiver should transmit.
232 * \param txPower The power at which the receiver should transmit, encoded according to the
233 * LoRaWAN specification of the region. \param enabledChannels A list containing the indices of
234 * channels enabled by this command. \param repetitions The number of repetitions the receiver
235 * should send when transmitting.
236 */
237 void AddLinkAdrReq(uint8_t dataRate,
238 uint8_t txPower,
239 std::list<int> enabledChannels,
240 int repetitions);
241
242 /**
243 * Add a LinkAdrAns command.
244 *
245 * \param powerAck Whether the power can be set or not.
246 * \param dataRateAck Whether the data rate can be set or not.
247 * \param channelMaskAck Whether the channel mask is coherent with the device's current state or
248 * not.
249 */
250 void AddLinkAdrAns(bool powerAck, bool dataRateAck, bool channelMaskAck);
251
252 /**
253 * Add a DutyCycleReq command.
254 *
255 * This command accepts an 8-bit integer as dutyCycle. The actual dutyCycle
256 * that will be implemented in the end-device will then be, in fraction form,
257 * 1/2^(dutyCycle).
258 *
259 * \param dutyCycle The dutyCycle in 8-bit form.
260 */
261 void AddDutyCycleReq(uint8_t dutyCycle);
262
263 /**
264 * Add a DutyCycleAns command.
265 */
266 void AddDutyCycleAns();
267
268 /**
269 * Add a RxParamSetupReq command.
270 *
271 * \param rx1DrOffset The requested data rate offset for the first receive window.
272 * \param rx2DataRate The requested data rate for the second receive window.
273 * \param frequency The frequency at which to listen for the second receive window.
274 */
275 void AddRxParamSetupReq(uint8_t rx1DrOffset, uint8_t rx2DataRate, double frequency);
276
277 /**
278 * Add a RxParamSetupAns command.
279 */
280 void AddRxParamSetupAns();
281
282 /**
283 * Add a DevStatusReq command.
284 */
285 void AddDevStatusReq();
286
287 /**
288 * Add a NewChannelReq command with provided fields.
289 *
290 * \param chIndex The ChIndex field.
291 * \param frequency The Frequency field.
292 * \param minDataRate The MinDR field.
293 * \param maxDataRate The MaxDR field.
294 */
295 void AddNewChannelReq(uint8_t chIndex,
296 double frequency,
297 uint8_t minDataRate,
298 uint8_t maxDataRate);
299
300 /**
301 * Return a list of pointers to all the MAC commands saved in this header.
302 *
303 * \return The list of pointers to MacCommand objects.
304 */
305 std::list<Ptr<MacCommand>> GetCommands();
306
307 /**
308 * Add a predefined command to the list in this frame header.
309 *
310 * \param macCommand A pointer to the MacCommand object to add.
311 */
312 void AddCommand(Ptr<MacCommand> macCommand);
313
314 private:
315 uint8_t m_fPort; //!< The FPort field
316
317 LoraDeviceAddress m_address; //!< The DevAddr field
318
319 bool m_adr; //!< The ADR field of the FCtrl
320 bool m_adrAckReq; //!< The ADRACKReq field of the FCtrl
321 bool m_ack; //!< The ACK field of the FCtrl
322 bool m_fPending; //!< The FPending/ClassB field of the FCtrl
323 uint8_t m_fOptsLen; //!< The FOptsLen field of the FCtrl
324
325 uint16_t m_fCnt; //!< The FCnt field
326
327 Buffer m_fOpts; //!< The FOpts field
328 std::list<Ptr<MacCommand>> m_macCommands; //!< List containing all the MacCommand instances that
329 //!< are contained in this LoraFrameHeader
330
331 bool m_isUplink; //!< Whether this frame header is uplink or not
332};
333
334template <typename T>
335Ptr<T>
337{
338 // Iterate on MAC commands and try casting
339 std::list<Ptr<MacCommand>>::const_iterator it;
340 for (it = m_macCommands.begin(); it != m_macCommands.end(); ++it)
341 {
342 if (DynamicCast<T>(*it))
343 {
344 return DynamicCast<T>(*it);
345 }
346 }
347
348 // If no command was found, return 0
349 return nullptr;
350}
351} // namespace lorawan
352
353} // namespace ns3
354#endif
iterator in a Buffer instance
Definition buffer.h:89
automatically resized byte buffer
Definition buffer.h:83
Protocol header serialization and deserialization.
Definition header.h:33
Smart pointer class similar to boost::intrusive_ptr.
a unique identifier for an interface.
Definition type-id.h:48
This class represents the device address of a LoraWAN end device.
This class represents the Frame header (FHDR) used in a LoraWAN network.
bool m_ack
The ACK field of the FCtrl.
void AddDutyCycleReq(uint8_t dutyCycle)
Add a DutyCycleReq command.
bool GetAck() const
Get the value of the ACK bit field.
uint8_t GetFPort() const
Get the FPort value.
void AddLinkCheckReq()
Add a LinkCheckReq command.
uint32_t Deserialize(Buffer::Iterator start) override
Deserialize the contents of the buffer into a LoraFrameHeader object.
void AddCommand(Ptr< MacCommand > macCommand)
Add a predefined command to the list in this frame header.
void SetFCnt(uint16_t fCnt)
Set the FCnt value.
bool GetAdr() const
Get the value of the ADR bit field.
Ptr< T > GetMacCommand()
Return a pointer to the first MacCommand of type T, or 0 if no such MacCommand exists in this header.
void AddNewChannelReq(uint8_t chIndex, double frequency, uint8_t minDataRate, uint8_t maxDataRate)
Add a NewChannelReq command with provided fields.
void AddDutyCycleAns()
Add a DutyCycleAns command.
bool m_fPending
The FPending/ClassB field of the FCtrl.
void AddRxParamSetupAns()
Add a RxParamSetupAns command.
void SetAck(bool ack)
Set the value of the ACK bit field.
bool m_adr
The ADR field of the FCtrl.
uint16_t m_fCnt
The FCnt field.
void SetAdr(bool adr)
Set the value of the ADR bit field.
uint8_t m_fOptsLen
The FOptsLen field of the FCtrl.
void AddDevStatusReq()
Add a DevStatusReq command.
bool GetFPending() const
Get the value of the FPending bit field.
uint32_t GetSerializedSize() const override
Return the size required for serialization of this header.
void SetAddress(LoraDeviceAddress address)
Set the address.
uint16_t GetFCnt() const
Get the FCnt value.
void Print(std::ostream &os) const override
Print the header in a human-readable format.
bool GetAdrAckReq() const
Get the value of the ADRACKReq bit field.
std::list< Ptr< MacCommand > > m_macCommands
List containing all the MacCommand instances that are contained in this LoraFrameHeader.
void SetAsUplink()
State that this is an uplink message.
LoraDeviceAddress m_address
The DevAddr field.
Buffer m_fOpts
The FOpts field.
LoraDeviceAddress GetAddress() const
Get this header's device address value.
void SetAdrAckReq(bool adrAckReq)
Set the value of the ADRACKReq bit field.
~LoraFrameHeader() override
Destructor.
void Serialize(Buffer::Iterator start) const override
Serialize the header.
static TypeId GetTypeId()
Register this type.
bool m_adrAckReq
The ADRACKReq field of the FCtrl.
void SetFPending(bool fPending)
Set the value of the FPending bit field.
void AddLinkCheckAns(uint8_t margin, uint8_t gwCnt)
Add a LinkCheckAns command.
void AddLinkAdrAns(bool powerAck, bool dataRateAck, bool channelMaskAck)
Add a LinkAdrAns command.
bool m_isUplink
Whether this frame header is uplink or not.
void AddLinkAdrReq(uint8_t dataRate, uint8_t txPower, std::list< int > enabledChannels, int repetitions)
Add a LinkAdrReq command.
uint8_t m_fPort
The FPort field.
LoraFrameHeader()
Default constructor.
std::list< Ptr< MacCommand > > GetCommands()
Return a list of pointers to all the MAC commands saved in this header.
TypeId GetInstanceTypeId() const override
Get the most derived TypeId for this Object.
void SetAsDownlink()
State that this is a downlink message.
void SetFPort(uint8_t fPort)
Set the FPort value.
void AddRxParamSetupReq(uint8_t rx1DrOffset, uint8_t rx2DataRate, double frequency)
Add a RxParamSetupReq command.
uint8_t GetFOptsLen() const
Get the FOptsLen value.
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Ptr< T1 > DynamicCast(const Ptr< T2 > &p)
Cast a Ptr.
Definition ptr.h:580