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

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