mirror of
https://gitlab.ibr.cs.tu-bs.de/tschuber/ns-3-leo.git
synced 2025-06-08 01:53:58 +02:00
Update usage documentation
This commit is contained in:
Tim Schubert
parent
1f19d41668
commit
61b6fd7ea1
2 changed files with 127 additions and 111 deletions
28
doc/leo.h
Normal file
28
doc/leo.h
Normal 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 */
|
||||
210
doc/leo.rst
210
doc/leo.rst
|
|
@ -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
|
||||
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
|
||||
==========
|
||||
|
||||
|
|
@ -48,80 +31,103 @@ Usage
|
|||
*****
|
||||
|
||||
Interaction with the mobility model is mostly at configuration time using the
|
||||
associated helpers. At simulation time, various parts of |ns3| may interact
|
||||
associated helpers. At simulation time, various parts of |ns3| may interact
|
||||
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
|
||||
|
||||
$ ./waf --run "leo-orbit \
|
||||
.. sourcecode:: bash
|
||||
|
||||
$ ./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.
|
||||
|
||||
.. sourcode::bash
|
||||
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.
|
||||
|
||||
.. 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
|
||||
|
||||
$ ./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.
|
||||
.. sourcecode:: bash
|
||||
|
||||
$ ./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
|
||||
**********
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue