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 You can interact with OCP service via RESTCONF, so you have to install
 155 the following features to enable RESTCONF.
 156
 157 ::
 158
 159     karaf#>feature:install odl-restconf odl-l2switch-switch odl-mdsal-apidocs
 160
 161 Then install the odl-ocpplugin-all feature which includes the
 162 odl-ocpplugin-southbound and odl-ocpplugin-app-ocp-service features.
 163 Note that the odl-ocpjava-all feature will be installed automatically as
 164 the odl-ocpplugin-southbound feature is dependent on the
 165 odl-ocpjava-protocol feature.
 166
 167 ::
 168
 169     karaf#>feature:install odl-ocpplugin-all
 170
 171 After all required features are installed, use following command from
 172 karaf console to check and make sure features are correctly installed
 173 and initialized.
 174
 175 ::
 176
 177     karaf#>feature:list | grep ocp
 178
 179 Configuration
 180 -------------
 181
 182 Configuring the OCP plugin can be done via its configuration file,
 183 62-ocpplugin.xml, which can be found in the
 184 <odl-install-dir>/etc/opendaylight/karaf/ directory.
 185
 186 There are the following settings that are configurable:
 187
 188 1. **port** specifies the port number on which the OCP plugin listens
 189    for connection requests
 190
 191 2. **radioHead-idle-timeout** determines the time duration (unit:
 192    milliseconds) for which a radio head has been idle before the idle
 193    event is triggered to perform health check
 194
 195 3. **ocp-version** specifies the OCP protocol version supported by the
 196    OCP plugin
 197
 198 4. **rpc-requests-quota** sets the maximum number of concurrent rpc
 199    requests allowed
 200
 201 5. **global-notification-quota** sets the maximum number of concurrent
 202    notifications allowed
 203
 204 .. figure:: ./images/ocpplugin/plugin-config.jpg
 205    :alt: OCP plugin configuration
 206
 207    OCP plugin configuration
 208
 209 Test Environment
 210 ----------------
 211
 212 The OCP Plugin project contains a simple OCP agent for testing purposes;
 213 the agent has been designed specifically to act as a fake radio head
 214 device, giving you an idea of what it would look like during the OCP
 215 handshake taking place between the OCP agent and OpenDaylight (OCP
 216 plugin).
 217
 218 To run the simple OCP agent, you have to first download its JAR file
 219 from OpenDaylight Nexus Repository.
 220
 221 ::
 222
 223     wget https://nexus.opendaylight.org/content/repositories/opendaylight.release/org/opendaylight/ocpplugin/simple-agent/${ocp-version}/simple-agent-${ocp-version}.jar
 224
 225 Then run the agent with no arguments (assuming you already have JDK 1.8
 226 or above installed) and it should display the usage that lists the
 227 expected arguments.
 228
 229 ::
 230
 231     java -classpath simple-agent-${ocp-version}.jar org.opendaylight.ocpplugin.OcpAgent
 232
 233     Usage: java org.opendaylight.ocpplugin.OcpAgent <controller's ip address> <port number> <vendor id> <serial number>
 234
 235 Here is an example:
 236
 237 ::
 238
 239     java -classpath simple-agent-${ocp-version}.jar org.opendaylight.ocpplugin.OcpAgent 127.0.0.1 1033 XYZ 123
 240
 241 Programmatic Interface
 242 ----------------------
 243
 244 The OCP Plugin project has implemented a complete set of the C&M
 245 operations (elementary functions) defined in the OCP specification, in
 246 the form of both northbound and southbound APIs, including:
 247
 248 -  health-check
 249
 250 -  set-time
 251
 252 -  re-reset
 253
 254 -  get-param
 255
 256 -  modify-param
 257
 258 -  create-obj
 259
 260 -  delete-obj
 261
 262 -  get-state
 263
 264 -  modify-state
 265
 266 -  get-fault
 267
 268 The API is documented in the OCP Plugin Developer Guide under the
 269 section Southbound API and Northbound API, respectively.