e2sim/README.md

   1 #/*****************************************************************************
   2 #                                                                            *
   3 # Copyright 2019 AT&T Intellectual Property                                  *
   4 # Copyright 2019 Nokia                                                       *
   5 #                                                                            *
   6 # Licensed under the Apache License, Version 2.0 (the "License");            *
   7 # you may not use this file except in compliance with the License.           *
   8 # You may obtain a copy of the License at                                    *
   9 #                                                                            *
  10 #      http://www.apache.org/licenses/LICENSE-2.0                            *
  11 #                                                                            *
  12 # Unless required by applicable law or agreed to in writing, software        *
  13 # distributed under the License is distributed on an "AS IS" BASIS,          *
  14 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.   *
  15 # See the License for the specific language governing permissions and        *
  16 # limitations under the License.                                             *
  17 #                                                                            *
  18 #******************************************************************************/
  19
  20 This is an update to E2 Simulator, based on E2AP v1 defined in ORAN
  21 E2 Simulator is built as a library that supports basic functions and is
  22 linked by an E2 Simulation application.
  23
  24 The E2 Simulator breaks up the simulation roles into two:
  25 1. Base E2AP support
  26 2. E2SM Support
  27
  28 #1 is the role supported by E2 Simulator library, while #2 is supported by the
  29 calling application.  An example of a calling application is provided in this repo
  30 under the
  31
  32 E2 Simulator enables a specific E2SM to be supported by the calling application in
  33 the following way:
  34
  35 * E2SM must be registered by the calling application
  36 * E2SM-specific code uses callbacks to handle interaction from xApp
  37 * E2SM-specific code must continuously implement simulation logic
  38
  39 Registration of an E2SM with the E2 Simulator entails the following:
  40 * RAN function definition
  41 * Callback functions for any of the following:
  42   Subscription
  43   Control
  44   Any Responses
  45
  46 The following is the E2 Simulator Main Program Flow
  47 1. Upon startup, Simulator generates E2 Setup Request
  48    For each E2SM that is registered, include RAN function definition
  49
  50 2. Upon receiving incoming requests, decode
  51    Identify RAN function ID
  52    Call appropriate callback function for RAN function ID and request type
  53    Provide entire encoded request
  54    If no callback is provided, we return an error response
  55 3. Upon receiving responses, decode:
  56    Identify RAN function ID
  57    If a callback is registered for this message type, call it based on RAN function ID and request type
  58    Provide entire encoded response
  59    If no callback is registered, no action is taken
  60
  61 E2SM Callback Functions:
  62
  63 * Callback functions are responsible for sending responses
  64 * They may also need to set up ongoing simulation messaging
  65   REPORT Service sends back periodic Indication messages containing REPORT
  66   INSERT Service sends back periodic Indication messages containing INSERT
  67 * They may need to associate incoming messages with existing service invocation
  68   Modify Subscription
  69   CONTROL message associated with INSERT
  70 * Base E2 simulator should not be concerned with these details; only specific E2SM code should be responsible for any messaging
  71
  72
  73 # INSTALLATION Instructions (tested on Ubuntu 16.04)
  74   1. Install dependencies
  75     $ sudo apt-get update
  76     $ sudo apt-get install -y
  77         build-essential
  78         git
  79         cmake
  80         libsctp-dev
  81         lksctp-tools
  82         autoconf
  83         automake
  84         libtool
  85         bison
  86         flex
  87         libboost-all-dev
  88     $ sudo apt-get clean
  89
  90   2. Build the official e2sim
  91     $ mkdir build
  92     $ cd build
  93     $ cmake ..
  94     $ make package
  95     $ cmake .. -DDEV_PKG=1
  96     $ make package
  97
  98 # Building docker image and running simulator instance
  99
 100 To start building docker image one should generate the `.deb` packages using following
 101 commands :
 102
 103 ```
 104 $ cd build          // create folder if not present
 105 ```
 106
 107 Generate .deb packages and move it to `e2sm_examples/kpm_e2sm` folder :
 108 ```
 109 cmake .. && make package && cmake .. -DDEV_PKG=1 && make package
 110 cp *.deb ../e2sm_examples/kpm_e2sm/
 111 ```
 112
 113 Now we are ready to build the docker image using below command :
 114 ```
 115 cd ../e2sm_examples/kpm_e2sm/
 116 docker build -t <simulator-image-name> .
 117 ```
 118
 119 if you wish to change the e2t address to connect then modify the `Dockerfile` in `e2sm_examples/kpm_e2sm/` path.
 120 ```
 121 CMD kpm_sim 10.110.102.29 36422
 122 ```
 123 Create instance of simulator :
 124 ```
 125 $ docker run <simulator-image-name>
 126 ```
 127
 128 It will connect to specified e2t instance.