A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
waypoint-mobility-model.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2009 Phillip Sitbon
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Phillip Sitbon <phillip@sitbon.net>
7 */
8#ifndef WAYPOINT_MOBILITY_MODEL_H
9#define WAYPOINT_MOBILITY_MODEL_H
10
11#include "mobility-model.h"
12#include "waypoint.h"
13
14#include "ns3/vector.h"
15
16#include <deque>
17#include <stdint.h>
18
20
21namespace ns3
22{
23
24/**
25 * @ingroup mobility
26 * @brief Waypoint-based mobility model.
27 *
28 * Each object determines its velocity and position at a given time
29 * from a set of ns3::Waypoint objects. Past waypoints are discarded
30 * after the current simulation time greater than their time value.
31 *
32 * By default, the initial position of each object corresponds to the
33 * position of the first waypoint, and the initial velocity of each
34 * object is zero. Upon reaching the last waypoint, object position
35 * becomes static and velocity is zero.
36 *
37 * When a node is in between waypoint times, it moves with a constant
38 * velocity between the position at the previous waypoint and the position
39 * at the current waypoint. To make a node hold a certain position for a
40 * time interval, two waypoints with the same position (but different times)
41 * should be inserted sequentially.
42 *
43 * Waypoints can be added at any time, and setting the current position
44 * of an object will set its velocity to zero until the next waypoint time
45 * (at which time the object jumps to the next waypoint), unless there are
46 * no more waypoints in which case it will not change without user
47 * intervention.
48 *
49 * The model has two attributes with methods that allow clients to get
50 * the next waypoint value (NextWaypoint) and the number of waypoints left
51 * (WaypointsLeft) beyond (but not including) the next waypoint.
52 *
53 * In addition, there are two attributes that govern model behavior. The
54 * first, LazyNotify, governs how the model calls the CourseChange trace.
55 * By default, LazyNotify is false, which means that each time that a
56 * waypoint time is hit, an Update() is forced and the CourseChange
57 * callback will be called. When LazyNotify is true, Update() is suppressed
58 * at waypoint times, and CourseChange callbacks will only occur when
59 * there later are actual calls to Update () (typically when calling
60 * GetPosition ()). This option may be enabled for execution run-time
61 * performance improvements, but when enabled, users should note that
62 * course change listeners will in general not be notified at waypoint
63 * times but instead at the next Update() following a waypoint time,
64 * and some waypoints may not be notified to course change listeners.
65 *
66 * The second, InitialPositionIsWaypoint, is false by default. Recall
67 * that the first waypoint will set the initial position and set velocity
68 * equal to 0 until the first waypoint time. In such a case, the
69 * call to SetPosition(), such as from a PositionAllocator, will be
70 * ignored. However, if InitialPositionIsWaypoint is set to true
71 * and SetPosition() is called before any waypoints have been added,
72 * the SetPosition() call is treated as an initial waypoint at time zero.
73 * In such a case, when SetPosition() is treated as an initial waypoint,
74 * it should be noted that attempts to add a waypoint at the same time
75 * will cause the program to fail.
76 */
78{
79 public:
80 /**
81 * Register this type with the TypeId system.
82 * @return the object TypeId
83 */
84 static TypeId GetTypeId();
85
86 /**
87 * Create a path with no waypoints at location (0,0,0).
88 */
90 ~WaypointMobilityModel() override;
91
92 // Inherited from MobilityModel
93 Ptr<MobilityModel> Copy() const override
94 {
96 }
97
98 /**
99 * @param waypoint waypoint to append to the object path.
100 *
101 * Add a waypoint to the path of the object. The time must
102 * be greater than the previous waypoint added, otherwise
103 * a fatal error occurs. The first waypoint is set as the
104 * current position with a velocity of zero.
105 *
106 */
107 void AddWaypoint(const Waypoint& waypoint);
108
109 /**
110 * Get the waypoint that this object is traveling towards.
111 * @returns The waypoint
112 */
114
115 /**
116 * Get the number of waypoints left for this object, excluding
117 * the next one.
118 * @returns The number of waypoints left
119 */
120 uint32_t WaypointsLeft() const;
121
122 /**
123 * Clear any existing waypoints and set the current waypoint
124 * time to infinity. Calling this is only an optimization and
125 * not required. After calling this function, adding waypoints
126 * behaves as it would for a new object.
127 */
128 void EndMobility();
129
130 private:
131 friend class ::WaypointMobilityModelNotifyTest; // To allow Update() calls and access to
132 // m_current
133
134 /**
135 * Update the underlying state corresponding to the stored waypoints
136 */
137 virtual void Update() const;
138 /**
139 * @brief The dispose method.
140 *
141 * Subclasses must override this method.
142 */
143 void DoDispose() override;
144 /**
145 * @brief Get current position.
146 * @return A vector with the current position of the node.
147 */
148 Vector DoGetPosition() const override;
149 /**
150 * @brief Sets a new position for the node
151 * @param position A vector to be added as the new position
152 */
153 void DoSetPosition(const Vector& position) override;
154 /**
155 * @brief Returns the current velocity of a node
156 * @return The velocity vector of a node.
157 */
158 Vector DoGetVelocity() const override;
159
160 protected:
161 /**
162 * @brief This variable is set to true if there are no waypoints in the std::deque
163 */
165 /**
166 * @brief If true, course change updates are only notified when position
167 * is calculated.
168 */
170 /**
171 * @brief If true, calling SetPosition with no waypoints creates a waypoint
172 */
174 /**
175 * @brief The double ended queue containing the ns3::Waypoint objects
176 */
177 mutable std::deque<Waypoint> m_waypoints;
178 /**
179 * @brief The ns3::Waypoint currently being used
180 */
182 /**
183 * @brief The next ns3::Waypoint in the deque
184 */
186 /**
187 * @brief The current velocity vector
188 */
189 mutable Vector m_velocity;
190 /**
191 * @brief Update event
192 */
194};
195
196} // namespace ns3
197
198#endif /* WAYPOINT_MOBILITY_MODEL_H */
Waypoint Mobility Model Notify Test.
An identifier for simulation events.
Definition event-id.h:44
Smart pointer class similar to boost::intrusive_ptr.
Definition ptr.h:67
a unique identifier for an interface.
Definition type-id.h:49
a (time, location) pair.
Definition waypoint.h:25
Vector m_velocity
The current velocity vector.
void DoDispose() override
The dispose method.
Waypoint GetNextWaypoint() const
Get the waypoint that this object is traveling towards.
bool m_initialPositionIsWaypoint
If true, calling SetPosition with no waypoints creates a waypoint.
Ptr< MobilityModel > Copy() const override
Copy function allows one to copy the underlying MobilityModel from a MobilityModel pointer,...
virtual void Update() const
Update the underlying state corresponding to the stored waypoints.
Vector DoGetVelocity() const override
Returns the current velocity of a node.
WaypointMobilityModel()
Create a path with no waypoints at location (0,0,0).
uint32_t WaypointsLeft() const
Get the number of waypoints left for this object, excluding the next one.
Waypoint m_current
The ns3::Waypoint currently being used.
bool m_first
This variable is set to true if there are no waypoints in the std::deque.
std::deque< Waypoint > m_waypoints
The double ended queue containing the ns3::Waypoint objects.
bool m_lazyNotify
If true, course change updates are only notified when position is calculated.
void EndMobility()
Clear any existing waypoints and set the current waypoint time to infinity.
void DoSetPosition(const Vector &position) override
Sets a new position for the node.
Vector DoGetPosition() const override
Get current position.
Waypoint m_next
The next ns3::Waypoint in the deque.
static TypeId GetTypeId()
Register this type with the TypeId system.
void AddWaypoint(const Waypoint &waypoint)
Ptr< T > CreateObject(Args &&... args)
Create an object by type, with varying number of constructor parameters.
Definition object.h:619
Every class exported by the ns3 library is enclosed in the ns3 namespace.