..
   SPDX-FileCopyrightText: © 2020 Open Networking Foundation <support@opennetworking.org>
   SPDX-License-Identifier: Apache-2.0
.. _gNB-Simulator:

gNBSim Usage
=============

Description
-----------
The gNBSim tool simulates gNodeB and UE by generating and processing NAS and
NGAP messages for the configured UEs and call flows. The tool currently supports
simulation profiles for the following procedures,

* Registration
* UE Initiated PDU Session Establishment
* UE Initiated De-registration.
* AN Release
* Ue Initiated Service Request Procedure
* NW triggered de-registration
* UE Requested PDU Session Release
* NW triggered PDU Session Release

It is also capable to generate and send user data packets (ICMP echo request)
and process down-link user data (ICMP echo response) over the established data
plane path (N3 Tunnel).

gNBSim Code References
----------------------

* Code Repository: `github repository <https://github.com/omec-project/gnbsim>`_
* Helm Chart: `gerrit repository <https://gerrit.opencord.org/plugins/gitiles/sdcore-helm-charts/+/refs/heads/master/5g-ran-sim/>`_
* RAN SIM Helm Chart: `5g-ran-sim repository <https://charts.aetherproject.org>`_


Configure gNBSim
-----------------
* The sample config file for gNBSim can be found `here <https://github.com/omec-project/gnbsim/blob/main/config/gnbsim.yaml>`_

    *Note: The configuration has following major fields (Read the comments in
    the config file for more details)*

    * **gnbs**:
        List of gNB's to be simulated. Each item in the list holds configuration
        specific to a gNB.
    * **profiles**:
        List of test/simulation profiles. Each item in the list holds
        configuration specific to a profile.
    * **customProfiles**:
        List of custom profiles. Each item in the list holds
        configuration specific to a customProfile.

* Enable or disable a specific profile using the `enable` field within profile block.
    Note: Currently following profiles are supported


Run gNBSim
-----------

* To quickly launch and test AiaB with 5G SD-CORE using gNBSim:

    .. code-block:: bash

        $ make 5g-test

    (refer AiaB documentation :ref:`aiab5g-guide`)

* Alternatively, you can do following
    running:

    .. code-block:: bash

        $ make 5g-core

* Once all PODs are up then you can enter into the gNBSim pod by running

    .. code-block:: bash

        $ kubectl exec -it gnbsim-0 -n omec bash

* Then run following command to launch gNBSim profiles:

    .. code-block:: bash

        $ ./gnbsim

    *Note: By default, the gNB Sim reads the configuration from
    /gnbsim/config/gnb.conf file. To provide a different configuration file, use
    the below command*

    .. code-block:: bash

        $ ./gnbsim --cfg <config file path>

Build gNBSim
------------

* If you find a need to change gNBSim code and use the updated image in the AIAB setup then
  follow below steps.

* To modify gNBSim and build a new docker image:

    .. code-block:: bash

        $ git clone https://github.com/omec-project/gnbsim.git
        $ cd gnbsim
        $ make docker-build  #requires golang installed on the machine

* To use newly created image in the AiaB cluster:

Update *~/aether-in-box/sd-core-5g-values.yaml* to point to the newly built image, then run:

    .. code-block:: bash

        $ cd ~/aether-in-a-box/
        $ make reset-5g-test


    .. code-block:: bash

        $ make 5g-test

    (refer AiaB documentation :ref:`aiab5g-guide`)


gNBSim System level features
----------------------------

* Logging summary result

* HTTP API to create new profile. Below configuration enables http server in gNBSim.
  Example to use gNBSim can be found `script <https://github.com/omec-project/gnbsim/blob/main/scripts/create-new-profile.sh>`_

    .. code-block:: bash

      config:
        gnbsim:
          httpServer:
            enable: true #enable httpServer in gnbsim
            port: 6000

* Gnbsim can generate and send user data packets (ICMP echo request)
  and process downlink user data (ICMP echo response) over the established data
  plane path (N3 Tunnel). Configure number of data packets to be sent. Configure
  AS (Application Server) address. This is used to send data packets.

    .. code-block:: bash

      - profileType: nwtriggeruedereg # profile type
        profileName: profile6 # uniqely identifies a profile within application
        enable: false # Set true to execute the profile, false otherwise.
        gnbName: gnb1 # gNB to be used for this profile
        startImsi: 208930100007497 # First IMSI. Subsequent values will be used if ueCount is more than 1
        ueCount: 1 # Number of UEs for for which the profile will be executed
        defaultAs: "192.168.250.1" #default icmp pkt destination
        perUserTimeout: 10 #if no expected event received in this time then treat it as failure


* Executing all enabled profiles in parallel or in sequential order.

    .. code-block:: bash

       config:
         gnbsim:
           yamlCfgFiles:
             gnb.conf:
               configuration:
                   execInParallel: false #run all profiles in parallel

.. note::
  There is execInParallel option under each profile as well. execInParallel under profile means that all the
  subscribers in the profile are run in parallel

* Timeout for each call flow within profile

    .. code-block:: bash

       - profileType: nwtriggeruedereg # profile type
         profileName: profile6 # uniqely identifies a profile within application
         perUserTimeout: 10 #if no expected event received in this time then treat it as failure

* Getting gNBSim golang profile

    .. code-block:: bash

       config:
         gnbsim:
           goProfile:
             enable: true #enable/disable golang profile in gnbsim
             port: 5000

* Run gNBSim with single Interface or multi interface

    .. code-block:: bash

       config:
         gnbsim:
           yamlCfgFiles:
             gnb.conf:
               configuration:
                   singleInterface: false #default false i.e. multiInterface. Works well for AIAB

* Support of Custom Profiles: User can now define your own profile. New profile can be
  created by using existing baseline procedure. Example of custom profile can be found here.
  Check customProfiles in `gNBSim config <https://github.com/omec-project/gnbsim/blob/main/config/gnbsim.yaml>_`

    .. code-block:: bash

       customProfiles:
         customProfiles1:
           profileType: custom # profile type
           profileName: custom1 # uniqely identifies a profile within application
           enable: false # Set true to execute the profile, false otherwise.
           execInParallel: false #run all subscribers in parallel
           stepTrigger: true #wait for trigger to move to next step
           gnbName: gnb1 # gNB to be used for this profile
           startImsi: 208930100007487
           ueCount: 5
           defaultAs: "192.168.250.1" #default icmp pkt destination
           opc: "981d464c7c52eb6e5036234984ad0bcf"
           key: "5122250214c33e723a5dd523fc145fc0"
           sequenceNumber: "16f3b3f70fc2"
           plmnId: # Public Land Mobile Network ID, <PLMN ID> = <MCC><MNC>
             mcc: 208 # Mobile Country Code (3 digits string, digit: 0~9)
             mnc: 93 # Mobile Network Code (2 or 3 digits string, digit: 0~9)
           startiteration: iteration1
           iterations:
             #at max 7 actions
             - "name": "iteration1"
               "1": "REGISTRATION-PROCEDURE 5"
               "2": "PDU-SESSION-ESTABLISHMENT-PROCEDURE 5"  #5 second delay after this procedure
               "3": "USER-DATA-PACKET-GENERATION-PROCEDURE 10"
               "next":  "iteration2"
             - "name": "iteration2"
               "1": "AN-RELEASE-PROCEDURE 100"
               "2": "UE-TRIGGERED-SERVICE-REQUEST-PROCEDURE 10"
               "repeat": 5
               "next":  "iteration3"
             - "name": "iteration3"
               "1": "UE-INITIATED-DEREGISTRATION-PROCEDURE 10"
               #"repeat": 0 #default value 0 . i.e execute once
               #"next":  "quit" #default value quit. i.e. no further iteration to run

* Delay between Procedures can be added using customProfiles.