A Discrete-Event Network Simulator
API
lr-wpan-orphan-scan.cc
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2023 Tokushima University, Japan.
3  *
4  * This program is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU General Public License version 2 as
6  * published by the Free Software Foundation;
7  *
8  * This program is distributed in the hope that it will be useful,
9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11  * GNU General Public License for more details.
12  *
13  * You should have received a copy of the GNU General Public License
14  * along with this program; if not, write to the Free Software
15  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
16  *
17  * Author: Alberto Gallegos Ramonet <alramonet@is.tokushima-u.ac.jp>
18  */
19 
20 /*
21  * [00:00:00:00:00:00:00:01 | 00:01] [00:00:00:00:00:00:00:02 | ff:ff]
22  * PAN Coordinator 1 (PAN: 5) End Device
23  * |---------------------100m-----------------------|
24  * Channel 12 (Orphan Scan channels 11-14)
25  *
26  *
27  * This example demonstrate the usage of the MAC MLME-SCAN.request (ORPHAN scan) primitive as
28  * described by IEEE 802.15.4-2011 (See Figures 14 and 15).
29  *
30  * Orphan scan is used typically on devices as a result of repeated communication failures
31  * (For example, lossing too many ACK). An orphan scan represents the attempt of a device to
32  * relocate its coordinator. In some situations, it can be used by devices higher layers to not only
33  * rejoin a network but also join a network for the first time (Like in the joining through
34  * orphaning mechanism described in Zigbee networks).
35  *
36  * In this example, the end device is set to scan 4 channels (11~14) for a period of
37  * macResponseWaitTime until it finally gets in contact with the coordinator.
38  * On contact, the coordinator responds to the device (via coordinator realignment command)
39  * an assign it a short address. The detailed sequence of events is as following:
40  *
41  * 1) [Time 2s] The coordinator start a network in channel 12.
42  * 2) [Time 3s] The end device start orphan scan and transmits a orphan
43  * notification cmd on channel 11.
44  * 3) No response is received in channel 11, therefore, the device ends scanning on
45  * channel 11 after macResponseWaitTime and repeats step 2 in channel 12.
46  * 4) [Time 3.00269s] The orphan notification command is received by the coordinator in
47  * channel 12. The coordinator verify the requesting device and replies to the device
48  * with a coordinator realignment command containing the assigned short address [DE:AF].
49  * 5) [Time 3.00646s] The device receives the coordinator realignment command, update its
50  * macPanId, macShortAddress, macCoordShortAddress and macCoordExtAddress.
51  * 6) Scanning of the remaining channels 13 and 14 is cancelled.
52  */
53 
54 #include <ns3/constant-position-mobility-model.h>
55 #include <ns3/core-module.h>
56 #include <ns3/log.h>
57 #include <ns3/lr-wpan-module.h>
58 #include <ns3/packet.h>
59 #include <ns3/propagation-delay-model.h>
60 #include <ns3/propagation-loss-model.h>
61 #include <ns3/simulator.h>
62 #include <ns3/single-model-spectrum-channel.h>
63 
64 #include <iostream>
65 
66 using namespace ns3;
67 
68 static void
70 {
71  if (params.m_status == LrWpanMacStatus::SUCCESS)
72  {
73  std::cout << Simulator::Now().As(Time::S) << " Node " << device->GetNode()->GetId() << " ["
74  << device->GetMac()->GetShortAddress() << " | "
75  << device->GetMac()->GetExtendedAddress()
76  << "] MLME-SCAN.confirm: Active scan status SUCCESSFUL "
77  << "(Coordinator found and address assigned) \n";
78  }
79  else if (params.m_status == LrWpanMacStatus::NO_BEACON)
80  {
81  std::cout << Simulator::Now().As(Time::S) << " Node " << device->GetNode()->GetId() << " ["
82  << device->GetMac()->GetShortAddress() << " | "
83  << device->GetMac()->GetExtendedAddress()
84  << "] MLME-SCAN.confirm: Could not locate coordinator "
85  << "(Coord realignment command not received) "
86  << "status: " << params.m_status << "\n";
87  }
88  else
89  {
90  std::cout << Simulator::Now().As(Time::S) << " Node " << device->GetNode()->GetId() << " ["
91  << device->GetMac()->GetShortAddress() << " | "
92  << device->GetMac()->GetExtendedAddress()
93  << "] MLME-SCAN.confirm: An error occurred during scanning, "
94  << "status: " << params.m_status << "\n";
95  }
96 }
97 
98 static void
100 {
101  // The steps taken by the coordinator on the event of an orphan indication
102  // are meant to be implemented by the next higher layer and are out of the scope of the
103  // standard. In this example, we simply accept the request , assign a fixed short address
104  // [DE:AF] and respond to the requesting device using a MLME-ORPHAN.response.
105 
106  std::cout << Simulator::Now().As(Time::S) << " Node " << device->GetNode()->GetId() << " ["
107  << device->GetMac()->GetShortAddress() << " | "
108  << device->GetMac()->GetExtendedAddress()
109  << "] MLME-ORPHAN.indication: Orphan Notification received, processing...\n";
110 
111  MlmeOrphanResponseParams respParams;
112  respParams.m_assocMember = true;
113  respParams.m_orphanAddr = params.m_orphanAddr;
114  respParams.m_shortAddr = Mac16Address("DE:AF");
115 
117 }
118 
119 int
120 main(int argc, char* argv[])
121 {
123 
124  // Create 2 PAN coordinator nodes, and 1 end device
125  Ptr<Node> coord1 = CreateObject<Node>();
126  Ptr<Node> endNode = CreateObject<Node>();
127 
128  Ptr<LrWpanNetDevice> coord1NetDevice = CreateObject<LrWpanNetDevice>();
129  Ptr<LrWpanNetDevice> endNodeNetDevice = CreateObject<LrWpanNetDevice>();
130 
131  // PAN Coordinators configurations require to set both, the EUI-64 (extended address)
132  // and to assign their own short address.
133  coord1NetDevice->GetMac()->SetExtendedAddress(Mac64Address("00:00:00:00:00:00:00:01"));
134  coord1NetDevice->GetMac()->SetShortAddress(Mac16Address("00:01"));
135 
136  // Other devices must have only its EUI-64 and later on, their short address is
137  // potentially assigned by the coordinator.
138  endNodeNetDevice->GetMac()->SetExtendedAddress(Mac64Address("00:00:00:00:00:00:00:02"));
139 
140  // Configure Spectrum channel
141  Ptr<SingleModelSpectrumChannel> channel = CreateObject<SingleModelSpectrumChannel>();
143  CreateObject<LogDistancePropagationLossModel>();
145  CreateObject<ConstantSpeedPropagationDelayModel>();
146  channel->AddPropagationLossModel(propModel);
147  channel->SetPropagationDelayModel(delayModel);
148 
149  coord1NetDevice->SetChannel(channel);
150  endNodeNetDevice->SetChannel(channel);
151 
152  coord1->AddDevice(coord1NetDevice);
153  endNode->AddDevice(endNodeNetDevice);
154 
155  // Mobility
156  Ptr<ConstantPositionMobilityModel> coord1Mobility =
157  CreateObject<ConstantPositionMobilityModel>();
158  coord1Mobility->SetPosition(Vector(0, 0, 0));
159  coord1NetDevice->GetPhy()->SetMobility(coord1Mobility);
160 
161  Ptr<ConstantPositionMobilityModel> endNodeMobility =
162  CreateObject<ConstantPositionMobilityModel>();
163  endNodeMobility->SetPosition(Vector(100, 0, 0));
164  endNodeNetDevice->GetPhy()->SetMobility(endNodeMobility);
165 
166  // MAC layer Callbacks hooks
167  endNodeNetDevice->GetMac()->SetMlmeScanConfirmCallback(
168  MakeBoundCallback(&ScanConfirm, endNodeNetDevice));
169 
170  coord1NetDevice->GetMac()->SetMlmeOrphanIndicationCallback(
171  MakeBoundCallback(&OrphanIndication, coord1NetDevice));
172 
174  // ORPHAN SCAN //
176 
177  // PAN coordinator N0 (PAN 5) is set to channel 12 in non-beacon mode
178  // but answer to beacon request and orphan notification commands.
180  params.m_panCoor = true;
181  params.m_PanId = 5;
182  params.m_bcnOrd = 15;
183  params.m_sfrmOrd = 15;
184  params.m_logCh = 12;
186  Seconds(2.0),
188  coord1NetDevice->GetMac(),
189  params);
190 
191  // End device N1 is set to scan 4 channels looking for the presence of a coordinator.
192  // On each channel, a single orphan notification command is sent and a response is
193  // waited for a maximum time of macResponseWaitTime. If a reply is received from a
194  // coordinator within this time (coordinator realignment command), the programmed scans on
195  // other channels is suspended.
196  // Scan Channels are represented by bits 0-26 (27 LSB)
197  // ch 14 ch 11
198  // | |
199  // 0x7800 = 0000000000000000111100000000000
200  MlmeScanRequestParams scanParams;
201  scanParams.m_chPage = 0;
202  scanParams.m_scanChannels = 0x7800;
203  scanParams.m_scanType = MLMESCAN_ORPHAN;
205  Seconds(3.0),
207  endNodeNetDevice->GetMac(),
208  scanParams);
209 
210  Simulator::Stop(Seconds(2000));
211  Simulator::Run();
212 
214  return 0;
215 }
void MlmeScanRequest(MlmeScanRequestParams params) override
IEEE 802.15.4-2011, section 6.2.10.1 MLME-SCAN.request Request primitive used to initiate a channel s...
Definition: lr-wpan-mac.cc:623
void MlmeStartRequest(MlmeStartRequestParams params) override
IEEE 802.15.4-2006, section 7.1.14.1 MLME-START.request Request to allow a PAN coordinator to initiat...
Definition: lr-wpan-mac.cc:584
void MlmeOrphanResponse(MlmeOrphanResponseParams params) override
IEEE 802.15.4-2011, section 6.2.7.2 MLME-ORPHAN.response Primitive used to initiatte a response to an...
Definition: lr-wpan-mac.cc:803
Ptr< Node > GetNode() const override
void SetChannel(Ptr< SpectrumChannel > channel)
Set the channel to which the NetDevice, and therefore the PHY, should be attached to.
Ptr< LrWpanMac > GetMac() const
Get the MAC used by this NetDevice.
Ptr< LrWpanPhy > GetPhy() const
Get the PHY used by this NetDevice.
This class can contain 16 bit addresses.
Definition: mac16-address.h:44
an EUI-64 address
Definition: mac64-address.h:46
uint32_t AddDevice(Ptr< NetDevice > device)
Associate a NetDevice to this node.
Definition: node.cc:138
uint32_t GetId() const
Definition: node.cc:117
static void Destroy()
Execute the events scheduled with ScheduleDestroy().
Definition: simulator.cc:142
static void ScheduleWithContext(uint32_t context, const Time &delay, FUNC f, Ts &&... args)
Schedule an event with the given context.
Definition: simulator.h:588
static Time Now()
Return the current simulation virtual time.
Definition: simulator.cc:208
static void Run()
Run the simulation.
Definition: simulator.cc:178
static EventId ScheduleNow(FUNC f, Ts &&... args)
Schedule an event to expire Now.
Definition: simulator.h:605
static void Stop()
Tell the Simulator the calling event should be the last one executed.
Definition: simulator.cc:186
TimeWithUnit As(const Unit unit=Time::AUTO) const
Attach a unit to a Time, to facilitate output in a specific unit.
Definition: time.cc:415
@ S
second
Definition: nstime.h:116
@ MLMESCAN_ORPHAN
@ NO_BEACON
A scan operation failed to find any network beacons.
auto MakeBoundCallback(R(*fnPtr)(Args...), BArgs &&... bargs)
Make Callbacks with varying number of bound arguments.
Definition: callback.h:765
Time Seconds(double value)
Construct a Time in the indicated unit.
Definition: nstime.h:1326
static void OrphanIndication(Ptr< LrWpanNetDevice > device, MlmeOrphanIndicationParams params)
static void ScanConfirm(Ptr< LrWpanNetDevice > device, MlmeScanConfirmParams params)
Every class exported by the ns3 library is enclosed in the ns3 namespace.
@ SUCCESS
Definition: ff-mac-common.h:62
LogLevel
Logging severity classes and levels.
Definition: log.h:94
@ LOG_PREFIX_FUNC
Prefix all trace prints with function.
Definition: log.h:118
@ LOG_PREFIX_TIME
Prefix all trace prints with simulation time.
Definition: log.h:119
void LogComponentEnableAll(LogLevel level)
Enable the logging output for all registered log components.
Definition: log.cc:320
channel
Definition: third.py:88
params
Fit Fluctuating Two Ray model to the 3GPP TR 38.901 using the Anderson-Darling goodness-of-fit ##.
MLME-ORPHAN.indication params.
MLME-ORPHAN.response params.
Mac16Address m_shortAddr
The short address allocated.
Mac64Address m_orphanAddr
The address of the orphaned device.
bool m_assocMember
T = allocated with this coord | F = otherwise.
MLME-SCAN.confirm params.
MLME-SCAN.request params.
uint32_t m_scanChannels
The channel numbers to be scanned.
uint32_t m_chPage
The channel page on which to perform scan.
LrWpanMlmeScanType m_scanType
Indicates the type of scan performed as described in IEEE 802.15.4-2011 (5.1.2.1).
MLME-START.request params.