docs/user-guide/ocp-plugin-user-guide.rst

   1 .. _ocpplugin-user-guide:
   2
   3 OCP Plugin User Guide
   4 =====================
   5
   6 This document describes how to use the ORI Control & Management Protocol
   7 (OCP) feature in OpenDaylight. This document contains overview, scope,
   8 architecture and design, installation, configuration and tutorial
   9 sections for the feature.
  10
  11 Overview
  12 --------
  13
  14 OCP is an ETSI standard protocol for control and management of Remote
  15 Radio Head (RRH) equipment. The OCP Project addresses the need for a
  16 southbound plugin that allows applications and controller services to
  17 interact with RRHs using OCP. The OCP southbound plugin will allow
  18 applications acting as a Radio Equipment Control (REC) to interact with
  19 RRHs that support an OCP agent.
  20
  21 .. figure:: ./images/ocpplugin/ocp-sb-plugin.jpg
  22    :alt: OCP southbound plugin
  23
  24    OCP southbound plugin
  25
  26 It is foreseen that, in 5G, C-RAN will use the packet-based
  27 Transport-SDN (T-SDN) as the fronthaul network to transport both control
  28 plane and user plane data between RRHs and BBUs. As a result, the
  29 addition of the OCP plugin to OpenDaylight will make it possible to
  30 build an RRH controller on top of OpenDaylight to centrally manage
  31 deployed RRHs, as well as integrating the RRH controller with T-SDN on
  32 one single platform, achieving the joint RRH and fronthaul network
  33 provisioning in C-RAN.
  34
  35 Scope
  36 -----
  37
  38 The OCP Plugin project includes:
  39
  40 -  OCP v4.1.1 support
  41
  42 -  Integration of OCP protocol library
  43
  44 -  Simple API invoked as a RPC
  45
  46 -  Simple API that allows applications to perform elementary functions
  47    of the following categories:
  48
  49    -  Device management
  50
  51    -  Config management
  52
  53    -  Object lifecycle
  54
  55    -  Object state management
  56
  57    -  Fault management
  58
  59    -  Software management (not yet implemented)
  60
  61 -  Indication processing
  62
  63 -  Logging (not yet implemented)
  64
  65 -  AISG/Iuant interface message tunnelling (not yet implemented)
  66
  67 -  ALD connection management (not yet implemented)
  68
  69 Architecture and Design
  70 -----------------------
  71
  72 OCP is a vendor-neutral standard communications interface defined to
  73 enable control and management between RE and REC of an ORI architecture.
  74 The OCP Plugin supports the implementation of the OCP specification; it
  75 is based on the Model Driven Service Abstraction Layer (MD-SAL)
  76 architecture.
  77
  78 OCP Plugin will support the following functionality:
  79
  80 -  Connection handling
  81
  82 -  Session management
  83
  84 -  State management
  85
  86 -  Error handling
  87
  88 -  Connection establishment will be handled by OCP library using
  89    opensource netty.io library
  90
  91 -  Message handling
  92
  93 -  Event/indication handling and propagation to upper layers
  94
  95 **Activities in OCP plugin module**
  96
  97 -  Integration with OCP protocol library
  98
  99 -  Integration with corresponding MD-SAL infrastructure
 100
 101 OCP protocol library is a component in OpenDaylight that mediates
 102 communication between OpenDaylight controller and RRHs supporting OCP
 103 protocol. Its primary goal is to provide the OCP Plugin with
 104 communication channel that can be used for managing RRHs.
 105
 106 Key objectives:
 107
 108 -  Immutable transfer objects generation (transformation of OCP protocol
 109    library’s POJO objects into OpenDaylight DTO objects)
 110
 111 -  Scalable non-blocking implementation
 112
 113 -  Pipeline processing
 114
 115 -  Scatter buffer
 116
 117 -  TLS support
 118
 119 OCP Service addresses the need for a northbound interface that allows
 120 applications and other controller services to interact with RRHs using
 121 OCP, by providing API for abstracting OCP operations.
 122
 123 .. figure:: ./images/ocpplugin/plugin-design.jpg
 124    :alt: Overall architecture
 125
 126    Overall architecture
 127
 128 Message Flow
 129 ------------
 130
 131 .. figure:: ./images/ocpplugin/message_flow.jpg
 132    :alt: Message flow example
 133
 134    Message flow example
 135
 136 Installation
 137 ------------
 138
 139 The OCP Plugin project has two top level Karaf features,
 140 odl-ocpplugin-all and odl-ocpjava-all, which contain the following
 141 sub-features:
 142
 143 -  odl-ocpplugin-southbound
 144
 145 -  odl-ocpplugin-app-ocp-service
 146
 147 -  odl-ocpjava-protocol
 148
 149 The OCP service (odl-ocpplugin-app-ocp-service), together with the OCP
 150 southbound (odl-ocpplugin-southbound) and OCP protocol library
 151 (odl-ocpjava-protocol), provides OpenDaylight with basic OCP v4.1.1
 152 functionality.
 153
 154 There are two ways to interact with OCP service: one is via RESTCONF
 155 (programmatic) and the other is using DLUX web interface (manual), so
 156 you have to install the following features to enable RESTCONF and DLUX.
 157
 158 ::
 159
 160     karaf#>feature:install odl-restconf odl-l2switch-switch odl-mdsal-apidocs odl-dlux-core odl-dluxapps-applications
 161
 162 Then install the odl-ocpplugin-all feature which includes the
 163 odl-ocpplugin-southbound and odl-ocpplugin-app-ocp-service features.
 164 Note that the odl-ocpjava-all feature will be installed automatically as
 165 the odl-ocpplugin-southbound feature is dependent on the
 166 odl-ocpjava-protocol feature.
 167
 168 ::
 169
 170     karaf#>feature:install odl-ocpplugin-all
 171
 172 After all required features are installed, use following command from
 173 karaf console to check and make sure features are correctly installed
 174 and initialized.
 175
 176 ::
 177
 178     karaf#>feature:list | grep ocp
 179
 180 Configuration
 181 -------------
 182
 183 Configuring the OCP plugin can be done via its configuration file,
 184 62-ocpplugin.xml, which can be found in the
 185 <odl-install-dir>/etc/opendaylight/karaf/ directory.
 186
 187 There are the following settings that are configurable:
 188
 189 1. **port** specifies the port number on which the OCP plugin listens
 190    for connection requests
 191
 192 2. **radioHead-idle-timeout** determines the time duration (unit:
 193    milliseconds) for which a radio head has been idle before the idle
 194    event is triggered to perform health check
 195
 196 3. **ocp-version** specifies the OCP protocol version supported by the
 197    OCP plugin
 198
 199 4. **rpc-requests-quota** sets the maximum number of concurrent rpc
 200    requests allowed
 201
 202 5. **global-notification-quota** sets the maximum number of concurrent
 203    notifications allowed
 204
 205 .. figure:: ./images/ocpplugin/plugin-config.jpg
 206    :alt: OCP plugin configuration
 207
 208    OCP plugin configuration
 209
 210 Test Environment
 211 ----------------
 212
 213 The OCP Plugin project contains a simple OCP agent for testing purposes;
 214 the agent has been designed specifically to act as a fake radio head
 215 device, giving you an idea of what it would look like during the OCP
 216 handshake taking place between the OCP agent and OpenDaylight (OCP
 217 plugin).
 218
 219 To run the simple OCP agent, you have to first download its JAR file
 220 from OpenDaylight Nexus Repository.
 221
 222 ::
 223
 224     wget https://nexus.opendaylight.org/content/repositories/opendaylight.release/org/opendaylight/ocpplugin/simple-agent/${ocp-version}/simple-agent-${ocp-version}.jar
 225
 226 Then run the agent with no arguments (assuming you already have JDK 1.8
 227 or above installed) and it should display the usage that lists the
 228 expected arguments.
 229
 230 ::
 231
 232     java -classpath simple-agent-${ocp-version}.jar org.opendaylight.ocpplugin.OcpAgent
 233
 234     Usage: java org.opendaylight.ocpplugin.OcpAgent <controller's ip address> <port number> <vendor id> <serial number>
 235
 236 Here is an example:
 237
 238 ::
 239
 240     java -classpath simple-agent-${ocp-version}.jar org.opendaylight.ocpplugin.OcpAgent 127.0.0.1 1033 XYZ 123
 241
 242 Web / Graphical Interface
 243 -------------------------
 244
 245 Once you enable the DLUX feature, you can access the Controller GUI
 246 using following URL.
 247
 248 ::
 249
 250     http://<controller-ip>:8080/index.html
 251
 252 Expand Nodes. You should see all the radio head devices that are
 253 connected to the controller running at <controller-ip>.
 254
 255 .. figure:: ./images/ocpplugin/dlux-ocp-nodes.jpg
 256    :alt: DLUX Nodes
 257
 258    DLUX Nodes
 259
 260 And expand Yang UI if you want to browse the various northbound APIs
 261 exposed by the OCP service.
 262
 263 .. figure:: ./images/ocpplugin/dlux-ocp-apis.jpg
 264    :alt: DLUX Yang UI
 265
 266    DLUX Yang UI
 267
 268 For information on how to use these northbound APIs, please refer to the
 269 OCP Plugin Developer Guide.
 270
 271 Programmatic Interface
 272 ----------------------
 273
 274 The OCP Plugin project has implemented a complete set of the C&M
 275 operations (elementary functions) defined in the OCP specification, in
 276 the form of both northbound and southbound APIs, including:
 277
 278 -  health-check
 279
 280 -  set-time
 281
 282 -  re-reset
 283
 284 -  get-param
 285
 286 -  modify-param
 287
 288 -  create-obj
 289
 290 -  delete-obj
 291
 292 -  get-state
 293
 294 -  modify-state
 295
 296 -  get-fault
 297
 298 The API is documented in the OCP Plugin Developer Guide under the
 299 section Southbound API and Northbound API, respectively.