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 /**
93 * \param waypoint waypoint to append to the object path.
94 *
95 * Add a waypoint to the path of the object. The time must
96 * be greater than the previous waypoint added, otherwise
97 * a fatal error occurs. The first waypoint is set as the
98 * current position with a velocity of zero.
99 *
100 */
101 void AddWaypoint(const Waypoint& waypoint);
102
103 /**
104 * Get the waypoint that this object is traveling towards.
105 * \returns The waypoint
106 */
108
109 /**
110 * Get the number of waypoints left for this object, excluding
111 * the next one.
112 * \returns The number of waypoints left
113 */
114 uint32_t WaypointsLeft() const;
115
116 /**
117 * Clear any existing waypoints and set the current waypoint
118 * time to infinity. Calling this is only an optimization and
119 * not required. After calling this function, adding waypoints
120 * behaves as it would for a new object.
121 */
122 void EndMobility();
123
124 private:
125 friend class ::WaypointMobilityModelNotifyTest; // To allow Update() calls and access to
126 // m_current
127
128 /**
129 * Update the underlying state corresponding to the stored waypoints
130 */
131 virtual void Update() const;
132 /**
133 * \brief The dispose method.
134 *
135 * Subclasses must override this method.
136 */
137 void DoDispose() override;
138 /**
139 * \brief Get current position.
140 * \return A vector with the current position of the node.
141 */
142 Vector DoGetPosition() const override;
143 /**
144 * \brief Sets a new position for the node
145 * \param position A vector to be added as the new position
146 */
147 void DoSetPosition(const Vector& position) override;
148 /**
149 * \brief Returns the current velocity of a node
150 * \return The velocity vector of a node.
151 */
152 Vector DoGetVelocity() const override;
153
154 protected:
155 /**
156 * \brief This variable is set to true if there are no waypoints in the std::deque
157 */
159 /**
160 * \brief If true, course change updates are only notified when position
161 * is calculated.
162 */
164 /**
165 * \brief If true, calling SetPosition with no waypoints creates a waypoint
166 */
168 /**
169 * \brief The double ended queue containing the ns3::Waypoint objects
170 */
171 mutable std::deque<Waypoint> m_waypoints;
172 /**
173 * \brief The ns3::Waypoint currently being used
174 */
176 /**
177 * \brief The next ns3::Waypoint in the deque
178 */
180 /**
181 * \brief The current velocity vector
182 */
183 mutable Vector m_velocity;
184 /**
185 * \brief Update event
186 */
188};
189
190} // namespace ns3
191
192#endif /* WAYPOINT_MOBILITY_MODEL_H */
Waypoint Mobility Model Notify Test.
An identifier for simulation events.
Definition event-id.h:45
Keep track of the current position and velocity of an object.
a unique identifier for an interface.
Definition type-id.h:48
a (time, location) pair.
Definition waypoint.h:25
Waypoint-based mobility model.
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.
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)
Every class exported by the ns3 library is enclosed in the ns3 namespace.