dadada/ns-3-leo
dadada/ns-3-leo
1
0
Fork 0
mirror of https://gitlab.ibr.cs.tu-bs.de/tschuber/ns-3-leo.git synced 2025-06-08 01:53:58 +02:00
Code Issues Releases Wiki Activity

Update usage documentation

Browse source
This commit is contained in:
Tim Schubert 2020-09-06 16:15:52 +02:00
parent 1f19d41668
commit 61b6fd7ea1
2 changed files with 127 additions and 111 deletions
Download patch file Download diff file Expand all files Collapse all files

28
doc/leo.h Normal file
View file

@ -0,0 +1,28 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation;
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* Author: Tim Schubert <ns-3-leo@timschubert.net>
*/
#ifndef LEO_H
#define LEO_H
/**
* \defgroup leo LEO
*
* This section documents the API of the leo module.
*/
#endif /* LEO_H */

200
doc/leo.rst
View file

@ -1,5 +1,5 @@
Example Module Documentation
----------------------------
Low Earth Orbit Mobility
------------------------
.. include:: replace.txt
.. highlight:: cpp
@ -13,32 +13,15 @@ Example Module Documentation
Model Description
*****************
The source code for the new module lives in the directory ``contrib/leo``.
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 also contains required helpers
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.
Design
======
The models do not depend on each other, with the exception of
``LeoMockChannel``, which requires the participating devices to be
``MockNetDevices``, and may be used outside of the context of this module.
Scope and Limitations
=====================
There are some limitations to the precision of the model: The circular movement
model does not take into the earths gravitational model or amospheric drag. The
link parameters are only modelled using their statistical estimates. There is
currently no support for multiple antennas per link. MAC layer behaviour or
frequency coordination are currently not modelled, but any existing MAC model
may be combined with the models provided by this module.
References
==========
@ -53,75 +36,98 @@ with the mobility model and propagation loss models to obtain the position,
heading, speed of nodes and the path loss, including if a link can be
established between two nodes.
Topologies may be constructed using ``MockDevice``s and ``MockChannels``.
Topologies may be constructed using ``MockDevice`` and ``MockChannel``.
Helpers
=======
Since the configuration of these large network can be a large task with many
parameters and configuration steps, the helpers try to collect common
Since the configuration of these large networks can be complicated, the helpers try to collect common
configutation steps, such as setting up the LEO and ISL channels and adding
devices with the correct mobility patterns based on the constellation.
A typical usage for the position allocator and the mobility model would be through ``MobilityHelper``.
.. sourcecode:: cpp
MobilityHelper mobility;
mobility.SetPositionAllocator ("ns3::LeoCircularOrbitPostionAllocator",
"NumOrbits", IntegerValue (32),
"NumSatellites", IntegerValue (50));
mobility.SetMobilityModel ("ns3::LeoCircularOrbitMobilityModel",
"Altitude", DoubleValue (1200),
"Inclination", DoubleValue (40),
"Precision", TimeValue (Minutes (1)));
To configure the ground nodes, positions can be pre-defined and loaded into the simulation or generated using `PolarGridPositionAllocator`.
Ground stations may be installed using the ``LeoGndStationHelper``.
It provides methods for installing ground station by their polar coordinates, a uniform grid of polar coordinates or it can also load a CSV file containing a list of such coordinates.
The following exaple configures a 20 by 20 grid and places a source inside Middle Europe and a sink on the east cost of North America.
.. sourcecode:: cpp
LeoGndNodeHelper ground;
NodeContainer stations = ground.Install ("contrib/leo/data/ground-stations/usa-60.waypoints");
NodeContainer stations = ground.Install (20, 20);
MobilityHelper mobility;
LeoLatLong source (51.399, 10.536);
LeoLatLong destination (40.76, -73.96);
NodeContainer users = ground.Install (source, destination);
stations.Add (users);
The satellite orbits can be configured using the ``LeoOrbitNodeHellper``.
It sets the positions of the satellites according to their orbit definitions, which can either be provided using a CSV file or directly.
.. sourcecode:: cpp
mobility.SetPositionAllocator ("ns3::PolarGridPositionAllocator",
"MinX", DoubleValue (0.0),
"MinY", DoubleValue (0.0),
"DeltaX", DoubleValue (5.0),
"DeltaY", DoubleValue (10.0),
"GridWidth", UintegerValue (3),
"LayoutType", StringValue ("RowFirst"));
LeoOrbitNodeHelper orbit;
NodeContainer satellites;
The ISL network can be configured using `IslHelper`
// using CSV file
satellites = orbit.Install ("orits.csv");
.. sourcecode:: cpp
// defining orbits in code (height, inclination, satellites per plane, number of planes)
satellites = orbit.Install ({ LeoOrbit (1200, 20, 32, 16),
LeoOrbit (1180, 30, 12, 10) });
IslHelper islCh;
islCh.SetDeviceAttribute ("DataRate", StringValue ("1Gbps"));
islCh.SetChannelAttribute ("PropagationDelay", StringValue ("ns3::ConstantSpeedPropagationDelayModel"));
islCh.SetChannelAttribute ("PropagationLoss", StringValue ("ns3::IslPropagationLossModel"));
islNet = islCh.Install (satellites);
To select the parameters for a pre-defined constellation and construct a LEO
channel from it us the `LeoChannelHelper` and connect the satellites and ground
stations to it.
Afterwards, the channels between the satellites and betweeen the ground stations and the satellites need to be configured.
This can be acchieved using the ``LeoChannelHelper`` and the ``IslChannelHelper``.
.. sourcecode:: cpp
LeoChannelHelper utCh;
utCh.SetConstellation ("StarlinkUser");
utNet = utCh.Install (satellites, stations);
NetDeviceContainer utNet = utCh.Install (satellites, stations);
IslHelper islCh;
islCh.SetDeviceAttribute ("DataRate", StringValue ("1Gbps"));
NetDeviceContainer islNet = islCh.Install (satellites);
Afterwards, the ground stations should be connected to the satellites using a ``LeoMockChannel`` and the satellites should be connected to each other using ``IslMockChnnel``.
Please see their documentation to find additional parameters that can be configured using the helpers.
Output
======
The module itself does only provide trace sources for the transmission /
droppping of packets using ``MockNetDevice``. All other trace infomation
originating from this module is written to the trace sources associated with
the parent models (such as ``MobilityModel``).
The mobility of individual satellites can be traced using the respective trace sources of ``MobilityModel``.
To see what is going on inside the network, you may choose to configure trace sinks for the trace sources of network ``MockNetDevice``, ``IslPropagationLossModel``, ``LeoPropagationLossModel`` and ``MockChannel``.
Following example shows how to set up a trace sink to log dropped transmissions.
.. sourcecode:: cpp
uint64_t countBytes = 0;
static void
TracePacket (std::string context, Ptr<const Packet> packet)
{
Ptr<Packet> p = packet->Copy ();
std::cout << Simulator::Now () << ":" << context << ":" << p->GetUid () << ":" << (countBytes += p->GetSerializedSize ()) << std::endl;
}
int main (int argc, char *argv[])
{
// [...]
Config::Connect ("/NodeList/*/DeviceList/*/$ns3::MockNetDevice/MacTxDrop",
MakeCallback (&TracePacket));
Config::Connect ("/NodeList/*/DeviceList/*/$ns3::MockNetDevice/PhyTxDrop",
MakeCallback (&TracePacket));
Config::Connect ("/NodeList/*/DeviceList/*/$ns3::MockNetDevice/MacRxDrop",
MakeCallback (&TracePacket));
Config::Connect ("/NodeList/*/DeviceList/*/$ns3::MockNetDevice/PhyRxDrop",
MakeCallback (&TracePacket));
// [...]
}
It can also be quite useful to explore the network traffic using external tools like Wireshark.
PCAP output can be enabled on all network devices using the ``PcapHelper``
.. sourcecode:: cpp
utCh.EnablePcapAll ("my-user-netdev", false);
islCh.EnablePcapAll ("my-isl-netdev", false);
Examples
========
@ -129,66 +135,48 @@ Examples
leo-circlular-orbit
###################
The program configures a ``LeoCircularOrbitMobilityModel`` using the provided
parameters and logs all course changes to a CSV file. The file format for the
orbit configuration file is ``altitude in km,inclination in deg,number of
planes,number of satellites per plane``. The duration is given in seconds.
The program configures a ``LeoCircularOrbitMobilityModel`` and traces the positions of the satellites during the simulation.
.. sourcode::bash
.. sourcecode:: bash
$ ./waf --run "leo-orbit \
$ ./waf --run "leo-orbit
--orbitFile=contrib/leo/data/orbits/starlink.csv \
--duration=360.0 \
--precision=1.0 \
--traceFile=out.csv"
--duration=1000 \
--traceFile=os.log"
leo-delay
#########
The delay tracing example uses `UdpServer` and `UdpClient` to measure the delay
and packet loss on between two nodes. The source and destination locations are
given as pairs of longitude and latitude.
The delay tracing example uses ``UdpServer`` and ``UdpClient`` to measure the delay and packet loss on between two nodes.
The source and destination locations are given as pairs of longitude and latitude.
.. sourcode::bash
.. sourcecode:: bash
$ ./waf --run "leo-delay \
--destOnly=true \
--orbitFile=contrib/leo/data/orbits/starlink.csv \
--traceFile=out.csv
--precision=1.0 \
--duration=360.0 \
--numGws=120 \
--source=54.4:77.1 \
--destination=40.58:-74.97 \
--islRate=1Gbps \
--constellation="StarlinkGateway" \
--interval=1 \
--ttlThresh=30 \
--routeTimeout=0.25"
--constellation=StarlinkGateway \
--traceFile=dsai.log \
--islRate=2Gbps \
--islEnabled=true \
--duration=1000"
leo-throughput
##############
The throughput tracing example uses ``BulSendHelper`` and ``PacketSinkHelper``
to measure the throughput inbetween two nodes. The throughput and the TCP
parameters are logged to the `traceFile`.
The throughput tracing example uses ``BulkSendHelper`` and ``PacketSinkHelper``
to measure the throughput inbetween two nodes. The throughput is logged to the `traceFile`.
.. sourcode::bash
.. sourcecode:: bash
$ ./waf --run leo-throughput \
--orbitsFile=orbits.csv \
--groundFile=ground-stations.csv \
--traceFile=tcp-trace.csv \
--source=54.4,77.1 \
--destination=-10.0,25.8 \
--islRate=1Gbps \
--constellation="StarlinkGateway" \
--duration=10.0 \
--maxBytes=3GB
Troubleshooting
===============
Add any tips for avoiding pitfalls, etc.
$ ./waf --run "leo-bulk-send \
--destOnly=true \
--orbitFile=contrib/leo/data/orbits/telesat.csv \
--constellation=TelesatGateway \
--traceFile=btai.log \
--islRate=2Gbps \
--islEnabled=true \
--duration=1000"
Validation
**********