diff --git a/doc/leo.rst b/doc/leo.rst index e0f4cd4..53f3e05 100644 --- a/doc/leo.rst +++ b/doc/leo.rst @@ -15,12 +15,10 @@ Model Description The source code for the module lives in the directory ``contrib/leo``. -This module provides a mobility model for LEO satellites, propagation loss -models for satellite to satellite and satellite to ground transmission. It -also includes a simplistic model of the inter-satellite and satellite-ground -channels and the associated network devices. It contains required helpers -to build a LEO satellite network based on configurable parameters or import -mobility data from TLE files. +This module provides a mobility model for LEO satellites, propagation loss models for satellite to satellite and satellite to ground transmission. +It also includes a simplistic model of the inter-satellite and satellite-ground channels and the associated network devices. +It contains helpers to build a LEO satellite network based on configurable parameters or import mobility data from TLE files. + References ========== diff --git a/helper/arp-cache-helper.h b/helper/arp-cache-helper.h index 871c12b..9735937 100644 --- a/helper/arp-cache-helper.h +++ b/helper/arp-cache-helper.h @@ -25,12 +25,34 @@ #include "ns3/applications-module.h" #include "ns3/node-container.h" +/** + * \file + * \ingroup leo + * Declares ArpCacheHelper + */ + namespace ns3 { +/** + * \ingroup leo + * \brief Prepares the ARP cache, so the addresses do not have to be queried + */ class ArpCacheHelper { public: + /** + * \brief Install the addresses of the interfaces into the ARP caches of the devices + * \param devices devices + * \param interfaces interfaces + */ void Install (NetDeviceContainer &devices, Ipv4InterfaceContainer &interfaces) const; + + /** + * \brief Install the addresses of the interfaces into the ARP caches of the devices + * \param deviceSrc devices + * \param deviceDst devices + * \param interfaces interfaces + */ void Install (NetDeviceContainer &devicesSrc, NetDeviceContainer &devicesDst, Ipv4InterfaceContainer &interfaces) const; }; diff --git a/helper/ground-node-helper.h b/helper/ground-node-helper.h index 9fa6eac..8e2a7ab 100644 --- a/helper/ground-node-helper.h +++ b/helper/ground-node-helper.h @@ -29,29 +29,35 @@ #define LEO_GND_RAD_EARTH 6.371e6 /** - * \brief Builds a node container of nodes with constant positions - * - * Adds waypoints from file for each node. + * \file + * \ingroup leo */ namespace ns3 { +/** + * \ingroup leo + * \brief Builds a node container of nodes with constant positions + * Adds waypoints from file for each node. + */ class LeoGndNodeHelper { public: + /// constructor LeoGndNodeHelper (); + /// deconstructor virtual ~LeoGndNodeHelper (); /** - * + * \brief Create a node container with nodes at the positions in file * \param file path to latitude longitude file * \returns a node container containing nodes using the specified attributes */ NodeContainer Install (const std::string &file); /** - * + * \brief Create a node container with uniformly distributed nodes * \param latNodes a number of nodes to in latitude direction * \param lonNodes a number of nodes to in longitude direction * \returns a node container containing nodes using the specified attributes @@ -59,7 +65,7 @@ public: NodeContainer Install (uint32_t latNodes, uint32_t lonNodes); /** - * + * \brief Install two nodes at two locations * \param location1 first location * \param location2 second location * \returns a node container containing nodes using the specified attributes @@ -68,16 +74,17 @@ public: const LeoLatLong &location2); /** - * Set an attribute for each node - * + * \brief Set an attribute for each node * \param name name of the attribute * \param value value of the attribute */ void SetAttribute (std::string name, const AttributeValue &value); private: + /// Fatory for nodes ObjectFactory m_gndNodeFactory; + /// Convert the latitude and longitude to a position on a sphere static Vector3D GetEarthPosition (const LeoLatLong &loc); }; diff --git a/helper/isl-helper.h b/helper/isl-helper.h index 1163e49..92d6d54 100644 --- a/helper/isl-helper.h +++ b/helper/isl-helper.h @@ -27,17 +27,20 @@ #include +/** + * \file + * \ingroup leo + * Declares IslNetDevice + */ + namespace ns3 { class NetDevice; class Node; /** + * \ingroup leo * \brief Build a set of IslNetDevice objects - * - * Normally we eschew multiple inheritance, however, the classes - * PcapUserHelperForDevice and AsciiTraceUserHelperForDevice are - * "mixins". */ class IslHelper : public PcapHelperForDevice, public AsciiTraceHelperForDevice @@ -158,7 +161,6 @@ public: bool explicitFilename); private: - ObjectFactory m_queueFactory; //!< Queue Factory ObjectFactory m_channelFactory; //!< Channel Factory ObjectFactory m_deviceFactory; //!< Device Factory diff --git a/helper/leo-channel-helper.h b/helper/leo-channel-helper.h index 2c4e136..d3df2db 100644 --- a/helper/leo-channel-helper.h +++ b/helper/leo-channel-helper.h @@ -27,38 +27,136 @@ #include +/** + * \file + * \ingroup leo + * Declares LeoChannelHelper + */ + namespace ns3 { /** + * \ingroup leo * \brief Build a channel for transmissions between ns3::LeoMockNetDevice s */ class LeoChannelHelper : public PcapHelperForDevice, public AsciiTraceHelperForDevice { public: + /// constructor LeoChannelHelper (); + + /** + * constructor + * + * \param constellation name of the link parameter preset + */ LeoChannelHelper (std::string constellation); + + /// destructor virtual ~LeoChannelHelper () {}; + /** + * \brief Install the satellites and stations into the channel + * \param satellites satellites + * \param stations ground stations + * \return container of network devices attached to the channel + */ NetDeviceContainer Install (NodeContainer &satellites, NodeContainer &stations); + + /** + * \brief Install the satellites and stations into the channel + * \param satellites satellites + * \param stations ground stations + * \return container of network devices attached to the channel + */ NetDeviceContainer Install (std::vector > &satellites, std::vector > &stations); + + /** + * \brief Install the satellites and stations into the channel + * \param satellites satellites + * \param stations ground stations + * \return container of network devices attached to the channel + */ NetDeviceContainer Install (std::vector &satellites, std::vector &stations); + /** + * \brief Set the type and attributes of the queues of the ground stations + * \param type type of the queue + * \param n1 name of an attribute of the queue + * \param v1 value of an attribute of the queue + * \param n2 name of an attribute of the queue + * \param v2 value of an attribute of the queue + * \param n3 name of an attribute of the queue + * \param v3 value of an attribute of the queue + * \param n4 name of an attribute of the queue + * \param v4 value of an attribute of the queue + */ void SetGndQueue (std::string type, std::string n1 = "", const AttributeValue &v1 = EmptyAttributeValue (), std::string n2 = "", const AttributeValue &v2 = EmptyAttributeValue (), std::string n3 = "", const AttributeValue &v3 = EmptyAttributeValue (), std::string n4 = "", const AttributeValue &v4 = EmptyAttributeValue ()); + /** + * \brief Set the type and attributes of the queues of the satellite devices + * \param type type of the queue + * \param n1 name of an attribute of the queue + * \param v1 value of an attribute of the queue + * \param n2 name of an attribute of the queue + * \param v2 value of an attribute of the queue + * \param n3 name of an attribute of the queue + * \param v3 value of an attribute of the queue + * \param n4 name of an attribute of the queue + * \param v4 value of an attribute of the queue + */ void SetSatQueue (std::string type, std::string n1 = "", const AttributeValue &v1 = EmptyAttributeValue (), std::string n2 = "", const AttributeValue &v2 = EmptyAttributeValue (), std::string n3 = "", const AttributeValue &v3 = EmptyAttributeValue (), std::string n4 = "", const AttributeValue &v4 = EmptyAttributeValue ()); + /** + * \brief Set the type and attributes of the devices of the ground devices + * \param type type of the device + * \param n1 name of an attribute of the device + * \param v1 value of an attribute of the device + * \param n2 name of an attribute of the device + * \param v2 value of an attribute of the device + * \param n3 name of an attribute of the device + * \param v3 value of an attribute of the device + * \param n4 name of an attribute of the device + * \param v4 value of an attribute of the device + */ void SetGndDeviceAttribute (std::string name, const AttributeValue &value); + + /** + * \brief Set the type and attributes of the devices of the satellite devices + * \param type type of the device + * \param n1 name of an attribute of the device + * \param v1 value of an attribute of the device + * \param n2 name of an attribute of the device + * \param v2 value of an attribute of the device + * \param n3 name of an attribute of the device + * \param v3 value of an attribute of the device + * \param n4 name of an attribute of the device + * \param v4 value of an attribute of the device + */ void SetSatDeviceAttribute (std::string name, const AttributeValue &value); + + /** + * \brief Set the type and attributes of the channel + * \param type type of the channel + * \param n1 name of an attribute of the channel + * \param v1 value of an attribute of the channel + * \param n2 name of an attribute of the channel + * \param v2 value of an attribute of the channel + * \param n3 name of an attribute of the channel + * \param v3 value of an attribute of the channel + * \param n4 name of an attribute of the channel + * \param v4 value of an attribute of the channel + */ void SetChannelAttribute (std::string name, const AttributeValue &value); virtual void EnablePcapInternal (std::string prefix, Ptr nd, bool promiscuous, bool explicitFilename); @@ -67,20 +165,44 @@ public: Ptr nd, bool explicitFilename); + /** + * \brief Set the link parameter preset + * \param constellation name of the link parameter preset + */ void SetConstellation (std::string constellation); private: + /// Satellite queues ObjectFactory m_satQueueFactory; + /// Ground station queues ObjectFactory m_gndDeviceFactory; + /// Satellite devices ObjectFactory m_satDeviceFactory; + /// Ground station devices ObjectFactory m_gndQueueFactory; + /// Channel ObjectFactory m_channelFactory; + /// Propagation loss models ObjectFactory m_propagationLossFactory; + // + /// Propagation delay models ObjectFactory m_propagationDelayFactory; + /** + * \brief Set the factory and attributes of the queue + * \param factory queue factory + * \param n1 name of an attribute of the factory + * \param v1 value of an attribute of the factory + * \param n2 name of an attribute of the factory + * \param v2 value of an attribute of the factory + * \param n3 name of an attribute of the factory + * \param v3 value of an attribute of the factory + * \param n4 name of an attribute of the factory + * \param v4 value of an attribute of the factory + */ void SetQueue (ObjectFactory &factory, std::string type, std::string n1, const AttributeValue &v1, @@ -89,6 +211,17 @@ private: std::string n4, const AttributeValue &v4); + /** + * \brief Set the attributes of the link and propagation loss model + * \param eirp EIRP + * \param elevationAngle elevation angle of satellite beam + * \param fspl free space loss + * \param atmosphericLoss atmospheric loss + * \param linkMargin link margin + * \param dataRate data rate + * \param rxGain receiver gain + * \param rxLoss receiver loss + */ void SetConstellationAttributes (double eirp, double elevationAngle, double fspl, diff --git a/helper/leo-input-fstream-container.h b/helper/leo-input-fstream-container.h index 8090068..0ece2bc 100644 --- a/helper/leo-input-fstream-container.h +++ b/helper/leo-input-fstream-container.h @@ -23,32 +23,82 @@ #include "ns3/object.h" #include "ns3/waypoint.h" +/** + * \file + * \ingroup leo + * Declares LeoWaypointInputFileStreamContainer + */ + using namespace std; namespace ns3 { +/** + * \ingroup leo + * \brief Wrapper around a stream of Waypoint + */ class LeoWaypointInputFileStreamContainer : public Object { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); + /// constructor LeoWaypointInputFileStreamContainer (); + /// destructor virtual ~LeoWaypointInputFileStreamContainer (); + /** + * constructor + * + * \param filePath path to waypoints file + * \param lastTime the time until which to read waypoints + */ LeoWaypointInputFileStreamContainer (string filePath, Time lastTime); + /** + * \brief Get next waypoint + * \param [out] next waypoint + * \return true iff there are more waypoints + */ bool GetNextSample (Waypoint &sample); + /** + * \brief Set the path to the waypoint file + * \param path path to the waypoint file + */ void SetFile (const string path); + + /** + * \brief Get the path to the waypoint file + * \return path to the waypoint file + */ string GetFile () const; + /** + * \brief Set the path to the last time slot + * \param lastTime last time slot + */ void SetLastTime (const Time lastTime); + + /** + * \brief Get the last time slot + * \return last time slot + */ Time GetLastTime () const; private: + /// Path to the waypoints file string m_filePath; + + /// Time of the last timestamp Time m_lastTime; + + /// Waypoint file stream ifstream m_input; }; diff --git a/helper/leo-orbit-node-helper.h b/helper/leo-orbit-node-helper.h index aa01444..5880bd5 100644 --- a/helper/leo-orbit-node-helper.h +++ b/helper/leo-orbit-node-helper.h @@ -28,19 +28,27 @@ #include "ns3/leo-orbit.h" /** - * \brief Builds a node container of nodes with LEO positions using a list of - * orbit definitions. - * - * Adds orbits with from a file for each node. + * \file + * \ingroup leo */ namespace ns3 { +/** + * \ingroup leo + * \brief Builds a node container of nodes with LEO positions using a list of + * orbit definitions. + * + * Adds orbits with from a file for each node. + */ class LeoOrbitNodeHelper { public: + /// constructor LeoOrbitNodeHelper (); + + /// destructor virtual ~LeoOrbitNodeHelper (); /** @@ -73,6 +81,7 @@ public: void SetAttribute (std::string name, const AttributeValue &value); private: + /// Factory for nodes ObjectFactory m_nodeFactory; }; diff --git a/helper/nd-cache-helper.h b/helper/nd-cache-helper.h index 110c1a3..178a8a0 100644 --- a/helper/nd-cache-helper.h +++ b/helper/nd-cache-helper.h @@ -25,12 +25,34 @@ #ifndef NDS_CACHE_HELPER_ #define NDS_CACHE_HELPER_ +/** + * \file + * \ingroup leo + * Declares NdCacheHelper + */ + namespace ns3 { +/** + * \ingroup leo + * \brief Neighbor Cache helper fills the neighbor cache + */ class NdCacheHelper { public: + /** + * \brief Fill the cache of devices with addresses + * \param devices devices + * \param interfaces interfaces that have addresses + */ void Install (NetDeviceContainer &devices, Ipv6InterfaceContainer &interfaces) const; + + /** + * \brief Fill the cache of devices with addresses + * \param devicesSrc devices + * \param devicesDst devices + * \param interfaces interfaces that have addresses + */ void Install (NetDeviceContainer &devicesSrc, NetDeviceContainer &devicesDst, Ipv6InterfaceContainer &interfaces) const; }; diff --git a/helper/satellite-node-helper.h b/helper/satellite-node-helper.h index cc1bb15..56afca0 100644 --- a/helper/satellite-node-helper.h +++ b/helper/satellite-node-helper.h @@ -27,38 +27,46 @@ #include "ns3/leo-input-fstream-container.h" /** - * \brief Builds a node container with a waypoint mobility model - * - * Adds waypoints from file for each node. - * The node satId must must correspond to the NORAD id from Celestrack. + * \file + * \ingroup leo */ namespace ns3 { +/** + * \ingroup leo + * \brief Builds a node container with a waypoint mobility model + * + * Adds waypoints from file for each node. + * The node satId must must correspond to the NORAD id from Celestrack. + */ class LeoSatNodeHelper { public: + /// constructor LeoSatNodeHelper (); + /// destructor virtual ~LeoSatNodeHelper (); /** - * + * \brief Install the nodes * \param nodeIds paths to satellite to waypoint files * \returns a node container containing nodes using the specified attributes */ NodeContainer Install (std::vector &wpFiles); /** - * Set an attribute for each node - * + * \brief Set an attribute for each node * \param name name of the attribute * \param value value of the attribute */ void SetAttribute (std::string name, const AttributeValue &value); private: + /// Satellite nodes ObjectFactory m_satNodeFactory; + /// Stream of waypoints LeoWaypointInputFileStreamContainer m_fileStreamContainer; }; diff --git a/model/isl-mock-channel.h b/model/isl-mock-channel.h index 5f024a9..9a5896f 100644 --- a/model/isl-mock-channel.h +++ b/model/isl-mock-channel.h @@ -35,33 +35,51 @@ #include "mock-net-device.h" #include "mock-channel.h" +/** + * \file + * \ingroup leo + * IslMockChannel declaration + */ + namespace ns3 { class MockNetDevice; /** - * \ingroup network - * \defgroup channel Channel - */ -/** - * \ingroup channel - * \brief Simplified inter-satellite channel + * \ingroup leo + * \brief Simplified model of an inter-satellite channel * - * A perfect channel with varariable delay (time-of-flight). + * This channel distributes packets to all attached devies to which the sender has a line-of-sight. + * It is typically used in conjunction with the IslPropagationLossModel and ConstantSpeedPropagationDelay. * */ class IslMockChannel : public MockChannel { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); + /// constructor IslMockChannel (); + /// destructor virtual ~IslMockChannel (); + /** + * \brief Starts a transmission of a packet + * \return true iff the transmission was successful + * \param p the packet to transmit + * \param devId the id of the sender device as an index into the attached + * devices + * \param dst the destination address + * \param txTime the transmission delay of the packet + */ bool TransmitStart (Ptr p, uint32_t devId, Address dst, Time txTime); private: - std::vector > m_link; + std::vector > m_link; ///< Attached devices }; // class MockChannel diff --git a/model/isl-propagation-loss-model.h b/model/isl-propagation-loss-model.h index abdea63..68f24b5 100644 --- a/model/isl-propagation-loss-model.h +++ b/model/isl-propagation-loss-model.h @@ -22,25 +22,44 @@ #include #include +/** + * \file + * \ingroup leo + * + * Declaration of IslPropagationLossModel + */ + #define LEO_EARTH_RAD 6.371009e6 namespace ns3 { +/** + * \ingroup leo + * \brief An approximate model for the propagation loss between any two low + * earth orbit satellites using the line-of-sight + * + */ class IslPropagationLossModel : public PropagationLossModel { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); + /// constructor IslPropagationLossModel (); + /// destructor virtual ~IslPropagationLossModel (); /** - * true if there is at least one intersection of ISL line-of-sight with earth - * (LOS is blocked by earth) + * \brief Check if there is a direc line-of-sight between the two points * - * Assumes earth is sperical. + * Assumes earth is spherical. * - * \param a first node - * \param b second node + * \param a first point + * \param b second point + * \return true iff there is a line-of-sight between the points */ static bool GetLos (Ptr a, Ptr b); private: @@ -56,10 +75,7 @@ private: virtual double DoCalcRxPower (double txPowerDbm, Ptr a, Ptr b) const; - /** - * Subclasses must implement this; those not using random variables - * can return zero - */ + virtual int64_t DoAssignStreams (int64_t stream); }; diff --git a/model/leo-circular-orbit-mobility-model.h b/model/leo-circular-orbit-mobility-model.h index 2a1419a..65be9a0 100644 --- a/model/leo-circular-orbit-mobility-model.h +++ b/model/leo-circular-orbit-mobility-model.h @@ -25,6 +25,13 @@ #include "ns3/mobility-model.h" #include "ns3/nstime.h" +/** + * \file + * \ingroup leo + * + * Declaration of LeoCircularOrbitMobilityModel + */ + #define LEO_EARTH_RAD_KM 6371.0090 #define LEO_EARTH_GM_KM_E10 39.8600436 @@ -41,22 +48,42 @@ class LeoCircularOrbitMobilityModel : public MobilityModel { public: /** - * Register this type with the TypeId system. + * \brief Get the type ID. * \return the object TypeId */ static TypeId GetTypeId (void); + /// constructor LeoCircularOrbitMobilityModel (); + /// destructor virtual ~LeoCircularOrbitMobilityModel (); /** - * km/s + * \brief Gets the speed of the node + * \return the speed in m/s */ double GetSpeed () const; + /** + * \brief Gets the altitude + * \return the altitude + */ double GetAltitude () const; + /** + * \brief Sets the altitude + * \param the altitude + */ void SetAltitude (double h); + /** + * \brief Gets the inclination + * \return the inclination + */ double GetInclination () const; + + /** + * \brief Sets the inclination + * \param the inclination + */ void SetInclination (double incl); private: @@ -105,30 +132,46 @@ private: virtual Vector DoGetVelocity (void) const; /** - * Get the normal vector of the orbital plane + * \brief Get the normal vector of the orbital plane */ Vector3D PlaneNorm () const; + /** + * \brief Gets the distance the satellite has progressed from its original + * position at time t in rad + * + * \param t a point in time + * \return distance in rad + */ double GetProgress (Time t) const; /** - * Advances a satellite by a degrees on the orbital plane + * \brief Advances a satellite by a degrees inside the orbital plane + * \param a angle by which to rotate + * \param x vector to rotate + * \return rotated vector */ Vector3D RotatePlane (double a, const Vector3D &x) const; /** - * Calculate the position at time - * + * \brief Calculate the position at time t * \param t time + * \return position at time t */ Vector CalcPosition (Time t) const; /** - * Calc the latitude depending on simulation time inside ITRF coordinate + * \brief Calc the latitude depending on simulation time inside ITRF coordinate * system + * + * \return latitude */ double CalcLatitude () const; + /** + * \brief Update the internal position of the mobility model + * \return position that will be returned upon next call to DoGetPosition + */ Vector Update (); }; diff --git a/model/leo-circular-orbit-position-allocator.h b/model/leo-circular-orbit-position-allocator.h index 6ed027a..b6914ce 100644 --- a/model/leo-circular-orbit-position-allocator.h +++ b/model/leo-circular-orbit-position-allocator.h @@ -21,32 +21,54 @@ #include "ns3/position-allocator.h" +/** + * \file + * \ingroup leo + * + * Declaration of LeoCircularOrbitAllocator + */ + namespace ns3 { /** - * \brief Allocate pairs of latitude and longitude (offset within orbit) for + * \ingroup leo + * \brief Allocate pairs of longitude and latitude (offset within orbit) for * use in LeoCircularOrbitMobilityModel */ class LeoCircularOrbitAllocator : public PositionAllocator { public: /** - * Register this type with the TypeId system. + * \brief Get the type ID. * \return the object TypeId */ static TypeId GetTypeId (); + /// constructor LeoCircularOrbitAllocator (); + /// destructor virtual ~LeoCircularOrbitAllocator (); + /** + * \brief Gets the next position on the latitude longitude grid + * + * If all positions have been returned once, the first position is returned + * again and so on. + * + * \return the next latitude, longitude pair + */ virtual Vector GetNext (void) const; virtual int64_t AssignStreams (int64_t stream); private: + /// Number of orbits two distribute the satellites on uint64_t m_numOrbits; + /// Number of satellites per orbit uint64_t m_numSatellites; + /// The last orit that has been assigned mutable uint64_t m_lastOrbit; + /// The last position inside the orbit that has been assigned mutable uint64_t m_lastSatellite; }; diff --git a/model/leo-lat-long.h b/model/leo-lat-long.h index ccaec94..37c7f03 100644 --- a/model/leo-lat-long.h +++ b/model/leo-lat-long.h @@ -21,20 +21,47 @@ #include +/** + * \file + * \ingroup leo + * + * Declaration of LeoLatLong + */ + namespace ns3 { +/** + * \brief Wrapper around a pair of latitude and longitude + */ class LeoLatLong { public: + /// constructor LeoLatLong (); + /// destructor LeoLatLong (double latitude, double longitude); virtual ~LeoLatLong(); + /// Latitude double latitude; + /// Longitude double longitude; }; +/** + * \brief Serialize the LeoLatLong instance using a colon as a separator + * \param os stream to serialize into + * \param latLong to serialize + * \return returns the stream + */ std::ostream &operator << (std::ostream &os, const LeoLatLong &latLong); + +/** + * \brief Deserialize the LeoLatLong instance using a colon as a separator + * \param is stream to deserialize from + * \param latLong to deserialize into + * \return returns the stream + */ std::istream &operator >> (std::istream &is, LeoLatLong &latLong); }; diff --git a/model/leo-mock-channel.h b/model/leo-mock-channel.h index 7fb247c..6937e49 100644 --- a/model/leo-mock-channel.h +++ b/model/leo-mock-channel.h @@ -34,29 +34,42 @@ #include "ns3/propagation-loss-model.h" #include "mock-channel.h" +/** + * \file + * \ingroup leo + * + * Declaration of LeoMockChannl + */ + namespace ns3 { /** * \ingroup leo - * \defgroup channel Channel - */ -/** - * \ingroup channel - * \brief Mocked satellite-gateway, satellite-terminal channel types + * \brief Channel between satellite and gateway * + * Delivers packets to all attached devices on opposing site (satellite to + * gateway and vice-versa) + * + * Usually used together with LeoPropagationLossModel and LeoPropagationDelay. */ class LeoMockChannel : public MockChannel { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); + /// constructor LeoMockChannel (); + /// destructor virtual ~LeoMockChannel (); /** * \see MockChannel::TransmitStart * - * A packet is transmitted if the destination is reachable via the beam. + * \brief A packet is transmitted if the destination is reachable via the beam. */ virtual bool TransmitStart (Ptr p, uint32_t devId, Address dst, Time txTime); @@ -71,7 +84,11 @@ private: * type (no sat-sat or ground-ground). */ typedef std::map > DeviceIndex; + + /// Devices that are on the ground (gateways) DeviceIndex m_groundDevices; + + /// Devices that are in space (satellites) DeviceIndex m_satelliteDevices; }; // class MockChannel diff --git a/model/leo-mock-net-device.h b/model/leo-mock-net-device.h index 8a52310..503a44e 100644 --- a/model/leo-mock-net-device.h +++ b/model/leo-mock-net-device.h @@ -21,37 +21,66 @@ #include "mock-net-device.h" +/** + * \file + * \ingroup leo + */ + namespace ns3 { - /** - * \brief A mocked satellite-ground link communication device with a type - */ +/** + * \ingroup leo + * \brief A satellite-ground communication device with a type + */ class LeoMockNetDevice : public MockNetDevice { public: + /** + * \brief Type of the device. Can either be on ground or in space. + */ enum DeviceType { + /// Device is on the ground GND, + /// Device is in space SAT }; + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); + /// constructor LeoMockNetDevice (); + /// destructor virtual ~LeoMockNetDevice () { } + /** + * \brief Get the type of this device + * \return device type + */ DeviceType GetDeviceType () const; + + /** + * \brief Set the type of this device + * \return device type + */ void SetDeviceType (DeviceType deviceType); protected: virtual double DoCalcRxPower (double rxPower) const; private: + /// Device type DeviceType m_deviceType; + /// Receiver loss double m_rxLoss; + /// Receiver gain double m_rxGain; }; diff --git a/model/leo-oneweb-constants.h b/model/leo-oneweb-constants.h index d1af2e0..2e21ce2 100644 --- a/model/leo-oneweb-constants.h +++ b/model/leo-oneweb-constants.h @@ -19,18 +19,17 @@ #ifndef LEO_ONEWEB_CONSTANTS #define LEO_ONEWEB_CONSTANTS +/** + * \file + * \ingroup leo + * + * Declaration of constants + */ + namespace ns3 { /** * \ingroup leo - * \defgroup constants Channel - */ -/** - * \ingroup constants - * \defgroup oneweb - */ -/** - * \ingroup oneweb * \brief Constants for oneweb network estimated from channel parameters * * Source http://systemarchitect.mit.edu/docs/delportillo18b.pdf diff --git a/model/leo-orbit.h b/model/leo-orbit.h index b23f04f..79b8f45 100644 --- a/model/leo-orbit.h +++ b/model/leo-orbit.h @@ -21,21 +21,56 @@ #include "ns3/uinteger.h" +/** + * \file + * \ingroup leo + */ + namespace ns3 { class LeoOrbit; +/** + * \brief Serialize an orbit + * \return the stream + * \param os the stream + * \param [in] orbit is an Orbit + */ std::ostream &operator << (std::ostream &os, const LeoOrbit &orbit); + +/** + * \brief Deserialize an orbit + * \return the stream + * \param is the stream + * \param [out] orbit is the Orbit + */ std::istream &operator >> (std::istream &is, LeoOrbit &orbit); +/** + * \ingroup leo + * \brief Orbit definition + */ class LeoOrbit { public: + /// constructor LeoOrbit (); + /** + * \brief Constructor + * \param a altitude + * \param i inclination + * \param p number planes + * \param s number of satellites in plane + */ LeoOrbit (double a, double i, double p, double s) : alt (a), inc (i), planes (p), sats (s) {} + /// destructor virtual ~LeoOrbit (); + /// Altitude of orbit double alt; + /// Inclination of orbit double inc; + /// Number of planes with that altitude and inclination uint16_t planes; + /// Number of satellites in those planes uint16_t sats; }; diff --git a/model/leo-polar-position-allocator.h b/model/leo-polar-position-allocator.h index 2f0363e..9ab838e 100644 --- a/model/leo-polar-position-allocator.h +++ b/model/leo-polar-position-allocator.h @@ -23,31 +23,45 @@ #define LEO_GND_RAD_EARTH 6.371e6 +/** + * \file + * \ingroup leo + * + * Declaration of LeoPolarPositionAllocator + */ + namespace ns3 { /** - * \brief Allocate pairs of latitude and longitude. + * \ingroup leo + * \brief Allocator for pairs of latitude and longitude. */ class LeoPolarPositionAllocator : public PositionAllocator { public: /** - * Register this type with the TypeId system. + * \brief Get the type ID. * \return the object TypeId */ static TypeId GetTypeId (); + /// constructor LeoPolarPositionAllocator (); + /// desctructor virtual ~LeoPolarPositionAllocator (); virtual Vector GetNext (void) const; virtual int64_t AssignStreams (int64_t stream); private: + /// Number of latitudial positions uint32_t m_latNum; + /// Number of longitudinal positions uint32_t m_lonNum; + /// Current latitudinal position mutable uint32_t m_lat; + /// Current longitudinal position mutable uint32_t m_lon; }; diff --git a/model/leo-propagation-loss-model.h b/model/leo-propagation-loss-model.h index 8658c3b..eeef311 100644 --- a/model/leo-propagation-loss-model.h +++ b/model/leo-propagation-loss-model.h @@ -25,13 +25,30 @@ #define LEO_PROP_EARTH_RAD 6.37101e6 #define LEO_SPEED_OF_LIGHT_IN_AIR 299702458 +/** + * \file + * \ingroup leo + * Declaration of LeoPropagationLossModel + */ + namespace ns3 { +/** + * \ingroup leo + * \brief Propagation loss model for transmissions between satellites and + * gateways + */ class LeoPropagationLossModel : public PropagationLossModel { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); + /// constructor LeoPropagationLossModel (); + /// destructor virtual ~LeoPropagationLossModel (); private: @@ -57,9 +74,7 @@ private: double m_linkMargin; /** - * Returns the Rx Power taking into account only the particular - * PropagationLossModel. - * + * \brief Calculate the Rx Power * \param txPowerDbm current transmission power (in dBm) * \param a the mobility model of the source * \param b the mobility model of the destination @@ -68,15 +83,26 @@ private: virtual double DoCalcRxPower (double txPowerDbm, Ptr a, Ptr b) const; - /** - * Subclasses must implement this; those not using random variables - * can return zero - */ + virtual int64_t DoAssignStreams (int64_t stream); + /** + * \brief Set the elevation angle + * \param angle elevation + */ void SetElevationAngle (double angle); + + /** + * \brief Get the elevation angle + * \return elevation angle + */ double GetElevationAngle () const; + /** + * \brief Get the maximum communication distance for satellite + * \param sat satellite + * \return distance + */ double GetCutoffDistance (const Ptr sat) const; }; diff --git a/model/leo-starlink-constants.h b/model/leo-starlink-constants.h index 2ede8ef..634f6e1 100644 --- a/model/leo-starlink-constants.h +++ b/model/leo-starlink-constants.h @@ -19,18 +19,16 @@ #ifndef LEO_STARLINK_CONSTANTS #define LEO_STARLINK_CONSTANTS +/** + * \file + * \ingroup leo + * Definition of Starlink link constants + */ + namespace ns3 { /** * \ingroup leo - * \defgroup constants Channel - */ -/** - * \ingroup constants - * \defgroup starlink - */ -/** - * \ingroup starlink * \brief Constants for starlink network estimated from channel parameters * * Source http://systemarchitect.mit.edu/docs/delportillo18b.pdf diff --git a/model/leo-telesat-constants.h b/model/leo-telesat-constants.h index c298839..d424163 100644 --- a/model/leo-telesat-constants.h +++ b/model/leo-telesat-constants.h @@ -19,18 +19,16 @@ #ifndef LEO_TELESAT_CONSTANTS #define LEO_TELESAT_CONSTANTS +/** + * \file + * \ingroup leo + * Definition of Telesat link constants + */ + namespace ns3 { /** * \ingroup leo - * \defgroup constants Channel - */ -/** - * \ingroup constants - * \defgroup telesat - */ -/** - * \ingroup starlink * \brief Constants for Telesat network estimated from channel parameters * * Source http://systemarchitect.mit.edu/docs/delportillo18b.pdf diff --git a/model/mock-channel.h b/model/mock-channel.h index 567bb55..93f495e 100644 --- a/model/mock-channel.h +++ b/model/mock-channel.h @@ -34,27 +34,39 @@ #include "ns3/propagation-loss-model.h" #include "mock-net-device.h" +/** + * \file + * \ingroup leo + * Declaration of class MockNetDevice + */ + namespace ns3 { class MockNetDevice; /** - * \ingroup network - * \defgroup channel Channel - */ -/** - * \ingroup channel - * \brief Mocked channel - * + * \ingroup leo + * \brief Base class for LeoMockChannel and IslMockChannel */ class MockChannel : public Channel { public: + /** + * \brief Get the type ID. + * \return the object TypeId + */ static TypeId GetTypeId (void); + /// constructor MockChannel (); + /// destructor virtual ~MockChannel (); + /** + * \brief Get device at index i + * \param i index + * \return pointer to device + */ Ptr GetDevice (std::size_t i) const; /** @@ -71,13 +83,41 @@ public: */ virtual bool Detach (uint32_t deviceId); + /** + * \brief Get number of devices in channel + * \return number of devices + */ std::size_t GetNDevices (void) const; + + /** + * \brief Start to transmit a packet + * + * Subclasses must implement this. + */ virtual bool TransmitStart (Ptr p, uint32_t devId, Address dst, Time txTime) = 0; + /** + * \brief Get the propagation loss model + * \return propagation loss in dBm + */ Ptr GetPropagationLoss (void) const; + + /** + * \brief Set the propagation loss model + * \param model propagation loss + */ void SetPropagationLoss (Ptr model); + /** + * \brief Get the propagation delay model + * \return propagation delay + */ Ptr GetPropagationDelay (void) const; + + /** + * \brief Set the propagation delay model + * \param delay propagation delay + */ void SetPropagationDelay (Ptr delay); protected: @@ -90,25 +130,39 @@ protected: /** * \brief Get the propagation delay associated with this channel + * \param first mobility model + * \param second mobility model + * \param txTime time of the transmission * \returns Propagation time delay */ Time GetPropagationDelay (Ptr first, Ptr second, Time txTime) const; + /** + * \brief Get a device by it's address + * \param addr address of the device + * \return pointer to the device if it is attached to the channel, null otherwise + */ Ptr GetDevice (Address &addr) const; + /** + * \brief Deliver a packet to a destination + * \param p packet + * \param src source of a packet + * \param dst destination of a packet + * \param txTime transmission time of the packet + * \return true iff the transmission has been successful + */ bool Deliver ( Ptr p, Ptr src, Ptr dst, Time txTime); private: + /// All devices that are attached to the channel std::vector > m_link; - /** - * \brief Propagation delay model to be used with this channel - */ + /// Propagation delay model to be used with this channel Ptr m_propagationDelay; - /** - * \brief Propagation loss model to be used with this channel - */ + + /// Propagation loss model to be used with this channel Ptr m_propagationLoss; }; // class MockChannel diff --git a/model/mock-net-device.h b/model/mock-net-device.h index 3889a44..2bee19a 100644 --- a/model/mock-net-device.h +++ b/model/mock-net-device.h @@ -33,6 +33,15 @@ #include "ns3/mac48-address.h" #include "ns3/mobility-model.h" +/** + * \file + * \ingroup leo + * Declares MockNetDevice + * + * Lots of stuff copied and adapted from PointToPointNetDevice and + * CsmaNetDevice + */ + namespace ns3 { template class Queue; @@ -40,6 +49,10 @@ class NetDeviceQueueInterface; class MockChannel; class ErrorModel; +/** + * \ingroup leo + * \brief Network device for use with MockChannel + */ class MockNetDevice : public NetDevice { public: @@ -492,4 +505,4 @@ private: } // namespace ns3 -#endif /* ISL_NET_DEVICE_H */ +#endif /* MOCK_NET_DEVICE_H */ diff --git a/model/orbit.h b/model/orbit.h index 8b729e4..56033ce 100644 --- a/model/orbit.h +++ b/model/orbit.h @@ -21,12 +21,27 @@ #include "ns3/uinteger.h" +/** + * \file + * \ingroup leo + * Declares Orbit + */ + +/** + * \ingroup leo + * \brief Orbit + */ class Orbit { public: + /// constructor Orbit (double a, double i, double p, double s) : alt (a), inc (i), planes (p), sats (s) {} + /// Altitude double alt; + /// Inclination double inc; + /// Number of planes uint16_t planes; + /// Number of satellites in plane uint16_t sats; }; diff --git a/test/ground-node-helper-test-suite.cc b/test/ground-node-helper-test-suite.cc index cdbfc7e..ac09285 100644 --- a/test/ground-node-helper-test-suite.cc +++ b/test/ground-node-helper-test-suite.cc @@ -28,6 +28,18 @@ using namespace ns3; +/** + * \ingroup leo + * \defgroup leo-test LEO module tests + */ + + +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class EmptyGndNodeHelperTestCase : public TestCase { public: @@ -60,6 +72,12 @@ EmptyGndNodeHelperTestCase::DoRun (void) // ------------------------------------------------------------------------- // +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class SomeGndNodeHelperTestCase : public TestCase { public: @@ -92,6 +110,12 @@ SomeGndNodeHelperTestCase::DoRun (void) NS_ASSERT_MSG (mob != Ptr (), "Mobility model is valid"); } +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class GndNodeHelperTestSuite : public TestSuite { public: diff --git a/test/isl-mock-channel-test-suite.cc b/test/isl-mock-channel-test-suite.cc index 8395187..d305a4d 100644 --- a/test/isl-mock-channel-test-suite.cc +++ b/test/isl-mock-channel-test-suite.cc @@ -27,6 +27,18 @@ using namespace ns3; +/** + * \ingroup leo + * \defgroup leo-test LEO module tests + */ + + +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class IslMockChannelTransmitUnknownTestCase : public TestCase { public: @@ -49,6 +61,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class IslMockChannelTransmitKnownTestCase : public TestCase { public: @@ -82,6 +100,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class IslMockChannelTestSuite : public TestSuite { public: diff --git a/test/isl-propagation-test-suite.cc b/test/isl-propagation-test-suite.cc index ff63be9..57c34a7 100644 --- a/test/isl-propagation-test-suite.cc +++ b/test/isl-propagation-test-suite.cc @@ -25,6 +25,18 @@ using namespace ns3; #define EARTH_RAD 6.3781e6 +/** + * \ingroup leo + * \defgroup leo-test LEO module tests + */ + + +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class IslPropagationAngleTestCase1 : public TestCase { public: @@ -42,6 +54,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class IslPropagationAngleTestCase2 : public TestCase { public: @@ -59,6 +77,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class IslPropagationTestSuite : public TestSuite { public: diff --git a/test/isl-test-suite.cc b/test/isl-test-suite.cc index 61a8c6f..468d36c 100644 --- a/test/isl-test-suite.cc +++ b/test/isl-test-suite.cc @@ -30,6 +30,18 @@ using namespace ns3; +/** + * \ingroup leo + * \defgroup leo-test LEO module tests + */ + + +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class IslIcmpTestCase : public TestCase { public: @@ -109,6 +121,12 @@ IslIcmpTestCase::DoRun (void) Simulator::Destroy (); } +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class IslTestSuite : public TestSuite { public: diff --git a/test/leo-anim-test-suite.cc b/test/leo-anim-test-suite.cc index 3b9c359..dbd6725 100644 --- a/test/leo-anim-test-suite.cc +++ b/test/leo-anim-test-suite.cc @@ -30,6 +30,18 @@ using namespace ns3; +/** + * \ingroup leo + * \defgroup leo-test LEO module tests + */ + + +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoAnimTestCase1 : public TestCase { public: @@ -118,10 +130,12 @@ LeoAnimTestCase1::DoRun (void) Simulator::Destroy (); } -// The TestSuite class names the TestSuite, identifies what type of TestSuite, -// and enables the TestCases to be run. Typically, only the constructor for -// this class must be defined -// +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoAnimTestSuite : public TestSuite { public: diff --git a/test/leo-input-fstream-container-test-suite.cc b/test/leo-input-fstream-container-test-suite.cc index acd9a8e..4ac4ac1 100644 --- a/test/leo-input-fstream-container-test-suite.cc +++ b/test/leo-input-fstream-container-test-suite.cc @@ -21,6 +21,18 @@ using namespace ns3; +/** + * \ingroup leo + * \defgroup leo-test LEO module tests + */ + + +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoWaypointFileEmptyTestCase : public TestCase { public: @@ -57,6 +69,12 @@ LeoWaypointFileEmptyTestCase::DoRun (void) NS_TEST_ASSERT_MSG_EQ ((i == 0), true, "Reading waypoints from empty"); } +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoWaypointSomeEntriesTestCase : public TestCase { public: @@ -93,6 +111,12 @@ LeoWaypointSomeEntriesTestCase::DoRun (void) NS_TEST_ASSERT_MSG_EQ ((i > 0), true, "Reading from non-empty stream succeeds"); } +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoWaypointsTestSuite : public TestSuite { public: diff --git a/test/leo-mobility-test-suite.cc b/test/leo-mobility-test-suite.cc index 71112d6..b018fd2 100644 --- a/test/leo-mobility-test-suite.cc +++ b/test/leo-mobility-test-suite.cc @@ -24,6 +24,18 @@ using namespace ns3; NS_LOG_COMPONENT_DEFINE ("LeoMobilityTestSuite"); +/** + * \ingroup leo + * \defgroup leo-test LEO module tests + */ + + +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoMobilityWaypointTestCase : public TestCase { public: @@ -57,6 +69,12 @@ LeoMobilityWaypointTestCase::DoRun (void) NS_TEST_ASSERT_MSG_EQ ((mobility->WaypointsLeft () > 2), true, "Reading waypoints from empty"); } +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoMobilityTestSuite : public TestSuite { public: diff --git a/test/leo-mock-channel-test-suite.cc b/test/leo-mock-channel-test-suite.cc index 990ca6c..06b2092 100644 --- a/test/leo-mock-channel-test-suite.cc +++ b/test/leo-mock-channel-test-suite.cc @@ -27,6 +27,18 @@ using namespace ns3; +/** + * \ingroup leo + * \defgroup leo-test LEO module tests + */ + + +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoMockChannelTransmitUnknownTestCase : public TestCase { public: @@ -49,6 +61,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoMockChannelTransmitKnownTestCase : public TestCase { public: @@ -86,6 +104,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoMockChannelTransmitSpaceGroundTestCase : public TestCase { public: @@ -123,6 +147,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoMockChannelTransmitSpaceSpaceTestCase : public TestCase { public: @@ -160,6 +190,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoMockChannelTransmitGroundGroundTestCase : public TestCase { public: @@ -197,6 +233,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoMockChannelTestSuite : public TestSuite { public: diff --git a/test/leo-orbit-test-suite.cc b/test/leo-orbit-test-suite.cc index 41161e9..b4a8cb4 100644 --- a/test/leo-orbit-test-suite.cc +++ b/test/leo-orbit-test-suite.cc @@ -27,6 +27,18 @@ using namespace ns3; +/** + * \ingroup leo + * \defgroup leo-test LEO module tests + */ + + +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoOrbitSpeedTestCase : public TestCase { public: @@ -42,6 +54,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoOrbitPositionTestCase : public TestCase { public: @@ -58,6 +76,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoOrbitProgressTestCase : public TestCase { public: @@ -85,6 +109,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoOrbitLatitudeTestCase : public TestCase { public: @@ -106,6 +136,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoOrbitOffsetTestCase : public TestCase { public: @@ -127,6 +163,12 @@ private: } }; +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class LeoOrbitTracingTestCase : public TestCase { public: @@ -178,6 +220,12 @@ void LeoOrbitTracingTestCase::CourseChange (std::string context, Ptr (), "Mobility model is valid"); } +/** + * \ingroup leo-test + * \ingroup tests + * + * \brief Unit tests + */ class SatNodeHelperTestSuite : public TestSuite { public: