docs/user-guide.rst

   1
   2
   3 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   4 .. SPDX-License-Identifier: CC-BY-4.0
   5 ..
   6 .. CAUTION: this document is generated from source in doc/src/*
   7 .. To make changes edit the source and recompile the document.
   8 .. Do NOT make changes directly to .rst or .md files.
   9
  10
  11 ============
  12 User's Guide
  13 ============
  14 ---------------------
  15 Traffic Steering xAPP
  16 ---------------------
  17
  18 Introduction
  19 ============
  20
  21 The Traffic Steering Use Case demonstrates intelligent inferences in the Near-RT RIC and E2 interaction in order to execute on the inferences.
  22
  23 The current Use Case is comprised of five xApps:
  24
  25 * KPI Monitoring xApp: Gathers the radio and system Key Performance Indicators (KPI) metrics from E2 Nodes and stores them in the Shared Data Layer (SDL).
  26 * Anomaly Detection (AD) xApp: Fetches UE data regularly from SDL, monitors UE metrics and sends the anomalous UEs to Traffic Steering xApp.
  27 * Traffic Steering xApp (*this one*): Consumes A1 Policy Intent, listens for badly performing UEs, sends prediction requests to QP xApp, and listens for messages from QP that show UE throughput predictions in different cells to make decisions about UE Handover.
  28 * QoE Prediction (QP) xApp: Generates a feature set of metrics based on SDL lookups in UE-Metric and Cell-Metric namespaces for a given UE, and outputs Throughput predictions on the Serving and any Neighbor cells to the Traffic Steering xApp.
  29 * RAN Control (RC) xApp: Provides basic implementation of spec compliant E2-SM RC to send RIC Control Request messages to RAN/E2 Nodes.
  30
  31
  32 A1 Policy
  33 =========
  34
  35 A1 Policy is sent to Traffic Steering xApp to define the Intent which will drive the Traffic Steering behavior.
  36
  37 Policy Type ID is 20008.
  38
  39 Currently, there is only one parameter that can be provided in A1 Policy: *threshold*
  40
  41 An example Policy follows:
  42
  43 .. code-block::
  44
  45     { "threshold": 5 }
  46
  47 This Policy instructs Traffic Steering xApp to hand-off any UE whose downlink throughput of its current serving cell is 5% below the throughput of any neighboring cell.
  48
  49 Receiving Anomaly Detection
  50 ===========================
  51
  52 Traffic Sterring xApp defines a callback to listen to Anomaly Detection messages received from AD xApp. The RMR message type is 30003.
  53 The following is an example message body:
  54
  55 .. code-block::
  56
  57     [
  58         {
  59             "du-id":1010,
  60             "ue-id":"Train passenger 2",
  61             "measTimeStampRf":1620835470108,
  62             "Degradation":"RSRP RSSINR"
  63         }
  64     ]
  65
  66 .. ``[{"du-id": 1010, "ue-id": "Train passenger 2", "measTimeStampRf": 1620835470108, "Degradation": "RSRP RSSINR"}]``
  67
  68 Sending QoE Prediction Request
  69 ==============================
  70
  71 Traffic Steering listens for badly performing UEs.
  72 Each Anomaly Detection message received from AD xApp, results in a QoE Prediction Request to QP xApp.
  73 The RMR Message Type is 30000.
  74 The following is an example message body:
  75
  76 .. {"UEPredictionSet" : ["12345"]}
  77
  78 .. code-block::
  79
  80     { "UEPredictionSet": ["Train passenger 2"] }
  81
  82 Receiving QoE Prediction
  83 ========================
  84
  85 Traffic Steering xApp defines a callback for QoE Prediction received from QP xApp.  The RMR message type is 30002.  The following is an example message body:
  86
  87 .. {"12345" : { "310-680-200-555001" : [ 2000000 , 1200000 ] , "310-680-200-555002" : [ 800000 , 400000 ] , "310-680-200-555003" : [ 800000 , 400000 ]  } }
  88
  89 .. code-block::
  90
  91     {
  92         "Train passenger 2":{
  93             "310-680-200-555001":[2000000, 1200000],
  94             "310-680-200-555002":[1000000, 4000000],
  95             "310-680-200-555003":[5000000, 4000000]
  96         }
  97     }
  98
  99 This message provides predictions for UE ID "Train passenger 2".  For its service cell and neighbor cells, it lists an array containing two elements: DL Throughput and UL Throughput predictions.
 100
 101 Traffic Steering xApp checks for the Service Cell ID for UE ID, and determines whether the predicted throughput is higher in a neighbor cell.
 102 The first cell in this prediction message is assumed to be the serving cell.
 103
 104 Since RC xApp is not mandatory for the Traffic Steering use case, TS xApp sends CONTROL messages using either REST or gRPC calls.
 105 The CONTROL endpoint is set up in the xApp descriptor file called "config-file.json". Please, check out the "schema.json" file for configuration examples.
 106
 107 The following is an example of a REST message that requests the handover of a given UE:
 108
 109 .. code-block::
 110
 111     {
 112         "command": "HandOff",
 113         "seqNo": 1,
 114         "ue": "Train passenger 2",
 115         "fromCell": "310-680-200-555001",
 116         "toCell": "310-680-200-555003",
 117         "timestamp": "Sat May 22 10:35:33 2021",
 118         "reason": "Hand-Off Control Request from TS xApp",
 119         "ttl": 10
 120     }
 121
 122 Control messages might also be exchanged with E2 Simulators that implement REST-based interfaces.
 123 Traffic Steering then logs the REST response showing whether or not the control operation has succeeded.
 124
 125 The gRPC interface is only required to exchange messages with the RC xApp.
 126 The following is an example of the gRPC message (*string representation*) which requests the RC xApp to handover a given UE:
 127
 128 .. code-block::
 129
 130     e2NodeID: "000000000001001000110100"
 131     plmnID: "02F829"
 132     ranName: "enb_208_092_001235"
 133         RICE2APHeaderData {
 134         RanFuncId: 300
 135         RICRequestorID: 1001
 136     }
 137     RICControlHeaderData {
 138         ControlStyle: 3
 139         ControlActionId: 1
 140         UEID: "Train passenger 2"
 141     }
 142     RICControlMessageData {
 143         TargetCellID: "mnop"
 144     }
 145
 146 TS xApp also requires to fetch additional RAN information from the E2 Manager to communicate with RC xApp.
 147 By default, TS xApp requests information to the default endpoint of E2 Manager in the Kubernetes cluster.
 148 Still, the default E2 Manager endpoint from TS can be changed using the env variable "SERVICE_E2MGR_HTTP_BASE_URL".