diff --git a/src/mobility/helper/mobility-helper.cc b/src/mobility/helper/mobility-helper.cc index 82b832967..7f74536b6 100644 --- a/src/mobility/helper/mobility-helper.cc +++ b/src/mobility/helper/mobility-helper.cc @@ -179,6 +179,12 @@ MobilityHelper::InstallAll (void) { Install (NodeContainer::GetGlobal ()); } +/** + * Utility function that rounds |1e-4| < input value < |1e-3| up to +/- 1e-3 + * and value <= |1e-4| to zero + * \param v value to round + * \return rounded value + */ static double DoRound (double v) { diff --git a/src/mobility/helper/mobility-helper.h b/src/mobility/helper/mobility-helper.h index 6ca7dd12c..635dc2b8e 100644 --- a/src/mobility/helper/mobility-helper.h +++ b/src/mobility/helper/mobility-helper.h @@ -262,10 +262,15 @@ public: private: + /** + * Output course change events from mobility model to output stream + * \param stream output stream + * \param mobility mobility model + */ static void CourseChanged (Ptr stream, Ptr mobility); - std::vector > m_mobilityStack; - ObjectFactory m_mobility; - Ptr m_position; + std::vector > m_mobilityStack; //!< Internal stack of mobility models + ObjectFactory m_mobility; //!< Object factory to create mobility objects + Ptr m_position; //!< Position allocator for use in hierarchical mobility model }; } // namespace ns3 diff --git a/src/mobility/helper/ns2-mobility-helper.cc b/src/mobility/helper/ns2-mobility-helper.cc index ce8aa666d..16f966521 100644 --- a/src/mobility/helper/ns2-mobility-helper.cc +++ b/src/mobility/helper/ns2-mobility-helper.cc @@ -64,18 +64,20 @@ NS_LOG_COMPONENT_DEFINE ("Ns2MobilityHelper"); #define NS2_NS_SCH "$ns_" -// Type to maintain line parsed and its values +/** + * Type to maintain line parsed and its values + */ struct ParseResult { - std::vector tokens; // tokens from a line - std::vector ivals; // int values for each tokens - std::vector has_ival; // points if a tokens has an int value - std::vector dvals; // double values for each tokens - std::vector has_dval; // points if a tokens has a double value - std::vector svals; // string value for each token + std::vector tokens; //!< tokens from a line + std::vector ivals; //!< int values for each tokens + std::vector has_ival; //!< points if a tokens has an int value + std::vector dvals; //!< double values for each tokens + std::vector has_dval; //!< points if a tokens has a double value + std::vector svals; //!< string value for each token }; /** - * \brief Keeps last movement schedule. If new movement occurs during + * Keeps last movement schedule. If new movement occurs during * a current one, node stopping must be cancels (stored in a proper * event ID), actually reached point must be calculated and new * velocity must be calculated in accordance with actually reached @@ -83,12 +85,12 @@ struct ParseResult */ struct DestinationPoint { - Vector m_startPosition; // Start position of last movement - Vector m_speed; // Speed of the last movement (needed to derive reached destination at next schedule = start + velocity * actuallyTravelled) - Vector m_finalPosition; // Final destination to be reached before next schedule. Replaced with actually reached if needed. - EventId m_stopEvent; // Event scheduling node's stop. May be canceled if needed. - double m_travelStartTime; // Travel start time is needed to calculate actually traveled time - double m_targetArrivalTime; // When a station arrives to a destination + Vector m_startPosition; //!< Start position of last movement + Vector m_speed; //!< Speed of the last movement (needed to derive reached destination at next schedule = start + velocity * actuallyTravelled) + Vector m_finalPosition; //!< Final destination to be reached before next schedule. Replaced with actually reached if needed. + EventId m_stopEvent; //!< Event scheduling node's stop. May be canceled if needed. + double m_travelStartTime; //!< Travel start time is needed to calculate actually traveled time + double m_targetArrivalTime; //!< When a station arrives to a destination DestinationPoint () : m_startPosition (Vector (0,0,0)), m_speed (Vector (0,0,0)), @@ -99,51 +101,84 @@ struct DestinationPoint }; -// Parses a line of ns2 mobility +/** + * Parses a line of ns2 mobility + */ static ParseResult ParseNs2Line (const std::string& str); -// Put out blank spaces at the start and end of a line +/** + * Put out blank spaces at the start and end of a line + */ static std::string TrimNs2Line (const std::string& str); -// Checks if a string represents a number or it has others characters than digits an point. +/** + * Checks if a string represents a number or it has others characters than digits an point. + */ static bool IsNumber (const std::string& s); -// Check if s string represents a numeric value +/** + * Check if s string represents a numeric value + * \param str string to check + * \param ret numeric value to return + * \return true if string represents a numeric value + */ template static bool IsVal (const std::string& str, T& ret); -// Checks if the value between brackets is a correct nodeId number +/** + * Checks if the value between brackets is a correct nodeId number + */ static bool HasNodeIdNumber (std::string str); -// Gets nodeId number in string format from the string like $node_(4) +/** + * Gets nodeId number in string format from the string like $node_(4) + */ static std::string GetNodeIdFromToken (std::string str); -// Get node id number in int format +/** + * Get node id number in int format + */ static int GetNodeIdInt (ParseResult pr); -// Get node id number in string format +/** + * Get node id number in string format + */ static std::string GetNodeIdString (ParseResult pr); -// Add one coord to a vector position +/** + * Add one coord to a vector position + */ static Vector SetOneInitialCoord (Vector actPos, std::string& coord, double value); -// Check if this corresponds to a line like this: $node_(0) set X_ 123 +/** + * Check if this corresponds to a line like this: $node_(0) set X_ 123 + */ static bool IsSetInitialPos (ParseResult pr); -// Check if this corresponds to a line like this: $ns_ at 1 "$node_(0) setdest 2 3 4" +/** + * Check if this corresponds to a line like this: $ns_ at 1 "$node_(0) setdest 2 3 4" + */ static bool IsSchedSetPos (ParseResult pr); -// Check if this corresponds to a line like this: $ns_ at 1 "$node_(0) set X_ 2" +/** + * Check if this corresponds to a line like this: $ns_ at 1 "$node_(0) set X_ 2" + */ static bool IsSchedMobilityPos (ParseResult pr); -// Set waypoints and speed for movement. +/** + * Set waypoints and speed for movement. + */ static DestinationPoint SetMovement (Ptr model, Vector lastPos, double at, double xFinalPosition, double yFinalPosition, double speed); -// Set initial position for a node +/** + * Set initial position for a node + */ static Vector SetInitialPosition (Ptr model, std::string coord, double coordVal); -// Schedule a set of position for a node +/** + * Schedule a set of position for a node + */ static Vector SetSchedPosition (Ptr model, double at, std::string coord, double coordVal); diff --git a/src/mobility/helper/ns2-mobility-helper.h b/src/mobility/helper/ns2-mobility-helper.h index a9e5a13c5..d2c38a202 100644 --- a/src/mobility/helper/ns2-mobility-helper.h +++ b/src/mobility/helper/ns2-mobility-helper.h @@ -104,15 +104,33 @@ public: template void Install (T begin, T end) const; private: + /** + * \brief a class to hold input objects internally + */ class ObjectStore { public: virtual ~ObjectStore () {} + /** + * Return ith object in store + * \param i index + * \return pointer to object + */ virtual Ptr Get (uint32_t i) const = 0; }; + /** + * Parses ns-2 mobility file to create ns-3 mobility events + * \param store Object store containing ns-3 mobility models + */ void ConfigNodesMovements (const ObjectStore &store) const; + /** + * Get or create a ConstantVelocityMobilityModel corresponding to idString + * \param idString string name for a node + * \param store Object store containing ns-3 mobility models + * \return pointer to a ConstantVelocityMobilityModel + */ Ptr GetMobilityModel (std::string idString, const ObjectStore &store) const; - std::string m_filename; + std::string m_filename; //!< filename of file containing ns-2 mobility trace }; } // namespace ns3 diff --git a/src/mobility/model/box.cc b/src/mobility/model/box.cc index 65d75307a..0667a76fd 100644 --- a/src/mobility/model/box.cc +++ b/src/mobility/model/box.cc @@ -145,12 +145,26 @@ Box::CalculateIntersection (const Vector ¤t, const Vector &speed) const ATTRIBUTE_HELPER_CPP (Box); +/** + * \brief Stream insertion operator. + * + * \param os the stream + * \param box the box + * \returns a reference to the stream + */ std::ostream & operator << (std::ostream &os, const Box &box) { os << box.xMin << "|" << box.xMax << "|" << box.yMin << "|" << box.yMax << "|" << box.zMin << "|" << box.zMax; return os; } +/** + * \brief Stream extraction operator. + * + * \param is the stream + * \param box the box + * \returns a reference to the stream + */ std::istream & operator >> (std::istream &is, Box &box) { diff --git a/src/mobility/model/box.h b/src/mobility/model/box.h index ea62c1c0d..9a4801d47 100644 --- a/src/mobility/model/box.h +++ b/src/mobility/model/box.h @@ -34,6 +34,9 @@ namespace ns3 { class Box { public: + /** + * Enum class to specify sides of a box + */ enum Side { RIGHT, LEFT, diff --git a/src/mobility/model/constant-acceleration-mobility-model.h b/src/mobility/model/constant-acceleration-mobility-model.h index dc69e9971..9de72aff2 100644 --- a/src/mobility/model/constant-acceleration-mobility-model.h +++ b/src/mobility/model/constant-acceleration-mobility-model.h @@ -31,6 +31,10 @@ namespace ns3 { class ConstantAccelerationMobilityModel : public MobilityModel { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); /** * Create position located at coordinates (0,0,0) with @@ -38,6 +42,11 @@ public: */ ConstantAccelerationMobilityModel (); virtual ~ConstantAccelerationMobilityModel (); + /** + * Set the model's velocity and acceleration + * \param velocity the velocity (m/s) + * \param acceleration the acceleration (m/s^2) + */ void SetVelocityAndAcceleration (const Vector &velocity, const Vector &acceleration); private: @@ -45,10 +54,10 @@ private: virtual void DoSetPosition (const Vector &position); virtual Vector DoGetVelocity (void) const; - Time m_baseTime; - Vector m_basePosition; - Vector m_baseVelocity; - Vector m_acceleration; + Time m_baseTime; //!< the base time + Vector m_basePosition; //!< the base position + Vector m_baseVelocity; //!< the base velocity + Vector m_acceleration; //!< the acceleration }; } // namespace ns3 diff --git a/src/mobility/model/constant-position-mobility-model.h b/src/mobility/model/constant-position-mobility-model.h index 679d54464..029546aac 100644 --- a/src/mobility/model/constant-position-mobility-model.h +++ b/src/mobility/model/constant-position-mobility-model.h @@ -32,6 +32,10 @@ namespace ns3 { class ConstantPositionMobilityModel : public MobilityModel { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); /** * Create a position located at coordinates (0,0,0) @@ -44,7 +48,7 @@ private: virtual void DoSetPosition (const Vector &position); virtual Vector DoGetVelocity (void) const; - Vector m_position; + Vector m_position; //!< the constant position }; } // namespace ns3 diff --git a/src/mobility/model/constant-velocity-helper.h b/src/mobility/model/constant-velocity-helper.h index 9c0bf790e..fd68688ae 100644 --- a/src/mobility/model/constant-velocity-helper.h +++ b/src/mobility/model/constant-velocity-helper.h @@ -37,25 +37,67 @@ class ConstantVelocityHelper { public: ConstantVelocityHelper (); + /** + * Create object and set position + * \param position the position vector + */ ConstantVelocityHelper (const Vector &position); + /** + * Create object and set position and velocity + * \param position the position vector + * \param vel the velocity vector + */ ConstantVelocityHelper (const Vector &position, const Vector &vel); + /** + * Set position vector + * \param position Position vector + */ void SetPosition (const Vector &position); + /** + * Get current position vector + * \return Position vector + */ Vector GetCurrentPosition (void) const; + /** + * Get velocity; if paused, will return a zero vector + * \return Velocity vector + */ Vector GetVelocity (void) const; + /** + * Set new velocity vector + * \param vel Velocity vector + */ void SetVelocity (const Vector &vel); + /** + * Pause mobility at current position + */ void Pause (void); + /** + * Resume mobility from current position at current velocity + */ void Unpause (void); + /** + * Update position, if not paused, from last position and time of last update + * \param rectangle 2D bounding rectangle for resulting position; object will not move outside the rectangle + */ void UpdateWithBounds (const Rectangle &rectangle) const; + /** + * Update position, if not paused, from last position and time of last update + * \param bounds 3D bounding box for resulting position; object will not move outside the box + */ void UpdateWithBounds (const Box &bounds) const; + /** + * Update position, if not paused, from last position and time of last update + */ void Update (void) const; private: - mutable Time m_lastUpdate; - mutable Vector m_position; - Vector m_velocity; - bool m_paused; + mutable Time m_lastUpdate; //!< time of last update + mutable Vector m_position; //!< state variable for current position + Vector m_velocity; //!< state variable for velocity + bool m_paused; //!< state variable for paused }; } // namespace ns3 diff --git a/src/mobility/model/constant-velocity-mobility-model.h b/src/mobility/model/constant-velocity-mobility-model.h index 260e09c3e..32143b52b 100644 --- a/src/mobility/model/constant-velocity-mobility-model.h +++ b/src/mobility/model/constant-velocity-mobility-model.h @@ -35,6 +35,10 @@ namespace ns3 { class ConstantVelocityMobilityModel : public MobilityModel { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); /** * Create position located at coordinates (0,0,0) with @@ -54,8 +58,7 @@ private: virtual Vector DoGetPosition (void) const; virtual void DoSetPosition (const Vector &position); virtual Vector DoGetVelocity (void) const; - void Update (void) const; - ConstantVelocityHelper m_helper; + ConstantVelocityHelper m_helper; //!< helper object for this model }; } // namespace ns3 diff --git a/src/mobility/model/gauss-markov-mobility-model.h b/src/mobility/model/gauss-markov-mobility-model.h index 55c688bfd..6a2655277 100644 --- a/src/mobility/model/gauss-markov-mobility-model.h +++ b/src/mobility/model/gauss-markov-mobility-model.h @@ -80,33 +80,44 @@ namespace ns3 { class GaussMarkovMobilityModel : public MobilityModel { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); GaussMarkovMobilityModel (); private: + /** + * Initialize the model and calculate new velocity, direction, and pitch + */ void Start (void); + /** + * Perform a walk operation + * \param timeLeft time until Start method is called again + */ void DoWalk (Time timeLeft); virtual void DoDispose (void); virtual Vector DoGetPosition (void) const; virtual void DoSetPosition (const Vector &position); virtual Vector DoGetVelocity (void) const; virtual int64_t DoAssignStreams (int64_t); - ConstantVelocityHelper m_helper; - Time m_timeStep; - double m_alpha; - double m_meanVelocity; - double m_meanDirection; - double m_meanPitch; - double m_Velocity; - double m_Direction; - double m_Pitch; - Ptr m_rndMeanVelocity; - Ptr m_normalVelocity; - Ptr m_rndMeanDirection; - Ptr m_normalDirection; - Ptr m_rndMeanPitch; - Ptr m_normalPitch; - EventId m_event; - Box m_bounds; + ConstantVelocityHelper m_helper; //!< constant velocity helper + Time m_timeStep; //!< duraiton after which direction and speed should change + double m_alpha; //!< tunable constant in the model + double m_meanVelocity; //!< current mean velocity + double m_meanDirection; //!< current mean direction + double m_meanPitch; //!< current mean pitch + double m_Velocity; //!< current velocity + double m_Direction; //!< current direction + double m_Pitch; //!< current pitch + Ptr m_rndMeanVelocity; //!< rv used to assign avg velocity + Ptr m_normalVelocity; //!< Gaussian rv used to for next velocity + Ptr m_rndMeanDirection; //!< rv used to assign avg direction + Ptr m_normalDirection; //!< Gaussian rv for next direction value + Ptr m_rndMeanPitch; //!< rv used to assign avg. pitch + Ptr m_normalPitch; //!< Gaussian rv for next pitch + EventId m_event; //!< event id of scheduled start + Box m_bounds; //!< bounding box }; } // namespace ns3 diff --git a/src/mobility/model/hierarchical-mobility-model.h b/src/mobility/model/hierarchical-mobility-model.h index bc0866331..bbeb70e6e 100644 --- a/src/mobility/model/hierarchical-mobility-model.h +++ b/src/mobility/model/hierarchical-mobility-model.h @@ -57,6 +57,10 @@ namespace ns3 { class HierarchicalMobilityModel : public MobilityModel { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); HierarchicalMobilityModel (); @@ -98,11 +102,17 @@ private: virtual void DoSetPosition (const Vector &position); virtual Vector DoGetVelocity (void) const; + /** + * Callback for when parent mobility model course change occurs + */ void ParentChanged (Ptr model); + /** + * Callback for when child mobility model course change occurs + */ void ChildChanged (Ptr model); - Ptr m_child; - Ptr m_parent; + Ptr m_child; //!< pointer to child mobility model + Ptr m_parent; //!< pointer to parent mobility model }; diff --git a/src/mobility/model/mobility-model.h b/src/mobility/model/mobility-model.h index a1f1b197d..dcd06b798 100644 --- a/src/mobility/model/mobility-model.h +++ b/src/mobility/model/mobility-model.h @@ -39,6 +39,10 @@ namespace ns3 { class MobilityModel : public Object { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); MobilityModel (); virtual ~MobilityModel () = 0; @@ -128,6 +132,8 @@ private: * The default implementation does nothing but return the passed-in * parameter. Subclasses using random variables are expected to * override this. + * \param start starting stream index + * \return the number of streams used */ virtual int64_t DoAssignStreams (int64_t start); diff --git a/src/mobility/model/position-allocator.h b/src/mobility/model/position-allocator.h index f39f5958f..dda795f8a 100644 --- a/src/mobility/model/position-allocator.h +++ b/src/mobility/model/position-allocator.h @@ -35,6 +35,10 @@ namespace ns3 { class PositionAllocator : public Object { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); PositionAllocator (); virtual ~PositionAllocator (); @@ -67,18 +71,23 @@ public: class ListPositionAllocator : public PositionAllocator { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); ListPositionAllocator (); /** + * \brief Add a position to the list of positions * \param v the position to append at the end of the list of positions to return from GetNext. */ void Add (Vector v); virtual Vector GetNext (void) const; virtual int64_t AssignStreams (int64_t stream); private: - std::vector m_positions; - mutable std::vector::const_iterator m_current; + std::vector m_positions; //!< vector of positions + mutable std::vector::const_iterator m_current; //!< vector iterator }; /** @@ -88,6 +97,10 @@ private: class GridPositionAllocator : public PositionAllocator { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); /** @@ -145,11 +158,11 @@ public: */ double GetMinY (void) const; /** - * \return the x interval between two x-consecutive positions. + * \return the x interval between two consecutive x-positions. */ double GetDeltaX (void) const; /** - * \return the y interval between two y-consecutive positions. + * \return the y interval between two consecutive y-positions. */ double GetDeltaY (void) const; /** @@ -165,13 +178,13 @@ public: virtual Vector GetNext (void) const; virtual int64_t AssignStreams (int64_t stream); private: - mutable uint32_t m_current; - enum LayoutType m_layoutType; - double m_xMin; - double m_yMin; - uint32_t m_n; - double m_deltaX; - double m_deltaY; + mutable uint32_t m_current; //!< currently position + enum LayoutType m_layoutType; //!< currently selected layout type + double m_xMin; //!< minimum boundary on x positions + double m_yMin; //!< minimum boundary on y positions + uint32_t m_n; //!< number of positions to allocate on each row or column + double m_deltaX; //!< x interval between two consecutive x positions + double m_deltaY; //!< y interval between two consecutive y positions }; /** @@ -181,18 +194,30 @@ private: class RandomRectanglePositionAllocator : public PositionAllocator { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); RandomRectanglePositionAllocator (); virtual ~RandomRectanglePositionAllocator (); + /** + * \brief Set the random variable stream object that generates x-positions + * \param x pointer to a RandomVariableStream object + */ void SetX (Ptr x); + /** + * \brief Set the random variable stream object that generates y-positions + * \param y pointer to a RandomVariableStream object + */ void SetY (Ptr y); virtual Vector GetNext (void) const; virtual int64_t AssignStreams (int64_t stream); private: - Ptr m_x; - Ptr m_y; + Ptr m_x; //!< pointer to x's random variable stream + Ptr m_y; //!< pointer to y's random variable stream }; /** @@ -202,20 +227,36 @@ private: class RandomBoxPositionAllocator : public PositionAllocator { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); RandomBoxPositionAllocator (); virtual ~RandomBoxPositionAllocator (); + /** + * \brief Set the random variable stream object that generates x-positions + * \param x pointer to a RandomVariableStream object + */ void SetX (Ptr x); + /** + * \brief Set the random variable stream object that generates y-positions + * \param y pointer to a RandomVariableStream object + */ void SetY (Ptr y); + /** + * \brief Set the random variable stream object that generates z-positions + * \param z pointer to a RandomVariableStream object + */ void SetZ (Ptr z); virtual Vector GetNext (void) const; virtual int64_t AssignStreams (int64_t stream); private: - Ptr m_x; - Ptr m_y; - Ptr m_z; + Ptr m_x; //!< pointer to x's random variable stream + Ptr m_y; //!< pointer to y's random variable stream + Ptr m_z; //!< pointer to z's random variable stream }; /** @@ -226,22 +267,40 @@ private: class RandomDiscPositionAllocator : public PositionAllocator { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); RandomDiscPositionAllocator (); virtual ~RandomDiscPositionAllocator (); + /** + * \brief Set the random variable that generates position radius + * \param theta random variable that represents the radius of a position in a random disc. + */ void SetTheta (Ptr theta); + /** + * \brief Set the random variable that generates position angle + * \param rho random variable that represents the angle (gradients) of a position in a random disc. + */ void SetRho (Ptr rho); + /** + * \param x the X coordinate of the center of the disc + */ void SetX (double x); + /** + * \param y the Y coordinate of the center of the disc + */ void SetY (double y); virtual Vector GetNext (void) const; virtual int64_t AssignStreams (int64_t stream); private: - Ptr m_theta; - Ptr m_rho; - double m_x; - double m_y; + Ptr m_theta; //!< pointer to theta's random variable stream + Ptr m_rho; //!< pointer to rho's random variable stream + double m_x; //!< x coordinate of center of disc + double m_y; //!< y coordinate of center of disc }; @@ -265,6 +324,10 @@ private: class UniformDiscPositionAllocator : public PositionAllocator { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); UniformDiscPositionAllocator (); virtual ~UniformDiscPositionAllocator (); @@ -287,10 +350,10 @@ public: virtual Vector GetNext (void) const; virtual int64_t AssignStreams (int64_t stream); private: - Ptr m_rv; - double m_rho; - double m_x; - double m_y; + Ptr m_rv; //!< pointer to uniform random variable + double m_rho; //!< value of the radius of the disc + double m_x; //!< x coordinate of center of disc + double m_y; //!< y coordinate of center of disc }; } // namespace ns3 diff --git a/src/mobility/model/random-direction-2d-mobility-model.h b/src/mobility/model/random-direction-2d-mobility-model.h index df525a571..05f6cf27d 100644 --- a/src/mobility/model/random-direction-2d-mobility-model.h +++ b/src/mobility/model/random-direction-2d-mobility-model.h @@ -44,14 +44,30 @@ namespace ns3 { class RandomDirection2dMobilityModel : public MobilityModel { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); RandomDirection2dMobilityModel (); private: + /** + * Set a new direction and speed + */ void ResetDirectionAndSpeed (void); + /** + * Pause, cancel currently scheduled event, schedule end of pause event + */ void BeginPause (void); + /** + * Set new velocity and direction, and schedule next pause event + * \param direction (radians) + */ void SetDirectionAndSpeed (double direction); - void InitializeDirectionAndSpeed (void); + /** + * Sets a new random direction and calls SetDirectionAndSpeed + */ void DoInitializePrivate (void); virtual void DoDispose (void); virtual void DoInitialize (void); @@ -60,12 +76,12 @@ private: virtual Vector DoGetVelocity (void) const; virtual int64_t DoAssignStreams (int64_t); - Ptr m_direction; - Rectangle m_bounds; - Ptr m_speed; - Ptr m_pause; - EventId m_event; - ConstantVelocityHelper m_helper; + Ptr m_direction; //!< rv to control direction + Rectangle m_bounds; //!< the 2D bounding area + Ptr m_speed; //!< a random variable to control speed + Ptr m_pause; //!< a random variable to control pause + EventId m_event; //!< event ID of next scheduled event + ConstantVelocityHelper m_helper; //!< helper for velocity computations }; } // namespace ns3 diff --git a/src/mobility/model/random-walk-2d-mobility-model.h b/src/mobility/model/random-walk-2d-mobility-model.h index 52626468e..2b8a7e23f 100644 --- a/src/mobility/model/random-walk-2d-mobility-model.h +++ b/src/mobility/model/random-walk-2d-mobility-model.h @@ -46,6 +46,10 @@ namespace ns3 { class RandomWalk2dMobilityModel : public MobilityModel { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); /** An enum representing the different working modes of this module. */ enum Mode { @@ -59,7 +63,14 @@ private: * \param timeLeft The remaining time of the walk */ void Rebound (Time timeLeft); + /** + * Walk according to position and velocity, until distance is reached, + * time is reached, or intersection with the bounding box + */ void DoWalk (Time timeLeft); + /** + * Perform initialization of the object before MobilityModel::DoInitialize () + */ void DoInitializePrivate (void); virtual void DoDispose (void); virtual void DoInitialize (void); @@ -68,14 +79,14 @@ private: virtual Vector DoGetVelocity (void) const; virtual int64_t DoAssignStreams (int64_t); - ConstantVelocityHelper m_helper; - EventId m_event; - enum Mode m_mode; - double m_modeDistance; - Time m_modeTime; - Ptr m_speed; - Ptr m_direction; - Rectangle m_bounds; + ConstantVelocityHelper m_helper; //!< helper for this object + EventId m_event; //!< stored event ID + enum Mode m_mode; //!< whether in time or distance mode + double m_modeDistance; //!< Change direction and speed after this distance + Time m_modeTime; //!< Change current direction and speed after this delay + Ptr m_speed; //!< rv for picking speed + Ptr m_direction; //!< rv for picking direction + Rectangle m_bounds; //!< Bounds of the area to cruise }; diff --git a/src/mobility/model/random-waypoint-mobility-model.h b/src/mobility/model/random-waypoint-mobility-model.h index e49da9f03..75153b7af 100644 --- a/src/mobility/model/random-waypoint-mobility-model.h +++ b/src/mobility/model/random-waypoint-mobility-model.h @@ -52,22 +52,32 @@ namespace ns3 { class RandomWaypointMobilityModel : public MobilityModel { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); protected: virtual void DoInitialize (void); private: + /** + * Get next position, begin moving towards it, schedule future pause event + */ void BeginWalk (void); + /** + * Begin current pause event, schedule future walk event + */ void DoInitializePrivate (void); virtual Vector DoGetPosition (void) const; virtual void DoSetPosition (const Vector &position); virtual Vector DoGetVelocity (void) const; virtual int64_t DoAssignStreams (int64_t); - ConstantVelocityHelper m_helper; - Ptr m_position; - Ptr m_speed; - Ptr m_pause; - EventId m_event; + ConstantVelocityHelper m_helper; //!< helper for velocity computations + Ptr m_position; //!< pointer to position allocator + Ptr m_speed; //!< random variable to generate speeds + Ptr m_pause; //!< random variable to generate pauses + EventId m_event; //!< event ID of next scheduled event }; } // namespace ns3 diff --git a/src/mobility/model/rectangle.cc b/src/mobility/model/rectangle.cc index 8437a0816..b99cf57ab 100644 --- a/src/mobility/model/rectangle.cc +++ b/src/mobility/model/rectangle.cc @@ -124,12 +124,26 @@ Rectangle::CalculateIntersection (const Vector ¤t, const Vector &speed) co ATTRIBUTE_HELPER_CPP (Rectangle); +/** + * \brief Stream insertion operator. + * + * \param os the stream + * \param rectangle the rectangle + * \returns a reference to the stream + */ std::ostream & operator << (std::ostream &os, const Rectangle &rectangle) { os << rectangle.xMin << "|" << rectangle.xMax << "|" << rectangle.yMin << "|" << rectangle.yMax; return os; } +/** + * \brief Stream extraction operator. + * + * \param is the stream + * \param rectangle the rectangle + * \returns a reference to the stream + */ std::istream & operator >> (std::istream &is, Rectangle &rectangle) { diff --git a/src/mobility/model/rectangle.h b/src/mobility/model/rectangle.h index c46751927..9cc0b46ae 100644 --- a/src/mobility/model/rectangle.h +++ b/src/mobility/model/rectangle.h @@ -34,6 +34,9 @@ namespace ns3 { class Rectangle { public: + /** + * enum for naming sides + */ enum Side { RIGHT, LEFT, @@ -82,14 +85,10 @@ public: */ Vector CalculateIntersection (const Vector ¤t, const Vector &speed) const; - /* The x coordinate of the left bound of the rectangle */ - double xMin; - /* The x coordinate of the right bound of the rectangle */ - double xMax; - /* The y coordinate of the bottom bound of the rectangle */ - double yMin; - /* The y coordinate of the top bound of the rectangle */ - double yMax; + double xMin; //!< The x coordinate of the left bound of the rectangle + double xMax; //!< The x coordinate of the right bound of the rectangle + double yMin; //!< The y coordinate of the bottom bound of the rectangle + double yMax; //!< The y coordinate of the top bound of the rectangle }; std::ostream &operator << (std::ostream &os, const Rectangle &rectangle); diff --git a/src/mobility/model/steady-state-random-waypoint-mobility-model.h b/src/mobility/model/steady-state-random-waypoint-mobility-model.h index 8c34212ba..84228660d 100644 --- a/src/mobility/model/steady-state-random-waypoint-mobility-model.h +++ b/src/mobility/model/steady-state-random-waypoint-mobility-model.h @@ -55,42 +55,62 @@ namespace ns3 { class SteadyStateRandomWaypointMobilityModel : public MobilityModel { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); SteadyStateRandomWaypointMobilityModel (); protected: virtual void DoInitialize (void); private: + /** + * Configure random variables based on attributes; calculate the steady + * state probability that node is initially paused; schedule either end + * of pause time or initial motion of the node. + */ void DoInitializePrivate (void); + /** + * Use provided destination to calculate travel delay, and schedule a + * Start() event at that time. + * \param destination the destination to move to + */ void SteadyStateBeginWalk (const Vector &destination); + /** + * Start a pause period and schedule the ending of the pause + */ void Start (void); + /** + * Start a motion period and schedule the ending of the motion + */ void BeginWalk (void); virtual Vector DoGetPosition (void) const; virtual void DoSetPosition (const Vector &position); virtual Vector DoGetVelocity (void) const; virtual int64_t DoAssignStreams (int64_t); - ConstantVelocityHelper m_helper; - double m_maxSpeed; - double m_minSpeed; - Ptr m_speed; - double m_minX; - double m_maxX; - double m_minY; - double m_maxY; - double m_z; - Ptr m_position; - double m_minPause; - double m_maxPause; - Ptr m_pause; - EventId m_event; - bool alreadyStarted; - Ptr m_x1_r; - Ptr m_y1_r; - Ptr m_x2_r; - Ptr m_y2_r; - Ptr m_u_r; - Ptr m_x; - Ptr m_y; + ConstantVelocityHelper m_helper; //!< helper for velocity computations + double m_maxSpeed; //!< maximum speed value (m/s) + double m_minSpeed; //!< minimum speed value (m/s) + Ptr m_speed; //!< random variable for speed values + double m_minX; //!< minimum x value of traveling region (m) + double m_maxX; //!< maximum x value of traveling region (m) + double m_minY; //!< minimum y value of traveling region (m) + double m_maxY; //!< maximum y value of traveling region (m) + double m_z; //!< z value of traveling region + Ptr m_position; //!< position allocator + double m_minPause; //!< minimum pause value (s) + double m_maxPause; //!< maximum pause value (s) + Ptr m_pause; //!< random variable for pause values + EventId m_event; //!< current event ID + bool alreadyStarted; //!< flag for starting state + Ptr m_x1_r; //!< rv used in rejection sampling phase + Ptr m_y1_r; //!< rv used in rejection sampling phase + Ptr m_x2_r; //!< rv used in rejection sampling phase + Ptr m_y2_r; //!< rv used in rejection sampling phase + Ptr m_u_r; //!< rv used in step 5 of algorithm + Ptr m_x; //!< rv used for position allocator + Ptr m_y; //!< rv used for position allocator }; } // namespace ns3 diff --git a/src/mobility/model/waypoint-mobility-model.h b/src/mobility/model/waypoint-mobility-model.h index dcc77cab1..a16f4cd81 100644 --- a/src/mobility/model/waypoint-mobility-model.h +++ b/src/mobility/model/waypoint-mobility-model.h @@ -86,6 +86,10 @@ namespace ns3 { class WaypointMobilityModel : public MobilityModel { public: + /** + * Register this type with the TypeId system. + * \return the object TypeId + */ static TypeId GetTypeId (void); /** @@ -127,6 +131,9 @@ public: private: friend class ::WaypointMobilityModelNotifyTest; // To allow Update() calls and access to m_current + /** + * Update the underlying state corresponding to the stored waypoints + */ void Update (void) const; /** * \brief The dispose method. @@ -154,7 +161,14 @@ private: * \brief This variable is set to true if there are no waypoints in the std::deque */ bool m_first; + /** + * \brief If true, course change updates are only notified when position + * is calculated. + */ bool m_lazyNotify; + /** + * \brief If true, calling SetPosition with no waypoints creates a waypoint + */ bool m_initialPositionIsWaypoint; /** * \brief The double ended queue containing the ns3::Waypoint objects diff --git a/src/mobility/model/waypoint.cc b/src/mobility/model/waypoint.cc index f4254c165..e493fe5a7 100644 --- a/src/mobility/model/waypoint.cc +++ b/src/mobility/model/waypoint.cc @@ -34,11 +34,26 @@ Waypoint::Waypoint () { } +/** + * \brief Stream insertion operator. + * + * \param os the stream + * \param waypoint the waypoint + * \returns a reference to the stream + */ std::ostream &operator << (std::ostream &os, const Waypoint &waypoint) { os << waypoint.time.GetSeconds () << "$" << waypoint.position; return os; } + +/** + * \brief Stream extraction operator. + * + * \param is the stream + * \param waypoint the waypoint + * \returns a reference to the stream + */ std::istream &operator >> (std::istream &is, Waypoint &waypoint) { char separator;