F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

updated user documentation

Browse Source
This commit is contained in:
Nicola Baldo
2011-05-27 18:13:52 +02:00
parent cd2c5b8531
commit 1c3edc5d44
4 changed files with 252 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/lte/doc/source/lte-design.rst
View File

@@ -2,7 +2,7 @@
++++++++++++++++++++++++++
LTE Design Documentation
Design Documentation
++++++++++++++++++++++++++

4
src/lte/doc/source/lte-references.rst
View File

@@ -35,3 +35,7 @@
.. [R1-081483] 3GPP R1-081483 "Conveying MCS and TB size via PDCCH" http://www.3gpp.org/ftp/tsg_ran/WG1_RL1/TSGR1_52b/Docs/R1-081483.zip
.. [FFAPI] FemtoForum LTE MAC Scheduler Interface Specification v1.11 http://www.femtoforum.org/femto/technical.php
.. [ns3tutorial] The ns-3 Tutorial http://www.nsnam.org/docs/tutorial/html/
.. [ns3manual] The ns-3 Tutorial http://www.nsnam.org/docs/manual/html/

2
src/lte/doc/source/lte-testing.rst
View File

@@ -2,7 +2,7 @@
+++++++++++++++++++++++++++
LTE Testing Documentation
Testing Documentation
+++++++++++++++++++++++++++

291
src/lte/doc/source/lte-user.rst
View File

@@ -1,68 +1,269 @@
.. include:: replace.txt
+++++++++++++++++++++++++
LTE User Documentation
+++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++
User Documentation
+++++++++++++++++++++++++++++++++
Background
**********
We assume the reader is already familiar with how to use the ns-3
simulator to run generic simulation programs. If this is not the case,
we strongly recommend the reader to consult [ns3tutorial]_.
Usage
*****
Usage Overview
**************
Users interact with the LTE model through the LENA helper API and through the publicly visible methods of the model. The helper API is defined in ``src/lte/helper/lena-helper.h``.
The ns-3 LTE model is a software library that allows the simulation of
LTE networks. The process of performing such simulations typically involves the following
steps:
The ``src/lte/examples/`` directory contains some basic examples that shows how to set up the LTE model in order to simulate an EUTRA downlink transmission.
1. *Define the scenario* to be simulated
2. *Write a simulation program* that recreates the desired scenario
topology/architecture. This is done accessing the ns-3 LTE model
libraryusing the ``ns3::LenaHelper`` API defined in ``src/lte/helper/lena-helper.h``.
3. *Specify configuration parameters* of the objects that are being
used for the simulation. This can be done using input files (via the
``ns3::ConfigStore``) or directly within the simulation program.
4. *Configure the desired output* to be produced by the simulator
5. *Run* the simulation.
Example simulation program
--------------------------
``src/lte/examples/lena-first-sim.cc`` shows how to build a simple but complete simulation with one LTE eNB and one LTE UE. The detail explanation of the code follows:
#. Declare the helper. This helper keeps together all the LTE components::
LenaHelper lena;
All these aspects will be explained in the following sections by means
of practical examples.
#. Enable the logs in the LTE components::
lena.EnableLogComponents ();
Basic simulation program
------------------------
Here is the minimal simulation program that is needed to do an LTE simulation.
.. highlight:: none
#. Initial boilerplate::
#include "ns3/core-module.h"
#include "ns3/network-module.h"
#include "ns3/mobility-module.h"
#include "ns3/lte-module.h"
using namespace ns3;
int main (int argc, char *argv[])
{
#. Create eNB and UE. They are created in its own node container::
#. Create a LenaHelper object::
NodeContainer enbNodes;
NodeContainer ueNodes;
enbNodes.Create (1);
ueNodes.Create (1);
Ptr<LenaHelper> lena = CreateObject<LenaHelper> ();
This will instantiate some common
objects (e.g., the Channel object) and provide the methods to add
eNBs and UEs and configure them.
#. Create Node objects for the eNB(s) and the UEs::
NodeContainer enbNodes;
enbNodes.Create (1);
NodeContainer ueNodes;
ueNodes.Create (2);
Note that the above Node instances at this point still don't have
an LTE protocol stack installed; they're just empty nodes.
#. Configure the Mobility model for all the nodes::
MobilityHelper mobility;
mobility.SetMobilityModel ("ns3::ConstantPositionMobilityModel");
mobility.Install (enbNodes);
mobility.SetMobilityModel ("ns3::ConstantPositionMobilityModel");
mobility.Install (ueNodes);
The above will place all nodes at the coordinates (0,0,0). Please
refer to the documentation of the ns-3 mobility model for how to
set your own position or configure node movement.
#. Install an LTE protocol stack on the eNB(s)::
NetDeviceContainer enbDevs;
enbDevs = lena->InstallEnbDevice (enbNodes);
#. Install an LTE protocol stack on the UEs::
NetDeviceContainer ueDevs;
ueDevs = lena->InstallUeDevice (ueNodes);
#. Install mobility models to eNB and UE. This has to be done before devices are created and installed::
MobilityHelper mobility;
mobility.SetMobilityModel ("ns3::ConstantPositionMobilityModel");
mobility.Install (enbNodes);
mobility.SetMobilityModel ("ns3::ConstantPositionMobilityModel");
mobility.Install (ueNodes);
#. Create devices and install them to the eNB and UE::
NetDeviceContainer enbDevs;
NetDeviceContainer ueDevs;
enbDevs = lena.InstallEnbDevice (enbNodes);
ueDevs = lena.InstallUeDevice (ueNodes);
#. Attach a UE to a eNB. It will also create a RRC connection between them and configure the UE::
lena.Attach (ueDevs, enbDevs.Get (0));
#. Attach the UEs to an eNB. This will configure each UE according to
the eNB configuration, and create an RRC connection between them::
lena->Attach (ueDevs, enbDevs.Get (0));
#. Activate an EPS Bearer including the setup of the Radio Bearer between an eNB and its attached UE::
enum EpsBearer::Qci q = EpsBearer::GBR_CONV_VOICE;
EpsBearer bearer (q);
lena.ActivateEpsBearer (ueDevs, bearer);
enum EpsBearer::Qci q = EpsBearer::GBR_CONV_VOICE;
EpsBearer bearer (q);
lena->ActivateEpsBearer (ueDevs, bearer);
In the current version of the ns-3 LTE model, the activation of an
EPS Bearer will also activate two saturation traffic generators for
that bearer, one in uplink and one in downlink.
#. Set the stop time::
Simulator::Stop (Seconds (0.005));
This is needed otherwise the simulation will last forever, because
(among others) the start-of-subframe event is scheduled repeatedly, and the
ns-3 simulator scheduler will hence never run out of events.
#. Run the simulation::
Simulator::Run ();
#. Cleanup and exit::
Simulator::Destroy ();
return 0;
}
For how to compile and run simulation programs, please refer to [ns3tutorial]_.
Configuration of LTE model parameters
--------------------------------------
All the relevant LTE model parameters are managed through the ns-3
attribute system. Please refer to the [ns3tutorial]_ and [ns3manual]_
for detailed information on all the possible methods to do it
(environmental variables, C++ API, GtkConfigStore...).
In the following, we just briefly summarize
how to do it using input files together with the ns-3 ConfigStore.
First of all, you need to put the following in your simulation
program, right after ``main ()`` starts::
CommandLine cmd;
cmd.Parse (argc, argv);
ConfigStore inputConfig;
inputConfig.ConfigureDefaults ();
// parse again so you can override default values from the command line
cmd.Parse (argc, argv);
for the above to work, make sure you also ``#include "ns3/config-store.h"``.
Now create a text file named (for example) ``input-defaults.txt``
specifying the new default values that you want to use for some attributes::
default ns3::LenaHelper::Scheduler "ns3::PfFfMacScheduler"
default ns3::LenaHelper::PropagationModel "ns3::FriisSpectrumPropagationLossModel"
default ns3::LteEnbNetDevice::UlBandwidth "25"
default ns3::LteEnbNetDevice::DlBandwidth "25"
default ns3::LteEnbNetDevice::DlEarfcn "100"
default ns3::LteEnbNetDevice::UlEarfcn "18100"
default ns3::LteUePhy::TxPower "10"
default ns3::LteUePhy::NoiseFigure "9"
default ns3::LteEnbPhy::TxPower "30"
default ns3::LteEnbPhy::NoiseFigure "5"
Supposing your simulation program is called
``src/lte/examples/lte-sim-with-input``, you can now pass these
settings to the simulation program in the following way::
./waf --command-template="%s --ns3::ConfigStore::Filename=input-defaults.txt --ns3::ConfigStore::Mode=Load --ns3::ConfigStore::FileFormat=RawText" --run src/lte/examples/lte-sim-with-input
Furthermore, you can generate a template input file with the following
command::
./waf --command-template="%s --ns3::ConfigStore::Filename=input-defaults.txt --ns3::ConfigStore::Mode=Save --ns3::ConfigStore::FileFormat=RawText" --run src/lte/examples/lte-sim-with-input
note that the above will put in the file ``input-defaults.txt`` *all*
the default values that are registered in your particular build of the
simulator, including lots of non-LTE attributes.
Simulation Output
-----------------
The ns-3 LTE model currently supports the output to file of both MAC and RLC
level Key Performance Indicators (KPIs). You can enable it in the following way::
Ptr<LenaHelper> lena = CreateObject<LenaHelper> ();
// configure all the simulation scenario here...
lena->EnableMacTraces ();
lena->EnableRlcTraces ();
Simulator::Run ();
RLC KPIs are calculated over a time interval and stored on two ASCII
files, one for uplink and one for downlink. The time interval duration
and the name of the files can be controlled using the attributes
``ns3::RlcStatsCalculator::EpochDuration``,
``ns3::RlcStatsCalculator::DlOutputFilename`` and
``ns3::RlcStatsCalculator::UlOutputFilename``.
The content of the columns of these files is the following (the same
for uplink and downlink):
1. start time of measurement interval in seconds since the start of simulation
2. end time of measurement interval in seconds since the start of simulation
3. unique UE ID
4. RNTI
5. Logical Channel ID
6. Number of transmitted PDUs
7. Total bytes transmitted.
8. Number of received PDUs
9. Total bytes received
10. Average PDU delay in seconds
11. Standard deviation of the PDU delay
12. Minimum value of the PDU delay
13. Maximum value of the PDU delay
14. Average PDU size, in bytes
15. Standard deviation of the PDU size
16. Minimum PDU size
17. Maximum PDU size
MAC KPIs are basically a trace of the resource allocation reported by
the scheduler upon the start of every subframe. They are stored in
ASCII files. For downlink MAC KPIs the format is the following:
1. Simulation time in seconds at which the allocation is indicated by the scheduler
2. Cell Identifier
3. Frame number
4. Subframe number
5. RNTI
6. MCS of TB 1
7. size of TB 1
8. MCS of TB 2 (0 if not present)
9. size of TB 2 (0 if not present)
while for uplink MAC KPIs the format is:
1. Simulation time in seconds at which the allocation is indicated by the scheduler
2. Frame number
3. Subframe number
4. RNTI
5. MCS of TB
6. size of TB
The names of the files used for MAC KPI output can be customized via
the ns-3 attributes ``ns3::MacStatsCalculator::DlOutputFilename`` and
``ns3::MacStatsCalculator::UlOutputFilename``.
Further Reading
---------------
The directory ``src/lte/examples/`` contains some example simulation programs that
show how to simulate different LTE scenarios.
Performance evaluation