From 1c3edc5d446bec2e36975031ac45bf7f49bcd40f Mon Sep 17 00:00:00 2001 From: Nicola Baldo Date: Fri, 27 May 2011 18:13:52 +0200 Subject: [PATCH] updated user documentation --- src/lte/doc/source/lte-design.rst | 2 +- src/lte/doc/source/lte-references.rst | 4 + src/lte/doc/source/lte-testing.rst | 2 +- src/lte/doc/source/lte-user.rst | 291 ++++++++++++++++++++++---- 4 files changed, 252 insertions(+), 47 deletions(-) diff --git a/src/lte/doc/source/lte-design.rst b/src/lte/doc/source/lte-design.rst index 3c711360c..86b23773d 100644 --- a/src/lte/doc/source/lte-design.rst +++ b/src/lte/doc/source/lte-design.rst @@ -2,7 +2,7 @@ ++++++++++++++++++++++++++ - LTE Design Documentation + Design Documentation ++++++++++++++++++++++++++ diff --git a/src/lte/doc/source/lte-references.rst b/src/lte/doc/source/lte-references.rst index dacae06c1..279a24c70 100644 --- a/src/lte/doc/source/lte-references.rst +++ b/src/lte/doc/source/lte-references.rst @@ -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/ diff --git a/src/lte/doc/source/lte-testing.rst b/src/lte/doc/source/lte-testing.rst index 371467eed..18ee8887d 100644 --- a/src/lte/doc/source/lte-testing.rst +++ b/src/lte/doc/source/lte-testing.rst @@ -2,7 +2,7 @@ +++++++++++++++++++++++++++ - LTE Testing Documentation + Testing Documentation +++++++++++++++++++++++++++ diff --git a/src/lte/doc/source/lte-user.rst b/src/lte/doc/source/lte-user.rst index 8243a4278..15120d0df 100644 --- a/src/lte/doc/source/lte-user.rst +++ b/src/lte/doc/source/lte-user.rst @@ -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 lena = CreateObject (); + + 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 lena = CreateObject (); + + // 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