From 61b6fd7ea1bb9113ea0218888a80fa9d26aad7d4 Mon Sep 17 00:00:00 2001 From: Tim Schubert Date: Sun, 6 Sep 2020 16:15:52 +0200 Subject: [PATCH] Update usage documentation --- doc/leo.h | 28 +++++++ doc/leo.rst | 210 +++++++++++++++++++++++++--------------------------- 2 files changed, 127 insertions(+), 111 deletions(-) create mode 100644 doc/leo.h diff --git a/doc/leo.h b/doc/leo.h new file mode 100644 index 0000000..130e129 --- /dev/null +++ b/doc/leo.h @@ -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 + */ + +#ifndef LEO_H +#define LEO_H + +/** + * \defgroup leo LEO + * + * This section documents the API of the leo module. + */ + +#endif /* LEO_H */ diff --git a/doc/leo.rst b/doc/leo.rst index 9157098..e0f4cd4 100644 --- a/doc/leo.rst +++ b/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 packet) + { + Ptr 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 **********