doc: updated nr/tutorial

- added NED and INI file code

doc/src/index.rst

@@ -120,10 +120,14 @@ UniPi team:
 
 .. toctree::
  :hidden:
+ :glob:
+ :caption: Showcases
 
- showcases/index
+ showcases/*/standalone/doc/index
 
 .. toctree::
  :hidden:
+ :glob:
+ :caption: Tutorials
 
- tutorials/index
+ tutorials/*/doc/index

showcases/NR/standalone/doc/index.rst

@@ -6,11 +6,12 @@ Goal
 
 The goal of this showcase is to demonstrate a standalone 5G network deployment
 using the Simu5G framework. It aims to highlight the interactions between
-network elements such as the gNodeB and the User Equipment (UE) in a 5G NR
+network elements such as the *gNodeB* and the *User Equipment (UE)* in a *5G NR*
 environment, and how traffic flows between these elements.
 
-| Simu5G version: ``1.2.2``
-| Source files location: `simu5g/showcases/NR/standalone <https://github.com/Unipisa/Simu5G/tree/master/showcases/NR/standalone>`__
+.. versionadded:: 1.2.2
+
+| Source files location: `showcases/NR/standalone <https://github.com/Unipisa/Simu5G/tree/master/showcases/NR/standalone>`_
 
 Model
 -----
@@ -34,21 +35,21 @@ Configuration
 The simulation is configured via the provided INI file, with the following key settings:
 
 - **Simulation Time**: The simulation runs for a total of 20 seconds.
-- **Number of UEs**: Configured to have a single UE by default.
+- **Number of UEs**: Configured to have a single *UE* by default.
 - **Mobility**: UEs are confined within a 1000m x 1000m area.
-- **Transmission Power**: Configured for both the gNodeB and UE, with default values set to 40 and 26 respectively.
-- **IPv4 Configuration**: Managed by the `Ipv4NetworkConfigurator` with settings provided in `demo.xml`.
+- **Transmission Power**: Configured for both the *gNodeB* and *UE*, with default values set to 40 and 26 respectively.
+- **IPv4 Configuration**: Managed by the :ned:`Ipv4NetworkConfigurator` with settings provided in :file:`demo.xml`.
 
 Two traffic configurations are included:
 
-- **VoIP-DL**: Simulates Voice-over-IP traffic from the server to the UE.
-- **VoIP-UL**: Simulates Voice-over-IP traffic from the UE to the server.
+- :ini:`VoIP-DL`: Simulates Voice-over-IP traffic from the server to the *UE*.
+- :ini:`VoIP-UL`: Simulates Voice-over-IP traffic from the *UE* to the server.
 
 Results
 -------
 
-The simulation generates scalar and vector results captured in `*.sca` and
-`*.vec` files, respectively. Key metrics to observe include:
+The simulation generates scalar and vector results captured in :file:`*.sca` and
+:file:`*.vec` files, respectively. Key metrics to observe include:
 
 - **End-to-end delay**: Measures the latency experienced by VoIP packets.
 - **Throughput**: Assesses the network's capacity to handle data traffic.
@@ -61,11 +62,11 @@ Conclusion
 ----------
 
 This showcase provides a comprehensive overview of a standalone 5G network's
-operation using the Simu5G framework, focusing on the key interactions and
+operation using the *Simu5G* framework, focusing on the key interactions and
 performance metrics essential for evaluating the network's capabilities.
 
 Sources: :download:`omnetpp.ini <../omnetpp.ini>`,
- :download:`SingleCell_Standalone.ned <../../../../../simulations/NR/networks/SingleCell_Standalone.ned>`
+:download:`SingleCell_Standalone.ned <../../../../simulations/NR/networks/SingleCell_Standalone.ned>`
 
 Discussion
 ----------

tutorials/NR/doc/index.rst

@@ -1,98 +1,139 @@
-NR Tutorial
-===========
+New Radio Tutorial
+==================
 
 Goals
 -----
 
 This tutorials includes simulation examples that are intended to provide
 hints about the basic configurations of 5G NR networks.
 
-| Simu5G version: ``1.2.2``
-| Source files location: `simu5g/showcases/NR/standalone <https://github.com/Unipisa/Simu5G/tree/master/showcases/NR/standalone>`__
+.. versionadded:: 1.2.2
+
+Source files location: `showcases/NR/standalone <https://github.com/Unipisa/Simu5G/tree/master/showcases/NR/standalone>`_
 
 
 Introduction
 ------------
 
-The omnetpp.ini file is composed of several sections, each of which extends the scenario provided
+In this tutorial the :ini:`omnetpp.ini` file is composed of several sections, each of which extends the scenario provided
 by the previous one. This way, the beginner user is provided with a step-by-step guide towards
 scenarios with increasing complexities.
 
-All the configurations use the SingleCell_Standalone network that can be found in the
-simulations/NR/networks folder.
+All the configurations use the :ned:`SingleCell_Standalone` network that can be found in the
+:file:`simulations/NR/networks` folder.
 
-1. Single UE
-------------
+.. literalinclude:: ../../../simulations/NR/networks/SingleCell_Standalone.ned
+ :language: ned
+ :start-at: SingleCell_Standalone
+
+.. figure:: media/SingleCell_Standalone.png
+
+ Initial configuration of the network
+
+Step 1: Single UE
+-----------------
 
-Configuration: ``Single-UE``
+Configuration: :ini:`Single-UE`
 
-This simple scenario simulates only one UE attached to one gNB, with downlink traffic. The UE is
-located 400 meters far from the gNB and receives 800 kbps CBR traffic from a remote server.
+This simple scenario simulates only one *UE* attached to one *gNB*, with downlink traffic. The UE is
+located 400 meters far from the *gNB* and receives 800 kbps CBR traffic from a remote server.
 
-Since this scenario does not include any inter-cell interference and the gNB is lightly loaded
-(it is serving one UE only), you will observe that the throughput received by the UE is equal
+.. literalinclude:: ../omnetpp.ini
+ :language: ini
+ :start-at: [Config Single-UE]
+ :end-before: # ----
+ :emphasize-lines: 8,22-23,28-30
+
+Since this scenario does not include any inter-cell interference and the *gNB* is lightly loaded
+(it is serving one *UE* only), you will observe that the throughput received by the *UE* is equal
 to the throughput generated by the server.
-See 'cbrReceivedThroughput:mean' and 'cbrGeneratedThroughput:mean' statistics.
+See ``cbrReceivedThroughput:mean`` and ``cbrGeneratedThroughput:mean`` statistics.
 
+Step 2: Adding Inter-Cell Interference
+--------------------------------------
 
-2. Adding Inter-Cell Interference
----------------------------------
+Configuration: :ini:`BgTraffic`
 
-Configuration: ``BgTraffic``
+As a next step, let's add some inter-cell interference to the previous configuration. To do this,
+the scenario simulates one background cell, which serves 10 background UEs. Each background UEs
+receives 800 kbps CBR traffic.
 
-This configurations adds inter-cell interference to the previous configuration. To do this, the scenario
-simulates one background cell, which serves 10 background UEs. Each babkground UEs receives 800 kbps CBR
-traffic.
-NOTE: Background cells/UEs are simplified models of cells/UEs and have the only purpose to create
-interference on foreground cells/UEs. See the following paper for more information:
+.. note::
+
+ Background cells/UEs are simplified models of cells/UEs and have the only purpose to create
+ interference on foreground cells/UEs. See the following paper for more information:
 
- G. Nardini, G. Stea, A. Virdis, "Scalable Real-time Emulation of 5G Networks with Simu5G",
+  G. Nardini, G. Stea, A. Virdis, "Scalable Real-time Emulation of 5G Networks with Simu5G",
  IEEE Access, vol. 9, pp. 148504-148520, 2021. doi: 10.1109/ACCESS.2021.3123873.
 
+.. literalinclude:: ../omnetpp.ini
+ :language: ini
+ :start-at: [Config BgTraffic]
+ :end-before: # ----
+ :emphasize-lines: 5
+
 Due to the presence of interference you will observe smaller CQI for the foreground UE, as well as higher
 number of allocated Resource Blocks in the downlink of the foreground cell.
-See 'averageCqiDl:mean' and 'avgServerBlocksDl:mean' statistics.
+See ``averageCqiDl:mean`` and ``avgServerBlocksDl:mean`` statistics.
 
 
-3. Adding a Variable Number of UEs
-----------------------------------
+Step 3: Adding a Variable Number of UEs
+---------------------------------------
 
-Configuration: ``Multiple-UEs``
+Configuration: :ini:`Multiple-UEs`
 
-This configuration adds a variable number of (foreground) UEs (from 1 to 20) in the (foreground) gNB.
+This configuration adds a variable number of (foreground) *UEs* (from 1 to 20) in the (foreground) *gNB*.
 All of them receive 800 kbps CBR traffic from a remote server.
 
+.. literalinclude:: ../omnetpp.ini
+ :language: ini
+ :start-at: [Config Multiple-UEs]
+ :end-before: # ----
+ :emphasize-lines: 5,12
+
 Due to the increased offered load, you will observe higher number of allocated Resource Blocks in the
 downlink of the foreground cell. In particular, you will observe that the allocated RBs will reach the
 maximum number of available RBs in this scenario (6). As a consequence, some UEs will experience a lower
 throughput than the throughput generated at the server.
-See 'avgServerBlocksDl:mean' and 'cbrReceivedThroughput:mean' statistics.
+See ``avgServerBlocksDl:mean`` and ``cbrReceivedThroughput:mean`` statistics.
 
 
-4. Carrier Aggregation
-----------------------
+Step 4: Carrier Aggregation
+---------------------------
 
-Configuration: ``CarrierAggregation``
+Configuration: :ini:`CarrierAggregation`
 
-This configuration enables a second Component Carrier (CC) at the gNBs. Thus, the UEs will be allocated
+This configuration enables a second Component Carrier (CC) at the *gNBs*. Thus, the *UEs* will be allocated
 into the second CC when the RBs in the first one are terminated.
 
+.. literalinclude:: ../omnetpp.ini
+ :language: ini
+ :start-at: [Config CarrierAggregation]
+ :end-before: # ----
+ :emphasize-lines: 5,11,15,20
+
 Due to the higher radio capacity available, you will observe higher number of allocated Resource Blocks in the
 downlink of the foreground cell, but you will also observe that UEs will get higher throughput than the
 previous scenario.
-See 'avgServerBlocksDl:mean' and 'cbrReceivedThroughput:mean' statistics.
+See ``avgServerBlocksDl:mean`` and ``cbrReceivedThroughput:mean`` statistics.
 
 
-5. Numerology
--------------
+Step 5: Numerology
+------------------
 
-Configuration: ``Numerology``
+Configuration: :ini:`Numerology`
 
 This configuration shows how to change the numerology (u=0,1,2) assigned to all Component Carriers (CC).
 
+.. literalinclude:: ../omnetpp.ini
+ :language: ini
+ :start-at: [Config Numerology]
+ :end-before: # ----
+ :emphasize-lines: 5,6
+
 When numerology increases, you will observe that the number of allocated Resource Blocks will decrease and
 more UEs will get higher throughput.
-See 'avgServerBlocksDl:mean' and 'cbrReceivedThroughput:mean' statistics.
+See ``avgServerBlocksDl:mean`` and ``cbrReceivedThroughput:mean`` statistics.
 
 
 Sources: :download:`omnetpp.ini <../omnetpp.ini>`, :download:`SingleCell_Standalone.ned <../../../simulations/NR/networks/SingleCell_Standalone.ned>`